A-share filings: reductions, penalties, regulatory letters and stock halts. Source-linked facts.
Scored across 8 tools
Most tools have clearly distinct purposes: get_entity_state folds current entity status, get_event_with_context returns an event timeline, get_filing_parsed extracts filing content, get_related_filings follows citations, list_company_filings lists company filings, and list_coverage describes scope. The main overlap is between scan_recent_events and whats_new, which both surface recent events within a seven-day window, though their descriptions differentiate filters and pagination behavior.
Tool names are consistently snake_case and predominantly follow a verb_noun pattern: get_entity_state, get_event_with_context, get_filing_parsed, get_related_filings, list_company_filings, list_coverage, scan_recent_events. The only outlier is whats_new, which uses an informal phrase rather than a verb_noun structure, but it remains readable.
Eight tools is well within the ideal 3-15 range for a read-only regulatory filings and events server. Each tool covers a distinct retrieval or discovery need, and the set avoids both thinness and bloat.
The surface covers core workflows: coverage inspection, recent event discovery, company filing listing, parsed filing text, citation following, event context, and folded entity state. Minor gaps remain, such as no direct entity/company search by name, no cursor for historical company filings beyond the 50-row limit, and no market-wide historical event scan, but the descriptions make these limits clear and agents can often work around them.
Return what is true RIGHT NOW about one A-share listed company or one shareholder entity, folded from its regulatory filings: pending and executed share-reduction plans, administrative-penalty proceedings, and exchange inquiry letters. Call this when you need the current situation of a specific subject — for example 'is this shareholder still selling', 'is this company under investigation', 'has it replied to the inquiry letter'.
Do NOT call this to find out what happened across the market recently — use scan_recent_events or whats_new for that. Do NOT pass both (code, market) and aent_; pick one addressing mode.
Read the response in this order and stop at the first match: (1) found=false -> we do not cover this security/entity, do not retry; (2) visibility='hidden_unverified' -> the entity exists but its identity is not human-verified, so its name is withheld; query by code+market instead; (3) resolved_as='listed_company' -> your aent_ denoted the company itself and the request was redirected, use the returned code/market; (4) has_events=false -> the security EXISTS but had no covered filings in the covered period (this is the common case, ~85% of valid lookups) — report 'no filings in period', never 'company not found'; (5) companies=[...] -> a shareholder active across one or more companies, read each entry; (6) otherwise the state machines apply to that one company.
Fields that separate 'did not happen' from 'we do not know' are load-bearing: current_holding_reason, window_status ('expired_no_closure' = the plan window lapsed with no closing filing), entity_link, entities_status, plan_pairing ('unresolved' = several open plans and we refuse to guess the pairing), and unclassified_count. Never collapse them into 'nothing there'. Values are objective extractions with a source PDF link; we never rate, score or attribute.
| Name | Required | Description | Default |
|---|---|---|---|
| code | No | Security code, e.g. '000029'. Must be given together with market. | |
| aent_ | No | Opaque entity id taken from a previous response. Never construct or guess one. Mutually exclusive with code/market. | |
| locale | No | Language of human-readable data labels only; errors and this description are always English. | en |
| market | No | One of ['SH', 'SZ', 'BJ']. Required when code is given. |
| Name | Required | Description |
|---|---|---|
| found | Yes | False means we do not have this security/entity at all. |
| reason | No | Present only when found=false: 'unknown_security' or 'unknown_entity'. |
| companies | No | Present for shareholder entities: one entry per company, each carrying the same state machines. An empty list means the entity exists but has no linked filings — not that the person did nothing. |
| disclaimer | Yes | Always present. Objective facts only, no ratings. |
| has_events | No | False means the security EXISTS but has no filings of the covered types in the covered period. This is NOT the same as found=false. |
| visibility | No | Entity exists but its identity is not human-verified; its name and linked filings are withheld. Query by (code, market) instead. |
| resolved_as | No | The aent_ you passed denotes the listed company itself; the request was redirected. Use the returned code/market to attribute this state. |
| coverage_since | No | Earliest filing date we cover. Data before this is absent. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full behavioral burden and does so richly: found=false means do-not-retry, hidden_unverified withholds the name, ~85% of valid lookups return no filings (pre-empting a false 'not found'), and it flags the load-bearing fields (window_status, plan_pairing, unclassified_count) that separate 'did not happen' from 'we do not know'. It also discloses that values are objective extractions with source PDFs and are never rated or scored.
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-loaded with purpose and usage before the response-reading protocol, and every sentence carries real information. It is nonetheless long and the ordered response-interpretation list overlaps with what an output schema could convey, so it is efficient rather than maximally tight.
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?
For a tool whose output schema already exists, the description still supplies everything needed to interpret edge cases: the resolution order, the resolved_as redirect, the common no-events case, and the meaning of the ambiguous fields. Nothing an agent needs to call or correctly read this tool is missing.
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%, so all four parameters are already documented, making 3 the baseline. The description adds enforcement value beyond the schema by restating the mutual exclusivity of (code, market) vs aent_ and the need to pick a single addressing mode, which reduces misuse of the two-mode interface.
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?
Specific verb ('return what is true RIGHT NOW') plus a tightly scoped resource (one A-share listed company or shareholder entity) and a clear delineation from the market-wide siblings. An agent can distinguish this from get_filing_parsed, scan_recent_events, or whats_new without opening a schema.
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?
Explicitly states when to call ('is this shareholder still selling', investigation, inquiry-letter status) and when NOT to call, naming the exact alternatives (scan_recent_events, whats_new) for the market-wide case. It also enforces the addressing-mode rule so the agent cannot pass conflicting parameters.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return one specific filing event together with its full timeline (every stage the case went through, each with its own source PDF) and which subject's state it changed. Call this after another tool handed you an event id and you need the whole thread rather than a one-line summary — for example to see how a penalty case progressed from filing to decision.
Do NOT call this without an event id from a previous response: ids are opaque and cannot be guessed or constructed. Internal database identifiers are rejected.
affects_state lets you jump back to get_entity_state. Its subjects[].aent_ may be null when entity resolution has not run yet or does not apply — in that case use the code and market from the same affects_state, which never depends on entity resolution. If the id is unknown you get found=false, which is an answer, not an error: do not retry.
| Name | Required | Description | Default |
|---|---|---|---|
| aevt | Yes | Opaque event id from a previous response. Must start with 'aevt_'. | |
| locale | No | Language of data labels only. | en |
| Name | Required | Description |
|---|---|---|
| event | No | The event itself, including source_pdf_url. |
| found | Yes | |
| reason | No | |
| timeline | No | Every frame of this case, newest first; each frame carries its own source_pdf_url. |
| disclaimer | Yes | |
| affects_state | No | Which subject's state this changed: {code, market, subjects[]}. Use it to jump back to get_entity_state. Note subjects[].aent_ can be null when entity resolution is pending or not applicable — in that case use code+market, which never depends on entity resolution. |
| coverage_since | No | |
| possible_related_filings | No | Possible links to filings, each with aann_, title, ann_date, relation='possible_relation', reason, evidence_aanns and decided_at. These can change with new evidence and do not establish event identity. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full behavioral burden and does so well: it explains that ids are opaque and must come from a previous response, internal database ids are rejected, unknown ids yield found=false rather than an error, and callers should not retry. It also discloses the timeline/source-PDF behavior and the affected-state linkage.
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 purpose is front-loaded and the guidance is dense rather than padded. The final paragraph contains useful but somewhat output-oriented detail about affects_state and null subjects, which is relevant but slightly less essential given that an output schema exists.
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?
For a no-annotation tool with an output schema, the description is complete enough for correct invocation: it explains when to call, the provenance constraint on the id, invalid-id behavior, and how to use the resulting state linkage. Nothing critical for an agent to call it safely and correctly appears to be missing.
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%, so the schema already documents both parameters. The description adds useful semantic detail for the required aevt parameter, including its provenance, opacity, required prefix, and rejection of internal identifiers; locale is left to the schema.
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: return one specific filing event plus its full timeline, source PDFs, and affected subject state. It clearly distinguishes this from a one-line summary and frames the tool as a follow-up lookup after an event id has been obtained.
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 gives clear when-to-use guidance (after another tool returns an event id and the full thread is needed) and explicit when-not-to-use guidance (do not call without an event id, ids cannot be guessed). It also mentions get_entity_state and a one-line-summary alternative, though it does not differentiate against all relevant sibling tools such as get_filing_parsed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return ONE filing already parsed for you: its available normalised text and its tables as structured cells. Call it after list_company_filings, with the aann_ id that tool returned, when you need what a filing actually says rather than just its title and PDF link.
This is the step your own pipeline would otherwise have to do: a filing PDF is a layout format, not a data format, so pulling clean text and real table cells out of it is where ad-hoc extraction usually goes wrong. Tables come back as rows of cells you can read directly, not as an image or a flattened blob.
It serves ONE filing per call, whose date is at most seven days before the database current date (eight calendar dates including today). Older filings are not gone — the filing itself and its source PDF link stay available from list_company_filings for the company's whole history; only the parsed text is recent-only. When that is why you got nothing, reason says outside_parsed_window, which is a different answer from unknown_filing.
Source coverage is limited: PDFs over 150 pages are parsed only through the first 30 pages; table coverage is limited above 50 pages. Use source links for the complete original. text_chars measures stored text, not source completeness. text_truncated=false or next_text_offset=null does not mean every PDF page was parsed.
Stored text arrives in slices: read text_chars for the stored total and call again with next_text_offset until it is null. Do NOT use this to sweep a company or the market — it takes a single filing id and has no cursor.
Read text_unavailable before trusting the text. Two of its values are properties of the source file — a scan with no text layer, or a font we cannot map to Unicode — and retrying those will not help. A third, parse_failed, means the failure is ours rather than the document's, and asking again later may well work. Either way the source links are still worth opening.
| Name | Required | Description | Default |
|---|---|---|---|
| aann_ | Yes | Opaque filing id from list_company_filings, e.g. aann_Kyw46MM1gCnIaBxA. | |
| text_offset | No | 0-based offset into the filing's full text. Start at 0; then pass next_text_offset from the previous call. |
| Name | Required | Description |
|---|---|---|
| code | No | |
| note | No | |
| text | No | Normalised plain text of this filing, from `text_offset`, at most `limits.parsed_text_chunk_chars` characters per call. |
| aann_ | No | |
| found | Yes | False means either we hold no filing under this id, or the filing is outside the parsed-text window. Read `reason` to tell those apart. |
| title | No | Original Chinese title. Never translated. |
| market | No | |
| reason | No | unknown_filing = no such filing id. outside_parsed_window = the filing exists and its source PDF is still available from list_company_filings, but parsed text is only served for recent filings. |
| tables | No | Tables as cells, in document order: {index, page, n_rows, n_cols, cells, continuation_of}. continuation_of points at the table this one continues from when a table spans pages. Empty list means this filing has no tables. |
| sources | No | Every source link we hold for this filing, best first. Use them to check our text against the original. |
| ann_date | No | Filing date, YYYY-MM-DD. |
| parsed_at | No | When we parsed it. |
| disclaimer | Yes | |
| text_chars | No | Length of stored parsed text, which may cover only part of the PDF. Compare with text_offset + len(text) to see how much is left. |
| table_count | No | |
| text_offset | No | |
| window_days | No | Maximum filing-date age in database calendar days, inclusive of age zero. |
| text_truncated | No | True when more stored text follows. False does not guarantee full PDF coverage. |
| next_text_offset | No | Where to continue, or null at the end of stored text, not necessarily the source PDF. |
| text_unavailable | No | Why the text cannot be used, or null when it can. no_text_layer = the source PDF carries no text layer at all (a scan), so there is nothing to extract. unreadable_font_encoding = it has text, but the PDF embeds a subset font without a Unicode map, so the characters come out as (cid:NNNN) placeholders; the text is still returned, and the numbers and structure may still be readable, but the words are not. Those two are properties of the source file — re-requesting will not help. parse_failed means the failure is OURS, not the document's: we did not parse it successfully, and it is worth asking again later. Check this field rather than testing whether `text` is empty. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations the description carries the full burden, and it delivers: seven-day recency window with reason=outside_parsed_window vs unknown_filing, page-limit parsing caveats, paginated text slices via next_text_offset, and a taxonomy of text_unavailable values including which are retryable. This is unusually rich behavioral disclosure.
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-loaded with the core purpose, then window limits, then caveats, then pagination. Every paragraph carries distinct information, though the seven-day window is explained across three sentences and the piece is on the long side. No filler, but tightening is possible.
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?
An output schema exists, so return values needn't be described, yet the description goes further and covers return-value semantics (text_chars, text_truncated, next_text_offset, text_unavailable, reason) plus recency and coverage limits. Nothing an agent needs to call this correctly is missing.
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 already 100%, so the baseline is 3; the description adds value by specifying the aann_ id's provenance (must come from list_company_filings) and the pagination contract for text_offset/next_text_offset. It stops short of naming the parameter text_offset explicitly, but the semantics are clear from 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?
States a specific verb and resource ('Return ONE filing already parsed... normalised text and tables as structured cells') and distinguishes itself from list_company_filings by contrast (what a filing says vs its title and PDF link). An agent can tell it apart from siblings without opening any schema.
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: after list_company_filings, using the aann_ id it returned, when you need filing content. Explicit when-not: 'Do NOT use this to sweep a company or the market — it takes a single filing id and has no cursor.' Also routes to alternatives (source links, list_company_filings) for older filings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the most recent filings of ONE listed company: title, date, a direct link to the source PDF, and — where we have it — the structured extraction that filing produced. Call this to answer 'what has this company filed lately' and 'give me the original document', which is what most callers actually want before any analysis.
This is the widest view we offer: it covers EVERY filing we hold for the company, not just the ones we extract.
Do NOT use it to ask what a case or a plan currently amounts to — it returns documents in date order, not folded state; get_entity_state does that. Do NOT use it to sweep the market for one filing type across companies (scan_recent_events), and do NOT page through it for bulk export: it has no cursor and stops at 50 rows per call.
Read with_extraction: most filings have none, because we extract a focused set of filing types — call list_coverage for the ones we support today. extraction: null means we have not extracted that filing — it never means the filing is unimportant. When extraction is present, pass its aevt_ to get_event_with_context for the full case timeline.
Titles are returned in the original Chinese, unchanged — translating a filing title would be rewriting the fact. There is no cursor: this is a recent-filings view, not a bulk export.
published_at is null for most filings: it is present only when the source itself supplied a timestamp, and we do not substitute our own collection time for it. Use ann_date, which is always present, for the filing date.
| Name | Required | Description | Default |
|---|---|---|---|
| code | Yes | Six-digit A-share ticker, e.g. 000029. | |
| limit | No | 1..50. Default 20. | |
| market | Yes | Which exchange the ticker belongs to. |
| Name | Required | Description |
|---|---|---|
| found | Yes | False means we have no such security on file at all — not that it filed nothing. Check this before reading filings. |
| reason | No | |
| filings | No | Newest first. One entry per filing, already merged across the five sources it may appear in; `sources` lists every link we hold for it. |
| returned | No | |
| disclaimer | Yes | |
| more_available | No | True when older filings exist beyond what came back. There is no cursor; this tool is a recent-filings view, not a bulk export. |
| with_extraction | No | How many of the returned filings carry structured extraction. This is normally a small fraction — call list_coverage for the filing types we support today. A zero here means 'not extracted yet', never 'nothing happened'. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and delivers: no cursor, hard 50-row cap, `extraction: null` meaning (not a quality signal), and the fact that most filings have no extraction. It also discloses preservation quirks — titles kept in original Chinese, `published_at` null unless the source supplied it — which are non-obvious behaviors an agent would otherwise misread.
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?
Purpose and primary use case are front-loaded, and most sentences carry distinct operational facts (null semantics, chaining, title language). It loses a point for mild redundancy: the 'no cursor / not a bulk export' constraint is stated twice, in the exclusion paragraph and again at the end.
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?
An output schema exists, so return values needn't be re-explained, and the description still covers the edge cases that matter: null extraction, null published_at, and the ann_date fallback. Nothing an agent needs to call this correctly is missing.
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%, so code/market/limit syntax is already documented. The description adds behavioral meaning to `limit` by tying it to the 'no cursor, stops at 50 rows' hard ceiling, which the schema's maximum alone doesn't convey. It does not, however, explain market selection or code format beyond the schema.
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 the most recent filings of ONE listed company') and enumerates exactly what each row carries (title, date, PDF link, extraction). It explicitly differentiates itself from siblings like get_entity_state and scan_recent_events, so an agent can route without opening any schema.
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 caller intents ('what has this company filed lately', 'give me the original document') plus three explicit exclusions naming the correct alternative for each (get_entity_state for folded state, scan_recent_events for cross-company sweeps, no bulk export). It also instructs how to chain into get_event_with_context via aevt_.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return exactly what this server covers and the limits it enforces. Call this first, or whenever a query comes back empty and you want to know whether the filing type is even in scope, before concluding the data is incomplete.
It takes no arguments and does not touch the database, so it works even when everything else is degraded. Coverage is deliberately narrow and expanding over time; the event_types list in the response is the authoritative answer, and stating it plainly is preferable to letting you discover the boundary by trial and error. Read limits instead of probing for the caps.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| limits | Yes | Server-side caps. Read them instead of discovering them by hitting walls. |
| markets | Yes | |
| expanding | Yes | True: more filing types are being added over time. |
| disclaimer | Yes | |
| event_types | Yes |
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 well: it takes no arguments, does not touch the database, works when other capabilities are degraded, and notes that coverage is narrow and expanding. It also identifies `event_types` as authoritative and warns against trial-and-error boundary discovery.
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 front-loaded with purpose and usage, and each sentence adds operational value: when to call, why it is robust, coverage caveats, and how to interpret the response. There is no filler.
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?
For a zero-argument coverage/limits tool with an output schema, the description is complete enough. It explains the tool's behavior, its reliability characteristics, and the semantic importance of `event_types` and `limits` without needing to duplicate the output schema.
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 tool has zero parameters, so the baseline is 4. The description explicitly notes that it takes no arguments, which is accurate but largely redundant with the empty schema.
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 what the server covers and the limits it enforces. This is clearly a meta/coverage tool, distinct from the filing and event retrieval siblings, and an agent can identify its role immediately.
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 gives explicit call timing: call first, or whenever a query comes back empty, to determine whether a filing type is in scope before concluding data is incomplete. It also directs the agent to read `limits` rather than probing for caps.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Discover one filing event type across companies using linked filing dates within the last seven Beijing calendar days including today. Dates omitted use this whole window; one omitted end uses the corresponding allowed boundary. Partial overlap is clamped; reversed or wholly outside dates are errors. effective_since/effective_until report the actual dates. A new filing mentioning an old case qualifies without claiming new case progress.
Call this for market-wide recent filings. Do NOT use it for a full company state. Each event appears once, newest matching filing date first. matched_filing contains the qualifying filing id, date and its own PDF link; root source_pdf_url and phase describe current event context, not historical state at the selected date. phase filters current stage. At most 100 events per page. Pass cursor to continue; only non-null cursor means another page. Omit dates/phase on continuation or repeat their effective values; changing filters requires a fresh call. event_type must remain the same; limit/locale may change. matched_count counts the whole frozen window, so truncated can remain true on the last page. Windows that move outside the allowed dates fail with cursor_expired; restart without cursor. Results are a dynamic view, not a snapshot: new filings, stage changes or merges can move events between pages. Poll from the first page and deduplicate by aevt_. Empty results mean no matches after this position, not an empty database. coverage_since is data coverage, not permission to scan history. For a known company/entity use get_entity_state; for a known event use get_event_with_context.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | 1..100. Default 50. | |
| phase | No | Restrict to one stage of the case. Must belong to the chosen event_type; the error message lists the valid values. | |
| since | No | Inclusive start date, YYYY-MM-DD. | |
| until | No | Inclusive end date, YYYY-MM-DD (the whole day counts). | |
| cursor | No | Return the previous cursor unchanged to continue within its frozen dates. | |
| locale | No | Language of data labels only. | en |
| event_type | Yes | Which filing type to scan. Call list_coverage for the current scope. |
| Name | Required | Description |
|---|---|---|
| cursor | Yes | Continuation within the frozen effective dates; null means no next page. An expired window is an error: restart without cursor. |
| events | Yes | |
| truncated | Yes | True when the whole-window count exceeds this page's size, even on the last page. Only a non-null cursor means another page exists. |
| disclaimer | Yes | |
| matched_count | Yes | How many events matched in the whole window, before the limit was applied. |
| coverage_since | No | |
| window_clamped | Yes | Requested dates were intersected with the allowed recent window. |
| effective_since | Yes | Inclusive matching filing start date actually queried, YYYY-MM-DD. |
| effective_until | Yes | Inclusive matching filing end date actually queried, YYYY-MM-DD. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full behavioral burden and does so unusually well: it discloses cursor expiry behavior, that only a non-null cursor signals another page, that truncated can remain true on the last page, that results are a dynamic view rather than a snapshot, deduplication by aevt_, and that empty results mean no matches at this position rather than an empty database. It also explains the distinction between matched_filing (historical) and root-level source_pdf_url/phase (current context). Auth and rate limits are the only unmentioned traits.
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-loaded with the core purpose and scope, then ordered into usage, window semantics, pagination, and routing. The text is dense and long, but nearly every clause carries operational information (clamping, cursor expiry, dedup key). A few sentences could be tightened, but nothing is padding.
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?
For a 7-parameter, paginated, filter-bound tool with no annotations, the description covers purpose, window rules, error conditions, pagination lifecycle, result dynamism, and sibling routing. An output schema exists but the description still pre-empts the most confusing return fields, so an agent has everything needed to call and iterate 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?
Schema description coverage is 100%, so the baseline is 3, but the description adds real semantics the schema lacks: default window behavior when since/until are omitted, the one-sided-omission boundary rule, clamping on partial overlap, and errors for reversed or out-of-range dates, plus the effective dates returned. It also clarifies that event_type must stay fixed across pagination while limit/locale may change. Only the phase/cursor interplay is left mostly to the schema.
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 precise verb and resource: 'Discover one filing event type across companies using linked filing dates within the last seven Beijing calendar days'. It also distinguishes itself from siblings by scope (market-wide recent filings vs. full company state) and explicitly names get_entity_state and get_event_with_context as the alternatives. An agent can route correctly without opening any schema.
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 for market-wide recent filings'), explicit when-not ('Do NOT use it for a full company state'), and named alternatives for both the known-company and known-event cases. The continuation rules (omit dates/phase or repeat effective values; changing filters requires a fresh call) further disambiguate correct invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Discover events with a linked filing dated within the last seven Beijing calendar days including today, and updated in the last seven days. A new filing may mention an old case; this does not imply new case progress. matched_filing gives the filing date and PDF that qualified the event; root source_pdf_url, phase and payload describe current event context. announce_ts remains the original first disclosure.
Call this to follow recent disclosures. Do NOT use it for unrestricted history. Poll from the top and deduplicate event ids. To page backwards pass both cursor and cursor_aevt verbatim; these use processing time, not filing dates. Old cursors restart at the current window with clamped=true. Concurrent updates can move results between pages. end_of_window=true means no further results, including an empty first call; empty results are successful and do not prove the database is empty or ingestion is healthy. fallback_recent is always false: history never fills an empty window. Use a known company, entity or event for historical context.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | 1..100. Default 50. | |
| cursor | No | The `cursor` value from a previous response, passed back verbatim. | |
| locale | No | Language of data labels only. | en |
| cursor_aevt | No | The `cursor_aevt` value from the same response. Required together with cursor for correct paging. |
| Name | Required | Description |
|---|---|---|
| cursor | Yes | Pass back verbatim as `cursor` together with `cursor_aevt` to get the next page. Null means there is no next page. Do not construct it yourself. |
| events | Yes | |
| clamped | Yes | Your cursor was older than the lookback window, so paging restarted from the top of the window. |
| disclaimer | Yes | |
| cursor_aevt | Yes | Second half of the cursor. Both halves are required to page correctly; passing only `cursor` may repeat events sharing the same timestamp. |
| end_of_window | Yes | No more results in the allowed window for this request, including an empty first call. Events is empty and both cursor fields are null; this does not imply an empty database. |
| coverage_since | No | |
| fallback_recent | Yes | Always false: an empty window never returns older events. |
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.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
get_entity_stateget_event_with_contextget_filing_parsedget_related_filingslist_company_filingslist_coveragescan_recent_eventswhats_newInsider, Congress, 13F and federal contract filings for US stocks, each linked to its source.
Indian stocks: NSE/BSE filings read by AI with price reactions, fundamentals, IPOs and FPI flows.
US insider trades, 13F, 13D/G, Form 144, politician trades, financials, shorts; Taiwan stocks. Free.
Korean equities in English: DART filings, activist & foreign-holder classification, KRX news.
Add one secure layer between your agents and this server.