MCP_TOOLS.md

MCP tool contract

The public MCP endpoint is https://mzx-dilutionrisk-mcp.hf.space/gradio_api/mcp/. It exposes exactly seven read-only tools under the names below; the Space slug is not added to their public names:

Tool	Purpose	Maximum response scope
search_companies	Search ASX companies and screener metrics	25 companies per cursor page
get_company_snapshot	Retrieve one exact ticker snapshot	One company
search_documents	Full-text filing search with ranked snippets	25 documents per cursor page; 600-character snippets
get_document_metadata	Retrieve one canonical document	One document
get_document_markdown	Retrieve a published HF markdown excerpt	12,000 characters
get_dilution_instruments	Retrieve dilutive instruments for one ticker	100 instruments
get_dataset_status	Report service and Dataset provenance	One status record

Every successful response includes the exact immutable Dataset revision, the manifest publication timestamp, the ASX source watermark and a revision-pinned Dataset citation. Filing results also include canonical ASX source links. Instrument results carry the canonical document identities that support them. Search responses return an opaque, revision-aware next_cursor when another bounded page exists; cursors cannot be reused for a changed query or Dataset revision.

The markdown tool only reads artifact keys published under artifacts/v1/asx/ in the public mzx/dilutionrisk-public HF Bucket. It does not fall back to GCS, follow caller-supplied URLs or return an entire document.

No MCP tool accepts arbitrary SQL, URLs or storage paths. The service cannot write data, mutate the publishing pipeline, list storage or expose credentials and worker state. Automated extraction can contain errors; verify research against the cited issuer announcement. This is not financial advice.

Oversized values are rejected with clear tool errors instead of being silently truncated. Search accepts at most 120 characters and 12 terms. Citation hosts and public markdown artifact keys are fail-closed allowlists; service-level request and concurrency budgets are described in SECURITY.md.