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

The description adds substantial context beyond annotations: it flags that a real trade executes, specifies the DAY time-in-force, and discloses the non-obvious fallback behavior (ask lookup via event_symbol, rounded up to a whole cent) when limit_price is omitted. It does not state what happens to an unfilled DAY order or warn that retrying a non-idempotent buy could double-execute, which would be valuable for a money-moving tool.

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?

Front-loads purpose, then the risk warning, then the workflow, then parameters — the right order for a destructive-adjacent tool. The Args block is lengthy but every line carries non-redundant constraint detail that the 0%-coverage schema lacks.

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?

An output schema exists, so return values need no explanation; given that, the description covers the risk profile, ordering workflow, symbol provenance, and every parameter constraint. Nothing an agent needs to invoke this correctly is missing.

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?

Schema description coverage is 0%, so the description must carry all five parameters — and it does: example symbols for contract_symbol and event_symbol, quantity default and 2-decimal constraint, limit_price as dollars with whole cents bounded 0.01–0.99, the conditional requirement that event_symbol is needed when limit_price is omitted, and account_id's env-var fallback. This adds genuine meaning the bare schema cannot.

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?

States a specific verb (Buy), resource (event contract, defined parenthetically as the YES or NO side of a prediction market), and mechanism (DAY limit order). This clearly separates it from preflight_buy_event_contract and the generic place_order siblings without the agent needing to open any schema.

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?

Gives an explicit prerequisite ('Consider running preflight_buy_event_contract first') and a concrete end-to-end workflow for the recurring-market case, naming get_current_event, get_event_details, and wait_for_settlement in sequence. It also states the exclusion case for contract_symbol (not the '-EVENTCONTRACT' symbol used by get_event_contract_bars), so the agent knows which sibling takes which symbol form.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, openWorldHint=true, and idempotentHint=false. The description adds meaningful context beyond annotations: the operation is atomic, modifies an existing order, and is limited to specific asset types. It does not describe failure behavior or permission requirements, but the annotation coverage lowers the burden.

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 front-loaded with the atomic cancel-and-replace purpose and a warning that it modifies an existing order. The Args section is structured and each entry earns its place by clarifying a parameter. There is no wasted text.

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 tool has an output schema, so return values need not be explained. For a nine-parameter destructive mutation, the description covers purpose, mutation warning, supported asset types, and detailed parameter semantics. Nothing essential for correct invocation is missing.

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?

Schema description coverage is 0%, so the description carries the full burden of explaining parameters. It documents all nine parameters, including allowed order_type values, time_in_force default, mutual exclusivity of quantity and amount, conditional requirements for limit_price and expiration_time, and the optional account_id fallback. This is a strong compensation for the schema gap.

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 states a specific verb and resource: atomically cancel an existing order and replace it with new parameters. This distinguishes it from the sibling cancel_order and place_order tools by making the combined atomic replacement explicit. An agent can identify the operation 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.

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

The description provides clear usage context: it modifies an existing order and is supported for equity, option, and crypto quantity orders. It does not explicitly name alternatives such as using cancel_order followed by place_order, nor does it state when not to use this tool. The context is clear but exclusions and alternatives are absent.

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

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

The description adds behavioral context beyond annotations: cancellations may not be immediate during market hours, and confirmation via get_order is recommended. This complements the destructiveHint and idempotentHint annotations.

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 concise with a header, a brief note, and parameter docs. No extraneous text. Front-loaded with the main purpose.

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 output schema exists (though not detailed), the description covers key behavioral aspects (non-immediate cancellation, confirmation). It might lack details on edge cases (already cancelled order), but is sufficient for a simple cancel tool.

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 provides essential context: order_id is the UUID, account_id is optional if PUBLIC_COM_ACCOUNT_ID is set. This meaningfully compensates for the lack of schema descriptions.

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 'Cancel an existing order.' This is a specific verb and resource, and it distinguishes from siblings like 'cancel_and_replace_order' by implication. The note about non-immediate cancellation adds clarity.

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 advises using get_order to confirm cancellation, providing a clear after-use action. It does not explicitly list when not to use, but the note about non-guaranteed immediate cancellation sets expectations. Sibling 'cancel_and_replace_order' exists but is not contrasted.

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

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

The description adds value beyond annotations by detailing that it checks an environment variable and attempts authentication. Annotations already indicate readOnlyHint=true, but the description gives concrete behavioral context about what is actually verified.

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 just two sentences, front-loads the purpose, and contains no fluff. Every sentence is necessary and informative.

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 tool has no parameters, has an output schema, and annotations are present, the description is complete. It explains what the tool does, what it checks, and when to use it.

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 tool has no parameters, and schema description coverage is 100% (trivially). The description does not need to add parameter information, and with zero parameters a baseline of 4 is appropriate.

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 tool verifies Public.com API credentials, checks the PUBLIC_COM_SECRET environment variable, and attempts authentication. This is a specific verb-resource pair that clearly distinguishes it from sibling tools, which focus on orders, accounts, and other operations.

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 says 'Run this first to confirm connectivity,' providing clear context for when to use the tool as a prerequisite. It does not explicitly list exclusions or alternatives, but the guidance is sufficient for a setup validation tool.

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

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

Adds substantial behavior beyond the annotations: it is flagged experimental, non-atomic across two real orders, subject to price movement between fill and entry, and parameterized by a flatten_timeout (default 60s) with described skip semantics. Annotations declare destructive/openWorld/non-idempotent, and the description's warning reinforces rather than contradicts them.

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?

Front-loads the action and the experimental/non-atomic warning before the Args block, so risk is seen first. The Args list is long but each line earns its place given 0% schema coverage; only minor trimming is possible.

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?

For a 10-parameter destructive trading workflow, the description covers the two-order sequencing, skip behavior, timeout, order-type/price dependencies and account resolution; return values are covered by the output schema, so nothing an agent needs to invoke it safely is missing.

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?

Schema description coverage is 0%, so the description carries full burden and does: every one of the 10 parameters is named with meaning, enum values (MARKET, LIMIT, STOP, STOP_LIMIT, MARKET_ON_CLOSE, LIMIT_ON_CLOSE; DAY/GTD; CORE/EXTENDED), defaults, and conditional requirements (limit_price for LIMIT/STOP_LIMIT/LIMIT_ON_CLOSE, stop_price for STOP/STOP_LIMIT, expiration_time for GTD, ISO 8601 format, account_id fallback to PUBLIC_COM_ACCOUNT_ID). This is exactly what the missing schema descriptions need.

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?

States a specific two-step verb sequence (sell existing long, then place short) on a named resource (symbol position). It is clearly distinguishable from sibling place_short_order and place_order because it names the flatten-then-short workflow explicitly.

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?

Explains the key conditional path: if no long position exists the flatten step is skipped and only the short is placed, so the agent knows the tool is safe to call in both states. It stops short of naming place_short_order or preflight_short_order as the alternatives when a pure short entry (without flattening) is wanted.

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

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

