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

Beyond the readOnlyHint, openWorldHint, and idempotentHint annotations, the description discloses behavioral details like single parallel fan-out across SEC, GDELT/GNews, and USPTO; fallback logic; soft-failure due to API sunset; and the return format (changes[], total_changes, citation URIs). This is rich, non-obvious context that annotations alone do not provide.

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 contributes value: use cases, source fan-out, fallback, parameter format, output structure, and alternative tool. It is appropriately structured and front-loaded, though slightly long; the concentration of information could benefit from a brief separation of concerns, but it remains efficient.

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 (multiple data sources, fallbacks, date parsing) and the absence of an output schema, the description is remarkably complete. It explains the return structure, source-specific behaviors, fallback triggers, and parameter formats, leaving minimal gaps for an agent to resolve.

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 schema covers 100% of parameters, but the description adds meaningful semantics for 'since' by providing ISO date and relative shorthand examples ('7d', '30d', '3m', '1y') plus a recommendation ('Use 30d or 1m for typical monitoring'). It does not additionally elaborate on 'type' or 'value' beyond the schema, but the added since guidance moves it above the high-coverage baseline.

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 clearly identifies the tool as a 'change feed for a company in the last N days/weeks/months', with specific use-case examples like 'What's new with X' and 'latest on Y'. It also explicitly distinguishes itself from entity_profile ('Use entity_profile instead when you want the static profile'), setting it apart from at least one sibling and giving it a clear scope.

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 provides explicit when-to-use guidance through example queries, and explicitly names an alternative (entity_profile) for different needs. It also discloses fallback behavior (GDELT preferred, GNews when rate-limited or 5xx, USPTO soft-fail), which helps the agent make informed invocation decisions.

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