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

Annotations already declare idempotentHint=true, destructiveHint=false, and readOnlyHint=false. The description adds valuable behavioral context beyond these: authentication requirements (Authorization: Bearer or X-API-Key), the fact it's not guest-callable, and the exact REST endpoint. It does not disclose side effects (e.g., whether escrow is consumed) but the annotations cover safety basics, so the added context earns a 4.

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 concise, with a few sentences that front-load the context (paid access, free preview) before the core action. It includes the REST endpoint and auth requirements without verbosity. Slight redundancy (e.g., 'Requires an agent API key' and 'Not guest-callable') but overall efficient.

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 tool with 3 parameters and no output schema, the description covers auth, endpoint, and the parameters' roles, but does not explain the response format, what happens after attaching, or explicitly state that one of open_tx_hash or proof_escrow_id is required (schema allows both null). It also doesn't connect to subsequent query steps. Given the lack of output schema, more detail on expected behavior would improve completeness.

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 only 33% (only session_id has a description). The description mentions open_tx_hash and proof_escrow_id but only says 'open_tx_hash preferred, or proof_escrow_id', providing minimal guidance on how to choose between them or what they represent. It does not explain the meaning of 'proof escrow' or clarify that at least one is typically expected, leaving significant gaps given the low schema coverage.

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 action: 'Attach a buyer-funded proof escrow (open_tx_hash preferred, or proof_escrow_id) to an opened data session.' It identifies the resource (data session) and the operation (attach escrow). It also differentiates from siblings by mentioning data_preview for free access and the paid nature of this tool, making its purpose distinct.

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 description provides clear context: it's for buying per-query access after opening a session, requires an agent API key, and is not guest-callable. It explicitly references data_preview as a free alternative and implies the need for a previously opened session. However, it does not explicitly mention when to use this over data_session_fund or other funding tools, leaving some ambiguity.

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