Annotations already provide readOnlyHint=true, so description adds value by specifying the return format (account IDs and types). No contradiction, and no additional behavioral details needed.

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?

Two sentences, front-loaded with the main action, no wasted words. Ideal conciseness.

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 no parameters, presence of output schema, and annotations, the description covers the essential information. Could be slightly more explicit about scope (e.g., 'all accounts for API key'), but it's sufficient.

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?

No parameters, so baseline 4 applies. The description correctly adds no parameter information beyond what schema provides.

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 action (list) and resource (brokerage accounts), and mentions the return value (account IDs and types). This distinguishes it from sibling tools like get_portfolio or get_orders.

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?

No explicit when-to-use or when-not-to-use guidance. However, the purpose is clear and context implies it's for enumerating accounts, which is adequate for a simple list tool.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, covering the safety profile. The description adds valid filter values and the account_id environment fallback, but does not disclose pagination, rate limits, or default result size beyond what annotations imply.

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?

Front-loaded purpose sentence followed by a concise Args block that lists only necessary parameter details. No filler or repetition; the structure is appropriate for a tool with three undocumented parameters.

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 list/filter complexity and empty schema descriptions, the description covers purpose and all parameters adequately. It omits default behavior when filters are absent (return all instruments) and any pagination details, but the output schema presumably documents the return shape.

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?

Schema coverage is 0%, so the description must document all three parameters, and it does: type_filter and trading_filter include exhaustive valid value lists, and account_id explains its optionality and env fallback. This fully compensates for the empty schema descriptions.

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?

Clearly states the verb 'List' and resource 'all available tradeable instruments', and the scope 'with optional filters'. It implicitly distinguishes from the singular sibling get_instrument by emphasizing 'all', though it does not name the alternative explicitly.

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?

Provides valid filter values and notes that account_id is optional if PUBLIC_COM_ACCOUNT_ID is set, which is useful setup context. However, it does not say when to choose this tool over get_instrument or how it relates to other listing/search tools, so guidance is incomplete.

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

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

The annotations already establish read-only behavior via readOnlyHint=true and destructiveHint=false. The description adds behavioral detail by specifying the content domains (pricing, ratings, coupon schedule, maturity, call information) and the symbol format requirement. It does not contradict the annotations and provides context beyond what annotations convey, though it omits edge-case behavior like not-found handling.

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 compact and well-structured: a two-sentence overview followed by an Args section. It is front-loaded with purpose and return categories, contains no filler, and every sentence contributes to understanding the tool.

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 only two parameters (one required), a read-only annotation, and an output schema, this description is fully adequate. It explains both parameters, lists the return categories, and fits within the broader tool context. No critical information is missing.

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 zero descriptions (0% coverage), so the description carries the full burden. It explains symbol format with a concrete example ('912810TM0-BOND') and clarifies that account_id is optional if PUBLIC_COM_ACCOUNT_ID is set. This turns otherwise opaque schema properties into actionable parameter guidance.

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 verb and resource: 'Get comprehensive details for a single bond.' It also enumerates the specific types of information returned (pricing, ratings, coupon schedule, maturity, call info), which distinguishes it from sibling tools like search_bonds or get_instrument. The scope ('single bond') and identification method ('by its symbol') are explicit.

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 usage context is clear: this tool is for when you already have a bond symbol and need comprehensive details. It mentions the optional account_id and the environment variable fallback, which is practical guidance. However, it does not explicitly name alternative tools or state when not to use this tool, so it stops short of a full 5.

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

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

Annotations establish readOnly/destructive/openWorld, but the description adds non-obvious behavior the annotations cannot: windows whose resolution time has passed are skipped even though the API still lists them as unresolved, and the next window typically appears a minute or two after the prior close. This prevents an agent from grabbing a stale event.

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?

Purpose and the stale-window caveat are front-loaded, followed by the chaining guidance and a conventional Args block. It runs slightly long and the Args section restates parameter names, but each entry adds semantics absent from the schema, so the length is earned.

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?

An output schema exists, so return-value documentation isn't required, yet the description still names the key output field (eventSymbol) and how to consume it. Combined with the empty schema coverage and the wait/retry semantics, an agent has everything needed to call this correctly.

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?

Schema description coverage is 0%, so the description carries the full burden and does: series is tied to the `series` field of get_event_summary/get_event_details, category relates to get_event_categories with a performance hint, frequency's default and use case are explained, and wait_seconds' range (0–120) and default (0 = check once) are spelled out. Every parameter gains meaning 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?

Opens with a specific verb and resource: 'Find the event of a recurring market that is trading right now,' then pins down the exact semantics ('the open event of the series that closes soonest'). This clearly distinguishes it from siblings like get_event_summary, get_event_details, and get_event_categories without requiring schema inspection.

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?

Explicitly routes the agent through the downstream workflow: pass eventSymbol to get_event_details for contracts and asks, then preflight_buy_event_contract to price a buy. It also states the between-windows condition and how to handle it via wait_seconds, covering the main ambiguity an agent would face.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds real value beyond them by describing the shape of each returned item (subcategories and supported frequency filters) and the intended downstream call, which tells the agent how the result plugs into the workflow.

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?

Three short sentences with zero padding; the core purpose is front-loaded and the follow-up action is stated last. Every sentence carries information.

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?

For a zero-argument enumeration tool with an output schema present and annotations covering safety, the description supplies everything needed: what it returns, that it is safe/read-only, and where to go next. No material gap remains.

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 tool takes zero parameters, so the baseline is 4. The description's only parameter-relevant content is describing how values returned here feed get_event_summary's `category`/`subcategory` inputs, which is contextual rather than a gap.

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?

States a specific verb and resource ('List the categories for browsing event contracts'), scopes it to prediction markets, and implicitly separates it from get_event_summary, which handles the events themselves. An agent can tell immediately this is the enumeration/entry-point call.

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?

Explicitly routes the agent forward: 'Pass a returned `category` (and optionally `subcategory`) to get_event_summary'. That is clear next-step guidance. It does not state when not to use this tool or any prerequisites (e.g. needing setup/auth first), so it stops short of a 5.

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

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

Adds substantial behavior beyond the readOnlyHint/destructiveHint=false annotations: prices are dollars 0.00-1.00 equal to implied probability, '.N' symbols carry NO prices, bars start at the first priced period so multiple series can start at different timestamps and must be aligned by timestamp not index, and unknown/unpriced symbols are silently dropped. These are exactly the caveats an agent needs to interpret the response.

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?

Front-loads the highest-value semantics (price units and probability interpretation) before the argument details. Dense but purposeful; only the chart-alignment aside is slightly tangential, so it falls just short of perfectly tight.

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?

With 3 required parameters, 0% schema coverage, and an output schema already present, the description supplies everything else an agent needs: parameter meaning, identifier routing, unit conventions, and dropped-symbol behavior. Return-value explanation is correctly left to the output schema.

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?

