Public.com MCP Server

Official

Overview Schema Source Related Servers Discussions Admin

search_orders

Read-only

Search the last 30 days of order history by status, side, symbol, or date to find filled, cancelled, rejected, expired, or replaced orders. Call with no filters to list every order in the window.

Instructions

Search the account's order history — orders in ANY status, created in the last 30 days.

This is the order-history tool. It differs from get_orders, which returns only the open/active orders embedded in the portfolio snapshot: search_orders queries the order-history endpoint and also returns filled, cancelled, rejected, expired and replaced orders, narrowed by the filters below. All filters are optional and combine with AND; call it with no filters to list every order in the window.

Limits (enforced by the API): only orders created within the last 30 days are searchable, and at most 500 orders are returned — narrow with created_after / created_before or the other filters if a search could exceed that.

Each result has the same shape as get_order: the order plus trades (the individual fills: tradeId, quantity, price, side, timestamp and, when reported, marketIdentificationCode — the MIC of the execution venue), filledAt, replacedAt, lastModified and equityMarketSession. equityMarketSession reports the session an equity order was placed for as REGULAR, REST_OF_DAY or TWENTY_FOUR_HOURS.

Args: account_id: Account ID. Optional if PUBLIC_COM_ACCOUNT_ID is set. status: Only orders currently in this status. One of NEW, PARTIALLY_FILLED, FILLED, CANCELLED, QUEUED_CANCELLED, PENDING_CANCEL, PENDING_REPLACE, REPLACED, REJECTED, EXPIRED. side: BUY or SELL. symbols: Only orders for these instruments, each as "SYMBOL" or "SYMBOL:TYPE" (type defaults to EQUITY), e.g. ["AAPL", "BTC:CRYPTO", "SPY260313P00670000:OPTION"]. security_type: Only orders of this instrument type. One of EQUITY, OPTION, MULTI_LEG_INSTRUMENT, CRYPTO, ALT, TREASURY, BOND, INDEX, EVENTCONTRACT. open_close_indicator: OPEN or CLOSE (set on option and shorting orders only). created_after: Only orders created at or after this ISO 8601 timestamp (e.g. 2026-09-01T00:00:00Z). Cannot reach back more than 30 days. created_before: Only orders created before this ISO 8601 timestamp.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "search_orders"
  }
}

Input Schema

Name	Required	Description	Default
`side`	No
`status`	No
`symbols`	No
`account_id`	No
`created_after`	No
`security_type`	No
`created_before`	No
`open_close_indicator`	No

Output Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Addedv0.8.0Oct 16, 2026

TDQS

A4.9/5.0

Behavior5/5

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

Annotations (readOnlyHint, openWorldHint, destructiveHint=false) already cover the safety profile, and the description adds real context beyond them: two API-enforced limits (30-day searchable window, 500-result cap), AND semantics across all optional filters, and the fact that created_after cannot reach back past the window. No contradiction with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with purpose, then differentiation, then limits, then result shape, then args — a sensible order and nothing is filler. It is somewhat long, and the detailed enumeration of `trades` fields and `equityMarketSession` values is arguably redundant given an output schema exists, but the density is justified for an 8-param search tool.

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 filter-heavy search tool with zero schema descriptions, the definition covers scoping, limits, default behavior, filter combination semantics, parameter enums/formats and result shape. Nothing an agent needs in order to call it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description carries the full burden and does: it documents all eight parameters with enumerated values (status list, BUY/SELL, nine security types, OPEN/CLOSE), symbol syntax with concrete examples including crypto and option formats, ISO 8601 timestamp format with an example, and the account_id fallback to PUBLIC_COM_ACCOUNT_ID. It adds far more meaning than the bare schema.

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 ('Search the account's order history') plus the scope (any status, last 30 days), and explicitly contrasts itself with the sibling get_orders, which only returns open/active orders. An agent can pick between the two without opening either schema.

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 says when to use this vs. get_orders ('order-history endpoint' vs. 'portfolio snapshot'), states all filters are optional and AND-combined, tells the agent that calling with no filters lists everything, and instructs how to narrow when a result set could exceed the 500-order cap. When-to-use, defaults and the alternative are all covered.

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

Deploy Server