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

The annotations only provide generic hints (readOnlyHint false, idempotentHint false), while the description adds concrete behavioral context: each query costs 0.01 USDC, queries are capped at 20 per session, and the session must already be funded. This discloses cost and rate-limit behavior that an agent could not infer from the structured fields alone.

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 short and front-loads the core idea of per-query paid access, then gives the workflow and pricing. The listing-specific cost and quota detail is useful, though the marketing tone of the first sentence adds slight noise.

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?

With five parameters, no output schema, and low parameter-description coverage, the definition omits critical information about query syntax, k, delivery_receipt, and what the response contains. An agent can understand the workflow position but cannot confidently construct the body or interpret the result.

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?

Only 40% of schema properties have descriptions (session_id and sandbox_receipt). The main description does not explain the query parameter format, the k parameter semantics, or the delivery_receipt parameter. The listing text says the data is NOAA marine buoy observations, but that is not enough to construct a valid request.

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 frames the tool as buying per-query access and closes with the workflow sequence ending in data_session_query, which makes the resource and action identifiable. The schema description is clearer: 'Run a prepaid query against a funded data session.' It also differentiates from data_preview by calling it the free first taste, though the main description has a marketing tone.

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 explicitly gives the required sequence: data_session_open → data_session_fund → data_session_query, so an agent knows this must be called after a session is opened and funded. It also points to data_preview for a free preview, giving an alternative. It does not spell out formal when-not-to-use conditions, but the workflow is clear.

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