ai_search_volume

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

With no annotations, the description carries the full burden, and it does disclose meaningful traits: the metric is modeled rather than observed, has monthly history, and costs 0.05 USDC on Base via x402 (a real billing/auth detail). It stops short of describing the return shape (no output schema exists) or the repeat-purchase semantics, which are only encoded in the confirmNewPurchase parameter.

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?

Two dense sentences that front-load the definition and the most decision-relevant caveat ('not actual assistant query logs'), then layer on availability, cap, and cost. Nothing is padding, though the parenthetical pricing clause is slightly bolted on.

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 a paid, un-annotated tool with no output schema, the description covers provenance, cadence, caps, and price, which is a reasonable amount. It still leaves the response format and the practical consequences of repeated purchases unexplained, so an agent cannot fully predict the call's outcome or cost profile.

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 75%, comfortably in the territory where the schema does the heavy lifting, so a baseline 3 applies. The description reinforces the 1000-keyword cap already stated by maxItems but adds no new semantics for keywords, language_code (undocumented in the schema), or location_code.

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, unusual resource — a 'modeled AI question-demand indicator' derived from DataForSEO signals including People Also Ask — and explicitly disclaims that it is real assistant query logs. That verb+resource pairing is precise enough to distinguish it from near-neighbors like keyword_metrics, keyword_metrics_multi, and google_trends, though it never names an alternative.

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?

Usage is only implied: an agent can infer this is the tool for AI-search question demand rather than classic search volume, and the 'not actual assistant query logs' caveat warns when the data is inappropriate for certain claims. But there is no explicit when-to-use, when-not-to-use, or sibling routing guidance.

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