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

The description goes far beyond the readOnlyHint annotation, detailing the async settlement behavior, the meaning of needs_review, the withholding of prices for restricted goods, the exception for branded goods, and specific user-facing instructions. This is rich behavioral disclosure that an agent needs to correctly handle results. No contradictions with annotations.

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 a single paragraph but tightly packed; every sentence serves a purpose, from the polling behavior to the needs_review handling and the branded exception. It is longer than a one-liner but efficient. The core action is front-loaded. Not perfectly concise but not wasteful.

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 one-parameter tool with no output schema, the description compensates fully: it lists the return fields (settled, options, summary, follow-up questions, needs_review), explains the semantics of the critical flag, and gives explicit action steps. An agent has everything needed to call and interpret 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 coverage is 100% for the sole parameter, and its description already states it's the quote_id from generate_offer. The description reinforces this by saying 'a generated offer' but adds no new semantic detail beyond the schema. Baseline of 3 is appropriate since schema handles it.

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 states a specific verb ('Poll') and resource ('a generated offer') and clearly indicates the async nature and output (settled, needs_review). It distinguishes from generate_offer (creates) and track_shipment (tracks), even though it doesn't name them explicitly. The core purpose is unambiguous.

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 implies when to use it (after generate_offer, using the returned quote_id) and provides clear operational guidance (what to tell the user when needs_review is true). It does not explicitly state 'do not use for tracking' but the context and sibling names make the intended usage clear. No exclusions are stated, but the scenario is well implied.

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