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

With annotations already declaring readOnlyHint and openWorldHint, the description still adds substantial behavioral context: the explicit answer-status values (filing_found, news_halt_no_filing_yet, unexplained_by_primary_sources) and the coverage block let an agent distinguish 'nothing filed' from 'a source failed'. This is exactly the kind of operational transparency that annotations cannot convey.

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 value proposition and scope are front-loaded in the first sentence, followed by the ranked output detail. It is dense and long, but nearly every clause carries specific, non-redundant information; a small amount of the enumeration could be tightened.

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?

There is no output schema, so the description must carry the full burden of describing return values — and it does, covering ranking rationale, per-item fields (time, filing link, rank reason), filing-burst guidance, answer status, and coverage metadata. An agent has everything needed to call and interpret it.

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 description coverage is 100%, so both parameters (ticker, hours) are already documented with examples and bounds. The description only adds that the window is 'adjustable' and reiterates the 48-hour default, adding little beyond the schema — the baseline 3 is appropriate.

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 specific verb and resource — it returns the likely catalysts behind a US stock move, sourced from primary filings — and enumerates exactly what that includes (8-K events, Exhibit 99.1 headlines, offerings, Form 4 insider trades, 13D/13G stakes, halt status). This is far more precise than the bare title and lets an agent distinguish it from sibling tools like trading_halts or company_changes.

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?

It scopes usage clearly ('For a US stock ticker', last 48 hours adjustable) and gives an exclusion ('Facts only: no price data and no buy/sell opinions'), which tells the agent when not to reach for it. However, it never names an alternative sibling (e.g., trading_halts) or states explicitly when another tool should be preferred over this one.

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