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

Annotations already declare destructiveHint=true and idempotentHint=true, but the description adds meaningful context beyond them: it is free, generates nothing, approves no price, and requires a stable clientRequestId for safe reconciliation. The warning against restoring withdrawn consent reinforces the destructive nature. It stops short of describing what the call returns, but the added behavioral detail is substantial.

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?

Three dense sentences, front-loaded with the action and version requirement, followed by cost and recovery constraints. Every sentence carries information, though the recovery clause is somewhat terse and dense.

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?

For a destructive, no-output-schema write tool, the description covers purpose, cost side effects, idempotency, and failure/reconciliation behavior. It lacks return-value detail and doesn't spell out the version-mismatch error path, but is largely complete 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 0% schema description coverage, the description carries the burden and does so reasonably: it explains expectedVersion originates from soclo_rights_declaration_get (optimistic-concurrency version) and that clientRequestId should be 'stable' for idempotent reconciliation. It does not add format details, but the semantic origin and stability requirements for both params are conveyed.

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?

States a specific verb and resource: 'Record the owner's withdrawal against the current declaration version.' It names soclo_rights_declaration_get as the source of expectedVersion, distinguishing this write action from the read sibling. It doesn't explicitly contrast with soclo_rights_declaration_save, but the withdrawal action is 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?

Provides concrete when-not guidance: 'Do not automatically retry an uncertain withdrawal or restore withdrawn consent: read the current declaration and reconcile the same request ID.' This tells the agent how to handle uncertain/failed outcomes, though it does not explicitly frame the general trigger condition against siblings beyond the get reference.

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