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

The description goes well beyond the annotations by explaining the behavioral implications of authentication state: anonymous calls persist nothing, while authenticated calls create durable threads. It also discloses the significant caveat about fee schedules and the requirement to present the total as a subtotal when pricing_coverage is 'partial_estimate,' and mandates relaying the pricing_disclosure. While the annotations already note readOnlyHint=false, the description enriches the agent's understanding of the side effects and the appropriate way to handle the response.

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 packed with information in a compact space—five sentences that each carry a distinct purpose: definition, stateful behavior, comparison with sibling, caveat about fees, and explicit handling instructions. It avoids filler and front-loads the most essential information ('out-the-door quote') while progressively revealing complexity. The flow from simple to complex helps the agent parse it efficiently.

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 the tool's complexity (stateful/stateless behavior, partial fee schedules, pricing coverage variations, and required disclosure), the description is remarkably complete. It explains the tool's outputs ('Totals are estimates') even without an output schema, and the mention of 'pricing_coverage' and 'excluded' fields, though not in the schema, suggests an output contract an agent would need to know about. The existence of siblings like quote_preview, inventory_get, and lead_submit makes this differentiation and completeness even more valuable.

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 33% (one of three parameters described), but the description adds crucial context: it explains why idempotency_key matters ('Required when authenticated') and hints at identity/rooftop semantics. While it doesn't explicitly define identity or rooftop_slug, the phrase 'one available unit at a named rooftop' gives the agent better intuition than the bare schema. The mention of the authentication-dependent behavior of idempotency_key and the pricing_disclosure output field (not even in the schema) provides significant semantic value beyond the schema.

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 opens with a crisp specific definition: 'an out-the-door quote for one available unit at a named rooftop.' This uses a specific verb+resource and clearly distinguishes the tool from its sibling quote_preview ('read-only equivalent for browsing'). The complexity of what 'deal_quote' does beyond that — authentication states, fee disclosure, pricing estimates, and the required disclosure — is communicated in a way that purpose is unmistakable, even for an agent that hasn't encountered the tool before.

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 provides explicit guidance on when to use this tool versus quote_preview: 'quote_preview is the read-only equivalent for browsing.' It also clarifies behavioral differences based on authentication state ('Anonymous calls are stateless; authenticated calls persist a deal thread'), which is crucial for an agent deciding how to call this tool. No exclusions are stated, but the practical context for selecting this sibling over alternatives is clearly provided.

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