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

Beyond the annotations it discloses meaningful traits: idempotency keyed by user/slug/UUID, free owner-only result retrieval via a specific endpoint or nexscope_seo_call_result, call-history persistence, seven-day source-freshness rules, and that missing values are not zero. This is substantial behavioral context; only the readOnlyHint=false mutation implication is left for the caller to interpret.

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?

Sentences are individually efficient but the description is not front-loaded on purpose—it opens with output phrasing and retrieval mechanics. Operational caveats (missing values, examples) dilute the core signal an agent needs first.

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 no output schema and low parameter coverage, the description partially compensates by describing the result contents and retrieval mechanics, but leaves the five input parameters and the request behavior largely unexplained. Adequate but with clear gaps for a 5-parameter, open-world tool.

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 20%, so the description should compensate but does not: it never explains market, language, keyword, limit, or sources semantics. Only 'source relationships' loosely gestures at the sources parameter, leaving the four core parameters undocumented.

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 leads with an output phrase ('Deduplicated suggestions and related keywords with source relationships') rather than a verb+resource statement of what the tool does; only the title makes the expansion action clear. It offers no differentiation from the many sibling SEO keyword tools (keyword_ideas, search_autocomplete, keyword_metrics).

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?

There is no guidance on when to use this tool versus the numerous keyword alternatives, nor any prerequisites for invocation. Operational notes about retrieval and freshness do not tell the agent when this tool is the right choice.

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