Schema description coverage is 0%, so the description carries the full burden and does so: event_id format and server-side validation, period's enum meaning including the 'measured back from now or from event close once trading stopped' nuance, and symbols' count range with a concrete example. Every parameter is meaningfully documented beyond the bare schema types.

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?

Opens with a specific verb and resource: 'Get price-history bars for up to 8 event contracts of one event.' It explicitly separates itself from siblings by noting it takes charting identifiers rather than the discovery identifiers used by get_event_summary / get_event_details. An agent can tell what this returns and how it differs from the discovery tools without opening a schema.

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?

Gives clear context on which identifiers to pass and warns that the API rejects non '-EVENT' ids, plus the 1-8 symbol bound. It does not explicitly contrast with the sibling get_price_history or state a when-not-to-use condition, but the identifier routing is a solid usage signal.

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

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

Annotations already cover read-only/non-destructive, but the description adds substantial context beyond them: prices are dollars 0.00–1.00 equal to implied probability, outcome ids lack exchange prefixes while contract symbols carry them, and unknown eventSymbols return error code 7004. It also discloses SDK-derived fields (tradable, secondsLeft, winner) and the subtlety that raw state can still read STATE_OPEN after close — behavior an agent could not infer from the schema.

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?

Purpose and the highest-value caveat (which symbol id to pass) are front-loaded, and the Args block is clean. However, a large share of the text enumerates return payload fields even though an output schema exists, which is work the structured data already does; trimming that would sharpen the definition without losing routing information.

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?

An output schema exists, so return values need not be restated; combined with the read-only annotations, the description still supplies the semantic layer (pricing units, id formats, error code, truncation behavior) an agent needs to call this correctly. Nothing material is missing for a two-parameter read tool.

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?

Schema description coverage is 0%, so the description must carry the burden and it does: event_symbol is documented by source (get_event_summary), example format, anti-pattern (not the '-EVENT' id), and failure mode (error 7004). include_all_outcomes is documented with its default (True), the behavior when False (short list of up to 8), and the invariant that outcomeCount always reports the full total.

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?

States a specific verb and resource ('Get full details for one event contract'), with the parenthetical clarifying what a prediction-market event is. It is clearly distinguishable from siblings: it names get_event_summary as the source of the symbol and get_event_contract_bars as the tool that takes a different id, so an agent can route without opening schemas.

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?

Routing is effectively spelled out through the argument guidance — call get_event_summary first, take its eventSymbol, and do not reuse the '-EVENT' id consumed by get_event_contract_bars. It also explains when to set include_all_outcomes to false. It stops short of an explicit 'use this instead of get_event_summary when…' statement, so it is not a full 5.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, yet the description adds real behavioral value: 100-item page cap, resolved and halted events being included, the warning that related instrument symbols are often empty and are NOT the event's contracts, and how `series` is derived. The one omission is that it doesn't note whether display_resolved_events interacts with the resolved-events-included note, but overall this is well beyond the annotation bar.

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?

Front-loaded with purpose and return shape, then pitfalls, then a clean Args block; nearly every line earns its place. Slightly verbose where it restates the eventSymbol identifier warning across multiple sentences, but the redundancy is mild and useful given zero schema descriptions.

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?

For a 10-parameter, paginated discovery tool this covers what an agent needs: what a page contains, how to continue, what the identifiers mean, and which siblings to call next. An output schema exists, so explaining return values in depth isn't required — the description supplies the identifier caveats instead, which is the right thing for it to spend words on.

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?

Schema description coverage is 0%, so the description carries the full burden — and it does, documenting all ten parameters including acceptable frequency values, ISO 8601 format for the resolution windows, the source of category (get_event_categories), and the pagination contract for next_token.

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?

Opens with a specific verb and resource: "Browse event contracts (prediction-market events), one page at a time." It further disambiguates the identifier space (eventSymbol vs the "-EVENT" id used by get_event_contract_bars) and routes to get_event_details and get_current_event, so an agent can tell it apart from siblings without opening schemas.

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?

Gives explicit downstream routing ("Pass an eventSymbol to get_event_details for its outcomes, YES/NO contracts and pricing") and complete pagination instructions (call again with the same arguments plus next_token; token absent on the last page). Defaults and enumerated values for sorting_mode and frequencies are stated as well, leaving nothing to inference.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds value by specifying the types of data returned (trades, money movements, adjustments) and pagination behavior, which goes beyond the annotations.

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 concise, with a brief introductory sentence, a list of return types, and then parameter documentation in a clean Args block. No unnecessary information, and the most important details are front-loaded.

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 covers the core functionality, return types, and parameter semantics. However, it lacks behavioral details like default date ranges, default page_size, and behavior when parameters are omitted. Output schema exists, which supplements completeness.

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 schema description coverage at 0%, the description fully explains each parameter: account_id (optional with env var fallback), start/end (ISO 8601 format), page_size (max records), next_token (pagination). This is excellent for agent understanding.

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 tool retrieves account transaction history and lists the types of transactions included (trades, money movements, adjustments). This distinguishes it from sibling tools like get_orders and get_portfolio.

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 does not explicitly state when to use this tool instead of alternatives, such as get_orders for orders or get_portfolio for positions. The usage is implied by the purpose, but no direct guidance is provided.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety and reach profile is covered. The description adds the return content (trading status, fractional trading, option capability), but since an output schema exists this is largely redundant rather than genuinely new behavioral context.

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?

Purpose and return contents are front-loaded in two sentences, then parameters follow in a clean Args block. Slightly longer than strictly necessary given the output schema, but every line carries usable information.

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?

For a two-parameter read tool, nothing material is missing: both parameters are documented including the enum the schema omits, the return fields are previewed, and safety semantics come from annotations plus the output schema.

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?

Schema description coverage is 0% and the schema declares no enum, so the description carries the full parameter burden — and does so: it gives the symbol format with an example and spells out all eight valid instrument_type values plus the EQUITY default. Without this text the agent could not supply instrument_type correctly.

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?

States a specific verb+resource ('Get details about a specific tradeable instrument') and immediately enumerates what those details are. The singular 'a specific' implicitly contrasts with the sibling get_all_instruments, letting an agent route correctly without opening either schema.

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?

Usage is implied by 'a specific instrument', but there is no explicit when-to-use, no prerequisites, and no mention of alternatives such as get_all_instruments or get_option_chain. An agent can infer intent but must guess at the boundaries.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true. The description adds that it returns calls and puts but does not elaborate on error handling, authentication needs, or response structure. Adequate but not enhanced.

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?

Description is concise with a front-loaded purpose and a well-structured argument list. No unnecessary words.

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 presence of an output schema covering return values, the description is nearly complete. It explains parameters well but could mention that account_id may be required despite being optional. Still, it is sufficient for most use cases.

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?

