ib-gateway-mcp

Historical ticks

get_historical_ticks

Read-only

Fetch individual historical trades, quote changes, or midpoints (time and sales) for a contract. Page with start or end timestamps to retrieve up to 1000 ticks per request until the range is covered.

Instructions

Return individual historical trades, quote changes or midpoints (time and sales).

Give exactly one of `start` (ticks after it) or `end` (ticks before it). IBKR sends
at most 1000 ticks per request, with one-second timestamps, and may add a few to
finish the last second. When `truncated` is true there are probably more: page on
with start set to the last tick's time (or end set to the first tick's time); ticks
in that same second can repeat.

Needs market-data permissions for the instrument. Paced like small bars (about 60
requests per 10 minutes; BID_ASK counts double), so prefer get_historical_bars for
anything longer than minutes of activity.

Errors: not_found (no ticks in the range), invalid_request (both or neither
of start/end), rate_limit, ib_api_error 162 (pacing, permissions).

Input Schema

TableJSON Schema

Name	Required	Description	Default
`end`	No	Return the ticks up to this time (ISO 8601; no offset means UTC).
`count`	No	How many ticks, 1-1000 (IBKR's maximum).
`start`	No	Return ticks from this time on (ISO 8601; no offset means UTC). Give exactly one of start and end.
`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.
`ignore_size`	No	BID_ASK only: skip ticks where only the sizes changed.
`what_to_show`	No	TRADES (price, size, exchange, conditions), BID_ASK (bid/ask and sizes; counts double for pacing) or MIDPOINT.	TRADES

Output Schema

TableJSON Schema

Name	Required	Description
`end`	No	Requested end (UTC), if given.
`count`	Yes	How many ticks were requested.
`start`	No	Requested start (UTC), if given.
`ticks`	Yes
`use_rth`	Yes
`contract`	Yes
`truncated`	No	True when IBKR returned the full count, so more ticks probably exist: page on with start set to the last tick's time (or end set to the first tick's time).
`what_to_show`	Yes

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?

Annotations already declare readOnlyHint=true and openWorldHint=true, and the description adds substantial behavior beyond that: the 1000-tick cap, one-second timestamp granularity, possible repeated ticks in the same second, truncation-induced pagination guidance, and IBKR pacing limits. This is rich, non-obvious behavior the annotations do not cover.

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?

Every sentence earns its place: purpose first, then usage rules, then behavior quirks, pacing, and final error enumeration. Despite covering a lot, it stays focused and front-loaded, with no filler or restatement of schema descriptions.

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 output schema exists, the description need not explain the return shape. It covers error cases (not_found, invalid_request, rate_limit, ib_api_error 162), permissions, pagination, and the correct alternative tool. An agent has everything needed to call this tool safely and correctly.

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%, so the schema documents each parameter. The description still adds meaningful interaction semantics: the exactly-one-of start/end constraint (reinforcement), pagination via setting start/end to boundary times, and the note that ticks in the same second can repeat, which affects how start/end should be used.

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 and resource: 'Return individual historical trades, quote changes or midpoints (time and sales).' This clearly identifies what the tool does and distinguishes it from bar-based history tools like get_historical_bars and from real-time subscription tools among its 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?

Explicitly instructs to give exactly one of start or end, then states when to prefer an alternative: 'prefer get_historical_bars for anything longer than minutes of activity.' It also adds prerequisites (market-data permissions) and pacing limits, 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