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

Annotations already flag readOnlyHint=false and openWorldHint=true, but the description adds the concrete side effect that matters: track=true creates tracking entries for candidates and up to five competitors within the plan. That is real value beyond the boolean flags. It stops short of covering re-run/idempotency behaviour (idempotentHint=false), which would matter for a mutation-capable tool.

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?

Two dense sentences, zero filler, with the core action and the output composition front-loaded ahead of the conditional track behaviour. Every clause carries information.

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, the description usefully enumerates what discovery returns and explains the mutation side path, which is most of what an agent needs. Remaining gaps — quota consumption, duplicate-tracking on repeat runs, and how this differs from the sibling gap/opportunity tools — are moderate rather than fatal.

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 100%, so all three parameters are already documented in structured form. The description restates the track flag's meaning and adds the competitor cap, but says nothing about max_keywords or application_id beyond what the schema provides. Baseline 3 is appropriate.

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?

States a specific verb and resource — 'Run keyword discovery for an application' — and enumerates what discovery yields (title seeds, store suggestions, outranking app titles), so the agent knows the output shape. It does not distinguish itself from near-neighbours like expand_keyword_gap, get_keyword_gap or track_keyword_opportunities, so sibling differentiation is left implicit.

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 usable in-tool guidance on the track flag: false means preview, true means commit tracking. But it never states when to choose this tool over the many related siblings (track_keywords, list_keyword_opportunities, get_keyword_gap), so the routing decision is inferred rather than explained.

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