Despite 0% schema description coverage, the tool description provides clear explanations for all parameters, including format, default, and optionality, compensating fully for the schema's lack of descriptions.

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?

Clearly states the tool gets the full option chain (calls and puts) for a symbol and expiration. Differentiates from siblings like get_option_expirations and get_option_greek by specifying 'full option chain'.

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?

No explicit guidance on when to use this tool vs. siblings such as get_option_expirations or get_option_greek. The description lacks context on prerequisites or alternatives.

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

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

Annotations already indicate readOnlyHint=true and destructiveHint=false. The description adds value by noting that account_id is optional if PUBLIC_COM_ACCOUNT_ID is set, revealing an authentication behavior. However, no further behavioral details are given beyond the annotations.

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 concise with a clear front-loaded purpose and parameter explanations in a structured list. Every sentence adds value, though it could be slightly more streamlined.

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 presence of an output schema, the description does not need to explain return values. It covers the tool's purpose, all parameters with context, and an authentication nuance. The tool is simple and the description is complete for effective use.

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?

Although schema coverage is 0%, the description adds meaning to parameters: symbol is an underlying ticker, instrument_type has two specific values (EQUITY or UNDERLYING_SECURITY_FOR_INDEX_OPTION), and account_id is optional under a specific condition. This provides clarity beyond the schema's type definitions.

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 tool's purpose: 'Get available option expiration dates for a symbol.' This specific verb and resource distinguish it from siblings like get_option_chain or get_option_greek, which serve different purposes.

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?

No explicit guidance on when to use this tool versus alternatives. The description does not mention when not to use it or provide context for tool selection among siblings like get_option_chain.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description doesn't need to repeat safety. It adds minimal behavioral context beyond purpose, such as mentioning the specific Greeks returned. No contradictions, and the presence of an output schema reduces the need to describe return values, but no additional traits (e.g., rate limits, caching) are disclosed.

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 extremely concise: two sentences and a parameter list. Every sentence adds value, with no redundancy or fluff. It is front-loaded with the main action and then details the parameters.

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 simple nature of the tool (get greeks for one symbol), the presence of an output schema (reducing need to describe returns), and good parameter coverage, the description is complete. It covers all necessary input details for an agent to invoke the tool correctly.

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?

Schema description coverage is 0%, so the description must compensate. It does so effectively by explaining 'osi_symbol' as an OSI-normalized option symbol with an example ('AAPL260320C00280000') and clarifying that 'account_id' is optional if the environment variable is set. This adds significant meaning beyond the schema's type-only definitions.

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 tool retrieves option Greeks (delta, gamma, theta, vega, rho, IV) for a single option symbol. It distinguishes itself from sibling tools like 'get_option_greeks' (likely bulk) and 'get_option_chain' (full chain) by specifying 'single option symbol' and listing specific Greeks.

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 explicit parameter guidance: 'osi_symbol' is required and shown with an example, 'account_id' is optional if PUBLIC_COM_ACCOUNT_ID is set. This indicates when to use the tool (when you have a single OSI symbol). It does not explicitly state when not to use or mention alternatives, but the sibling context makes it clear.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description does not need to repeat safety traits. It adds no behavioral details beyond stating that it retrieves Greeks, which is consistent with the annotations. No contradictions.

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 concise with a one-line purpose statement followed by a structured Args section. It is front-loaded with the main action. Every sentence provides useful information, though the Args formatting is slightly more verbose than necessary.

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 tool has an output schema (not shown), the description need not detail return values. It covers input parameters adequately but omits information about error handling, rate limits, or behavior for invalid symbols. The description is adequate for a simple 2-parameter tool but not fully complete.

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?

Schema description coverage is 0%, so the description must compensate. It provides a meaningful explanation of 'osi_symbols' with an example format ('OSI-normalized option symbols') and clarifies that 'account_id' is optional if the environment variable is set. This adds significant value over 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 tool returns option Greeks (delta, gamma, theta, vega, rho, IV) for option symbols. It uses specific verb 'Get' and resource 'option Greeks.' However, it does not explicitly differentiate from its sibling 'get_option_greek' (singular), though the plural name and array parameter imply batch usage.

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?

No guidance is provided on when to use this tool versus alternatives, such as the singular 'get_option_greek' or other option-related tools. There is no discussion of prerequisites, scenarios, or exclusions.

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

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

Annotations already flag readOnly/openWorld/non-destructive, and the description adds real behavioral context beyond them: the 30-day retention window with a not-found error, the async indexing failure mode, and the exact response shape including equityMarketSession enum values and MIC semantics.

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?

Front-loaded with the core purpose and well organized in short paragraphs, but the detailed enumeration of return fields (tradeId, quantity, price, side, timestamp, MIC explanation) partly duplicates the output schema and lengthens the definition.

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 two params, an output schema, and read-only annotations, everything an agent needs is present: lookup limits, error conditions, bracket handling, and optional-account behavior. No material gaps.

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?

Schema coverage is 0%, so the Args section carries the burden: order_id is documented as a UUID and account_id as optional when PUBLIC_COM_ACCOUNT_ID is set. That resolves the key ambiguity (when account_id can be omitted), though identifier format/validation detail is modest.

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?

States a specific verb and resource (get status/details of a specific order, including fills) and implicitly distinguishes itself from the plural get_orders / search_orders siblings by emphasizing one order via its UUID. The bracketId note further clarifies the single-order scope.

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?

Gives concrete usage context: only orders from the last 30 days are retrievable, and just-placed orders may not yet be indexed due to async placement. It also routes the agent to get_orders for bracket sibling legs. No explicit exclusion versus search_orders, so not a 5.

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

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

Annotations already declare the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=true), so the bar is lower. The description still adds real behavioral context: the underlying portfolio fetch happens but only the orders list is returned, and bracket orders carry a bracketId linking entry and exit legs. Pagination and result limits remain unstated.

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?

Front-loaded with the primary action, then outcomes, then a genuinely useful bracketId note, then the arg. The bracket explanation is a bit long for one field, but every sentence carries information.

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?

Covers the single optional parameter, the filtering scope, and the key return-shape nuance (bracketId grouping). An output schema exists, so the extra field enumeration is bonus rather than required; the only gap is pagination/ordering behavior.

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?

Schema coverage is 0%, so the description must compensate, and it does: it explains that account_id is optional when the PUBLIC_COM_ACCOUNT_ID environment/config value is present, which the schema (bare 'Account Id', default null) does not convey.

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?

Specific verb ('Get') plus resource ('open/active orders on the account') and it states the scope is the full account portfolio. It does not explicitly differentiate from the singular sibling 'get_order', so an agent must infer the distinction from the plural naming.

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?

'Get all open/active orders' implies the collection-level use case versus the singular 'get_order', and 'Optional if PUBLIC_COM_ACCOUNT_ID is set' implies the config prerequisite. However, no explicit when-to-use/when-not-to-use statement or named alternative is given.

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

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

