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

Annotations already declare the write/open-world/idempotent profile, so the bar is lower, and the description adds real context: escrow_id must be unique, the sign-and-confirm handoff, webhook events (funded, PASS, FAIL, expired) with payload shape, and metadata echo. It does not state whether funds are irreversibly locked or the consequences of expiry beyond the schema's auto-cancel field.

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?

Front-loaded with the core value proposition, then segmented into proof-gate and white-label sections. Every sentence carries information, though the two sub-sections are slightly more verbose than strictly necessary.

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 an 18-param mutation tool with annotations and an output schema, the description covers the essential flows (escrow creation, proof gating, webhooks, delegation implied via schema). Missing only edge behavior such as failure modes or fee-hash/tier interaction, which the schema partially covers.

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 coverage is 100%, so the baseline is 3; the description goes beyond it by grouping the five proof-gate params (require_nft_proof, required_nft_issuer, nft_dvp, required_domain, required_vc_issuer_did) as a coherent feature set and explaining callback_url/metadata intent. It adds conceptual grouping rather than per-param syntax, so not a 5.

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+resource ('register an escrow vault AND get the ready-to-sign transaction') and explicitly positions itself as the combined shortcut over create_escrow_vault() + prepare_escrow(). An agent can distinguish it from those siblings without opening either schema.

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?

Names the two sibling calls it replaces and describes the workflow ('only needs to sign the returned transaction and confirm it'), which is clear routing guidance. It lacks an explicit when-NOT-to-use condition (e.g., when you want to inspect the vault before preparing), so it falls short of a 5.

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