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

Annotations already declare the safe-read profile (readOnlyHint, idempotentHint, destructiveHint=false, openWorldHint=false), so the description does not repeat safety claims. Instead it adds real behavioral context: version numbering semantics (1 = first report, higher = restatement), a restated flag on each value object, cursor paging via data.next_cursor, and that this is a 'Metadata call: free on every tier.' Ordering of results is not stated.

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?

Front-loads the core definition, then the item shape, then usage, then paging, cost, and fallback — a sensible priority order. Sentences are dense but each carries information; the only near-boilerplate is the closing request_data pointer, which is still a useful routing instruction.

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?

With annotations, an output schema, and full schema coverage already in place, the description covers the remaining gaps an agent needs: what qualifies as a change, restatement/version semantics, paging, and cost. It leaves result ordering and guidance on far-back `since` values (potential bulk re-reads after mass restatements) unaddressed, which is a minor but real omission for a polling feed.

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 the baseline is 3; the description earns a bump by reinterpreting `since` as a knowledge-interval boundary rather than merely 'known since this instant', which changes how an agent reasons about the cutoff. It also explains `company` in terms of the scoping use case ('scope it to one company') and names the cursor source (data.next_cursor) for `cursor`.

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?

States a specific verb and resource ('List facts') plus the exact scope ('whose knowledge interval opened since a timestamp'), and immediately disambiguates what counts: new periods from fresh filings and restatements of earlier periods. It also positions itself against a non-sibling concept ('the pull twin of the financial_data_updated webhook'), so an agent knows this is a change-feed rather than an event or filing browser.

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?

Gives concrete when-to-use contexts: 'poll it to keep a model, a cache or a watchlist current, or scope it to one company to see what changed in its history.' It also supplies a fallback route ('if a dataset, field, company or analysis you need is missing, call request_data'). It stops short of naming an exclusive when-not or a specific sibling such as company_events to use instead for discrete events.

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