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

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=false, so the safety profile is covered. The description adds real value beyond that: it documents the failure envelope (`{ ok: false, error }`) and instructs the agent to surface the error to the user rather than retry blindly. It says nothing about result size, pagination, or cost, which keeps it below 5.

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 capability statement, and the error-handling clause follows the read contract. Slightly long but every clause carries information; no filler or restatement of the name.

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 names the metrics returned, and it covers the failure mode. But for an 11-parameter filtered analytics query at 18% schema coverage, an agent is left guessing about date-range semantics, filter defaults, and result granularity — gaps the description should have closed.

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 18% across 11 parameters, so the description must compensate and largely does not. It never explains from/to, tagIds, funnelStages, languageCodes, sourceTypes, locations, or modelIds; only the words 'per-stage' and 'prompt mix' faintly gesture at funnelStages and modelIds. The two required analytics parameters (context, llm_model) are documented only in the schema.

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 ('Read per-stage funnel performance across AI Visibility and SEO for a project') and enumerates the metrics returned: prompt mix, visibility, share of voice, keyword counts, ranks. That is far more specific than the sibling tools (which mostly cover monitoring, prompts, cart/orders), but it never names a sibling or a boundary, so the 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 second sentence gives error-recovery guidance, but there is no statement of when to call this versus the near-neighbors like get-monitoring-stats, get-llm-monitoring, or get-llm-prompt. An agent cannot tell from the description what question this tool answers that those do not.

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