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

Annotations only provide readOnlyHint=false and destructiveHint=false, so the description adds meaningful behavioral context: each call costs 0.01 USDC and is capped at 20 queries per session. This rate-limit and pricing information is exactly the kind of beyond-annotation context an agent needs before invoking a paid operation. It does not describe fund deduction or error behavior, but the disclosed quota and cost are valuable.

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 compact: three short sentences covering pricing, quota, alternative, and required sequence. There is minor promotional phrasing in 'first taste free,' but no wasted tokens relative to the useful commercial and sequencing context.

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?

There is no output schema, yet the description does not say what a successful query returns or whether it returns matching listings, errors, or receipts. It also leaves the meaning of k and the query string to inference. The sequence and pricing are helpful, but the tool is not complete enough for an agent to call it confidently without additional assumptions.

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 40%, and the description does not compensate. It mentions 'per-query access' and the data listing, but gives no detail on what the query string should contain, what k controls, or when delivery_receipt matters. session_id is documented in the schema, but query and k remain effectively unexplained by the tool 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 states a specific action ('buy per-query access') and resource ('live data listings'), and it positions the tool in a clear sequence: data_session_open → data_session_fund → data_session_query. It also distinguishes itself from data_preview by calling it the free alternative. It does not explicitly say 'runs a query and returns results,' but the tool name and schema title make that recoverable.

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 sequence line gives explicit preconditions: a session must be opened and funded before this tool is used. The mention of 'first taste free via data_preview' provides a clear alternative path for trying before paying. It does not spell out exclusions, but the ordering is strong enough guidance.

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