Annotations already declare readOnlyHint, openWorldHint, and destructiveHint=false, so the safety profile is covered. The description adds value beyond that by disclosing the non-IRA account restriction and explaining how dayTradeBuyingPower behaves (equals buyingPower when not enabled, omitted when unreported).

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 purpose and return contents are front-loaded, and the account-type restriction appears early. The paragraph on dayTradeBuyingPower is slightly deep for a tool description, but it is scoped and relevant to interpreting the output.

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 an output schema already exists, the description needn't explain return formatting. It covers the key restriction, the optional-parameter fallback, and the one non-obvious field behavior, leaving no material gap for an agent to call it correctly.

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?

Schema description coverage is 0%, so the description must compensate, and it does: it labels account_id as an Account ID and explains that it is optional when PUBLIC_COM_ACCOUNT_ID is set. That resolves the practical ambiguity of a nullable, non-required parameter.

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 gives a specific verb and resource ('Get a snapshot of the account portfolio') and enumerates the contents (positions, equity breakdown, buying power, open orders, cash figures). This makes it clearly distinguishable from siblings such as get_accounts or get_orders, which do not return a consolidated snapshot.

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?

It states an important gating constraint ('Only non-IRA accounts are supported') and explains the optional-account_id fallback via PUBLIC_COM_ACCOUNT_ID. It does not explicitly route the agent away from alternatives, but the context is clear enough for correct selection.

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

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

Annotations already declare read-only/no-destructive, so the bar is lower, yet the description adds substantial behavioral context beyond them: the response structure (bars split into pre-market/regular/after-hours, previous close, total gain/loss), aggregation rejection behavior that lists valid options on error, the leadingFill object semantics, and the DAY-chart session toggle boundaries. This is rich disclosure not captured by structured fields.

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?

Purpose and routing are front-loaded before the Args block, and each parameter entry earns its place given 7 params and 0% schema coverage. It is long, but the length is largely warranted by the complexity; a few sentences (e.g. the full leadingFill key list) could be trimmed.

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?

For a 7-parameter tool with 0% schema coverage but an existing output schema, the description covers every parameter, the routing decision, and the non-obvious server-side behaviors. Nothing an agent needs to invoke it correctly is missing.

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?

Schema description coverage is 0%, so the description carries the full burden and does: it documents every parameter's meaning, formats (symbol, date 'YYYY-MM-DD'), defaults, conditional requirements (purchase_date only for SINCE_PURCHASE), and non-obvious edge behavior (invalid aggregation error, ipo_date fetch strategy, trading_session_toggle session windows).

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?

States a specific verb+resource+scope: 'Get historical OHLCV price bars for a symbol over a time period.' It explicitly distinguishes itself from get_quotes ('current price only') and get_history ('account activity, not prices'), so an agent can route correctly without opening any schema.

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?

Explicitly gives when-to-use ('trend analysis and historical prices') and names two sibling tools to avoid, plus a third alternative for a sub-case ('to chart several contracts of one event side by side, get_event_contract_bars is usually the better fit'). This is exactly the when/when-not/alternatives pattern.

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

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

Annotations already declare readOnlyHint, openWorldHint, and destructiveHint, so the safety profile is covered. The description adds useful behavioral context (env-var fallback for account_id, and the multi-call pattern for mixed types) but says nothing about rate limits, staleness, or failure behavior for a real-time quote source.

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?

Front-loaded with the purpose and return fields, then an Args block. The Args block largely mirrors the schema, but with 0% coverage that repetition is justified rather than wasteful.

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?

An output schema exists, so return values need not be detailed further, and the description already compensates for the zero schema coverage on all three parameters. Annotations cover safety, leaving no gap an agent needs to call this correctly.

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?

Schema description coverage is 0%, so the description carries the full burden and does so well: symbols is defined as a list of tickers with an example, instrument_type lists all eight valid values plus default, and account_id explains its optionality and fallback source.

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?

States a specific verb (Get) and resource (real-time quotes) with scope (one or more symbols) and enumerates the returned fields. This clearly distinguishes it from siblings like get_price_history and get_strategy_quote.

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?

Provides concrete usage context: instrument_type defaults to EQUITY, mixed instrument types require calling the tool multiple times, and account_id is optional when the env var is set. It stops short of naming sibling alternatives such as get_price_history for historical data.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description reinforces this by stating it is 'a read-only quote — it does NOT place or preflight an order,' adding behavioral context beyond annotations.

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 opening and parameter breakdown. While comprehensive, it is slightly lengthy; some details could be tightened without losing clarity.

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 of multi-leg options, the description covers all necessary aspects: parameters, optional fields, leg structure, and the read-only nature. An output schema exists, so return values need not be explained.

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?

Schema coverage is 0%, but the description fully documents all parameters, including the complex option_legs structure with required fields, optional fields, and an example. It explains each parameter's role clearly.

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 states a specific verb and resource: 'Get a consolidated quote for a multi-leg option strategy.' It distinguishes itself from siblings by clarifying it is a read-only quote and does not place or preflight orders.

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 indicates when to use (for pricing strategies) and explicitly states what it does not do (place/preflight order). However, it does not provide explicit when-not-to-use guidance or list alternative tools.

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

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

While annotations already declare readOnlyHint=true and destructiveHint=false, the description adds valuable behavioral context by specifying the return contents (per-lot unrealized gain/loss, holding term, cost basis, aggregate totals) and the authentication requirement (API key must have 'trading.read' scope). This goes beyond what annotations provide, without contradicting them.

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 concise and front-loaded: the first sentence states the primary purpose, the second details the return contents, and the Args section efficiently covers the one parameter. There is no superfluous text; every sentence earns its place.

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 tool's simple one-parameter interface and the presence of an output schema, the description adequately covers what it returns, the auth requirement, and parameter optionality. It doesn't need to explain return values in depth because an output schema exists, but it could have benefited from a brief note on when to choose this over the symbol-specific or CSV variants. Still, it is largely complete for its complexity.

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 schema provides only a default null and anyOf type for account_id, with 0% description coverage. The description fully compensates by explaining that account_id is 'Optional if PUBLIC_COM_ACCOUNT_ID is set,' thereby providing essential context about when it can be omitted and how the environment variable factor works. This is complete and clear for the sole parameter.

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 tool's function with a specific verb ('Get') and a precise resource: 'unrealized tax-lot summary for the account.' It further details what the summary includes (per-lot gains/losses, holding term, cost basis, aggregate totals), making its purpose unambiguous and distinguishing it from siblings like get_tax_lots_for_symbol and get_tax_lots_csv.

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?

There is no explicit guidance on when to use this tool versus its alternatives. The description does not mention the sibling get_tax_lots_for_symbol for symbol-specific queries or get_tax_lots_csv for CSV export, nor does it provide context about typical use cases. It only mentions the required scope, which is a prerequisite, not a usage guideline.

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

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

