ib-gateway-mcp

Fundamental report

get_fundamental_data

Read-only

Fetch a stock's Refinitiv fundamentals report as XML, covering key ratios, financial statements, and analyst estimates. Resolve the contract by symbol or con_id to get the data.

Instructions

Fetch a Refinitiv fundamentals report for a stock, as XML.

Deprecated by IBKR: reqFundamentalData was removed in TWS API 10.50. It still works on
IB Gateway stable (10.45); newer gateways may refuse it. Stocks only (sec_type STK).
Needs the Refinitiv (Reuters) fundamentals data subscription on the IBKR login.
Whitespace between XML tags is removed; long reports are cut at max_chars (default
50000, max 200000) with truncated=true, so prefer ReportSnapshot or ReportsFinSummary
over the large statement and ownership reports.
Errors: not_found (unknown stock, or IBKR has no such report for it, error
430), ambiguous_contract (give primary_exchange or con_id), ib_api_error 10358 (no
fundamentals subscription), invalid_request (not a stock), request_timeout (a newer
gateway may not answer at all). For key ratios without this report, use
subscribe_quotes with the fundamental_ratios generic tick.

Input Schema

TableJSON Schema

Name	Required	Description
`contract`	Yes	The instrument. A con_id alone is unambiguous; otherwise give symbol and sec_type, plus expiry, strike and right for options.
`max_chars`	No	Longest XML report to return, in characters (at most 200,000); a longer report is cut and truncated is true.
`report_type`	Yes	ReportSnapshot: company overview, key ratios, forecast summary. ReportsFinSummary: per-period EPS, revenue, dividends. ReportsFinStatements: income statement, balance sheet, cash flow (large). ReportsOwnership: holders (large). RESC: analyst estimates. CalendarReport: company calendar (often unavailable).

Output Schema

TableJSON Schema

Name	Required	Description
`xml`	Yes	The report as XML (whitespace between tags removed). Not well-formed when truncated is true.
`contract`	Yes	The stock the report is about.
`truncated`	No	True when the result was cut to the limit.
`report_type`	Yes	The report type that was requested.
`total_chars`	Yes	Length of the whole report before truncation.

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Sep 23, 2026

TDQS

A4.9/5.0

Behavior5/5

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

Discloses several non-obvious behaviors beyond the readOnlyHint annotation: deprecation and gateway compatibility, whitespace removal, truncation at max_chars with truncated=true, and a full error taxonomy including ib_api_error 10358 and request_timeout. This is rich behavioral context the annotations alone do not provide.

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 long but every sentence carries load: core purpose first, then deprecation, subscription requirement, output behavior, error handling, and alternative tool. The structure is logical and front-loaded, and no sentence is filler.

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, deprecated, subscription-gated tool, the description covers return format, truncation, error conditions, prerequisites, and alternatives. Combined with the rich input schema and output schema, an agent has everything needed to call this correctly and handle failures.

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?

Schema coverage is 100%, but the description adds real parameter-level value: it explains max_chars truncation behavior and default/max values, recommends smaller report types in relation to that limit, and tells the agent to resolve ambiguous_contract by supplying primary_exchange or con_id. This goes beyond what the schema states, though the schema already documents the parameters well.

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?

Opens with a specific verb-resource pair: 'Fetch a Refinitiv fundamentals report for a stock, as XML.' It explicitly names the data source (Refinitiv), the scope (stocks), and the output format (XML), and clarifies it is a read-only report tool, distinct from the many historical/subscription siblings.

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?

The description gives explicit when/when-not guidance: stocks only (sec_type STK), requires the Refinitiv subscription, is deprecated on newer gateways, and for key ratios recommends subscribe_quotes with fundamental_ratios instead. It even advises preferring ReportSnapshot or ReportsFinSummary over the large report types, giving an agent actionable selection criteria.

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

Deploy Server