kapmcp

Search disclosures

search_disclosures

Read-onlyIdempotent

Search Borsa Istanbul KAP disclosures by company, keyword, type, or date range to locate financial reports, material events, and regulatory announcements.

Instructions

Search KAP disclosures by company, keywords, type/template and date range, newest first, with cursor paging. Covers: latest disclosures, a company's disclosures over a period, everything since an id (monitoring), topic hunts like 'sözleşme' or 'bedelsiz' across companies (use query_scope='content' for subject/summary matching). The KAP API only pages by index, so wide ranges scan many windows: check scan_complete; if false, continue with cursor or raise max_pages. Items carry disclosure_id, templates (KAP's topic template codes), ticker, company name and source_url.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`limit`	No
`order`	No	desc = newest first	desc
`query`	No	Keywords (any word matches, Turkish-insensitive). With query_scope='metadata' they match the sender name and the disclosure template name (e.g. 'New Business Relation', 'Valuation Report'); with 'content' also the subject/summary of every scanned item (one KAP call per item, slower).
`cursor`	No	`next_cursor` from a previous call to continue paging
`tickers`	No	Restrict to these BIST tickers (e.g. ['THYAO','PGSUS'])
`end_date`	No	YYYY-MM-DD (inclusive)
`since_id`	No	Only disclosures newer than this id (polling). Overrides dates.
`max_pages`	No	Cap on 50-item index windows scanned (default 40, server max applies). Company/keyword filters on long ranges need more.
`company_id`	No	Restrict to one KAP member id
`start_date`	No	YYYY-MM-DD (inclusive). Resolved to an index via binary search.
`query_scope`	No	Where keywords are matched; see `query`	metadata
`disclosure_type`	No	FR financial report, ODA material event, DG other, DUY regulator, FON fund, CA corporate action
`include_details`	No	Also fetch published_at, subject, summary, attachments per item (one KAP call each)
`disclosure_class`	No

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.2.0Sep 21, 2026

TDQS

A4.5/5.0

Behavior5/5

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

Beyond the annotations, the description discloses non-obvious behavior: the KAP API pages by index, wide ranges require checking scan_complete, and callers must continue with cursor or raise max_pages. It also explains the difference between metadata and content scanning and notes the per-item cost of content matching, which is valuable operational context.

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

Conciseness5/5

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

Three sentences deliver a dense but efficient overview: core search capability, use cases, and a crucial paging caveat. Every sentence earns its place, and the main purpose is front-loaded before operational details.

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 14-parameter tool, the description is remarkably complete alongside the rich schema and output schema. It covers what the tool searches, key use cases, paging behavior, performance caveats, and the shape of returned items, so an agent has enough context to invoke and interpret results correctly.

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

Parameters3/5

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

Schema description coverage is 86%, so parameter semantics are already well documented. The description adds little beyond the schema: query_scope='content' is already explained in the query parameter, and since_id is already described as polling in the schema. It does not materially deepen parameter understanding, so the baseline of 3 is appropriate.

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 description names a specific verb and resource—'Search KAP disclosures'—and immediately enumerates the filter dimensions and supported use cases. Its scope is precise enough to distinguish it from sibling tools like get_disclosure or search_documents, and the mention of monitoring by since_id and content-scoped keyword hunts gives it a clear identity.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

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

The description explicitly lists when the tool is appropriate: latest disclosures, a company's disclosures over a period, monitoring via since_id, and cross-company topic searches. It does not name alternatives or exclusions, but the use-case coverage is clear and actionable.

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