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`](SECURITY.md).