mcp-hkex-filing

search_filings

Read-onlyIdempotent

Find HKEX filings by ticker, type, status, date range, or title text. Filter and page through results to locate specific filings before retrieving full documents.

Instructions

Use this to find filings by ticker, type, status, date range, or title text.

Prefer search_documents for full-text search over extracted text, and get_filing or get_filings to read filings whose ids you already have. Filters are optional and combinable; comma-separate a value to match several (e.g. filing_type="Annual Report,Dividend"). document_status accepts the real statuses plus unprocessed (no document yet). document_type accepts pdf, html, xlsx, docx, or unknown, and source is a free-text origin like HKEx. date_from/date_to are YYYY-MM-DD inclusive. order_by is one of filing_date_desc (default), filing_date_asc, title_asc, filing_id_asc. Returns paged filing rows (no document text); call get_filing for the document. This tool is read-only.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`offset`	No	Zero-based offset for paging.
`source`	No	Source of the filing, e.g. HKEx.
`ticker`	No	Company ticker filter, e.g. 0700.HK; comma-separate to match several.
`date_to`	No	Latest filing date, YYYY-MM-DD inclusive.
`exchange`	No	Exchange code, e.g. HK.
`order_by`	No	Sort order of the result.	filing_date_desc
`date_from`	No	Earliest filing date, YYYY-MM-DD inclusive.
`page_size`	No	Maximum filings to return (1..100).
`stock_code`	No	Numeric stock code filter, e.g. 00700; comma-separate to match several.
`filing_type`	No	Filing type(s), e.g. 'Annual Report'; comma-separate to match several.
`title_query`	No	Case-insensitive substring matched against the filing title.
`document_type`	No	Document type: pdf, html, xlsx, docx, or unknown.
`document_status`	No	Document status(es): processed, skipped, failed, or unprocessed; comma-separate to match several.
`filing_category`	No	Filing category(ies), e.g. LISTED_COMPANY; comma-separate to match several.
`referenced_ticker`	No	Ticker referenced by the filing (graph edge).

Output Schema

TableJSON Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedv0.1.3Sep 24, 2026

addedInput schema / properties / document_type

Added value: +{
+  "default": "",
+  "description": "Document type: pdf, html, xlsx, docx, or unknown.",
+  "title": "Document Type",
+  "type": "string"
+}

addedInput schema / properties / source

Added value: +{
+  "default": "",
+  "description": "Source of the filing, e.g. HKEx.",
+  "title": "Source",
+  "type": "string"
+}

First observedSep 23, 2026

TDQS

A4.6/5.0

Behavior4/5

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered structurally. The description adds genuine value by disclosing return behavior ('Returns paged filing rows (no document text)') and explaining the 'unprocessed' status edge case — details an agent could not infer from annotations or schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Purpose and routing are front-loaded in the first two sentences, and the filter-semantics block is dense but every sentence earns its place for a 15-parameter, all-optional tool. It is a long single paragraph and could benefit from light grouping, but there is no fluff or repetition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a complex search tool with 15 optional parameters, the description covers everything needed for correct invocation: purpose, sibling routing, filter combinability, value domains, date semantics, sort options, return behavior, and read-only confirmation. Output schema covers return fields and annotations cover safety, so no critical gap remains.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 100% schema description coverage, baseline is 3, but the description adds meaning above that: it generalizes comma-separation across filters with a concrete example (filing_type="Annual Report,Dividend"), clarifies date formats as YYYY-MM-DD inclusive, enumerates order_by values with the default, and defines document_status's special 'unprocessed' value.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The opening sentence states a specific verb plus resource and scope: 'find filings by ticker, type, status, date range, or title text.' It differentiates from siblings by naming what it is not — search_documents (full-text over extracted text) and get_filing/get_filings (by known ids) — so 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.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit routing: 'Prefer search_documents for full-text search over extracted text, and get_filing or get_filings to read filings whose ids you already have.' It also states that filters are optional and combinable, covering both when to use and when not to use this tool.

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

Deploy Server