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

With no annotations, the description carries the full behavioral burden and does so exceptionally: cursors are keyed to processing time rather than filing dates, stale cursors restart the window with clamped=true, concurrent updates can shift results across pages, end_of_window=true is terminal, empty results are successful and prove nothing about ingestion health, and fallback_recent is always false. This is exactly the kind of pagination and failure-mode disclosure an agent cannot get from the schema.

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?

It is long but dense, opening with the window definition and field meanings before moving to the caveats, with every sentence carrying operational content. Minor redundancy between the empty-results and fallback_recent notes keeps it just short of maximal.

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?

The tool takes zero required parameters and has an output schema, so the description does not need to enumerate return values, yet it goes further and explains the qualifying-filing field plus cursor and window edge cases. An agent has everything needed to call it, page it, and interpret an empty or clamped response.

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, but the description adds material semantics beyond the schema: cursor and cursor_aevt must be passed together and verbatim, and their ordering follows processing time, not filing dates. It does not add anything for limit or locale beyond what the schema already states.

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 names a specific verb (discover) and resource (events with a linked filing), then pins the scope precisely to a seven-day Beijing calendar window plus an update recency condition, and clarifies what matched_filing, root source_pdf_url, phase, payload and announce_ts each represent. It never names a sibling tool, so the differentiation from scan_recent_events and get_event_with_context is only implied by the window definition.

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?

Explicit when-to-use ('Call this to follow recent disclosures'), explicit when-not ('Do NOT use it for unrestricted history'), and explicit operational procedure: poll from the top, deduplicate event ids, pass both cursor and cursor_aevt verbatim for paging. It also redirects to the company/entity/event route for historical context, which is the closest thing to naming an alternative.

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