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

Annotations declare the mutation/cost profile (readOnlyHint=false, destructiveHint=true, openWorldHint=true), and the description adds genuinely non-obvious behavior: a cached snapshot within 12 hours is returned instead of a new purchase, and the index lags by days. The idempotency-key retry semantics are also useful. It stops short of stating the credit cost that destructiveHint implies.

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?

Three tight sentences, each load-bearing: resource/scope first, then the cache-window behavior, then the retry instruction. No filler and the important constraint is front-loaded.

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?

An output schema exists, so return values need not be described, and the annotations carry the safety profile. The description supplies the unusual caching and idempotency context an agent needs to call it correctly; the only meaningful omission is any indication of credit cost or side effects, which destructiveHint implies but never explains.

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 only 50%, but the description compensates for the undocumented parameter by explaining that idempotency_key must be unique on first call and reused on retry — semantics absent from the schema, which only gives length bounds. domain_id's meaning is already carried by the schema 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?

States a specific verb and resource ('Capture a fresh AI Share of Voice snapshot for a domain') and names the upstream source (DataForSEO LLM Mentions). The word 'fresh' implicitly separates it from a plain read like get_share_of_voice, but the sibling is never named, so the differentiation is inferential rather than explicit.

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 a concrete operating rule for retries ('Send a unique idempotency_key, and the same one on a retry') and explains the 12-hour cache window, which guides cost-aware use. However, it never says when to prefer this over get_share_of_voice or when a refresh is unnecessary, leaving the primary routing decision to inference.

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