preview_option_spread

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

With no annotations provided, the description carries the full behavioral disclosure burden and does so well: it states no order is sent, result contains a JSON preview plus confirm_token, the token expires in 10 minutes and works once, and complex orders are DAY-only with a 7AM–4PM ET window (ref 1110). This goes far beyond a generic 'previews an order' statement.

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 statement is front-loaded with the core purpose ('Always call this first') and then compactly lists parameters and operational constraints. No filler or repetition; the density is justified by the complexity of option spreads.

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?

The description tells the agent everything needed to invoke it correctly and handle the result: required arguments, transaction types, limit_type semantics, the confirm_token handoff, expiration, and Firstrade hours restriction. With no annotations and a bare schema, this is a fully self-sufficient description.

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?

The input schema has only parameter names and titles with zero descriptions, yet the docstring compensates fully: it explains OCC symbols, enumerates valid transaction values, defines limit_type, gives an example of debit call spreads, and notes default contract counts. Every schema parameter is meaningfully explained.

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 opens with a precise verb and resource: 'Preview a two-leg option spread WITHOUT sending it (dry_run=True).' It also says 'Always call this first,' which unambiguously frames the tool's role in the order workflow and distinguishes it from the actual send step (place_option_spread).

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 explicitly instructs that this tool should always be called first warnx and that the returned confirm_token must be passed unchanged to place_option_spread with identical arguments. This gives the agent a clear when-to-use rule and names the follow-up tool. It also states the dry_run behavior so users know no order is sent.

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