The description discloses that the return is a file object with fileName and base64Data, that the CSV is Base64-encoded, and that the API key must have trading.read scope. This adds significant behavioral context beyond the readOnlyHint and destructiveHint annotations and does not contradict them.

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 tight and front-loaded: purpose, return format, encoding, auth requirement, and parameter fallback are each covered in a few clear sentences with no filler. It earn its place.

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?

For a one-parameter export tool, the description fully covers purpose, output shape, encoding, auth, and optional parameter resolution. The output schema exists, but the return-format detail is still beneficial and does not leave gaps.

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 schema has one parameter with no description, and schema description coverage is 0%. The description's Args section compensates by noting account_id is optional and falls back to PUBLIC_COM_ACCOUNT_ID when set, adding operational meaning beyond the schema's default:null.

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 begins with 'Export the unrealized tax lots as a CSV file', using a specific verb and resource. The 'CSV' format clearly distinguishes it from sibling tools like get_tax_lots and get_tax_lots_for_symbol.

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 the tool: to export unrealized tax lots as a CSV file. It also states the required trading.read scope. However, it does not explicitly name alternatives or state when not to use it.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds meaningful context beyond annotations: it states the required API scope, explains that price is optional and defaults to current market price, and describes what fields are returned. No contradictions with annotations.

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: a one-sentence summary, a return-detail line, a scope requirement, then a concise Args list. Every sentence earns its place with no wasted words.

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 an output schema exists, return values are already partially documented. The description adds sufficient context: what lots are returned (gain/loss, term, cost basis), scope requirement, and parameter behavior. It is complete for a read-only single-symbol lookup tool.

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?

Schema coverage is 0%, but the description fully compensates with an Args section. It explains symbol with an example, price as an optional numeric string with omission behavior, and account_id as optional if a default is set. This goes well beyond the basic schema types.

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 starts with a specific verb+resource: 'Get the unrealized tax-lot detail for a single symbol.' It clearly distinguishes from sibling tools like get_tax_lots (all lots) and get_tax_lots_csv (export) by emphasizing the single-symbol scope.

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?

Provides clear context: it returns open lots with cost basis, can accept an optional price, and requires trading.read scope. It does not explicitly mention alternatives or when-not-to-use, but the single-symbol restriction is implied. Lacks explicit exclusion guidance for a 5.

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

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

Warns that the tool executes a real trade, which is critical behavioral context beyond annotations (which only indicate not read-only or destructive). Additional details like net credit are helpful; could elaborate on trade irreversibility but sufficient.

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?

Concise and well-structured: title, strategy explanation, warning, then parameter list. No wasted words; each sentence serves a purpose.

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?

Covers the essential aspects: what it does, how to use it, and when to use preflight. Could mention that this is a bearish strategy, but the title implies it. Output schema exists, so return values are covered. Complete for the task.

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 each parameter's meaning, constraints (e.g., 'lower strike' for sell, 'minimum net credit' for limit_price), and optionality, adding significant value.

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?

Explicitly states it places a Bear Call Spread, describes the mechanics (sell lower strike, buy higher strike, net credit), and is distinct from sibling tools like call debit spreads or put spreads.

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?

Clearly warns that this executes a real trade and recommends running preflight_call_credit_spread first, providing explicit when-to-use and alternative guidance.

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

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

Annotations indicate non-read-only, non-destructive, non-idempotent, open world. The description adds critical context: 'executes a real trade', which goes beyond the annotations by alerting about real financial risk. No contradictions.

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 concise (under 100 words), uses bullet points for args, and front-loads the purpose. Every sentence adds value, and the structure is clear.

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 (7 parameters, real trade execution) and that output schema exists, the description covers behavior, all parameters, and critical usage warnings. No gaps were identified.

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?

Schema description coverage is 0%, so the description must explain parameters. It explains each parameter's role (e.g., sell_contract_osi: call to sell, higher strike; quantity: number of spreads) and provides defaults for time_in_force and expiration_time, effectively compensating for the lack of schema descriptions.

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 identifies the tool as placing a Bull Call Spread, specifying the action (buy lower strike, sell higher strike) and distinguishing it from credit spreads. The title also reinforces this.

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?

It warns that this executes a real trade and explicitly suggests using preflight_call_debit_spread first for testing, providing clear when-to-use and when-not-to-use guidance. Sibling tools are listed for context.

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

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

Annotations already indicate readOnlyHint=false; description adds 'executes a real trade' warning and references preflight, providing useful behavioral context beyond annotations.

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?

Front-loaded with purpose and warning, then clear parameter breakdown with example; every sentence earns its place with no redundancy.

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?

Covers all parameters with explanations and example, references relevant sibling tool (preflight_multileg_order), and output schema exists so return format is not required.

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?

Despite 0% schema description coverage, the description extensively documents each parameter (e.g., limit_price meaning, leg structure with example), adding significant value beyond the 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?

Clearly states 'Place a multi-leg order (options strategies: spreads, straddles, etc.)' – specific verb and resource, and distinguishes from siblings like place_order and specific spread tools.

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?

Explicitly warns about real trade execution and recommends running preflight_multileg_order first, providing clear context for when to use this tool vs. the preflight alternative.

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

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

Beyond the annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=true), the description adds the critical warning that this executes a real trade and lays out API-enforced constraints (max 8 tax lots, same symbol, quantities must sum, tax-lot data freshness, bracket-order restrictions). This is exactly the behavior an agent cannot infer from structured fields.

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?

Front-loaded with the one-line purpose and the real-trade warning, then an Args list where every entry carries substantive information. The example values and some parenthetical detail add length, but nothing is truly redundant for an 18-parameter tool.

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?

With an output schema present, return values need no explanation, and the description covers all 18 parameters, their conditional dependencies, and the bracket/tax-lot edge cases. An agent has everything needed to construct a valid call.

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?

Schema description coverage is 0%, so the description carries the full burden — and it does: every parameter gets meaning plus conditional requirements (limit_price required for LIMIT/STOP_LIMIT/LIMIT_ON_CLOSE, expiration_time for GTD, open_close_indicator for options), mutual exclusions (quantity vs amount), and even a warning about the equity_market_session enum mismatch with other tools.

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?

States a specific verb (place) and resource (single-leg order) with the instrument scope (stocks, crypto, options), which cleanly separates it from siblings like place_multileg_order and place_short_order without opening their schemas.

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?

Explicitly recommends running preflight_order first for validation, and repeatedly notes what preflight_order cannot cover (exit legs), which is clear usage context. It never spells out when to prefer a sibling such as place_multileg_order, so it stops short of the 5 tier.

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

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

Description adds key behavioral disclosure: 'executes a real trade' and 'Receive a net credit'. Annotations are minimal (destructiveHint=false, readOnlyHint=false) but description warns of trade execution, adding context beyond annotations.

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?

Description is concise with a clear structure: purpose, warning, then args list. Every sentence adds value. Minor room for tighter phrasing but highly effective.

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?

