kapmcp

Financial statements (normalised)

get_financials

Read-onlyIdempotent

Fetch income statement, balance sheet, and cash flow for BIST stocks from Yahoo Finance or official KAP filings. Use ticker for time series or disclosure_id for exact reported figures.

Instructions

Income statement, balance sheet and cash flow in one normalised schema (revenue, gross_profit, operating_profit, ebitda, net_income, total_assets, cash, financial_debt, equity, operating/investing/financing cash flow …) with the source line/taxonomy name per field and the reporting currency. Two sources: ticker → Yahoo Finance time series (several periods); disclosure_id → the official KAP filing (source: kap, exact figures, labels '(3M)' quarter vs '(YTD)' cumulative). Find FR ids with search_disclosures(tickers=[…], disclosure_type='FR').

Input Schema

TableJSON Schema

Name	Required	Description	Default
`fields`	No	Subset of normalised fields; default all (see get_reference_codes.financial_fields)
`ticker`	No	BIST ticker, e.g. THYAO — time series from Yahoo Finance
`periods`	No
`frequency`	No	Yahoo series only	quarterly
`disclosure_id`	No	A KAP financial-report (FR) disclosure id — the official filing parsed from KAP's XBRL data (current period + prior-year comparatives)

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

Behavior4/5

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

Annotations already mark this as read-only, idempotent, and non-destructive. The description adds valuable behavioral context beyond annotations: it states that each field includes source line/taxonomy name, reporting currency, and that KAP filings provide exact figures with quarter vs. cumulative labels. This helps set expectations about data provenance and format without contradicting annotations.

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?

The description is dense but every part earns its place: what is returned, key fields, source metadata, the two invocation modes, and how to find FR ids. Even though it is a single paragraph, it avoids fluff and front-loads the core purpose before source-specific 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?

Given the tool's complexity (two data sources, many selectable fields, an output schema, and rich annotations), the description is thorough enough for an agent to decide when to call it and how to construct a valid request. The only minor omission is explicit comparison to get_financial_ratios, but that is not necessary for correct invocation.

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 80% schema coverage, the schema already documents most parameters. The description adds meaning beyond that by explaining the two mutually relevant parameter families (ticker vs. disclosure_id), the source difference, and the field source/taxonomy metadata. It also directs the agent to search_disclosures for constructing valid disclosure_id values.

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 clearly identifies what the tool returns: income statement, balance sheet, and cash flow data in one normalized schema, with a concrete list of fields. It also distinguishes the two data sources (ticker vs. disclosure_id), which helps differentiate usage from related sibling tools like get_financial_ratios or compare_financials.

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 explains the two invocation modes: ticker for Yahoo Finance time series and disclosure_id for official KAP filings. It also points the agent to search_disclosures with a specific pattern to find FR ids, giving clear contextual guidance. It stops short of naming alternatives to avoid, but the source-selection guidance is strong.

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