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

Annotations already declare idempotentHint=true and destructiveHint=false, and the description adds useful behavioral context beyond those: authentication requirements via Bearer or X-API-Key, guest-call restrictions, the REST endpoint, and a preference for open_tx_hash over proof_escrow_id. It does not describe success/failure responses or billing side effects, but the annotations cover the main safety profile. No contradiction with 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?

The description is concise and well-organized, leading with the value proposition, then requirements, the core action, and the REST endpoint. The phrase 'first taste free via data_preview' is a slight extra but serves as a useful pointer. Overall, every sentence earns its place without excessive verbosity.

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 gives enough to make the call: endpoint, required auth, session_id, and escrow references. However, with no output schema, it does not describe the response format or what the agent should do after a successful attach, nor does it explain the relationship to data_session_fund or data_session_query. This is a moderate gap for a tool that is part of a multi-step paid-access flow.

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%, with only session_id explained in the schema. The description adds some value by stating that open_tx_hash is preferred and proof_escrow_id is an alternative, but it does not explain what these fields semantically represent or how an agent would obtain them. This partially compensates for the low schema coverage but leaves meaningful gaps.

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 identifies the operation: attaching a buyer-funded proof escrow to an opened data session to enable per-query access to live listings. It uses a specific verb and resource, and references data_preview, but it does not explicitly differentiate itself from the sibling data_session_fund, leaving some ambiguity about when to use one over the other.

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 concrete usage context: it requires an agent API key, is not guest-callable, and should be applied to a session opened via data_session_open. It also points to data_preview for a free first taste, which is a useful alternative signal. However, it does not explicitly state when not to use this tool versus data_session_fund or other siblings.

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