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

Beyond the readOnly/openWorld annotations, it discloses result volume (up to 1000 per page), vendor cost (1 API credit), and a non-obvious auth caveat: an Operations App login calls this without credentials, limiting results to internet/anonymous-visible data. Those are exactly the operational details an agent cannot infer from structured fields.

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?

Content is front-loaded: the search capability and tracking_type contract come first, with pagination, auth, and cost notes trailing. It is dense but every sentence carries information; only the trailing endpoint/cost line is slightly tacked on.

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 correctly states what is returned (shipment summaries, page cap) and the schema covers pagination mechanics. Auth limitations and cost are disclosed, leaving only minor gaps like the fields present in a summary record.

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 100%, so the baseline is 3, but the description adds real meaning by enumerating what each tracking_type value matches (Location = origin/destination or stop name, Postal = zip or zip+4, Tracking = references/barcodes) and clarifying that DateOnly takes no criteria. This goes beyond the terse schema enum descriptions.

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?

The first sentence states a specific verb (search) and resources (orders and route stops) plus the searchable dimensions, so an agent immediately knows this is a multi-field summary search. It doesn't explicitly name which sibling to prefer (e.g., cxt_track_shipments vs cxt_list_recent_orders), but the summary-search framing differentiates it adequately.

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?

The description clearly explains how tracking_type drives search_criteria, including the DateOnly case where criteria is omitted and the date range is used. That is strong context for correct invocation, but it offers no explicit exclusions or guidance on when to pick a sibling like cxt_track_shipments instead.

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