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

Annotations only declare a safe read; the description adds substantial context beyond that: the two status states the caller can observe, the 'not_found' result for missing or foreign offer ids, the caveat that market ranges are estimates rather than company pay bands, and the confidence field that can claim no position. That is exactly the kind of behavioral disclosure annotations cannot carry.

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?

Front-loaded with what the tool returns, then status behavior, then the estimate caveat and error case — a sensible priority order with no filler. The opening is a long, dense enumeration, but every listed artifact (scripts, deltas, confidence) tells the agent something actionable, so the length is largely earned.

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?

Given an output schema exists, the description could have stopped at purpose; instead it covers return contents, async status transitions, error behavior, and an important interpretive caveat about market estimates. An agent has everything needed to call this correctly and to interpret the response honestly.

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?

Only one parameter, and the description gives no syntax detail beyond the schema, but the schema's own property description ('Id of the offer to fetch, from list_offers or analyze_offer') covers the parameter meaning and provenance. With a single, schema-documented parameter there is little left for the description to add.

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?

Opens with a specific verb+resource ('Full analysis of one offer') and then enumerates exactly what the analysis contains (health score, verdict, pay components, flags, leverage points, scripts). This clearly distinguishes it from list_offers (which enumerates) and analyze_offer (which produces the analysis), so an agent can route correctly without opening the schema.

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 status semantics ('processing' while the analysis runs, 'completed' once done) implicitly tell the agent this is a poll/read tool that follows an analyze_offer call, and the schema's offer_id description names list_offers and analyze_offer as sources. However, the description never states explicitly 'call this after analyze_offer' or gives guidance about polling cadence, so the when-to-use context is strong but not fully spelled out.

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