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

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false), and the description adds genuinely new context: results come from a historical provider database rather than a live model execution, so there is a freshness caveat. It also warns that evidence can be nullable and dimensions unsupported, which prepares the agent for gaps in the response — something no structured field conveys.

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?

Four compact sentences with the core statement front-loaded and no filler. The final sentence ('Preserve nullable evidence and unsupported dimensions') is the weakest — it reads as an instruction rather than information — but the overall length is appropriate for the payload.

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 7 parameters, a required nested union array, no output schema, and 0% schema coverage, the description is far too thin. It never explains what a 'new' versus 'lost' mention actually means, how groupRange affects the result shape, or what platform selection changes — the agent would be guessing on required inputs.

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 0% at the top level, so the description has to compensate. It does add real meaning for the most complex parameter: domain targets filter against cited sources while keyword targets filter against answer text, which explains the DOMAIN/KEYWORD union in `target`. Nothing is said about dateFrom/dateTo, groupRange granularity, or platform (google vs chat_gpt), leaving the majority of parameters unexplained in either place.

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?

It names a specific resource — new and lost mention statistics, kept as separate nonnegative values — which is more than a restatement of the tool name. But it never says these are AI-answer mention counts over a date range, and it gives no differentiation from close siblings such as nexscope_seo_ai_mention_deltas, nexscope_seo_ai_mention_history, or nexscope_seo_backlink_new_lost. An agent has to infer which of these four it wants.

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 statement of when to use this over nexscope_seo_ai_mention_deltas or nexscope_seo_ai_mention_history, and no prerequisites or exclusions. The only routing-adjacent sentence ('Historical provider database facts, not a live model execution') tells the agent the data is historical but does not help it choose between tools.

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