Covers all 7 parameters with context, provides a warning and prerequisite, mentions net credit. Output schema exists but unnecessary to describe return values. Complete for an execution tool.

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?

Schema has 0% description coverage; the description compensates fully by explaining each parameter: sell_contract_osi (higher strike), buy_contract_osi (lower strike), quantity, limit_price (minimum net credit), time_in_force, expiration_time, account_id. This adds significant meaning.

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 tool places a Bull Put Spread, explains the mechanics (sell higher-strike put, buy lower-strike put, net credit), and distinguishes it from siblings like place_put_debit_spread and place_call_credit_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?

Explicitly recommends running preflight_put_credit_spread first, guiding when to use this execution tool versus a simulation. Lacks explicit when-not-to-use but the preflight suggestion provides clear context.

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

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

Annotations indicate readOnlyHint=false and destructiveHint=false, but description adds the explicit warning '⚠️ This executes a real trade.' which is critical for a trade execution tool. No contradictions.

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?

Description is well-structured with a brief intro, a warning, and a bulleted Args list. It is clear and informative without being verbose. Could potentially trim minor redundancy, but overall effective.

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 7 parameters and 4 required, the description covers all parameters and provides crucial context (real trade, preflight suggestion). An output schema exists (though not shown), so return behavior is likely documented elsewhere. The description is complete for the agent's needs.

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?

Schema coverage is 0%, requiring the description to explain all 7 parameters. The Args section provides clear semantics: sell_contract_osi (lower strike), buy_contract_osi (higher strike), quantity, limit_price (max net debit), time_in_force (DAY or GTD), expiration_time (ISO 8601), account_id (optional with env var). Adds significant value beyond 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?

Clear verb 'Place' with specific resource 'Put Debit Spread'. Explains strategy (buy high strike, sell low strike) and net debit nature. Distinct from sibling tools like place_call_credit_spread, place_put_credit_spread, etc.

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?

Explicitly recommends running preflight_put_debit_spread first. Warns that it executes a real trade. Does not specify when NOT to use, but the preflight suggestion and context imply careful consideration.

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

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

Annotations already declare readOnly=false, openWorld=true and non-idempotent, but the description adds the crucial operational warning that this executes a real trade and recommends a preflight step. It doesn't disclose retry/duplicate-order risk even though idempotentHint=false, which would be valuable for an agent deciding whether to retry after a timeout.

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?

Purpose and the real-trade warning are front-loaded, followed by a tight Args block where every line supplies information not present elsewhere. No redundant restatement of the tool name or filler.

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?

An output schema exists, so return values need not be explained, and all nine parameters are documented despite zero schema coverage. Remaining gap: equity_market_session lists CORE/EXTENDED without explaining the behavioral difference, and there is no note on rejection/partial-fill behavior after submission.

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?

Schema description coverage is 0%, so the description must carry the full load and does: it enumerates allowed values for order_type and time_in_force, states defaults, and specifies the conditional requirements (limit_price for LIMIT/STOP_LIMIT/LIMIT_ON_CLOSE, stop_price for STOP/STOP_LIMIT, expiration_time when GTD). It also adds format details (ISO 8601) and clarifies account_id is optional when PUBLIC_COM_ACCOUNT_ID is set.

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 first sentence names a specific verb and resource ('Place an equity short-sale order'), which cleanly separates it from the sibling place_order and the various preflight_* tools. An agent can pick this tool 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.

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

It explicitly directs the agent to run preflight_short_order first, which is a concrete when-to-use hint tied to a real sibling. It doesn't state when-not to use it (e.g. cover/locate failures, account restrictions), so it stops short of full routing guidance.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds meaningful behavior beyond that: it is a DAY limit buy, the response contains the limit price used and a preflight estimate including commission and exchange fee, and no order is placed. The fallback lookup behavior for limit_price is also disclosed.

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 front-loaded with the core purpose and the no-order guarantee, then provides a compact Args section. Despite being somewhat long, every sentence adds necessary detail given zero schema parameter descriptions.

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?

It is complete for a preflight pricing tool: it explains the operation, the limit-order semantics, the response contents, the no-order guarantee, and every parameter despite the schema having no descriptions. The existence of an output schema means it need not fully detail the return object.

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?

Schema description coverage is 0%, so the description carries the full burden and does so well. It documents all five parameters: contract symbol format and side convention, quantity precision and default, limit price range and fallback behavior, event_symbol dependency when limit_price is omitted, and account_id environment fallback.

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 states a specific verb and resource: price a buy of an event contract on the YES or NO side without placing it. It distinguishes itself from order-placement siblings by explicitly saying it does NOT place an order, and even warns against using the '-EVENTCONTRACT' symbol used by get_event_contract_bars.

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?

It clearly establishes the preflight use case and says no order is placed, which implicitly positions buy_event_contract as the execution alternative. However, it does not explicitly name buy_event_contract or explain exclusions such as when to use preflight_order instead.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. Description adds that it estimates costs and does not place an order, reinforcing safety. No contradictions.

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?

Description is well-structured with a brief overview followed by parameter list. Every sentence adds value. Could potentially shorten the parameter descriptions slightly, but overall efficient.

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 output schema exists, description doesn't need to explain return values. All parameters are documented with semantics, usage guidance clear, and no behavioral gaps. Completely adequate for a 7-param tool with rich annotations.

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?

All 7 parameters are described with meaning beyond schema: sell_contract_osi is lower strike, buy_contract_osi higher strike, limit_price is net credit (positive), time_in_force defaults to DAY, expiration_time required for GTD, account_id optional. Schema coverage 0% but description fully compensates.

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?

Clearly states it estimates costs for a Bear Call Spread (call credit spread) before placing. Specifies sell lower-strike, buy higher-strike, net credit. Distinct from siblings like preflight_call_debit_spread and place_call_credit_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?

Explicitly says 'before placing it' and 'Does NOT place an order.' This distinguishes it from place_call_credit_spread. Also indicates when to use: to estimate costs, not to execute. No confusion with other preflight tools.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. Description reinforces non-destructive nature and adds context about the spread strategy. No contradictions.

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?

Concise and well-structured: a short purpose paragraph followed by a clear args list. Front-loaded with essential information.

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?

Covers purpose, strategy, and all parameters. Lacks details about the output format, but an output schema exists to provide that information.

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 provides meaningful explanations for all 7 parameters, including defaults and conditional requirements.

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?

Clearly states it estimates costs for a Bull Call Spread (call debit spread), with specific verb+resource. Distinguishes from sibling preflight tools for other spread types.

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?

Explains it is for estimating costs before placing an order and explicitly says 'Does NOT place an order.' Implicitly contrasts with order placement tools, but could be more explicit about when to use vs. other preflight tools.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds that it estimates costs and does not place an order, but provides no additional behavioral context (e.g., authentication, rate limits, or error behavior). The added value over annotations is minimal.

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 front-loaded with purpose and a clear disclaimer. The argument list is structured but duplicates some schema information. It is slightly verbose but efficiently communicates essential details.

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?

