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

Annotations already establish read-only, non-destructive, closed-world behavior, and the description adds substantial context on top: figures are backed by the same selection as the dashboard, score and share_of_voice are null when the scope has nothing to score, and scope.run_id is null for a date window. This is behavior an agent could not infer from the schema or annotations.

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?

The purpose and the get-prompt-scores exclusion are front-loaded, and the remaining sentences carry real information about return fields, defaults, and scope precedence. It is dense and long for a single paragraph, but almost nothing 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 9-parameter tool with nested filters and no output schema, the description supplies the return-field mapping (score/coverage/share_of_voice/mentions/counts) and null-case semantics, which is exactly the missing piece. An agent has enough to call it correctly and interpret the response.

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 the baseline is 3, but the description meaningfully extends it: the prompt_type taxonomy (non_branded excludes us and competitors, branded names only us, competitor_branded names a competitor) and the rule that each prompt belongs to exactly one segment are semantic content absent from the schema. Scope precedence and filters validation are partly duplicated from scheme descriptions, which keeps this short of a 5.

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 opening sentence names a specific verb and resource ('get the exact visibility score') and enumerates the scope axes (prompt type, topic, filters, engine, run or date window). It also explicitly distinguishes itself from get-prompt-scores, stating that per-prompt scores do not average into the scoped figure.

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 scope resolution precedence is spelled out in full (run_id > run_date > latest_run > last `range` days with a 15d default), and the description routes agents to list-prompt-filters for valid filter keys and to compare-visibility-runs for run/slice comparisons. It even states a negative condition: filters with undeclared keys are rejected.

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