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

Annotations already convey idempotent, non-read-only, non-destructive behavior. The description adds valuable operational context: the exact auth headers, the not-guest-callable restriction, the REST endpoint, and the preference for open_tx_hash. It does not contradict annotations; the only notable omission is direct language about the session becoming billable.

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 reasonably tight and information-dense: purpose, auth, operation, guest restriction, and endpoint all appear in four sentences. It is not perfectly front-loaded because the broad 'Buy per-query access' opener precedes the precise attach action, and the auth and guest restrictions overlap slightly. Overall it is well-structured for an agent.

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?

It covers purpose, auth, endpoint, and the opened-session prerequisite, which is strong for a three-parameter tool. However, there is no output schema and no statement of what the call returns or how success is confirmed, and the relationship between this tool and data_session_fund/data_session_funding_package is left implicit. For an idempotent mutating call, an agent needs clearer postconditions.

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 low (33%), but the description partially compensates by indicating open_tx_hash is preferred over proof_escrow_id and that both identify a proof escrow. It still leaves ambiguity about whether one of the two optional parameters is required when both default to null, and it does not define the escrow identifiers beyond the schema's bare types.

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 identifies a specific operation: 'Attach a buyer-funded proof escrow ... to an opened data session,' with a clear verb and resource. It also positions itself against data_preview by noting the free taste, though it does not explicitly distinguish itself from the closely named sibling data_session_fund. The opening phrase 'Buy per-query access' is a bit broader than the actual attach action, so not a perfect 5.

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 gives practical preconditions: first taste free via data_preview, requires an agent API key, not guest-callable, and attaches to an opened session. These are clear context signals but it stops short of drawing an explicit when-to-use boundary against data_session_fund or saying what to do when the session has not been opened. A 5 would require explicit alternatives and exclusions.

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