firstrade-mcp-server

Overview Schema Source Related Servers Discussions Admin

preview_option_order

Check an option order in dry-run mode to validate pricing and terms, then get a one-time confirm token to pass with the identical order for actual placement.

Instructions

Preview an option order WITHOUT sending it (dry_run=True). Always call this first.

Args: option_symbol: OCC format symbol (e.g. 'AAPL250620C00150000'). order_type: buy_to_open | sell_to_close | sell_to_open | buy_to_close ('buy' = buy_to_open, 'sell' = sell_to_open; to exit a long option you MUST use sell_to_close, otherwise Firstrade treats it as opening a short and rejects with ref 1103). contracts: Number of contracts. price_type: limit | market | stop | stop_limit duration: day | day_ext | gt90 price: Limit price per contract (required for limit orders). stop_price: Stop trigger price (required for stop/stop_limit orders).

Returns JSON with order preview confirmation data, plus "confirm_token": pass that token unchanged to place_option_order (with the identical order arguments) to actually send it. The token expires in 10 minutes and works once.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "option_symbol": "<option_symbol>",
      "order_type": "<order_type>",
      "contracts": "<contracts>"
    },
    "name": "preview_option_order"
  }
}

Input Schema

Name	Required	Default
`price`	No
`duration`	No	day
`contracts`	Yes
`order_type`	Yes
`price_type`	No	limit
`stop_price`	No
`option_symbol`	Yes

Output Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Sep 10, 2026

TDQS

A5/5.0

Behavior5/5

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

With no annotations, the description fully discloses the crucial behavior: it is a dry run that does not send the order, the returned token is single-use, expires in 10 minutes, and must be passed to the placement tool with identical arguments. It even documents broker-specific rejection behavior (ref 1103).

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?

Dense but efficient: every sentence contributes purpose, parameter semantics, or workflow behavior. The token flow and the critical sell_to_close warning earn their place.

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?

Covers all seven parameters despite zero schema descriptions, specifies required conditions, explains return value and token usage, and gives a concrete error-code warning. Nothing needed for correct invocation is left implicit.

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 coverage is 0%, so the description carries full responsibility for parameter meaning. It explains the OCC symbol format, enumerates allowed values for order_type, price_type, and duration, clarifies aliases, and states which prices are required for which order types.

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 ('Preview') and resource ('option order') and immediately clarifies it does NOT send the order (dry_run=True). This distinguishes it from place_option_order and preview_stock_order without ambiguity.

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?

Provides explicit guidance: 'Always call this first,' and explains that the returned confirm_token must be passed to place_option_order with identical arguments to actually send. It also gives a concrete exclusion warning about when Firstrade rejects sell orders unless sell_to_close is used, which routes the agent away from a common mistake.

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

Deploy Server