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

Annotations already mark this as readOnly, idempotent, openWorld, and non-destructive. The description goes well beyond these by detailing the fan-out to three sources, the GDELT→GNews fallback under rate limiting/5xx, and the USPTO soft-fail until May 2025. It also specifies the return format (structured changes[], total_changes, citation URIs) and the parallel-call behavior, giving the agent full insight into what will happen.

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 and information-rich, front-loaded with user intent and supported by organized details about sources, parameters, and output. It is longer than the calibration examples but every clause contributes (e.g., provider sunset, fallback logic, return shape). The structure flows logically from use-cases to behaviors to parameters, although it could be split into bullet points for even quicker scanning.

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 (three upstream data sources, fallback rules, time-window parsing, structured return), the description covers all critical aspects: sources, fallbacks, soft-fail caveats, parameter syntax, recommended values, Return format, and differentiation from sibling entity_profile. No output schema exists, but the description compensates by naming the return fields and citation URIs. This is complete for an agent to select and invoke correctly.

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 covers all three parameters with descriptions and an enum for type. The description adds concrete usage context: `since` accepts both ISO dates and relative shorthand ("7d", "30d", "3m", "1y") and recommends "30d" or "1m" for typical monitoring. It also clarifies that type only supports "company" and provides example values for ticker/CIK, which is exactly the kind of extra semantic meaning that helps invocation.

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 concrete user intents ("What's new with X" / "latest on Y") and defines the tool as a "change feed for a company in the last N days/weeks/months in ONE parallel call." It specifies the resources (SEC EDGAR, GDELT/GNews, USPTO) and explicitly distinguishes itself from the sibling entity_profile by contrasting the dynamic change feed with a static profile.

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 clear when-to-use guidance through query examples and explicitly names the alternative: "Use entity_profile instead when you want the static profile (filings + fundamentals + LEI + patents) regardless of window." It also discloses provider fallback behavior (GDELT→GNews) and soft-fail conditions (USPTO), helping the agent decide if this tool fits the request.

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