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

Beyond the readOnlyHint annotation, the description adds meaningful behavioral details: the tool never consumes lookups, is presence-based rather than volume-weighted, and provides no historical trend. It also defines what a 'gap' means. This is valuable context for an agent deciding whether the answer will satisfy the user's underlying request.

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 compact and front-loaded: the core metric appears first, followed by a definition of gaps, explicit scope limitations, parameter sourcing, and cost behavior. Every sentence provides distinct, useful information without redundancies.

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 single-parameter read-only tool with an output schema present, this description covers the key decisions an agent needs: what the metric means, what it excludes, where to get the id, and what invoking it costs. Nothing essential is missing.

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?

The schema only says project_id is a positive integer, but the description explains it is a ranking id from list_projects. This significantly compensates for the 0% schema description coverage and tells the agent where to obtain a valid value.

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 defines exactly what the tool computes: project-scoped share of voice, top-10 presence versus tracked competitors, and per-keyword gaps. This clearly distinguishes it from sibling tools like get_keyword_rankings or get_ai_visibility by including a scope and specific metric.

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 explicit context: tracked keywords only, presence-based not volume-weighted, and no historical trend. It also tells the agent project_id comes from list_projects and that calling is free. It stops short of naming alternative tools for cases where volume or historical trend is needed, so it lacks explicit sibling routing.

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