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

Annotations already declare readOnly, non-destructive, closed-world, so the safety profile is covered; the description adds real value by defining how each metric is computed (win rate conditioned on runs recommending any tracked product) and by warning that zero-hit and null-rate conventions live in `howToRead`. It stops short of stating cost/latency or what happens when no products are tracked.

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?

Purpose is front-loaded in the opening clause, and the second sentence about howToRead conventions is a useful pointer rather than filler. The main sentence is dense with parenthetical definitions, but every clause carries metric semantics.

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, two-parameter, no-output-schema tool, the description explains what each returned figure means and where interpretation rules live, which is most of what an agent needs. It leaves a small gap around the zero-required-parameter case, i.e. what is returned if neither clientId nor projectId is passed.

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 100%, so both parameters are already documented, including the clientId note about resolving to the newest AI-Visibility project. The description only restates "Takes projectId or clientId" without adding precedence rules or behavior when neither (both are optional) is supplied.

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 resource (product-level AI shopping visibility) and enumerates the distinct outputs — recommendation rate with standard error, head-to-head win rate, and untracked discoveries — which no sibling defines. It does not explicitly distinguish itself from near neighbors like get_ai_visibility_metrics, get_visibility_trend, or get_brand_perception, so an agent must infer the split.

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?

Scope is implied by "for an AI-Visibility project" and by the two accepted identifiers, but there is no explicit when-to-use/when-not guidance and no sibling is named as an alternative. An agent can guess this is the shopping-prompt view rather than the general visibility metrics, but the routing is left to inference.

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