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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), yet the description still adds real behavioral context: that 'over_time' is recomputed from stored daily results and available for the whole window immediately, that 'period' overrides 'days' and changes the response shape (with the specific period block fields named), and that 'concise' trims matrices to protect context while 'detailed' returns the full grid.

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?

Front-loaded with purpose, then cleanly sectioned into Views and Args. It is longer than average, and a few clauses (the business-line quote example, the Competitive Trend chart aside) are illustrative rather than load-bearing, but almost every line carries decision-relevant 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?

For a 9-parameter, no-output-schema tool, the description is complete enough to call correctly: it covers views, per-parameter constraints, the period-block response shape, and the concise/detailed tradeoff. An agent would not need to guess at response structure for the main paths.

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 only 11%, so the description carries the burden and does so thoroughly: it explains brand_id, every enum value of view, competitor behavior on both 'head-to-head' and 'over_time' (including that it pulls in competitors outside the top slice), days vs. period interaction, tag_ids semantics plus its dependency on list_tags, and limit's range and ordering. This is meaning well beyond what the bare schema enums convey.

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 ('Get competitor analysis data from AI search') and then enumerates seven named views, each with a one-line definition of the data it returns. An agent knows exactly what this produces without opening the schema, and the view list distinguishes it from single-metric siblings like get_visibility_scores or get_rankings.

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 view descriptions function as usage guidance, and constraints are explicit: 'head-to-head' requires the competitor param, 'period' is view='summary' only, 'limit' is 'over_time' only. What's missing is routing against siblings — compare_brands and compare_reports are never mentioned as alternatives for cross-brand comparisons, so the agent must infer when this tool is the right one.

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