Live order status

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered; the description adds genuinely new behavior: customer calls are restricted to the caller's own orders, staff phone lookups return the latest 5 orders only. It stops short of explaining where session_key/staff_session come from (presumably foran_login/foran_staff_login) or what happens when no identifier is supplied.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three tight sentences with no filler, each doing a distinct job: payload contents, caller routing, invocation trigger. Arguably the long return-field list is placed ahead of the more decision-relevant caller-routing rule, but the ordering is defensible and nothing is redundant.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description compensates by enumerating the returned fields, and it explains both access modes and the staff result limit. Remaining gaps are how to obtain the session credentials and behavior when no selector is passed — modest for a read-only status tool with annotations covering safety.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is only 25% — just the phone field is documented — so the description must carry the rest, and it largely does: session_key is identified as the customer credential scoped to own orders, staff_session as the staff credential, and the order_id/phone pair is explained as alternative selectors with a 5-order cap on phone. Only order_id itself is left to inference, which is minor.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Names a specific resource (a Foran order) and an explicit capability (real-time status) and enumerates exactly what the response carries: stage, timeline, store, rider name/phone, items, delivery charge, total, payment. That is far more concrete than the title alone. It does not, however, distinguish itself from close siblings like foran_track_order or foran_order_details, so an agent still has to guess which of the three answers a status question.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives a clear use trigger ('whenever someone asks where is my order?') and splits the calling convention by caller type: customers pass session_key and are scoped to their own orders, staff pass staff_session plus order_id or phone. What is missing is any exclusion or alternative routing, e.g. when to prefer foran_track_order or foran_my_orders instead.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.