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

Even though readOnlyHint annotation already indicates safety, the description adds substantial context: the tool never costs money, is summary-first and token-aware, explains that rank is a position where negative delta means improvement, and discloses that lost keywords are never dropped silently. This goes well beyond the annotation and clarifies behavior in edge cases like no completed research.

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?

The description is long but each sentence adds value: purpose, read-only guarantee, response format, rank semantics, lost keywords, edge case, parameter guidance, and sibling differentiation. It is information-dense with no fluff, though the single block of text could benefit from slight restructuring for scanability.

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?

Given the tool's complexity (5 parameters, response variations, edge cases), the description covers all necessary context: full response behavior, optional parameters, authentication nuance, and the no-research case. It even explains the `researched:false` response with guidance. The presence of an output schema doesn't reduce the need for this interpretive context, which is thoroughly provided.

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%, but the description explains every parameter in context: `sort` with default 'etv' and options, `limit` default 10 max 100, `domain`, `min_volume`, and `site_id` optional when OAuth-authenticated. It also explains the `truncated` block and `lost_keywords`, giving semantic meaning beyond raw schema definitions.

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 opens with a specific action and resource: 'Return the latest competitor SEO snapshot for the site (FD-041)' and details exactly what data is included (keywords, positions, search_volume, cpc, etv, rank changes). It explicitly distinguishes itself from sibling tools by saying 'This is the external competitor lens... for YOUR OWN search performance use get_keyword_performance, and for your content playbook use get_content_actions.'

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?

The description gives clear usage direction: use it to see competitor rankings, pass `domain` to focus on one competitor, `min_volume` to filter. It explicitly warns that the tool cannot trigger research ('this tool never runs a research... it only reads what was already fetched') and provides an alternative ('must be triggered from the dashboard first'). It also names sibling tools as alternatives for different use cases.

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