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

Beyond annotations (readOnlyHint, idempotentHint, etc.), the description discloses the deduplication behavior (many articles collapsed into one event), return fields (corroboration count, confidence score, sources list, url), the nature of the confidence score (0-1, 1.0 = fully corroborated), and the corpus scope (260+ global outlets, five-year archive, tier-dependent history). It also flags the raw recency feed's noise issue and advises on how to filter it. These behavioral details far exceed what annotations provide and are directly actionable.

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 description is dense but every sentence earns its place: the first sentence states the action and resource, the second defines return values, then usage guidance, anti-pattern warning, and scope. It front-loads the core purpose and then layers practical advice. There is no filler or redundancy; the length is justified by the tool's complexity and the need to prevent common misuses.

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?

Given the tool's complexity (8 parameters, deduplication, corroboration scoring, multiple use cases), the description covers all critical aspects: what it returns, how to interpret confidence/corroboration, when to use or avoid alternatives, how to filter for high signal, and the corpus scope. With no output schema, it still describes the key return fields. An agent could call this correctly without additional information.

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?

The input schema already documents all 8 parameters with good descriptions, so baseline is 3. The description adds valuable usage context beyond the schema: it explains that min_sources should be 2-3 for high-signal asks, that semantic requires q and is better for concepts, and interprets what the returned fields mean. This enriches parameter understanding, especially for min_sources and semantic, though it doesn't add syntax-level detail for every param. That raises it to a 4.

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 precise action: 'Query the deduped news event graph by theme, source, category and time window.' It clearly explains the core resource (deduped event graph vs. raw articles) and differentiates from siblings by calling itself 'the primary tool' and explicitly warning against calling get_event per item. This gives an agent unambiguous understanding of what the tool does and how it differs from search_articles and get_event.

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 explicit when-to-use guidance: 'prefer it over raw articles' for event-level questions, and instructs to pass min_sources: 2 or 3 for 'headlines, briefings, or what's happening asks.' It also states when NOT to use it: 'do NOT call get_event per item or re-verify counts (only drill in when the user wants EVERY outlet's link for one story).' These usage directives are concrete and unambiguous, leaving no doubt about selection criteria.

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