Skip to main content
Glama
alpacahq

alpaca-mcp-server

Official
by alpacahq
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

create_locate

Requests a short sale locate for a stock symbol and share quantity, with optional limit price and all-or-none flag. Unavailable in paper trading.

Instructions

Creates a locate request for a short sale. Requires a symbol and quantity. Optionally set a limit price and all-or-none flag. Not available in paper trading.

Input Schema

NameRequiredDescriptionDefault
qtyYesNumber of shares to locate. Must be positive and in round lots of 100; invalid quantities return HTTP 400.
symbolYesStock symbol.
all_or_noneNoReject the locate unless the full requested quantity is available.
limit_priceNoMaximum acceptable locate fee per share, as a decimal string in USD. If omitted, any quoted fee is accepted.
Idempotency-KeyNoOptional client-generated key for safe retries and duplicate request detection. This endpoint currently accepts keys up to 128 characters. Alpaca is moving toward a 36-character maximum; new implementations should generate a unique UUIDv7 or UUIDv4 value (36 characters including hyphens) for each logical operation. Do not reuse a key across operations.

Output Schema

NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv2.4.0
    • changedInput schema / properties / Idempotency-Key / description
      Previous value: -"Optional idempotency key for safe retries. Reusing the same key with\nthe same request returns the original locate response. Reusing the same\nkey with a different request returns HTTP 422.\nWe recommend always providing this header in production so timeouts,\nnetwork errors, and 5xx responses can be safely retried without creating\nduplicate locates. Use a client-generated unique value, such as a UUID,\nfor each logical locate.\n"New value: +"Optional client-generated key for safe retries and duplicate request detection.\nThis endpoint currently accepts keys up to 128 characters. Alpaca is moving toward\na 36-character maximum; new implementations should generate a unique UUIDv7 or\nUUIDv4 value (36 characters including hyphens) for each logical operation. Do not\nreuse a key across operations.\n"
  2. Addedv2.3.2

TDQS

A3.8/5.0
Behavior3/5

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

With no annotations, the description carries the full behavioral burden. It usefully discloses one non-obvious constraint (paper trading unavailable), but says nothing about fee/cost implications, whether a locate reserves shares or expires, or auth requirements for a mutation.

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?

Four short, front-loaded sentences with no filler and the purpose stated first. Sentences two and three largely echo the schema's required/optional split, which is mild redundancy rather than waste.

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

Completeness3/5

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

An output schema exists, so return values need no explanation, and the parameter surface is fully covered by the schema. What remains thin is behavioral context for an unannotated mutation tool — expiry, reservation semantics, and auth — which the description does not address.

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 coverage is 100%, so rounding rules, limit_price format, all_or_none semantics, and idempotency guidance are already fully documented in the schema. The description only restates required vs optional status, adding no syntax or meaning beyond the structured fields. Baseline 3 applies.

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 ('Creates a locate request for a short sale'), which cleanly separates it from the sibling read tools get_locate, get_locates, and get_locate_quotes. An agent can identify what this does without opening the schema.

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 clear preconditions (symbol and quantity required) and a genuine when-not constraint ('Not available in paper trading'). It stops short of pointing to an alternative (e.g. get_locate_quotes for price discovery before committing to a locate), so routing is left partly to inference.

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