`lookup_order_status` Example Violates Recommended Use of `status` Field for Tool Clarity

[gonalbz]

Issue Description:

The example provided in the Defining effective tool functions section violates the documented best practice regarding the use of the status field:

"It’s a highly recommended practice to include a status key (e.g., 'success', 'error', 'pending', 'ambiguous') to clearly indicate the outcome of the tool execution for the model."

However, in the current example, the status field is overloaded to represent both:

• The order state ('shipped', 'processing', 'pending')
• And the execution outcome ('error')

This creates ambiguity for the LLM or consuming clients when parsing the response.

Example from the docs:

# Success case:
{"status": "shipped", "tracking_number": "1Z9..."}

# Error case:
{"status": "error", "error_message": "Order ID not found."}

In this format:

• The meaning of status is context-dependent.
• There is no consistent flag to determine whether the tool executed successfully.
• It contradicts the structure used in other examples (e.g., getWeatherReport in Java), which properly separates status from the payload.

---

Suggested Fix:

Adopt a consistent schema that reserves the status field for signaling execution outcome (success, error, etc.), and uses a separate key (e.g., order) for business data:

# On success:
{
    "status": "success",
    "order": {
        "state": "shipped",
        "tracking_number": "1Z9..."
    }
}

# On error:
{
    "status": "error",
    "error_message": "Order ID not found."
}

This structure improves clarity, aligns with the ADK guidance, and ensures consistency across tool implementations.

---

Let me know if you want to reference the fix as a pull request or link it to an example file.