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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so safety is covered; the description adds real behavioral substance on top, namely what each mode actually inspects (crawler access, firewall blocks, challenges, cloaking, competitor naming) and where the data originates (Brand Radar, citation counts, ahrefs/semrush). It does not mention rate limits, cost, or auth requirements, which is the remaining gap.

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?

Front-loaded purpose sentence followed by a tight mode-by-mode breakdown; the 'mode = behavior. Needs X.' pattern is scannable and every clause carries information. The mode blocks are run-on but justified by the four-way branching and the differing input requirements.

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 10-parameter, four-mode tool with an output schema present (so return values need not be described), the description covers the mode semantics and per-mode required inputs well. It leaves out the secondary parameters (detail, source, competitors, memory_key) and any note that no parameter is strictly required, which an agent choosing a mode would benefit from.

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 70% schema coverage the schema does part of the work, but the description maps parameters to modes (url for check/bots, site+brand+responses for gaps, pages for citations) and spells out the nested response fields (question, response, links, search_queries, engine, volume) that the schema leaves bare. It omits any explanation of detail, source, memory_key or competitors, which are common-trap parameters here.

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?

Opens with a concrete outcome ('whether AI assistants can read, quote and recommend a site') and then enumerates four named modes (check, bots, gaps, citations) with the specific artifact each produces. An agent can immediately distinguish this from siblings like robots_txt, llms_txt or scan_page, which cover only fragments of this scope.

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 effectively driven by mode selection, and the description states exactly what each mode needs ('Needs url', 'Needs site, brand, responses[...]', 'Needs pages[...]'), so the agent knows which inputs select which behavior. It stops short of naming when-not-to-use or pointing at alternative siblings, so it is clear context without explicit exclusions.

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