confirm_operation

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

Discloses critical behaviors: token expiration (120 seconds), hash matching for safety, and server-side resource change detection. This goes beyond simple confirmation by warning about failure conditions, ensuring the agent understands risks even without 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?

Well-structured and informative, but slightly verbose. Each sentence adds value, though the example could be slightly condensed. Front-loaded with purpose, then parameter details and safety checks.

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?

Comprehensive coverage: explains purpose, parameters, expiry, safety mechanisms, and error conditions. No output schema exists, but the description adequately specifies that the operation is executed silently on success or denied with reason on failure. No gaps for an agent to misunderstand.

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?

Despite 0% schema description coverage, the description fully explains both parameters: 'token' is the confirmation token from the destructive call, 'operation_hash' is optional but must match the original hash to prevent misuse. Provides concrete example showing how token could be reused maliciously without hash.

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's purpose: 'Confirm and execute a destructive operation.' It explains the role of the token and operation_hash, distinguishing this as a secondary step after a destructive tool call, unlike sibling tools that are direct actions.

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?

Explicit when-to-use: after a destructive tool that returns a token. Provides when-not: token expires after 120 seconds, operation_hash mismatch, or resource change. It implies alternatives by stating only destructive operations need this step, guiding the agent to use other tools for non-destructive actions.

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