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

Beyond the destructive, idempotent, and openWorld annotations, it discloses that the call spends credits, requires owner price approval, is recoverable via status after lost replies or restarts, and warns that pending is not ready or necessarily unpaid. This adds substantial behavioral context without contradicting 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?

It front-loads the cost warning, then packs prerequisites, recovery path, and retry condition into compact sentences without filler. The density is appropriate for a high-risk credit-spending operation.

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, credit-spending, idempotent tool with no output schema, the description covers authorization, cost, quote binding, request identity, recovery, and retry boundaries. Remaining gaps are minor content-field semantics that are partly covered by the schema.

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 schema coverage at 17%, the description supplies key semantics for quoteId, expectedCredits, clientRequestId, ownerApprovedPrice, and retryAdmission, including the exact saved-request resend rule. It does not explain the nested input content fields such as description, previewText, and language, and model meaning is left to schema, so compensation is strong but not complete.

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 opening 'SPENDS credits: buys the quoted voice previews' names the action, resource, and cost model, and later references to soclo_hosted_voices_quote and soclo_hosted_voices_design_status distinguish it from the quote and status siblings.

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?

It states prerequisites explicitly: owner approval of the exact price, unchanged input, quoteId, expectedCredits, and a stable clientRequestId. It also names the uncertainty path by directing the agent to soclo_hosted_voices_design_status with the original ID, and narrows retryAdmission to reconciling a missing admission.

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