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

The description discloses meaningful behavior beyond the annotations: it runs one live Google search per target keyword, conditionally omits opportunity score and cluster placement when no completed research run exists, and notes credit consumption and daily/monthly caps. The annotations only say readOnlyHint=false and destructiveHint=false, so this additional context is valuable and not contradictory.

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 dense sentences with no filler. The core behavior is front-loaded, followed by usage sequencing, conditional outputs, exclusions, and cost/rate information — each sentence earns its place.

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 tool with three required parameters and no output schema, the description is unusually complete: it explains inputs, expected outputs, conditional behavior, when to use it, when not to use it, and account-level limits. Nothing critical for an agent to select and invoke this tool correctly appears 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?

Schema coverage is low at 33%, but the description partially compensates by clarifying that the tool acts on 'one article idea that is already in the project,' which maps to suggestionId and projectId. The context parameter is already well described in the schema itself. The description does not fully walk through each parameter, but it adds enough relational meaning to be useful.

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 states a specific verb and resource: 'attach real search data to one article idea that is already in the project.' It also names concrete outputs — 'volume bands and the pages currently ranking for each' — and explicitly contrasts itself with start_research_run, so an agent can distinguish it from siblings without opening schemas.

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 explicit sequencing: 'Use after create_article_suggestion_with_input, or on any existing suggestion the operator wants judged on data instead of instinct.' It also names the alternative for a different use case: 'Do not use to find new ideas or map a niche — that is start_research_run.' This leaves little to inference.

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