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

Annotations already declare readOnly/idempotent/non-destructive, so those needn't be restated. The description adds real behavioral context beyond them: 'Marks nothing as seen' (important for downstream state), 'Uses the existing app comparison window, never an invented custom period' (a hard scoping constraint), and the null semantics for a change that falls inside sampling noise. Return-format detail is thinner, which keeps this at 4 rather than 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?

The trigger is correctly front-loaded, and most clauses carry information. However it is a single dense paragraph with awkward embedded clauses ('the change against the window before') and enumerates return fields at length even though an output schema already exists, so some sentences compete with structured data rather than adding to it.

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 an output schema present, the description doesn't need to document returns, yet the added explanation of what null means and which sections surface which data is genuinely useful for calling it correctly. Annotations cover the safety profile. Only the undocumented offset/marketId parameters leave a gap.

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 only 25%, so the description carries extra burden. It maps the optional sections values to their payloads (chart history, notices, waiting state, first-mention evidence, workspace wins), which usefully explains the enum. But offset and marketId get no mention anywhere, leaving half the surface documented only by bare types.

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 description states a concrete outcome set: share of tracked AI answers mentioning the brand, the change versus the prior window, new insights since last visit, and first mention. It also differentiates from siblings by name ('parse_next_tasks for what to do', 'parse_evidence for the answers behind an insight'). The core verb is fuzzier than the author intends ('what changed'), but the payload description makes the tool's job unambiguous.

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?

Opens with an explicit trigger ('Use when the user asks how the brand is doing or what is new') and routes onward to parse_next_tasks and parse_evidence. It also covers the degenerate case (comparison window unusable). What's missing is any statement of when NOT to reach for this tool versus siblings like parse_tracking or parse_why.

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