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

Annotations already declare readOnlyHint=true and destructiveHint=false with openWorldHint=true, so the safety profile is covered. The description adds real behavioral value beyond that: it discloses the response contents (clicks, impressions, click share, top queries per group) and the fallback to dashboard-saved brand terms when brand_terms is omitted. No output schema exists, so this return-shape disclosure matters.

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 sentences, front-loaded with the operation and its outputs, followed by the one non-obvious invocation rule. Nothing is repeated from the schema and no sentence is filler.

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 read-only report with 6 parameters and no output schema, the description covers purpose, segmentation rule, return contents, and the brand_terms fallback, which is enough to call it correctly. The only gap is the `top` limit, which has no description in the schema and no mention in the prose.

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 83%, so baseline is 3. The description goes beyond the schema by explaining the fallback semantics of omitting brand_terms (site-level saved brand terms), which the schema does not state anywhere, and by reinforcing that common spellings should be passed as multiple terms. The `top` parameter remains unexplained in both places.

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?

"Splits Search Console queries into branded ... and non-branded, with clicks, impressions and click share for each, plus the top queries in both groups" gives a specific verb, resource, segmentation logic, and the exact output contents. It is unmistakable against siblings like report_cannibalization or report_quick_wins, which address entirely different analyses.

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 conditional guidance for one parameter ("leave it out to use the brand terms saved for the site in the dashboard"), which tells the agent how to invoke it in the default case. However, it never states when a brand/non-brand split is the right analysis versus the other report_* tools, so tool selection still rests on the name alone.

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