This server lets an AI agent trade US stocks on Interactive Brokers, monitor account state, and manage orders — all with built-in safety guards.
Session & Market State
session_status — Check authentication, account type (LIVE/PAPER), dry-run mode, daily budget remaining, and whether it's safe to trade
market_status — Check if the US market is currently open
reconcile_pending — Reconcile dispatched-but-unconfirmed orders to unblock the safety layer
Account & Market Data
account_summary — View available funds, net liquidation value, and buying power
positions — List all open positions
portfolio — Combined snapshot of account summary + positions + unrealized P&L
get_quote / get_quotes — Fetch current last/bid/ask for one or multiple US stock symbols
Order Placement
buy — Buy by dollar amount (fractional shares) or share quantity; market or limit
sell — Sell by share quantity; market or limit
close_position — Close 100% of a position, resolving exact fractional quantity automatically
stop_order — Place a stop or stop-limit order
trailing_stop — Place a trailing stop by fixed dollar amount or percentage
bracket_order — Place an entry order with attached take-profit and stop-loss (OCO bracket)
preview_order — Preview margin impact, commission, and warnings without sending the order
Order Management & Auditing
order_status — Check state, filled quantity, and average price of a placed order
wait_for_fill — Poll an order until it fills, cancels, or times out (up to 120s)
cancel_order — Cancel an open order by ID
open_orders — List all currently active orders
trade_history — View the local audit log of recent order attempts without hitting IBKR
Allows trading on Binance spot market via CCXT, including buying, selling, stop orders, trailing stops, and account queries.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@mcp-ibkr-agent show my account balance"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Two MCP servers over one shared safety core, giving an AI agent (like Claude Code) the ability to trade: ibkr on Interactive Brokers (US stocks, fractional shares by dollar amount via cashQty) and crypto on crypto exchanges (spot, via CCXT — persistent API key, 24/7). Both expose quotes, balance, positions and buy/sell under mirrored tool names.
The investment decision (what/when to buy or sell) stays with you and your skill's prompt — e.g. Vizier, the decision-making brain of this stack. This project delivers only the reliable trading plumbing — with safety guards on by default.
Part of a three-piece stack — brain, senses, hands: Vizier (the /vizier skill) decides, Scout researches (62 keyless market-data tools: stocks, crypto, macro, SEC filings), and Valet (this repo) executes. Each piece works standalone; together they close the research → decision → execution loop.
⚠️ Not financial advice. Runs against a paper account by default; live trading requires explicit opt-in. Use at your own risk.
What to expect. The crypto server is the low-friction path: just a persistent API key, 24/7, no gateway — it can run unattended. The IBKR server needs a funded IBKR Pro account and a manual browser login about once a day (IBKR offers no OAuth for retail — an IBKR constraint, not ours), so the stock side isn't fully hands-off. First-time setup is roughly 30–60 min per venue.
Hexagonal (ports & adapters). The agent talks only to the MCP tools; the safety guards sit on the path of every order; IBKR is an adapter detail:
flowchart LR
A["AI agent<br/>(/vizier skill)"] -->|MCP tools| B["MCP server<br/>(FastMCP)"]
B --> C["GuardedBroker<br/>(safety guards)"]
B --> D["MarketData"]
C --> E["CPAPI adapters"]
D --> E
E -->|REST localhost:5000| F["IBKR Client<br/>Portal Gateway"]
F --> G["Interactive Brokers"]src/
trading_core/ shared core — domain models, ports, trade journal, the generic
GuardedBroker, and the per-venue Capabilities contract
ibkr_agent/ IBKR adapter (cpapi/ over the Client Portal API) + the `ibkr` MCP server
crypto_agent/ crypto adapter (adapters/ccxt/, spot) + the `crypto` MCP serverEach venue is a thin adapter over trading_core; adding a third venue is a new *_agent
package, not a change to the core. The diagram above shows the IBKR server specifically.
The reasoning behind the key choices lives in DECISIONS.md.
Related MCP server: IBKR TWS MCP Server
This repo is a monorepo of two execution servers over one shared safety core
(trading_core): the IBKR server above, and a crypto server (spot, via
CCXT). They are separate MCP processes — own login,
own tools, registered separately — and only share code.
Crypto is here because it removes IBKR's structural friction: a persistent API key
(no gateway, no daily browser login, no tickle), a 24/7 market, and CCXT behind one
interface for ~100 exchanges. The tools mirror the IBKR names (session_status,
get_quote, buy, sell, stop_order, close_position, open_orders, …) so one skill
can drive both venues uniformly. Buy-by-value mirrors IBKR's cashQty via CCXT's
createMarketBuyOrderWithCost. stop_order places an exchange-native trigger order
(CCXT unified triggerPrice) that rests on the exchange and fires with no agent running —
most spot APIs (binance included) only offer stop-LIMIT, so pass limit_price; where the
exchange has no native stops the tool refuses cleanly. Spot-only by default.
# register the crypto server (separate from ibkr)
# Windows: claude mcp add crypto -- /path/to/.venv/Scripts/python.exe -m crypto_agent.server.app
# Linux/macOS: claude mcp add crypto -- /path/to/.venv/bin/python -m crypto_agent.server.app
python -m crypto_agent.healthcheck # exchange, mode, balance, a quoteSafety mirrors the IBKR posture: sandbox (exchange testnet — free keys, no deposit) is
paper-first; the live and dry-run arms are per-venue (CRYPTO_ALLOW_LIVE /
CRYPTO_DRY_RUN, both independent of the IBKR gates — arming IBKR does not arm crypto),
while the policy limits (MAX_ORDER_VALUE, MAX_DAILY_VALUE, …) are shared. See
ADR-014 for the rationale and the CRYPTO_* keys in
.env.example.
Most retail trading APIs force you into whole shares. This project leans on the IBKR Client Portal API's cashQty field, which lets you buy by dollar amount (e.g. "$50 of AAPL") and get a fractional position — the unlock for dollar-cost averaging, rebalancing, and small accounts. See DECISIONS.md for the full rationale.
Python 3.12+
An Interactive Brokers account that is open, funded, and IBKR Pro (an API requirement, even to use the associated paper account).
Fractional permission enabled: Client Portal → Settings → Trading → Trading Permissions → Stocks section → check "Global (Trade in Fractions)".
IBKR Client Portal Gateway running locally (Java 8u192+).
A dedicated username for the bot: IBKR allows only one brokerage session per username — logging into TWS/mobile with the same user kills the gateway session.
git clone https://github.com/pedrobraiti/agentic-trading-mcp.git
cd agentic-trading-mcp
python -m venv .venv
# Windows (PowerShell): & ".venv\Scripts\Activate.ps1" (on a policy error: Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass)
# Linux/macOS: source .venv/bin/activate
pip install -e ".[dev]"
cp .env.example .env # fill in IBKR_ACCOUNT_ID etc..env)See .env.example. Main keys:
Key | Default | Description |
|
| Client Portal Gateway endpoint |
| — | Account id (e.g. |
|
| A label only — it does not pick the account. Whether real money is at stake depends on which account you log the gateway into; the ground truth is IBKR's |
|
| Hard lock: |
|
| Validates but does not send orders |
|
| Allow a SELL bigger than the held position (opening a short) |
|
| Per-order limit (USD) |
| — | Cumulative daily buy cap (empty = no cap; only the per-order |
|
| Reject identical orders within this window ( |
Valet talks to a local Client Portal Gateway — a small Java app from IBKR that bridges to your account. It's the most common place people get stuck, so:
Download clientportal.gw.zip (from IBKR's API page). Requires Java 8u192+.
Unzip it somewhere outside this repo and start it:
# Linux/macOS: bin/run.sh root/conf.yaml
# Windows: bin\run.bat root\conf.yamlOpen https://localhost:5000 and log in with 2FA. Accept the self-signed certificate warning — it's local and expected.
You'll know it worked when the page says "Client login succeeds" and python -m ibkr_agent.healthcheck shows authenticated=True connected=True.
Keep the gateway running while you use Valet; the session needs a fresh login about once a day (see Keeping the session alive). If the browser login misbehaves, see Login troubleshooting.
With the gateway running and logged in, register the MCP server with Claude Code:
# Windows: claude mcp add ibkr -- /path/to/.venv/Scripts/python.exe -m ibkr_agent.server.app
# Linux/macOS: claude mcp add ibkr -- /path/to/.venv/bin/python -m ibkr_agent.server.app(or run it directly to test: python -m ibkr_agent.server.app)
The tools appear in a new Claude Code session.
Check the connection anytime (with the gateway logged in):
python -m ibkr_agent.healthcheck # or: ibkr-healthcheckShows the server version, auth status, account flags (supportsCashQty/supportsFractions), balance and a quote.
The gateway session expires (without /tickle in ~6 min; lasts at most ~24h; daily maintenance ~01:00 drops it) — and IBKR offers no OAuth for retail, so reauth is always a manual browser login.
While the MCP server is running it keeps its own session warm — a background /tickle runs on the server's lifespan, so you don't need a separate process for interactive use. For when the MCP server isn't running (e.g. scheduled jobs, or just to watch the session), there's also a standalone keep-alive:
python -m ibkr_agent.keepalive # or: ibkr-keepaliveBoth /tickle every TICKLE_INTERVAL_SECONDS and, when the session drops, emit an alert ([ALERT] Reauthentication required: ...) telling you to log back in. When merely connected without a brokerage session, they try to recover on their own (no new 2FA).
https://localhost:5000 won't load at all (ERR_CONNECTION_REFUSED / "connection refused") — the login page never even appears? That page only exists while the gateway is running, so this means the gateway isn't up. Start it (bin\run.bat root\conf.yaml on Windows, bin/run.sh root/conf.yaml on Linux/macOS) and leave that window open — if it closes, the gateway stops and the port refuses connections again. Only once the page loads do the login steps below apply.
If you log in and approve 2FA but nothing happens — the page just sits there and the API stays authenticated:false/connected:false (sometimes ssodh/init returns HTTP 500 / no bridge):
Restart the gateway clean and log in fresh — this is what fixes it almost every time. Kill the Java process, start it again, reload https://localhost:5000, and log in. An incognito/private tab also helps (stale cookies).
The login is not sticky: each time you need a fresh login, restart the gateway first, then log in — don't retry against the already-running gateway.
If it still persists, log out of any other IBKR session (IBKR Mobile or Client Portal web) — only one brokerage session per username is allowed — then restart the gateway and try again.
The old launcher build (2023) is not the problem — at runtime the gateway connects to the current backend.
session_status, market_status, get_quote, get_quotes, account_summary, positions, portfolio, preview_order, buy, sell, close_position, stop_order, trailing_stop, bracket_order, order_status, wait_for_fill, cancel_order, open_orders, trade_history, reconcile_pending.
get_quotes(symbols) quotes a whole watchlist in one snapshot call (cheaper than one get_quote per symbol).
preview_order(symbol, side, ...) estimates an order's margin impact, commission and warnings via IBKR's whatif — without sending it — so the agent can reason about cost before committing.
buy takes cash_amount (USD, fractional via cashQty) or quantity (shares, fractional ok). Pass limit_price for a LIMIT order (market by default; LIMIT needs quantity).
sell takes only quantity (shares, fractional ok); optional limit_price for a LIMIT sell. IBKR does not allow selling by dollar amount — cashQty is buy-only.
close_position(symbol) closes 100% of a position by trading the exact fractional quantity.
stop_order(symbol, side, quantity, stop_price, limit_price?) places a STOP (e.g. a stop-loss) — a market order triggered at stop_price, or a STOP-LIMIT if limit_price is given.
trailing_stop(symbol, side, quantity, trail_amount | trail_percent) places a trailing stop — the trigger follows the price (by a US$ amount or a %), locking in gains as it moves.
bracket_order(symbol, quantity, take_profit, stop_loss, ...) places an entry with attached take-profit + stop-loss exits (OCO) — when one exit fills the other is cancelled.
order_status(order_id) reports an order's state, filled quantity and average price — use it after buy/sell to confirm a fill (positions lag right after a trade). wait_for_fill(order_id, timeout_seconds) polls until it fills (or is cancelled/rejected), so the agent doesn't orchestrate the retry itself. filled_quantity is always in SHARES, never dollars: a cash_amount order additionally reports the US$ spent in filled_cash and sets is_cash_quantity (IBKR itself reports that order's fill in dollars, in the same field it uses for shares — Valet converts it; see ADR-017).
portfolio() returns a single snapshot: account summary + open positions + total unrealized P&L.
trade_history(limit) returns the audit log of recent order attempts (buys, sells, dry-runs, blocks) — answers "what did my agent do?".
reconcile_pending(resolve_missing?) reconciles dispatched-but-unconfirmed orders against IBKR's open orders. After a timeout/crash an order may have landed without its outcome journaled, so the safety layer blocks an identical resend until reconciled: orders found resting are marked resolved; ones not found stay blocked (resending blind could double them).
With the MCP registered, you talk in natural language and the agent uses the tools:
You: "Buy $50 of AAPL." The agent calls
buy(symbol="AAPL", cash_amount=50)— IBKR fills a fractional order (≈ 0.16 share), no need to pay for a whole share (~$300).
You: "Close my AAPL position." The agent calls
close_position(symbol="AAPL"), which reads the exact quantity and sells 100%.
Every tool returns an {"ok": ..., "data": ...} envelope. A real example of an executed fractional buy (validated live against an IBKR account):
{
"ok": true,
"data": {
"order_id": "8645012XX",
"status": "filled",
"symbol": "AAPL",
"side": "BUY",
"message": "Bought 0.0066 AAPL Market, Day"
}
}Fractional buys use
cashQty(dollar amount). Fractional sells are by share quantity — IBKR rejectscashQtyon sells; that's whyclose_positionexists, resolving the exact quantity for you.
paper by default; live blocked unless TRADING_ALLOW_LIVE=true.
dry-run on by default (no real order is sent).
Know which account is live. session_status and portfolio report account_type ("LIVE"/"PAPER") straight from IBKR's isPaper — not the IBKR_TRADING_MODE label, which can disagree with the account the gateway is actually logged into. A LIVE account also returns an explicit warning. Check it before trading: real-money and paper accounts are never told apart by the config alone.
The money-lock is bound to the real account, not the label. Before sending, the guard verifies IBKR's isPaper and the logged-in account and fails closed if the configured IBKR_ACCOUNT_ID doesn't match, if a real-money account isn't armed with TRADING_ALLOW_LIVE=true, or if IBKR_TRADING_MODE disagrees with reality — so a mislabelled setup can't quietly trade real money.
No accidental shorts: a SELL larger than the held position is blocked (unless TRADING_ALLOW_SHORT=true); exits are never trapped. No inverted stops: a stop already on the wrong side of the market (it would fire instantly) is rejected.
Buys above MAX_ORDER_VALUE are rejected (it's a spend cap; exits — sells, closes, stop-losses — aren't value-gated, so a large position can always be closed or protected).
Orders only during regular trading hours (RTH), accounting for NYSE holidays (via the holidays lib).
CPAPI confirmation warnings are auto-accepted only through an allow-list; an unknown warning blocks the order.
Optional daily spend cap (MAX_DAILY_VALUE) across all buys, tracked in the audit log — not just per-order. It is off by default (no cap): out of the box only the per-order MAX_ORDER_VALUE bounds spending, so many sub-cap buys are unbounded over a day. When it's off and live trading is armed (TRADING_ALLOW_LIVE / CRYPTO_ALLOW_LIVE), the server emits a loud startup warning — set MAX_DAILY_VALUE to bound cumulative daily spend.
The audit-backed caps treat an inactive order conservatively: CPAPI uses inactive for both a dead order and one parked until the open (and a rejected order can arrive as inactive too), so it counts toward the daily cap and duplicate window on purpose — the fail-safe direction (it may over-block a retry, never over-spend).
Duplicate-order guard: an identical order within DUPLICATE_WINDOW_SECONDS is rejected (protects against timeout/retry double-buys).
Every order attempt (sent, dry-run, or blocked) is written to a local audit log (logs/trades.jsonl, gitignored).
Optional symbol allow/deny list (SYMBOL_ALLOWLIST / SYMBOL_DENYLIST) restricts the universe the agent can trade.
The keep-alive can also POST to an optional webhook (REAUTH_WEBHOOK_URL, e.g. ntfy/Discord) when the session needs a fresh login — a one-way notification, no account data, no trade.
python -m pytest -q # 206 tests, all offline (brokers/exchanges are faked)
python -m ruff check . # lintSee CONTRIBUTING.md and SECURITY.md.
MIT.
Account summary: available funds, net liquidation, buying power.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. The description only lists output fields but does not disclose behavioral traits like whether the operation is read-only, requires authentication, or has any side effects. For a tool with no annotations, this is insufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded with the tool's purpose, no unnecessary words. Extremely concise and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no parameters, no output schema, and no annotations, the description is minimal. It lists three fields but does not clarify if these are all returned fields or just examples, nor does it describe the return format. Adequate for a simple tool but leaves some ambiguity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has zero parameters, so schema description coverage is 100%. According to guidelines, baseline is 4. The description does not need to add parameter details because none exist.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool returns an account summary with specific fields (available funds, net liquidation, buying power). The verb 'summary' implies retrieval, distinguishing it from sibling tools like 'portfolio' or 'positions' that provide different granularity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives such as 'portfolio' or 'positions'. Missing context on whether this is a high-level snapshot or if it includes additional details, and no exclusions for specific scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Place an entry order with attached take-profit and stop-loss exits (OCO).
The entry buys (or sells) quantity shares — market by default, or a limit if
entry_limit_price is set. Once it fills, two exits go live: a limit at
take_profit and a stop at stop_loss; when one fills the other is cancelled.
Returns one result per leg (labelled entry / take_profit / stop_loss in message).
| Name | Required | Description | Default |
|---|---|---|---|
| side | No | BUY | |
| symbol | Yes | ||
| quantity | Yes | ||
| stop_loss | Yes | ||
| take_profit | Yes | ||
| entry_limit_price | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Details OCO mechanism, default market vs limit entry, and per-leg return format. Lacks edge cases like unfilled entry, but given no annotations, it provides solid behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with clear structure: purpose, then behavior details, then return format. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers main interaction and output labels. No output schema, so description's return info is helpful. Missing failure modes (e.g., entry not filled) but sufficient for primary use case.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description explains key parameters (entry_limit_price, take_profit, stop_loss, quantity, side is implied via price direction). Could explicitly state side and symbol but adds meaningful behavior context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool places an entry order with OCO take-profit and stop-loss exits, distinguishing it from sibling tools like buy, sell, or stop_order which lack both exits.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use for bracket orders but does not explicitly state when to use it versus alternatives (e.g., placing separate orders) or provide when-not conditions to avoid ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Buy. Provide cash_amount (US$, fractional via cashQty) OR quantity (shares).
Omit limit_price for a market order. Pass limit_price for a LIMIT order —
LIMIT requires quantity (cashQty is market-only). A limit order may surface a
confirmation IBKR hasn't mapped yet; if so it is blocked (safe) until allow-listed.
A cash_amount buy comes back with is_cash_quantity: true. Its fill is reported in
SHARES in filled_quantity and in US$ in filled_cash (IBKR itself reports both in the
same field — see order_status); size any protective stop from the SHARE count.
| Name | Required | Description | Default |
|---|---|---|---|
| symbol | Yes | ||
| quantity | No | ||
| cash_amount | No | ||
| limit_price | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. Discloses limit order confirmation blocking, cash_amount buy returns 'is_cash_quantity', fill reporting in shares and dollars, and protective stop sizing.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Concise but information-dense. Uses bullet-like structure to separate parameter rules and behavioral notes. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, but description explains return fields (is_cash_quantity, filled_quantity, filled_cash). Covers parameter semantics, usage rules, and behavioral notes comprehensively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so description must explain parameters. Clearly explains each parameter's meaning and constraints (exclusive or, limit_price requires quantity, cashQty market-only).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool buys a security. Distinguishes market vs limit orders, cash vs share quantity. Differentiates from siblings like 'sell' and 'bracket_order'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit instructions on when to use cash_amount vs quantity, when to include limit_price. Lacks direct comparison to sibling tools but context makes it clear this is for simple buys.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Cancels an open order by its order_id.
| Name | Required | Description | Default |
|---|---|---|---|
| order_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist; description only says 'Cancels an open order.' No disclosure of side effects (e.g., irreversibility), error handling (e.g., invalid order_id), or state changes beyond cancellation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, perfectly concise, no filler. Essential information front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter tool, description covers core action. Lacks behavioral details like idempotency or error responses, but still mostly adequate for agent use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Only one parameter (order_id). Description merely repeats 'by its order_id' without adding format, source, or validation rules. Schema coverage is 0%, so description fails to add meaning beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description states verb 'Cancels' and resource 'open order by its order_id.' Clearly distinguishes from siblings like 'preview_order' or 'order_status'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit when-to-use or alternatives are provided. Usage is implied by name and description, but no guidance on when not to use or conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Closes 100% of a symbol's position, trading the exact fractional quantity.
Reads the exact position size and sends the opposite order. Note: IBKR's
portfolio is eventually-consistent — right after a recent BUY the position may
not appear yet (and the close will return closed=False). In that case, wait
a few seconds and try again, or sell the exact quantity via sell.
| Name | Required | Description | Default |
|---|---|---|---|
| symbol | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses behavior: it reads position size, sends opposite order, and explains eventual consistency and failure mode (closed=False). This provides excellent transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is fairly concise with two paragraphs, front-loading the core action. It could be slightly more streamlined, but it efficiently conveys important behavioral notes.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given a single parameter, no output schema, and no annotations, the description covers the tool's purpose, behavior, edge cases, and alternative usage. It is complete for practical use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 0% description coverage. The description mentions 'symbol' implicitly but doesn't add extra detail beyond the schema's required field. For one parameter, more elaboration on format or constraints would improve clarity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'Closes 100% of a symbol's position' with specific verb and resource. It distinguishes from sibling 'sell' by specifying full closure and exact fractional quantity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context for use (closing entire position) and mentions the eventual consistency issue and fallback to 'sell'. It could explicitly list when not to use, but the guidance is effective.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Current quote (last/bid/ask) for a US stock symbol.
| Name | Required | Description | Default |
|---|---|---|---|
| symbol | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the burden. It states 'current quote' and lists fields (last/bid/ask), but does not disclose data freshness, source, permission requirements, or error behavior. This is adequate for a simple read but lacks depth.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that covers the essential purpose without any wasted words. It is well-structured and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the tool (1 parameter, no output schema, no annotations), the description is insufficient. It does not explain the return format, possible error states, or what happens for invalid symbols. A financial data tool should provide more context on the returned data structure.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description only adds 'US stock symbol' to the parameter, providing minimal extra meaning beyond the schema's 'Symbol' title. It does not explain format, constraints, or examples.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns a current quote (last/bid/ask) for a US stock symbol, which is a specific verb+resource combo. It also implies a distinction from the sibling tool 'get_quotes' (plural) which likely handles multiple symbols.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides implied usage by limiting to 'a US stock symbol', but it lacks explicit guidance on when to use this vs 'get_quotes' or other price-related tools. No when-not-to-use or alternatives are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Quotes for several US stock symbols at once (one snapshot — cheaper for a watchlist).
| Name | Required | Description | Default |
|---|---|---|---|
| symbols | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It mentions 'one snapshot' (implying non-streaming) and 'cheaper', but does not disclose rate limits, data freshness, or error behavior. Minimal transparency beyond basic function.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with a clarifying parenthetical. No redundant words; front-loaded key information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one parameter and no output schema, the description covers the essentials (what, when, benefit). Lacks details on output structure or limitations (e.g., max symbols), but still reasonably complete for its complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description should elaborate on the 'symbols' parameter. It specifies 'US stock symbols' but lacks details on format, case sensitivity, or maximum count. Adds marginal meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('get quotes'), resource ('several US stock symbols at once'), and differentiates from sibling tool 'get_quote' by emphasizing batch retrieval and cost benefit for watchlists.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use this tool (for multiple symbols, cheaper snapshot) and distinguishes from likely single-quote sibling, but does not explicitly exclude single-symbol scenarios or mention alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Indicates whether the US market is open (RTH) right now.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description should fully disclose behavior. It states the tool indicates market open status, but does not specify return format, latency, caching, or whether 'right now' is real-time or with delay.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence containing the essential information, no waste. Front-loaded with the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no parameters and no output schema, the description is minimally adequate. It could be improved by specifying the output type (e.g., boolean or string) or any caveats.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so schema coverage is 100%. Baseline is 4; no additional parameter info is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Indicates') and resource ('whether the US market is open (RTH) right now'). It clearly distinguishes the tool's purpose from siblings like buy/sell or account_summary.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for checking market status before trading, but provides no explicit guidance on when to use versus alternatives like session_status, nor 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.
Lists the active orders (live orders) in the account.
Same unit contract as order_status: filled_quantity in SHARES, filled_cash in US$.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits. It states it lists active orders but does not mention if it is read-only, what authentication is needed, or any side effects. It adds unit contract info but lacks broader transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences, front-loading the primary purpose. No extraneous information; every word serves a purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the core purpose and one data format detail. However, with no output schema and no annotations, it lacks information about the structure of the returned data (e.g., list of orders with fields, pagination) and completeness for a simple listing tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, so the description adds value by clarifying the unit contract (filled_quantity in SHARES, filled_cash in US$). This compensates for the lack of parameter info.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool lists active (live) orders. The verb 'lists' and specific resource 'active orders' make the purpose clear. It does not explicitly differentiate from siblings like 'order_status' or 'trade_history', but the name and description are sufficient.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like 'order_status' (for a single order) or 'trade_history' (for past trades). The description mentions unit contract consistency with 'order_status', but this is more about data format than usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Status of a placed order by its order_id: state, filled quantity, average price.
Use this after buy/sell to confirm whether the order actually filled —
positions is eventually-consistent and lags right after a trade.
Units: filled_quantity is ALWAYS in SHARES, filled_cash is the US$ spent (set only on
a cash_amount order). If quantity_is_estimate is true the share count was derived from
a partial cash fill — do NOT size an exit from it; read positions for the exact size.
| Name | Required | Description | Default |
|---|---|---|---|
| order_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description fully bears the transparency burden. It details that 'filled_quantity' is always in shares, 'filled_cash' only present on cash_amount orders, and explains the 'quantity_is_estimate' flag's implications. Fully discloses output format and edge cases.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four concise sentences, each adding distinct value. Front-loaded with the main purpose. No redundant or unnecessary information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema, the description thoroughly explains return fields, units, and special cases. It addresses usage context relative to siblings and provides necessary warnings. Complete for a status-check tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Only parameter is 'order_id', which is self-explanatory. Schema coverage is 0%, but description adds no further details about the parameter itself. However, the parameter's purpose is obvious from context, so score is adequate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it returns status (state, filled quantity, average price) for a specific order by order_id. It distinguishes itself from sibling tools like 'positions' by noting eventual consistency, and from 'wait_for_fill' by being a status check rather than a wait action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly advises using after 'buy'/'sell' to confirm fill, contrasts with 'positions' which lags, and warns not to use 'quantity_is_estimate' for exit sizing. Provides clear when-to-use and when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Combined snapshot: account summary + open positions + total unrealized P&L.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The term 'snapshot' implies a read-only operation, which is transparent about the behavioral trait. Since no annotations are provided, the description adequately conveys the non-destructive nature of the tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence that is front-loaded with the key phrase 'Combined snapshot', concise with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description fully explains what the tool returns without missing critical information, given the simplicity of the tool and absence of output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With no parameters (0 params, 100% schema coverage), the description adds value by specifying what the tool returns (account summary, open positions, total unrealized P&L), which is beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that it provides a combined snapshot of account summary, open positions, and total unrealized P&L, using specific verbs ('snapshot') and resources, which distinguishes it from sibling tools like account_summary and positions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies it should be used when a consolidated view is needed, but it does not explicitly state when to use it versus alternatives, nor does it provide exclusion criteria or mention 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.
Open positions in the account.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description should disclose behavioral traits like read-only nature, data freshness, or authentication requirements. The minimal description fails to provide such context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with one sentence, but it could be more informative without being wordy. It is front-loaded and avoids redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given zero parameters, no output schema, and many sibling tools, the description is incomplete. It does not explain the output format or how it differs from similar tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are no parameters, and schema coverage is 100%. The description adds no value beyond the schema, earning a baseline score of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Open positions in the account' clearly indicates the tool retrieves open positions, but it is vague and does not differentiate from sibling tools like 'portfolio' which may also list positions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as 'portfolio', 'account_summary', or 'close_position'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Preview an order's impact (margin, estimated commission, warnings) WITHOUT sending it.
Uses IBKR's whatif so the agent can reason about cost/margin before committing. side
is "BUY" or "SELL"; size is cash_amount (USD) or quantity (shares). Pass
limit_price to preview a LIMIT order (needs quantity).
| Name | Required | Description | Default |
|---|---|---|---|
| side | No | BUY | |
| symbol | Yes | ||
| quantity | No | ||
| cash_amount | No | ||
| limit_price | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully explains behavior: it uses IBKR's whatif, returns margin/commission/warnings, and does not send the order. Parameter usage is also detailed, covering side, size options, and limit_price requirement.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences: first states purpose, second explains parameters. Front-loaded, no extraneous information. Every word serves a purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (5 parameters, no output schema), the description covers everything needed: what the tool does, when to use it, how to set parameters, and what it returns.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% coverage, but the description compensates by explaining that side is 'BUY' or 'SELL', size can be cash_amount (USD) or quantity (shares), and limit_price is for LIMIT orders needing quantity. This adds crucial meaning beyond schema types.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Preview an order's impact (margin, estimated commission, warnings) WITHOUT sending it.' It specifies the action (preview), the resource (order impact), and distinguishes it from executing orders like buy/sell siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'before committing,' indicating when to use this tool. It does not list alternatives or exclusions, but the context of sibling tools (e.g., buy, sell) makes the usage clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Reconcile dispatched-but-unconfirmed orders against IBKR's open orders.
After a timeout/crash an order may have landed without its outcome journaled, so the
safety layer BLOCKS an identical resend until it is reconciled. This clears that block:
orders found resting on IBKR are marked resolved; ones not found stay blocked (they may
have filled — resending blind would double them). Set resolve_missing=true to also clear
the not-found ones AFTER you've verified via positions/trade_history that they didn't fill.
| Name | Required | Description | Default |
|---|---|---|---|
| resolve_missing | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses the blocking mechanism, the clearing of blocks for resting orders, and the risk of doubling orders if missing ones are blindly resolved. It also explains the safety layer's role, providing sufficient transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise yet complete, with each sentence adding value. It is well-structured: main action, context, mechanism, and parameter usage. No fluff or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (safety-critical reconciliation) and lack of annotations/output schema, the description covers the problem, behavior, parameter, and recommended workflow. It does not describe return values, but the simplicity of the tool makes this acceptable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter, resolve_missing, has no schema description (0% coverage), but the description adds clear meaning: setting it to true clears the block for not-found orders only after verification via positions/trade_history. This adds critical context beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool reconciles dispatched-but-unconfirmed orders against IBKR's open orders, explaining the specific scenario (timeout/crash) and action. It distinguishes itself from sibling tools like cancel_order or order_status by addressing a unique problem of blocked resends.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use this tool (after timeout/crash when an order may have landed without journaling) and provides guidance on handling missing orders (recommending verification before setting resolve_missing=true). It does not explicitly mention when not to use it, but the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Sell by quantity (shares, fractional ok). Omit limit_price for market, pass it for LIMIT.
IBKR does NOT accept selling by US$ value (cashQty is buy-only). To exit
100% of a position use close_position; to sell a dollar amount,
compute the quantity via get_quote.
| Name | Required | Description | Default |
|---|---|---|---|
| symbol | Yes | ||
| quantity | Yes | ||
| limit_price | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description covers key behavioral constraints: IBKR restriction on cashQty for sells and guidance for dollar amount orders. It lacks return value info but is otherwise transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four sentences, front-loaded with core instruction, no unnecessary words. Efficiently packs key constraints and alternatives.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 3 params, no output schema, and sibling tools, the description is complete: covers usage, constraints, and related tools for alternate scenarios.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Adds meaning beyond schema: explains quantity as fractional ok, and limit_price behavior (omit for market, pass for limit). With 0% schema coverage, this is valuable context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool sells a specified quantity of shares, with fractional shares allowed. It distinguishes between market and limit orders by parameter usage, and references sibling tools like close_position for full position exit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly explains when to omit or include limit_price for market vs limit orders. Warns against using cashQty for sells (buy-only) and directs to close_position for full exit or get_quote for dollar amount conversion.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Trading posture — "am I safe to trade right now?" — plus which account is live.
Identity: authenticated/connected/competing, account_id, account_type
("LIVE"/"PAPER", the ground truth from IBKR's isPaper, NOT the IBKR_TRADING_MODE
label) and is_paper. A LIVE account includes a warning.
Posture (so an unattended caller can self-gate): dry_run, allowlist_active,
daily_cap_configured, remaining_daily_budget (when a cap is set), unresolved_orders
(dispatched-but-unconfirmed orders that must be reconciled before resending), trade_stops
(active reasons NOT to trade — a competing session, or unresolved in-flight orders) and an
advisory safe_to_trade. When live trading is armed with no cap, a daily_cap_warning.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description thoroughly discloses the tool's behavior and return values, including details like account_type being ground truth from IBKR's isPaper, trade_stops being active reasons not to trade, and the advisory safe_to_trade flag. No annotations are provided, so the description carries the full burden and does so excellently.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear purpose statement followed by detailed bullet points. It is somewhat verbose but every sentence adds value. Could be slightly more concise, but overall well-organized.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no output schema, the description fully explains all return fields: identity, posture, warnings. It covers everything needed for an agent to understand and use the tool correctly. No gaps are apparent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has no parameters, so baseline 4 applies. The description does not need to explain parameters, but it adds meaning about the output, which is valuable given no output schema. The description effectively communicates what the tool returns.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: to check trading posture and which account is live. It starts with a direct question 'am I safe to trade right now?' and explains it returns identity, account info, and safety indicators. This distinguishes it from sibling tools that perform actions like buying or selling.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for an unattended caller to self-gate and mentions 'safe_to_trade', but it does not explicitly state when to use this tool versus alternatives. It provides context but lacks explicit when-to-use or when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Place a STOP order (e.g. a stop-loss). Triggers a market order when stop_price is hit.
side is "BUY" or "SELL" (a stop-loss on a long position is a SELL). Pass
limit_price to make it a STOP-LIMIT (becomes a limit order on trigger instead
of a market order). Sized by quantity (shares).
| Name | Required | Description | Default |
|---|---|---|---|
| side | Yes | ||
| symbol | Yes | ||
| quantity | Yes | ||
| stop_price | Yes | ||
| limit_price | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses key behavior: triggers a market order (or limit order if limit_price given) on stop_price hit. No annotations, so description handles transparency well, but could note order validity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise, front-loaded sentences with no redundant words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Adequate for a 5-param tool with no output schema; covers order type and parameter behavior, but could mention return value or order lifecycle.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description explains side, stop_price, limit_price, and quantity meaningfully. Symbol is not explained but is standard.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the action 'Place a STOP order' and the trigger behavior, distinguishing it from siblings like bracket_order or trailing_stop.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explains side usage for stop-loss and optional stop-limit, but does not explicitly mention when not to use or compare with alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Audit log of the agent's recent order attempts (buys, sells, dry-runs, blocks).
Reads the local trade journal — answers "what did my agent do?". Does not hit IBKR.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses it is a read operation ('Reads the local trade journal') and is local-only ('Does not hit IBKR'). However, it does not detail output format, whether data is real-time, or how 'recent' is defined. Overall, good transparency for a simple local read.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, using two short sentences to convey core purpose and behavior. Every sentence adds value, and the key phrase 'answers what did my agent do?' is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given one optional parameter and no output schema or annotations, the description adequately explains what the tool returns (audit log of order attempts) and where it reads from (local trade journal). However, it could clarify what 'recent' means and whether limit applies to maximum entries or pagination. It is minimally sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter 'limit' has no description in the schema (0% coverage) and is not mentioned in the tool description. The description does not explain its purpose, default, or effect on results. This fails to add value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states it is an audit log of recent order attempts (buys, sells, dry-runs, blocks) and answers 'what did my agent do?'. It distinguishes itself from sibling tools like buy/sell (execution) and account_summary (overview) by specifying it reads the local trade journal and does not hit IBKR.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for reviewing recent actions and notes it does not hit IBKR (suggesting low cost), but does not explicitly state when to use instead of alternatives like positions, portfolio, or open_orders. It lacks exclusions or alternative recommendations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Place a TRAILING stop — a stop that follows the price (locks in gains as it moves).
The trigger trails the market by trail_amount (US$) or trail_percent (%).
side is "BUY" or "SELL" (a trailing stop-loss on a long position is a SELL).
Sized by quantity (shares).
| Name | Required | Description | Default |
|---|---|---|---|
| side | Yes | ||
| symbol | Yes | ||
| quantity | Yes | ||
| trail_amount | No | ||
| trail_percent | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description must disclose all behavioral traits. It explains the two trail methods and side logic, but does not disclose whether the order becomes a market order when triggered, what happens if both trail_amount and trail_percent are set, order duration, or cancellation behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (4 sentences) and well-structured, using line breaks and bullet-point style. It conveys key information without extra words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and no annotations, the description covers the core functionality but lacks details on execution behavior, potential errors, and order lifecycle. It is adequate for a simple trailing stop order but not fully comprehensive for all edge cases.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so description carries full burden. It explains trail_amount and trail_percent as alternatives (though not explicit about mutual exclusivity), clarifies side with an example, and mentions quantity. Symbol is self-explanatory but not described. This adds significant value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it places a trailing stop and explains what a trailing stop does ('follows the price, locks in gains'). It distinguishes from a regular stop (sibling stop_order) by using 'trailing' and describing the trail mechanism, but does not explicitly name the alternative.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives guidance on side ('trailing stop-loss on a long position is a SELL') and explains the two trail methods, but does not specify when to use a trailing stop versus a regular stop order or other order types. No when-not-to-use or alternative names are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Poll an order until it reaches a terminal state (filled/cancelled/rejected/inactive), or the timeout elapses.
Closes the confirm-the-fill loop so the agent doesn't have to orchestrate the
retry itself. Returns the latest status with timed_out true if it was still
working when time ran out. timeout_seconds is capped at 120. Note: an inactive
result usually means the order was rejected/killed, but IBKR also uses it for an
order parked until the market opens — so confirm intent before assuming it's dead.
Same unit contract as order_status: filled_quantity in SHARES, filled_cash in US$,
and quantity_is_estimate true when the share count was derived from a partial cash fill.
| Name | Required | Description | Default |
|---|---|---|---|
| order_id | Yes | ||
| timeout_seconds | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully describes behavior: polling, terminal states, timeout cap, timed_out flag, inactive nuance, and unit conventions. It does not mention rate limits or side effects, but is still transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two paragraphs, front-loaded with purpose and key states, followed by details. Efficient without redundancy, though slightly verbose in the second paragraph.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, no annotations, and moderate complexity, the description covers terminal states, timeout behavior, inactive interpretation, and units. It does not address error handling or authentication, but is sufficient for a polling tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but the description explains timeout_seconds cap at 120 and return fields (timed_out, filled_quantity, etc.) which aid understanding. However, order_id parameter lacks format hints, and parameter-specific details are minimal.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool polls an order until a terminal state or timeout, with specific verbs and resource. It distinguishes from sibling tools like order_status by emphasizing the polling and loop closure.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains the tool is for closing the confirm-the-fill loop, implying use after placing an order, and not for simple status checks. It mentions timeout cap and inactive ambiguity, but lacks explicit when-not-to-use alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Each tool serves a distinct purpose: account info, quotes, order placement (different order types), order management, preview, history, reconciliation, and session status. Descriptions clearly differentiate even similar-sounding tools like 'open_orders' and 'order_status'.
Tool names follow a consistent snake_case verb_noun pattern (e.g., account_summary, cancel_order, get_quote). A few are single verbs (buy, sell) but that is standard for basic actions and does not break consistency.
With 20 tools, the server covers a wide range of trading operations without being excessive. Some tools (e.g., get_quote and get_quotes) could be merged, but the count is still appropriate for the domain.
The tool set covers core trading workflows: account info, quotes, various order types, order management, preview, history, and reconciliation. Minor gaps like order modification are absent, but the set is largely complete for common trading tasks.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Connect AI agents to bank accounts, transactions, balances, and investments.
Paper trading for AI: live quotes, indicators, and virtual trades on stocks, crypto, and forex.
Build, backtest, and deploy quantitative trading strategies from your AI agent.
US stock market data for AI agents: SEC filings, financials, insider trades, 13F, options, macro.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/pedrobraiti/agentic-trading-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
