Skip to main content
Glama
alpacahq

alpaca-mcp-server

Official
by alpacahq
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

Place Option Order

place_option_order
Destructive

Submit single-leg or multi-leg options orders to Alpaca. Specify symbol, side, and quantity, or provide up to four legs with ratio quantities, to open or close option positions.

Instructions

Place an options order (single-leg or multi-leg).

For single-leg orders, provide symbol, side, and qty. For multi-leg orders, provide qty, legs, and optionally order_class="mleg" (auto-inferred). Symbol and side on the parent are not needed for multi-leg.

Input Schema

NameRequiredDescriptionDefault
qtyYesNumber of contracts. Required for both single-leg and multi-leg orders. For multi-leg, this is the strategy multiplier — each leg's ratio_qty is scaled by this value (e.g., qty="10" with ratio_qty="2" = 20 contracts for that leg).
legsNoList of leg dicts for multi-leg orders (max 4). Each leg requires "symbol" and "ratio_qty" (string). Optional per-leg fields: "side" ("buy" or "sell") and "position_intent".
sideNo"buy" or "sell". Required for single-leg.
typeNo"market", "limit", "stop", or "stop_limit" for single-leg. Multi-leg supports only "market" and "limit".market
symbolNoOCC option symbol (e.g., "AAPL250321C00150000"). Required for single-leg.
stop_priceNoRequired for stop and stop_limit orders. Single-leg only.
limit_priceNoRequired for limit and stop_limit orders. For multi-leg, this is the net debit/credit (positive = debit/cost, negative = credit/proceeds).
order_classNoSet to "mleg" for multi-leg orders. Automatically inferred when legs are provided.
time_in_forceNo"day" or "gtc".day
client_order_idNoUnique idempotency key. If the request times out, you can safely retry with the same value — the API will reject duplicates. Recommended for every order.
position_intentNo"buy_to_open", "buy_to_close", "sell_to_open", or "sell_to_close". Clarifies whether the trade opens or closes a position. Optional but recommended.

Output Schema

NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed4 schema fields changedv2.4.0
    • changedInput schema / properties / limit_price / description
      Previous value: -"Required for limit orders. For multi-leg, this is\n         the net debit/credit (positive = debit/cost,\n         negative = credit/proceeds)."New value: +"Required for limit and stop_limit orders. For\n         multi-leg, this is the net debit/credit\n         (positive = debit/cost, negative = credit/proceeds)."
    • addedInput schema / properties / stop_price
      Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Required for stop and stop_limit orders. Single-leg\n        only."
+}
    • changedInput schema / properties / time_in_force / description
      Previous value: -"\"day\" only. Options do not support other\n           values."New value: +"\"day\" or \"gtc\"."
    • changedInput schema / properties / type / description
      Previous value: -"\"market\" or \"limit\"."New value: +"\"market\", \"limit\", \"stop\", or \"stop_limit\" for single-leg.\n  Multi-leg supports only \"market\" and \"limit\"."
  2. Changed10 schema fields changedv2.3.2
    • addedInput schema / properties / client_order_id / description
      Added value: +"Unique idempotency key. If the request times out,\n             you can safely retry with the same value — the API\n             will reject duplicates. Recommended for every order."
    • addedInput schema / properties / legs / description
      Added value: +"List of leg dicts for multi-leg orders (max 4). Each leg\n  requires \"symbol\" and \"ratio_qty\" (string). Optional\n  per-leg fields: \"side\" (\"buy\" or \"sell\") and\n  \"position_intent\"."
    • addedInput schema / properties / limit_price / description
      Added value: +"Required for limit orders. For multi-leg, this is\n         the net debit/credit (positive = debit/cost,\n         negative = credit/proceeds)."
    • addedInput schema / properties / order_class / description
      Added value: +"Set to \"mleg\" for multi-leg orders. Automatically\n         inferred when legs are provided."
    • addedInput schema / properties / position_intent / description
      Added value: +"\"buy_to_open\", \"buy_to_close\", \"sell_to_open\",\n             or \"sell_to_close\". Clarifies whether the trade\n             opens or closes a position. Optional but\n             recommended."
    • addedInput schema / properties / qty / description
      Added value: +"Number of contracts. Required for both single-leg and\n multi-leg orders. For multi-leg, this is the strategy\n multiplier — each leg's ratio_qty is scaled by this\n value (e.g., qty=\"10\" with ratio_qty=\"2\" = 20\n contracts for that leg)."
    • addedInput schema / properties / side / description
      Added value: +"\"buy\" or \"sell\". Required for single-leg."
    • addedInput schema / properties / symbol / description
      Added value: +"OCC option symbol (e.g., \"AAPL250321C00150000\").\n    Required for single-leg."
    • addedInput schema / properties / time_in_force / description
      Added value: +"\"day\" only. Options do not support other\n           values."
    • addedInput schema / properties / type / description
      Added value: +"\"market\" or \"limit\"."
  3. Addedv2.0.0

TDQS

A3.9/5.0
Behavior3/5

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

Annotations already declare destructive=true, openWorld=true, and idempotentHint=false, carrying the safety profile. The description adds structural behavior (order_class auto-inference, which fields are not needed for multi-leg) but says nothing about the idempotency caveat implied by idempotentHint=false, nor what state is affected.

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 the core action and then branches cleanly by order mode with no wasted sentences. The mid-sentence line breaks are slightly awkward but content is tight.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With a 100% documented schema, rich annotations, and an output schema handling returns, the description covers what an agent needs to correctly select and populate the call. It stops short of the idempotency/permission cautions that a destructive write tool could usefully flag.

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

Parameters3/5

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

Schema description coverage is 100%, so the schema already documents each parameter thoroughly. The description adds a useful mode-based grouping of parameters (symbol/side/qty vs qty/legs), but this is a mild reinforcement rather than new syntax or format detail.

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 (place) plus resource (options order) and explicitly scopes it to single-leg or multi-leg. This clearly distinguishes it from the sibling place_stock_order and place_crypto_order by asset class.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives conditional guidance: which parameters to supply for single-leg versus multi-leg, and notes order_class is auto-inferred. However, it never states when NOT to use this tool or routes the agent to alternatives (e.g., replace_order_by_id for modifications).

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

Deploy Server

Other Tools