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

Annotations already indicate non-read-only, idempotent, and non-destructive. The description adds meaningful behavioral context: requires authentication, not guest-callable, and the REST endpoint. It also clarifies the funding requirement ('buyer-funded proof escrow'). This goes beyond the structured annotations and helps the agent understand prerequisites and constraints.

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 relatively compact but packs several pieces of information: purchase model, free preview link, authentication requirements, escrow attachment, endpoint route. It is front-loaded with the main purpose and then provides supporting details. Not every sentence is essential, but the structure is logical and no content is redundant.

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 covers the main operational context: what to attach, where (session), how (REST), and prerequisites (API key, funded escrow). It lacks detail on return values or error behavior, and the two optional parameters are semantically under-described. Given the absence of an output schema, the agent has limited understanding of what to expect post-call.

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 and states a preference, but does not explain what these values represent or when to choose one over the other. Beyond the parameter names and types, there is no semantic explanation in either the schema or the description.

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 opens with a clear statement of what the tool does: 'Buy per-query access to live data listings' and then states the core action: 'Attach a buyer-funded proof escrow to an opened data session.' This is a specific verb+resource combination that distinguishes it from siblings like data_session_fund and data_preview.

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 requires an API key, is not guest-callable, and suggests a preferred parameter (open_tx_hash). It also mentions data_preview as a free first taste, which implies a usage flow. However, it does not explicitly state when to use this instead of data_session_fund or other alternatives.

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