For a multi-leg options tool, the description covers the input parameters well and the presence of an output schema compensates for lack of return value explanation. It lacks edge case or error handling details, but overall is sufficiently complete for an AI agent.

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?

Schema description coverage is 0%, so the description must compensate. It gives a detailed example and structure for the 'legs' parameter, including required fields and optional fields with defaults. Other parameters like 'limit_price' and 'time_in_force' receive only brief explanations. Overall adds meaningful context beyond the schema, but could be more thorough for all parameters.

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?

Description clearly states 'Estimate costs for a multi-leg (options strategy) trade before placing it.' and explicitly notes 'Does NOT place an order.' This distinguishes it from sibling tools like place_multileg_order and specific preflight functions.

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?

Provides clear context for when to use (before placing a multi-leg order to estimate costs) and what it does not do (place the order). However, it lacks explicit guidance on when to use this tool versus the more specific preflight call/put spread tools.

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

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

Annotations already cover the read-only, non-destructive, open-world profile, and the description reinforces it while adding real domain context: what the estimate contains, and hard API-enforced constraints on tax_lot_matching_instructions (max 8 lots, SELL equity + CLOSE only, same symbol, quantity must sum, tax-lot data must be refreshed today). It omits latency/refresh characteristics of the estimate, which keeps it from a 5.

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?

Front-loaded: purpose, then returned values, then the not-a-write disclaimer, before the Args block. The length is proportionate to 14 parameters and every line adds information — even the aside about on-close types executing at the closing auction earns its space.

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?

An output schema exists and the description names the main returned figures (commission, fees, order value, buying power, margin impact), so nothing critical is missing for a read-only estimation tool. Only gap is no note on whether the estimate is a point-in-time snapshot that can go stale before placement.

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?

Schema coverage is 0% across 14 parameters, so the description carries the full burden and does so thoroughly: value domains for instrument_type, order_side and order_type, conditional requirements for limit_price/stop_price/expiration_time, the quantity-vs-amount mutual exclusion, defaults, and the account_id fallback to PUBLIC_COM_ACCOUNT_ID. This is meaning an agent cannot get from 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?

States a specific verb ('Estimate') plus resource ('costs and impact of a potential single-leg trade'), and 'single-leg' scopes it away from the multileg and spread-preflight siblings. The explicit negative 'Does NOT place an order' separates it from place_order at a glance.

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?

Timing is clear — run it before placing the trade — and the 'does NOT place an order' sentence implicitly routes the actual execution to place_order. However, none of the specialized siblings (preflight_multileg_order, preflight_short_order, preflight_buy_event_contract, the spread preflights) are named, so an agent must infer from the input shape which preflight variant applies.

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

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

Annotations declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true. The description reinforces that it is a side-effect-free estimation tool and adds that it 'Does NOT place an order.' It also explains the credit received nature. No contradictions exist, and the description adds context beyond annotations.

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: a clear one-line purpose, a brief strategy explanation, a key behavioral note, and a bulleted list of parameters. It is concise with no unnecessary text. The critical information is front-loaded, and the format is easy to parse.

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?

All 7 parameters are described, with 4 required parameters clearly noted. The tool's read-only nature, credit computation, and order prevention are covered. An output schema exists (as per context signals), so the return value is handled externally. The description is complete for an agent to use the tool correctly.

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?

Schema description coverage is 0%, but the description compensates fully. It provides detailed explanations for each parameter in the Args section, including the role of sell_contract_osi (higher strike) and buy_contract_osi (lower strike), limit_price semantics (positive = credit received), time_in_force options (DAY or GTD), and conditional requirements for expiration_time. This adds substantial meaning beyond the raw 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 states 'Estimate costs for a Bull Put Spread (put credit spread) before placing it.' It clearly identifies the action (estimate), the resource (put credit spread), and the context (before placing). The title 'Preflight Put Credit Spread' aligns with the purpose, and the sibling set distinguishes it from other preflight and placement tools.

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 says 'Does NOT place an order,' guiding when not to use this tool. It explains the mechanics (sell higher-strike, buy lower-strike) and mentions receiving a net credit. While it does not explicitly compare to other preflight tools, the pair structure and type are clearly defined, making the usage context reasonably clear.

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

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

Annotations already declare readOnlyHint=true. Description adds that no order is placed, which is consistent and slightly reinforces the behavior. No additional details on auth, rate limits, or side effects, but adequate for a read-only estimation tool.

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?

Description is brief but complete: a clear opening sentence, a concise strategy explanation, and a well-structured bullet list of parameters. No wasted words; front-loaded with purpose.

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?

With 7 parameters, an output schema (presumably describing cost estimate), and sibling tools, the description covers purpose, parameters, and key behavior. It meets the needs for a preflight check tool, though it does not detail what the output contains (but output schema handles that). Minor gap: no mention of prerequisites like market data availability.

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?

Schema has 0% description coverage, but the description provides clear explanations for all 7 parameters, including OSI symbols, quantity, limit price as net debit, time_in_force options, expiration_time format, and account_id optionality. Adds significant value beyond schema titles.

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?

Description clearly states the tool estimates costs for a Bear Put Spread, explains the strategy (buy higher strike, sell lower strike), and explicitly says it does not place an order. Distinguishes well from sibling preflight and order placement tools.

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?

Explicitly says 'Estimate costs before placing it' and 'Does NOT place an order', implying use before order placement. Sibling tools include 'place_put_debit_spread' for actual order placement, making usage context clear. No explicit when-not-to-use but sufficient.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true. The description adds substantive context beyond that: what is estimated (commission, fees, buying-power impact) and the crucial assurance that no order is placed. It does not cover error conditions or account prerequisites beyond the env-var fallback.

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?

Front-loaded with purpose and the no-placement warning, then a compact Args block. Each argument line carries information, though the format is closer to a docstring dump than tightly integrated prose.

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?

For a 9-parameter tool with zero schema coverage and an existing output schema, the definition supplies everything an agent needs: the conditional parameter rules, order-type semantics, default values, and the account_id fallback. Return values are already covered by the output schema.

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?

Schema description coverage is 0%, so the description bears the full burden, and it delivers: it documents every parameter and the conditional requirements (limit_price for LIMIT/STOP_LIMIT/LIMIT_ON_CLOSE, stop_price for STOP/STOP_LIMIT, expiration_time for GTD, account_id optional when the env var is set). It also explains on-close execution at the closing auction, which is not in the 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?

States a specific verb and resource ('Estimate costs for a short-sale equity order') and explicitly contrasts with the sibling that places orders ('Does NOT place an order', 'before placing it'). An agent can distinguish it from place_short_order without opening any schema.

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 says the tool is to be used before placing, which implies pairing with place_short_order, and explicitly excludes placement. It stops short of naming the alternative tool or stating when not to preflight at all.

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