ib-gateway-mcp

Scanner parameters

get_scanner_parameters

Read-only

Browse the IBKR market scanner catalogue to find valid scan codes, instruments, locations, and filters for scanner queries. Use it to discover supported inputs before running a scan.

Instructions

Browse IBKR's market scanner catalogue to find valid inputs for run_scanner.

Sections:
- scan_codes: what a scan ranks by (e.g. TOP_PERC_GAIN, MOST_ACTIVE, HOT_BY_VOLUME),
  with the instrument types each supports.
- instruments: instrument types (e.g. STK for US stocks, IND.US, FUT.US).
- locations: markets and exchanges (e.g. STK.US.MAJOR, STK.NASDAQ), nested via parent.
- filters: filter tags for run_scanner's `filters` (e.g. avgVolumeAbove), with
  their value type and, for choice filters, the allowed values.
`query` matches codes and names (case-insensitive substring; for filters also the
filter group and category); `instrument` keeps only entries for that instrument
type. Default limit 50, at most 500; `total` says how many matched. The catalogue
is fetched once per gateway session, so the first call can take a few seconds.
Errors: not_found when nothing matches or the instrument type is unknown.

Input Schema

TableJSON Schema

Name	Required	Description
`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.
`query`	No	Case-insensitive text to look for in codes and names, e.g. gain.
`section`	Yes	What to list: scan_codes (what a scan ranks by), instruments (instrument types), locations (markets and exchanges) or filters (filter tags).
`instrument`	No	Only entries that work with this instrument type, e.g. STK.

Output Schema

TableJSON Schema

Name	Required	Description
`query`	No	The substring filter applied, if any.
`total`	Yes	How many entries matched, before the limit.
`filters`	No
`section`	Yes
`locations`	No
`truncated`	No	True when the result was cut to the limit.
`fetched_at`	Yes	When the catalogue was fetched from IBKR (UTC).
`instrument`	No	The instrument filter applied, if any.
`scan_codes`	No
`instruments`	No

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 only mark readOnly/openWorld, so the description adds real behavioral value: session-level caching, first-call latency, default limit and cap, total-count semantics, and not_found error behavior. All disclosed traits are consistent with the 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 front-loads its purpose, then organizes the remaining content into compact, scannable sections: catalogue sections, filtering behavior, limits, latency, and errors. No sentence is redundant or wasted.

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 read-only catalogue tool with an output schema and annotations, the description covers all four sections, query and instrument filtering, default and maximum limits, total counts, network/session latency, and error cases. Nothing needed to invoke it correctly 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 descriptions already document all four parameters, so this is a baseline-3 situation. The description still adds meaning beyond the schema by specifying the default limit (50), the cap (500), the total-count signal, and that query for filters also matches group and category.

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 action ('Browse'), a concrete resource ('IBKR's market scanner catalogue'), and its goal ('to find valid inputs for run_scanner'). The section list disambiguates it from scanner execution and from other data-listing 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 positions the tool as the catalogue look-up step before run_scanner, which is the main user of its output. It also tells the agent how to narrow results using query and instrument, so the right context-of-use is clear.

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

Deploy Server