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

The description adds meaningful behavior beyond the annotations by explicitly stating that this operation 'does not sign or broaden sharing' — a useful safety guarantee. It also frames the operation as a confirmation/retry rather than a fresh action. The annotation destructiveHint=true is not contradicted; retrying updates can still apply pending write effects.

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 two short sentences with no filler. The core action is front-loaded, and the important 'does not sign or broaden sharing' caveat is included without adding unnecessary detail.

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?

The description is adequate for understanding the basic action and safety posture, and an output schema exists so return details are not needed. However, it does not explain what makes an update 'unfinished,' how this relates to confirmation_token or idempotency_key, or how it fits with other sparkclose operations. These gaps are partially mitigated by the annotations and self-explanatory parameter names.

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 description coverage is 0%, and the description provides no parameter-level guidance. While names like project_id, investment_id, expected_version, idempotency_key, and confirmation_token are somewhat self-explanatory, the description does not clarify their roles, the meaning of expected_version, or when confirmation_token is required.

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 ('Confirm retry') and a specific resource ('unfinished canonical CRM/document updates'), and the title clarifies this is the SAFE-record retry operation. This clearly distinguishes it from sibling tools like sparkclose.close_investment or sparkclose.record_approval, which serve different stages of the workflow.

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 phrase 'retry of unfinished... updates' gives clear context for when to invoke the tool: when a prior canonical update did not complete and needs confirmation/retry. It does not explicitly name alternatives or exclusions, so it falls short of a perfect 5, but the context is unambiguous enough for an agent to select it.

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