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

Annotations already declare this a safe, idempotent read, so the description focuses on disclosing behavior that annotations cannot capture: the scoring pipeline (LLM scorer or Jev with LLM fallback below 0.5 confidence), that each answer counts once even if its brand is no longer primary, and exactly how restatements like null versus 0 behave. It also explains the data-quality hazard of days before 20 September 2026 being withheld and how overall, window.dataFrom, and coverage.daysWithheld account for them.

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 scope are front-loaded in the first sentence, and the long body is dense with operational detail rather than filler. It is still a single wall of text, and a few clauses, such as the repeated withholding explanation, could be tightened without loss.

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?

Even though there is no output schema, the description fully documents what the agent will receive: averageScore, label thresholds above 0.3 and below -0.3, the positive/neutral/negative counts, coverage.responses versus coverage.scoredResponses, and the null conventions. Together with the withholding caveats, this is complete for a one-parameter read tool.

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 100%, so the windowDays parameter (30 or 90, default 30) is already documented in the schema. The description adds real meaning by clarifying that the window consists of completed UTC days ending yesterday, which is not in the schema, but it never references the parameter by name or repeats its allowed values, so the added value is modest.

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 (sentiment of AI answers toward the primary brand), plus the exact scope: a fixed window of completed UTC days ending yesterday, overall and daily, across every platform. It also draws boundaries that separate it from nearby tools, noting scores are 'never competitors' and that there is 'no per-platform breakdown.'

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 interpretive guidance ('Read coverage before comparing averages') and explains when figures are withheld, which helps an agent use the output correctly. However, it never says when to choose this tool over a sibling, such as the competitive-position or accuracy tools in the catalog, nor does it state prerequisites for calling it.

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