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

Beyond the annotations (readOnlyHint=true, destructiveHint=false), the description discloses the payment gate ("Priced per record with a minimum per pull"), the accepted payment channels, and crucially the failure mode: "Without payment the result is a 402 with the price and a preview count." It also discloses the privacy behavior (guaranteed absent identifiers) and where the schema lives. This far exceeds the annotation baseline and tells the agent exactly what to expect before paying.

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?

Five dense sentences with zero filler: dataset contents, privacy guarantees, filtering and pagination, pricing and payment, and the no-payment failure mode plus schema pointer. The "Never a name..." clause adds specific value rather than restating "de-identified," and each sentence carries a distinct piece of information.

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?

For an 11-parameter, monetized data tool with no output schema, the description covers the data shape, filters, pagination, payment behavior, and the 402 failure mode. It doesn't describe the successful response format or exact parameter value formats, but the /data.json reference and the field enumeration make a correct first invocation feasible.

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?

With only 36% schema description coverage, the description compensates by naming seven filter dimenions in domain language ("state, since, until, door, vendor; limit and offset") and four payment modes ("prepaid buyer key, x402, MPP or AP2"). It adds meaning the bare schema lacks, though it doesn't specify value formats such as date syntax for since/until; the /data.json pointer partially fills that gap.

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 names a specific resource and action: the de-identified demand dataset of auto insurance requests, with the title supplying the verb "Buy." It enumerates the exact fields contained (age band, ZIP3, vehicle, coverage, door, outcome) and explicitly carves out what it never contains ("Never a name, phone, email, date of birth or five-digit ZIP"), sharply distinguishing it from siblings like pull_requests, get_quotes, and check_eligibility.

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 gives clear usage context: retrieve demand records, "Filter by state, since, until, door, vendor; limit and offset," and pay via prepaid buyer key, x402, MPP or AP2. It also points to a free sample at /data.json. However, it never explicitly names sibling tools or states when not to use this tool versus pull_requests or get_quotes, leaving alternative-selection to inference.

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