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

The description adds meaningful behavior beyond annotations: it explains idempotency concretely ('same payload reuses the existing tracker'), discloses the persistent side effect, and describes the synchronous return behavior plus a conditional follow-up call. Annotations already include idempotentHint and destructiveHint, but the description enriches the agent's understanding of what happens during and after the call.

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?

The description is compact and front-loaded: core behavior first, then idempotency, then usage routing, then a conditional follow-up, then field delegation. Every sentence earns its place, and there is no redundant restatement of the name or title.

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?

For a tool with 12 parameters and nested objects, the description wisely delegates field details to create_tracker and relies on the presence of an output schema for return semantics. It covers the key operational context: persistence, synchronous results, idempotency, and when to use an alternative. The phrase 'per-shipment plan' is slightly unexplained, but overall the agent has enough direction to call the tool correctly.

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 description coverage is only 8%, and the description does not explain any of the 12 parameters. It defers responsibility with 'Accepts the same fields as create_tracker — see that tool for field details,' which is a helpful pointer but not self-contained. An agent may need to fetch another tool's definition to understand parameters like courierCode, shippingDate, or clientTrackerId.

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 description clearly states a specific behavior: 'Creates a persistent tracker on the account AND returns full tracking results synchronously in one call.' This goes beyond the tool name and titles, describing both the resource affected (persistent tracker) and the immediate outcome (tracking results), while also distinguishing it from the one-off search_tracking sibling.

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 gives explicit routing guidance: 'Prefer search_tracking for one-off lookups when the per-call plan is available.' It also provides a concrete follow-up instruction to call get_tracking_results when the shipment is pending with no events. It does not fully contrast track with create_tracker, but it points to create_tracker for field semantics, which indirectly clarifies the relationship.

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