ib-gateway-mcp

Price histogram

get_histogram

Read-only

Retrieve trading volume distribution across price levels for a contract and period to identify support, resistance, and value areas.

Instructions

Return how trading volume was distributed over price levels during a period.

Each entry is a price and IBKR's count (traded volume) at that price, sorted by
price. Useful for volume-at-price, support/resistance and value-area questions.
Default limit 200 price levels, at most 1000; when there are more, the busiest levels
are kept and `truncated` is true. Needs market-data permissions for the instrument.

Errors: not_found (no data for the period), invalid_request (bad period).

Input Schema

TableJSON Schema

Name	Required	Description	Default
`limit`	No	Maximum number of items to return. Omit for the tool's default; larger values are capped. The result's truncated flag says whether more were available.
`period`	No	Look-back period: '<n> days\|weeks\|months\|years', e.g. '3 days', '1 week', '1 month'.	1 week
`use_rth`	No	True: regular trading hours only. False: include pre-market, after-hours and overnight data.
`contract`	Yes	The instrument. A con_id alone is unambiguous; otherwise give symbol and sec_type, plus expiry, strike and right for options.

Output Schema

TableJSON Schema

Name	Required	Description
`total`	Yes	How many price levels IBKR returned before the limit.
`period`	Yes	The period sent to IBKR, e.g. '1 week'.
`entries`	Yes	Sorted by price, lowest first. When truncated, the busiest price levels (highest count) are the ones kept.
`use_rth`	Yes
`contract`	Yes
`truncated`	No	True when the result was cut to the limit.

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Sep 23, 2026

TDQS

A4.7/5.0

Behavior5/5

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

The annotations only provide readOnlyHint=true, but the description goes far beyond: it discloses the default limit (200), maximum (1000), truncation behavior (busiest levels kept, `truncated` flag), the market-data permission requirement, and the possible error codes. This fully enriches the agent's understanding of the tool's behavior.

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?

Four sentences, each with a distinct job: purpose, output format and use cases, limits/truncation/permissions, and errors. No filler; the core purpose is front-loaded.

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?

With an output schema present and all parameters already well documented, the description covers all additional behavioral context an agent needs: truncation semantics, permissions, and error conditions. Nothing necessary for correct invocation is missing.

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%, giving a baseline of 3. The description adds meaningful value by specifying the default limit (200), the absolute cap (1000), and the 'busiest levels are kept' truncation behavior, which the schema leaves unspecified.

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?

States a specific verb and resource: 'Return how trading volume was distributed over price levels during a period.' The description's focus on price-level volume counts distinguishes it from all sibling data tools, such as get_historical_bars or get_historical_ticks, even without naming them.

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?

Explicitly names three use cases: 'volume-at-price, support/resistance and value-area questions.' This gives an agent clear signals about when to select this tool, though it does not mention alternatives or specify when not to use it.

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

Deploy Server