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

The description goes well beyond annotations, disclosing that new reservations are refused before any claim is written, that it re-reads CDP and confirms only the exact current claim and reserved expiry, and that it does not issue new permissions. It also explains the authentication requirement and the permissive input schema behavior, all without contradicting the annotations (readOnlyHint=false, idempotentHint=true).

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 dense but every sentence adds value, starting with the core purpose, then usage constraints, behavioral details, and authentication. It is structured logically—purpose, exclusions, confirmation logic, fallback behavior, and security—without padding or repetition. It is appropriately sized for the complexity of the tool.

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 (legacy behavior, security, and branching logic) and the presence of an output schema, the description is remarkably complete. It covers what the tool does, when to use it, side effects, authentication, and validation nuances. The existence of an output schema means return values need not be described, and nothing critical is missing for correct invocation.

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?

With zero parameters in the schema, the description adds critical meaning by explaining that the listed schema is intentionally permissive and that the strict schema is validated only after authentication. It also clarifies that authentication is via the request header, not arguments. This fully compensates for the empty schema and provides guidance an agent would otherwise lack.

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 the tool confirms an in-flight legacy Model B cap, specifying it does not issue new permissions and that new reservation requests are retired. This distinguishes it from sibling tools that handle reservations or permissions. The verb 'confirm' plus the specific resource 'legacy Model B cap' makes the purpose 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 explicitly states when to use this tool—for confirming a permission minted against a prior reservation—and when not to, such as for new reservations or when a mismatch or Stop overlap occurs, directing the agent to use a fresh explicit Stop instead. It also details the server-to-server authentication requirement through the x-otto-delegation-auth header, providing comprehensive usage guidance.

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