alpaca-mcp-server

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

Annotations provide readOnlyHint=true and openWorldHint=true, indicating safe read operations with potentially large data. The description adds valuable context beyond this: it explains default lookback behavior, feed restrictions for free accounts (avoiding 403 errors), and data limits (max 10000 points). It does not contradict annotations and enriches understanding of practical constraints.

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 parameter explanations. It is appropriately sized for an 11-parameter tool, but some sentences could be more concise (e.g., the feed explanation is slightly verbose). Overall, it is front-loaded and informative without unnecessary fluff.

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 complexity (11 parameters, 0% schema coverage) and the presence of an output schema (which handles return values), the description is highly complete. It covers all parameters, behavioral nuances, and practical considerations like account limitations. No gaps remain for effective tool invocation.

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 fully compensates by explaining all 11 parameters in detail. It clarifies meanings (e.g., symbols as comma-separated tickers), defaults (e.g., minutes=20), interactions (e.g., start omission triggers lookback), constraints (e.g., limit range 1-10000), and critical usage notes (e.g., feed requirements for free accounts). This adds significant value beyond the bare 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 the specific action ('Retrieve historical trade data') and resource ('for one or more stocks'), distinguishing it from siblings like get_stock_bars, get_stock_latest_trade, or get_stock_quotes which focus on different data types or timeframes. It precisely defines what the tool does without being vague or tautological.

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 clear context for when to use certain parameters (e.g., 'When start is omitted...', 'Paper/free accounts must set feed="iex" to avoid 403 errors'), but it does not explicitly state when to use this tool versus alternative tools like get_stock_bars or get_stock_latest_trade. The guidance is operational rather than comparative.

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