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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses multi-source fan-out (SEC EDGAR, GDELT→GNews fallback, USPTO with a soft-fail note), and specifies the return structure (changes[] grouped by source + total_changes + citation URIs). It also explains the fallback conditions (rate-limited or 5xx) and the API sunset, which are important behavioral traits not captured in 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 description is dense but well-organized, front-loading with query examples before the core definition. The middle section packs source details, fallback behavior, and date formats, and the final sentence provides the sibling-tool pointer. While the initial example list is somewhat redundant, every sentence earns its place given the tool's complexity; a 4 reflects minor excess but strong structure.

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 there is no output schema, the description compensates by specifying the return payload (structured changes[], total_changes, pipeworx:// citation URIs). It also covers edge cases (GDELT→GNews fallback, USPTO soft-fail until reactivated) and clarifies the `since` window formats. For a tool with three required parameters and this complexity, the description is complete enough to guide correct invocation and expectation-setting.

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% with descriptions for all three params. The description adds substantial extra meaning for `since` by giving concrete formats (ISO date or '7d', '30d', '3m', '1y') and a recommendation ('Use 30d or 1m for typical monitoring'), which goes beyond the schema's phrasing. The other parameters are already well-described in the schema, so the description adds marginal but useful context.

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 opens with a list of natural-language query examples and then defines the tool as a 'change feed for a company in the last N days/weeks/months in ONE parallel call.' It explicitly differentiates from the sibling entity_profile by directing users to that tool for static profiles, making the purpose unmistakable.

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 explicitly gives when-to-use cues (queries like 'what's new with X', 'latest on Y') and provides an explicit alternative: 'Use entity_profile instead when you want the static profile...'. It also offers parameter-level guidance, recommending '30d' or '1m' for typical monitoring. This is clear usage guidance with exclusions.

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