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

With readOnlyHint and openWorldHint already present, the description adds meaningful behavioral details: it promises 'nothing is stored or streamed,' describes the return format (decimal implied_vol plus greeks), and enumerates error scenarios including a 4-second timeout and potential market-data permission issues. This goes well beyond the annotation coverage.

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 structured with the one-line purpose first, followed by constraints, return behavior, usage context, and a compact error list. Every sentence carries information; the error list is internally organized with error-name to cause, so no sentence is wasted.

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 three-parameter calculation tool with an output schema, this description is unusually complete: it specifies exact contract requirements, return format, usage scenario, non-persistence, timeout, and permission-related failures. The only minor omission is assumptions of the IBKR model, but that is a named model rather than a behavioral gap.

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 already documents all three parameters (100% coverage), so the baseline is 3. The description enriches the contract parameter significantly by requiring sec_type OPT or FOP and adding that futures options need an exchange (e.g. CME), and it clarifies the meaning of option_price as per-share. This extra guidance justifies a score above baseline.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb ('Compute') and resource ('option's implied volatility'), clarifies the input ('from a given option price'), and notes the IBKR model. It is clear and not tautological, but it does not explicitly contrast with the sibling calculate_option_price, so differentiation is left to the reader.

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 gives explicit context: it is 'useful for what-if pricing' and requires the contract to be a single option, with futures options needing an exchange. It also points to get_option_chain when an option cannot be resolved, but does not explicitly state when to prefer calculate_option_price, so some inference remains.

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 openWorldHint=true, and the description adds substantial behavioral context: the pricing model is IBKR's, the return is per share with a multiplier caveat, errors are enumerated (invalid_request, not_found, ambiguous_contract, request_timeout with a 4-second limit, ib_api_error for missing permissions). This goes well beyond what annotations provide.

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 primary purpose, then moves logically through contract constraints, output format, use-case scenarios, and error handling. Every sentence adds operational value, and the error enumeration is compact rather than rambling.

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 complexity and the fact that an output schema exists, the description is complete: it covers contract requirements, output units and greeks, the multiplier adjustment, intended scenario use, and all realistic failure modes. An agent has everything needed to invoke 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 100%, so the schema already fully documents contract, volatility, and underlying_price. The description mostly restates the contract requirements and the decimal-volatility convention already present in the schema, adding limited new meaning beyond the percent-above-10 error behavior.

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 names a specific verb (Compute), a precise resource (option's theoretical price and greeks), and the condition (at a given volatility, with IBKR's model). This clearly differentiates it from the inverse sibling calculate_implied_volatility, since this tool takes volatility as an input rather than solving for it.

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 states clear context for use: pricing scenarios where you vary volatility or underlying_price. It provides detailed contract constraints and error conditions, but it does not explicitly say when NOT to use this tool or direct the agent to an alternative like calculate_implied_volatility, so it stops short of full exclusion 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 mark readOnlyHint=true and openWorldHint=true. The description goes well beyond by specifying refresh cadence (~3 minutes and after trades), that no market-data subscription is required, that `values` contains every summary row including per-currency ledger rows, and the invalid_request error behavior listing valid tags. This is rich behavioral disclosure.

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 dense but purposeful: purpose and field list come first, followed by structure, refresh, subscription, and error details. While somewhat long, each sentence contributes useful information. The structure could be slightly tightened with headings, but it's well organized.

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 read-only tool with no required parameters and an existing output schema, the description covers purpose, exact fields, return structure, refresh behavior, subscription requirements, and error handling. An agent has everything needed to invoke 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 coverage is 100%, so the schema already documents both `tags` and `account` with descriptive text. The description does not add parameter-level meaning beyond schema; its mention of 'headline fields are always filled' relates to behavior, not parameter semantics. Baseline 3 applies.

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: 'Return an account's headline balances' and enumerates the specific fields returned. It doesn't explicitly contrast with sibling tools like get_account_values or get_portfolio, but the scope is precise enough to understand what this tool does.

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 only contextual note is 'No market-data subscription needed,' which is a benefit, not a selection criterion. The description never says 'use this for headline balances' or names a sibling to avoid.

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 and openWorldHint, but the description adds substantial behavioral context: values update every ~3 minutes or on change, default and maximum limits (200/1000), truncated flag semantics, repeated fetching behavior with model_code, and error behavior with invalid_request listing valid tags. These details go well beyond the annotations and schema, with no contradiction.

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 dense but well organized, leading with the core purpose, then use cases, update cadence, limits, and errors. Each sentence adds distinct information and none feel redundant with the schema or annotations.

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 output schema exists and the input schema already covers parameters, the description still provides essential behavioral context: cadence, limits/truncation, error handling, and use-case differentiation from get_account_summary. An agent has enough information to select and invoke the tool correctly in most scenarios.

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 100%, so the baseline is 3. The description adds meaningful value on top: it explains the row structure (raw value and numeric amount), clarifies model_code fetches the model's values once, and connects the limit/truncation semantics. This lifts it above the baseline, though most parameter-level detail still comes from 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?

The description states a specific verb and resource: 'Return the full key/value account data: every tag IBKR reports, per currency.' It also distinguishes this tool from the sibling summary tool, so an agent can reliably tell get_account_values apart from get_account_summary 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?

The description explicitly tells when to use this tool: 'Use it for details the summary lacks' and gives concrete examples such as per-currency cash, accrued interest, and segment values. It also references the alternative get_account_summary and explains special cases like model_code for financial advisors, giving clear contextual 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?

Beyond the readOnlyHint annotation, the description discloses valuable behavioral traits: newest-first ordering, IBKR-limited historical range, default/maximum limits, and the specific error (ib_api_error 321) when the gateway is in read-only mode. It also notes that get_executions still works in that scenario. These details go well beyond the annotation's simple read-only flag.

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 with the core purpose. Each sentence adds value: purpose, data-range limitation, alternative tool, and error behavior. Slight redundancy exists where the limit defaults were repeated from the schema, but the overall structure is tight 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 output schema exists and the input schema fully documents all three optional parameters, the description covers everything needed for correct selection and invocation: what the tool returns, ordering, data-range constraints, default/cap values, an explicit alternative, and a failure mode. No critical gap remains for an agent to call this 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 100%, with each parameter (limit, account, api_only) already well described in the schema, including defaults, caps, and behavior. The description adds only minor redundancy ('Default limit 100, maximum 1000') without introducing new parameter semantics, so the baseline 3 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 uses a specific verb+resource combination: 'List recently filled or cancelled orders, newest first, with IBKR's completion status.' This clearly identifies what the tool returns and its ordering, distinguishing it from get_executions (which reports fill prices) and get_open_orders (open orders). The scope is unambiguous.

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 directs agents to 'Use get_executions for fill prices and commissions,' providing a clear alternative for a related but distinct need. It also explains the data-range limitation ('IBKR decides how far back this reaches') and the read-only error scenario with get_executions as a fallback, giving concrete guidance on when to choose this tool vs its sibling.

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 openWorldHint=true, and the description adds useful behavior beyond that: it lists what data is included and discloses that when disconnected the session fields are null. This gives the agent a realistic expectation of the result even in an offline state.

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 front-loaded: the first sentence states the core purpose, and the second sentence efficiently enumerates the returned fields. No words are wasted, and every sentence adds meaningful 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-parameter read-only tool with an output schema present, this description is complete. It explains the purpose, the returned content, and the edge case of being disconnected, so an agent has everything needed to select and 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?

The tool has no parameters, so there is no parameter semantics to clarify. The description appropriately focuses on what the tool returns instead, which is the correct use of description space here.

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 uses a specific verb ('Return') and a specific resource ('technical details of the API session'), then lists concrete fields like endpoint, client id, and API versions. This clearly distinguishes it from sibling get_* tools such as get_user_info or get_server_time, so an agent can identify its purpose 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 gives clear context by stating the tool returns session-level technical details and explicitly notes it 'works when disconnected too.' It does not name sibling alternatives or state when not to use it, but for a zero-parameter diagnostic tool this level of context is largely 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?

Beyond the readOnlyHint/openWorldHint annotations, the description discloses that partial contracts can match multiple instruments, derivatives are sorted by expiry/strike/right, limit defaults to 20 with a cap of 200, and total/truncated report match counts. It also surfaces throttling for broad option specs and names expected error types.

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 text is dense but every sentence earns its place: purpose, output fields, matching behavior, performance caveats, and errors are arranged logically. It is front-loaded with the core purpose and returns info before moving into caveats and alternatives.

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 what the tool returns, how partial specs behave, pagination semantics, performance considerations, exchange prerequisites, and error cases. With a rich input schema and output schema present, nothing essential for invoking the tool 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 coverage is 100%, so the schema already documents the parameters thoroughly. The description adds meaningful value on top: it explains partial-spec matching (e.g., symbol + sec_type FUT + exchange lists every future expiry), gives the concrete limit default/cap, and clarifies include_expired's role in a usage context.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with 'Return IBKR's full contract details for every instrument a spec matches,' a specific verb and resource. It then enumerates the concrete returned fields (identifiers, sessions, min tick, accepted order types, bond terms), making the scope unmistakable and clearly distinct from sibling tools like search_symbols or qualify_contract.

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 gives direct routing advice: for broad option specs, 'use get_option_chain for expiries and strikes, then look up single options.' It also warns that futures and indexes need their listing exchange rather than SMART, recommends include_expired for expired futures, and states that combos (BAG) are rejected with invalid_request. This is explicit when/how-to-use 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 and openWorldHint, so the description only needs to add context. It does so by stating 'The list is static and cached for the gateway session' and 'this list does not' subscribe to depth. This helps the agent understand the data is not live and the tool has no side effects beyond returning a cached list.

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 two tight sentences. The first sentence delivers the core purpose. The second adds field details, usage timing, the subscription distinction, and caching behavior—all without waste. Information is front-loaded and each 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?

With zero parameters, a defined output schema, and readOnly/openWorld annotations, the description covers all essential context: what the tool returns, the fields in each row, when to use it, and its static/cached nature. No critical details are missing for correct invocation.

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

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

The input schema has zero parameters, so the baseline is 4. No parameter explanation is needed, and the description correctly avoids inventing any. The description's field-level details (exchange, security type, listing exchange, depth service type) apply to the output, which the output schema covers.

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 a specific action and resource: 'List the exchanges that offer market depth (level 2 order book), per security type.' It clearly differentiates from subscription tools by framing itself as a reference list to consult before subscribing. The title and description align without tautology.

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 when-to-use guidance: 'Check it before subscribing to market depth.' It also clarifies what this tool does not do: 'Depth itself needs a separate depth data subscription at IBKR; this list does not.' It implies the alternative (subscribe_market_depth) but does not name it explicitly, so it falls just 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?

The annotations only signal read-only and open-world behavior, so the description carries the burden of explaining field semantics. It adds valuable behavior: commission is null until IBKR reports it, realized_pnl is 0 for position-opening fills, and the default/maximum limit are concretely specified. This goes well beyond the annotations and introduces no contradiction.

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 organized into short, focused sentences: purpose first, then time coverage, then field semantics and limits. Every sentence earns its place, and there is no filler or redundant restatement.

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 that the output schema exists and all parameter schemas are already descriptive, the description supplies the remaining contextual essentials: data availability window, null/zero value semantics, and limit behavior. An agent has enough information to select and invoke this 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?

All six parameters are already documented in the input schema, so the baseline is 3. The description adds the specific default limit of 100 and maximum of 1000, which the schema leaves unspecified, providing meaningful extra value for the limit 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 states the exact resource ('executions (fills)') and the verb 'List', and it specifies ordering ('newest first') and the key returned fields ('commission and realized P&L'). This makes it clearly distinct from sibling order-status tools like get_open_orders and get_completed_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?

It gives clear context: it covers the current trading day only, with a possible 7-day extension depending on the gateway setting, and explicitly states that older trades are not available through the API. It does not name a sibling alternative, so it stops short of full when-to-use-vs-alternative routing.

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?

Discloses several non-obvious behaviors beyond the readOnlyHint annotation: deprecation and gateway compatibility, whitespace removal, truncation at max_chars with truncated=true, and a full error taxonomy including ib_api_error 10358 and request_timeout. This is rich behavioral context the annotations alone do not provide.

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 long but every sentence carries load: core purpose first, then deprecation, subscription requirement, output behavior, error handling, and alternative tool. The structure is logical and front-loaded, and no sentence is 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?

For a complex, deprecated, subscription-gated tool, the description covers return format, truncation, error conditions, prerequisites, and alternatives. Combined with the rich input schema and output schema, an agent has everything needed to call this correctly and handle failures.

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 100%, but the description adds real parameter-level value: it explains max_chars truncation behavior and default/max values, recommends smaller report types in relation to that limit, and tells the agent to resolve ambiguous_contract by supplying primary_exchange or con_id. This goes beyond what the schema states, though the schema already documents the parameters well.

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-resource pair: 'Fetch a Refinitiv fundamentals report for a stock, as XML.' It explicitly names the data source (Refinitiv), the scope (stocks), and the output format (XML), and clarifies it is a read-only report tool, distinct from the many historical/subscription siblings.

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 gives explicit when/when-not guidance: stocks only (sec_type STK), requires the Refinitiv subscription, is deprecated on newer gateways, and for key ratios recommends subscribe_quotes with fundamental_ratios instead. It even advises preferring ReportSnapshot or ReportsFinSummary over the large report types, giving an agent actionable selection criteria.

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, so the description is not required to restate safety. It adds valuable behavior beyond the annotation: the tool 'Needs market-data permissions', 'counts toward IBKR's historical-data limits', and may fail with not_found for missing contracts or data types. This is useful operational context that annotations do not provide.

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 has no filler: one sentence for the core result, one for usage context, and one for errors. The most important information is front-loaded, and every sentence earns its place by conveying permissions, rate-limit impact, or failure modes.

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 rich input schema (especially ContractSpec), the presence of an output schema, and readOnlyHint, the description covers what an agent needs: the purpose, when to call it, permission and pacing consequences, and the not_found error. Return-value details are already handled by the output schema, so nothing essential 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 100%, so the schema already documents contract, use_rth, and what_to_show in detail. The description adds only a loose tie to what_to_show ('for this what_to_show') and permission context, but it does not meaningfully expand parameter meaning beyond the schema. Baseline 3 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 opens with a precise statement: 'Return the earliest date and time IBKR has historical data for an instrument.' This names a specific verb, resource, and result scope, and it clearly distinguishes the tool from siblings like get_historical_bars, get_histogram, and get_historical_ticks by its unique head-timestamp purpose.

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 gives explicit when-to-use guidance: 'Use it before long get_historical_bars requests, or when they come back empty.' It also names the relevant alternative tool (get_historical_bars) and ties the call to the what_to_show parameter, so an agent can decide correctly without 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?

The description adds substantial behavior beyond the annotations: it never fails itself, enumerates all possible state values with meanings, explains circuit breaker behavior, api_read_only, paper accounts, market data type, subscription limits, and probe semantics. This goes far beyond readOnlyHint=true and openWorldHint=true with no contradiction.

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 long but every sentence earns its place by defining state semantics, related gates, and probe behavior. The lead sentence states the purpose immediately, and the state list is structured for quick agent parsing.

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 health-check tool with a rich output schema, the description covers when to call it, what each state means, what related fields like trading_enabled and api_read_only indicate, and how to force a live check. 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?

The single parameter probe is fully documented in the schema (100% coverage), so the baseline is 3. The description adds extra meaning by explaining why to use probe: the state alone can lag behind a stalled socket. This justifies the step above baseline.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: 'Report whether the Interactive Brokers gateway connection is usable, and why not.' It clearly identifies this as a health/diagnostic tool and distinguishes it from sibling data-retrieval tools by positioning it as the first call when other tools fail.

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 tells the agent when to use it: 'Call this first when another tool fails with not_connected or times out.' It also explains when probe=true is appropriate. It does not explicitly contrast with get_connection_info or state when not to use it, 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?

The annotations only provide readOnlyHint=true, but the description goes far beyond: it discloses the default limit (200), maximum (1000), truncation behavior (busiest levels kept, `truncated` flag), the market-data permission requirement, and the possible error codes. This fully enriches the agent's understanding of the tool's behavior.

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?

Four sentences, each with a distinct job: purpose, output format and use cases, limits/truncation/permissions, and errors. No filler; the core purpose is 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?

With an output schema present and all parameters already well documented, the description covers all additional behavioral context an agent needs: truncation semantics, permissions, and error conditions. Nothing necessary 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 coverage is 100%, giving a baseline of 3. The description adds meaningful value by specifying the default limit (200), the absolute cap (1000), and the 'busiest levels are kept' truncation behavior, which the schema leaves unspecified.

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: 'Return how trading volume was distributed over price levels during a period.' The description's focus on price-level volume counts distinguishes it from all sibling data tools, such as get_historical_bars or get_historical_ticks, even without naming them.

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 names three use cases: 'volume-at-price, support/resistance and value-area questions.' This gives an agent clear signals about when to select this tool, though it does not mention alternatives or specify 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 declare readOnlyHint=true and openWorldHint=true, and the description is consistent with those. It adds substantial behavioral context beyond the annotations: truncation behavior (newest kept, truncated flag), UTC vs trading-date time semantics, IBKR pacing limits (60 requests/10 min, 5 per contract/data type in 2s, 15s cache), data availability limits for expired contracts, and permission requirements. No contradiction 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 dense but well-organized: first sentence states the core purpose, then range semantics, then limits/truncation, then IBKR pacing, then errors. It is longer than average, but every sentence carries operational information an agent needs. The error list is compact and actionable. Slight redundancy in the pacing section (multiple rate limits listed) but all are distinct constraints.

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 tool with 7 parameters, an output schema, and complex IBKR-specific constraints, the description covers all the critical operational context: range semantics, truncation, pacing, permissions, expired contracts, and error handling. The output schema exists so return values need not be described. The only minor gap is that it doesn't explicitly state the output format, but the output schema covers that.

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 100%, so the schema already documents all 7 parameters. The description adds value by explaining the interaction between duration and bar_size (e.g., 'bars of 30 seconds or less reach back about 6 months'), the meaning of the truncated flag relative to limit, and the end default ('now when omitted'). It doesn't restate every parameter but adds cross-parameter context that the schema lacks.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: 'Return historical OHLCV bars for one instrument, oldest first.' This clearly distinguishes it from siblings like get_historical_ticks (ticks vs bars) and get_head_timestamp (timestamp only). The scope is explicit: one instrument, OHLCV bars, chronological order.

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 extensive usage guidance: it explains how duration/end define the range, when truncation occurs and how to avoid it, IBKR pacing limits and duration reach, market-data permission requirements, and the include_expired caveat for futures. It also lists specific error conditions and remediation steps (check what_to_show, use_rth, get_head_timestamp). This is far beyond a minimal when-to-use statement.

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 goes well beyond the readOnlyHint annotation by disclosing pagination behavior (default 50, max 300, move end back), subscription requirements, supported instrument types, UTC timestamps, and specific error conditions with recovery guidance. This is rich, actionable 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?

The description is dense but every sentence earns its place: purpose, return fields, supported instruments, limits, pagination, subscriptions, and errors. It is front-loaded with the core purpose and then systematically covers invocation-relevant 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?

Given the 5-parameter schema, output schema, and read-only annotations, the description covers everything an agent needs to invoke this correctly: what is returned, how to paginate, provider requirements, and expected errors. Nothing important 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 coverage is 100%, so the baseline is 3. The description adds value beyond the schema by specifying the exact default limit (50), the cap (300), the pagination technique using end, and the subscription-per-provider constraint.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: 'Return past news headlines about one instrument, newest first.' It clearly distinguishes the tool from siblings like get_news_article and get_news_providers by explaining that headlines carry provider_code and article_id for use with get_news_article.

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 gives practical workflow context: headlines reference get_news_article, provider codes come from get_news_providers, and subscription requirements are stated. It stops short of explicitly saying 'use this for historical news, not live news' or naming subscribe_news as the alternative, so it misses the top score.

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 openWorldHint=true, and the description adds substantial behavior beyond that: the 1000-tick cap, one-second timestamp granularity, possible repeated ticks in the same second, truncation-induced pagination guidance, and IBKR pacing limits. This is rich, non-obvious behavior the annotations do not cover.

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?

Every sentence earns its place: purpose first, then usage rules, then behavior quirks, pacing, and final error enumeration. Despite covering a lot, it stays focused and front-loaded, with no filler or restatement of 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?

Given the output schema exists, the description need not explain the return shape. It covers error cases (not_found, invalid_request, rate_limit, ib_api_error 162), permissions, pagination, and the correct alternative tool. An agent has everything needed to call this tool safely and 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 coverage is 100%, so the schema documents each parameter. The description still adds meaningful interaction semantics: the exactly-one-of start/end constraint (reinforcement), pagination via setting start/end to boundary times, and the note that ticks in the same second can repeat, which affects how start/end should be used.

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: 'Return individual historical trades, quote changes or midpoints (time and sales).' This clearly identifies what the tool does and distinguishes it from bar-based history tools like get_historical_bars and from real-time subscription tools among its siblings.

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 instructs to give exactly one of start or end, then states when to prefer an alternative: 'prefer get_historical_bars for anything longer than minutes of activity.' It also adds prerequisites (market-data permissions) and pacing limits, giving an agent actionable selection criteria.

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 goes well beyond annotations by disclosing that IBKR may omit some IDs (missing_ids), that unanswered rules are probably unknown, and that the call fails with not_found if none are answered. It also explains the semantics of the returned tick ladder, which is valuable 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?

The description is organized into three logically separated paragraphs: purpose, data format, and behavioral caveats. While slightly longer than strictly necessary, each sentence carries distinct information and the key purpose is 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?

Given the output schema exists and annotations cover read-only safety, the description fully addresses what an agent needs: the meaning of the tick ladder, how to source IDs, when to use it, and the specific failure modes (missing_ids, not_found). Nothing essential is omitted.

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 the schema already describes market_rule_ids and its source, the description strengthens semantics by noting the relationship between market_rule_ids and valid_exchanges from get_contract_details. This adds useful context beyond a generic integer array, warranting above-baseline scoring.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with 'Return the price increments (tick ladder) of IBKR market rules,' a specific verb and resource. It further explains the structure of the data (low_edge, increment) and explicitly ties it to get_contract_details, distinguishing it from sibling 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 states to get IDs from get_contract_details and says 'Use it to round limit prices correctly.' This gives clear when-to-use guidance and names the source tool, leaving no ambiguity about the workflow or the purpose.

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 goes well beyond the readOnly/openWorld annotations: it discloses HTML-to-plain-text conversion, truncation behavior with truncated and total_chars, binary article handling via article_type=binary, and the two error modes ib_api_error and not_found. This gives the agent a precise model of the tool's behavior.

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 definition is front-loaded with the core purpose, followed by a compact paragraph of behavioral details and a final error list. Every sentence carries useful information; there is no filler or repetition of schema titles.

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 read-only retrieval tool with an output schema, the description covers everything an agent needs to call it correctly: input provenance, content transformation, truncation, binary edge cases, subscription requirement, and expected errors. Nothing material 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 schema already documents all four parameters at 100% coverage, so the baseline is 3. The description adds value by connecting provider_code and article_id to headline sources, explaining the max_chars default and truncation semantics, and noting the effect of plain_text for HTML articles.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with the specific operation: 'Return the full text of a news article, given its provider code and article id.' This clearly identifies the resource and inputs, and the mention of get_historical_news as the source of headers distinguishes this retrieval tool from headline-listing siblings.

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 says where to obtain the inputs ('Take both from a headline (get_historical_news or a news subscription)') and notes the prerequisite that the user needs a subscription to the provider. It does not enumerate exclusions or alternative retrieval tools, but the call context is 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 mark readOnlyHint and openWorldHint; the description adds valuable behavior beyond them: only subscribed providers are returned, free API feeds require separate IBKR market-data subscriptions, and not_found is returned when the login has none. This explains filtering and failure behavior beyond what annotations convey.

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 main verb and resource appear in the first sentence, followed by compact usage, subscription caveat, and error information. There is no filler or redundant restatement of the title or schema.

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-parameter, read-only list tool with an output schema, the description covers purpose, downstream consumers, subscription caveat, and error behavior. An agent has everything needed to call it correctly and interpret the result.

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 no parameters and schema coverage is 100%, so there are no parameter semantics to document; the 0-parameter baseline applies. The description's mention of returning 'code and name' is output-focused and does not need to compensate for any parameter gaps.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: 'List the news providers this IBKR login can use through the API (code and name).' This unambiguously states what the tool returns and its scope, and it is clearly distinct from sibling news tools like get_news_article and subscribe_news.

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 provides clear downstream usage guidance: 'Use the codes with get_historical_news, get_news_article and subscribe_news,' and it explains the subscription limitation ('Only subscribed providers are listed'). It does not explicitly enumerate when not to use the tool, but the context and workflow are clear enough.

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 only declare readOnlyHint and openWorldHint. The description adds essential behavioral detail: modifiable is true only for orders placed by this same server/client, other clients' orders are informational only, and IBKR can refuse the request on a read-only API with error 321 and a specific workaround. This is exactly the kind of context structured annotations cannot convey.

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 dense but every sentence earns its place: scope and output fields, modifiability semantics, the completed-orders alternative, the read-only edge case, and the error code. The core purpose is front-loaded with no 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?

For a read-only listing tool with no required parameters and an output schema present, the description covers all needed context: what is returned, what is excluded, which sibling to use instead, the read-only failure mode, and the fallback behavior. Nothing essential 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 coverage is 100%, but the description still adds meaning beyond it: it explains the modifiable constraint tied to the API client and precisely what include_other_clients=false does under read-only gateway conditions. This goes well beyond the schema's one-line parameter 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 opens with 'List the account's working orders' and specifies the returned fields: status, filled/remaining quantity, and prices. It explicitly contrasts with get_completed_orders by stating which order states are excluded, making it clearly distinguishable from the large sibling set.

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 states this tool shows working orders only, that filled/cancelled orders are excluded, and directs the agent to get_completed_orders for those. It also explains when include_other_clients=false is needed under a read-only API, giving concrete 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?

Beyond the readOnlyHint/openWorldHint annotations, the description discloses important behavioral traits: strikes are the union across expirations and not every strike exists for every expiry, so qualify_contract must be used before quoting. It also covers exchange merging behavior, cost characteristics (no subscription, no pacing concerns), and specific error conditions (not_found, invalid_request). No contradiction with annotations found.

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 and front-loaded: it starts with the core purpose and the critical 'no prices' caveat, then covers output shape, usage notes, and errors in separate digestible blocks. Every sentence earns its place, and there is no 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?

Given the annotations already cover the read-only safety profile and an output schema exists, the description supplies all remaining essential context: underlying kinds, exchange behavior, subscription behavior, the need to call qualify_contract before quoting, and error conditions. Nothing important for selecting or invoking the tool 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 schema already documents all parameters richly, so the baseline is 3. The description adds operational meaning beyond the schema by recommending SMART for US stock/index underlyings and explaining why exchange-specific chains are not merged, which adds useful context beyond what the schema says.

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 states a specific verb and resource: 'List the option expirations and strikes available on an underlying (no prices).' The description goes further to distinguish the tool from pricing tools by explicitly saying 'no prices,' and explains it returns one entry per trading class with multiplier, exchanges, expirations, and strikes.

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 gives clear when-to-use guidance: 'This is the cheap way to explore options; it needs no market data subscription and has no pacing concerns.' It also tells callers to pass exchange SMART for US stocks/indexes because IBKR lists a chain per exchange and chains are not merged, and it routes quote/greek needs to the options and market_data 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 the description aligns with that. It adds substantial behavioral context beyond the annotations: results are sorted by strike with calls before puts, limit defaults to 20 with max 40, skipped strikes/legs are reported, snapshots take a few seconds, and live quotes require specific IBKR data subscriptions. No contradiction with annotations exists.

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 dense but well organized: main behavior first, then selection and output details, then market-data caveats and error mapping. Every paragraph earns its place, and the most decision-relevant information is 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?

For a tool with 9 parameters, an output schema, and market-data dependencies, the description covers all essential context: return fields, selection semantics, truncation behavior, subscription requirements, latency expectations, error conditions, and sibling alternatives. 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?

Even with 100% schema coverage, the description adds meaning beyond the schema: it explains the range-vs-ATM selection tradeoff, that both rights are returned unless right is set, that limit caps leg pairs, and that a range keeps the lowest strikes while ATM keeps the nearest. This connects the parameters into a coherent selection model the schema alone 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?

The description names a specific verb ('Snapshot quotes and greeks') and a specific resource ('a slice of one option expiration (a mini chain)'), clearly distinguishing this from the broader get_option_chain and streaming subscribe_quotes siblings. It also specifies the two strike-selection modes, so an agent knows exactly what the tool returns and how to scope it.

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 gives explicit routing guidance: use get_option_chain for expiries/strikes without quotes and subscribe_quotes for streaming a single option. It also notes the market_data_type dependency and when to pass trading_class. This tells the agent both when to use this tool and when to pick an 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 readOnlyHint annotation, the description discloses the entire behavioral profile: one-shot subscription, wait time (a few seconds, usually about one), automatic cancellation, fresh reading per call, no need to unsubscribe, and error behavior (request_timeout after login or for data-less accounts, retry once). This is rich, non-obvious context that the agent needs to anticipate network behavior.

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 in the first sentence, then packs the behavioral contract into a compact second block. There is no filler, and every sentence covers a distinct aspect: purpose, subscription lifecycle, and error handling.

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 are covered there. The description provides the remaining context: base currency, P&L components, timing, one-shot semantics, and error behavior. Nothing an agent needs to call 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 100%, with both parameters (account and model_code) already well documented. The description adds no additional parameter-specific meaning beyond what the schema provides, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: 'Return the account's live P&L: today's (daily), unrealized and realized, in base currency.' This precisely identifies what is returned and distinguishes the tool from per-position P&L (get_position_pnl) and account summaries. The scope is clear and immediately usable by an agent.

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 gives clear context: it is a one-shot snapshot that subscribes, waits for the first update, and cancels, so the agent knows it is not a continuous subscription and does not require explicit unsubscription. It also describes error handling and a retry. However, it does not explicitly name alternatives or state when-not-to-use, leaving the distinction from siblings like get_position_pnl to inference from the 'account's live P&L' phrase.

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?

With readOnlyHint and openWorldHint provided by annotations, the description adds substantial extra behavioral context: values use IBKR's own valuation, require no market-data subscription, refresh about every 3 minutes, and a non-default account causes extra latency because IBKR streams one account at a time. These are meaningful operational traits an agent needs to set expectations, going well beyond the annotation flags.

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 sentences, each earning its place: the first defines the output, the second explains valuation and refresh behavior, the third warns about latency. Core purpose is front-loaded)Skip, and there is no filler or repetition of schema content.

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?

Despite being a simple tool with one optional parameter, the description covers what is returned, the valuation source, refresh cadence, and performance trade-offs. Since an output schema exists, return fields need no explanation. The one caveat about non-default accounts is exactly the kind of operational detail that helps an agent decide when to call it. Nothing essential 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 fully documents the single optional 'account' parameter with a description including an example ID and instructions to omit it for the default account. Since schema coverage is 100%, the description need not repeat parameter details. The latency note for non-default accounts is behavior, not parameter semantics, so the baseline 3 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 opens with 'List an account's positions with market price, market value and unrealized/realized P&L', stating a specific verb and resource. It clearly differentiates from siblings like get_positions (positions without valuation) and get_pnl (P&L summary without positions) by combining both. The wording is specific enough for an agent to select it without guessing.

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 implies when to use it by enumerating the returned data (positions + market value + P&L), but it never explicitly contrasts it with get_positions, get_pnl, or get_position_pnl, nor does it state conditions when an alternative would be better. The only usage note, about non-default accounts taking longer, is a performance caveat, not a routing guideline. This is adequate but leaves selection partially 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?

Beyond the readOnlyHint and openWorldHint annotations, the description discloses useful runtime behavior: 'Waits a few seconds at most for IBKR's first update' and enumerates four distinct error modes with their triggers (not_found, ambiguous_contract, invalid_request, request_timeout). This gives the agent realistic expectations about latency and failure 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 four sentences, front-loaded with purpose, followed by the key input trick, the latency behavior, and a compact error list. Every sentence contributes meaning; there is no filler or repetition of schema content.

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 that an output schema exists (return values are covered there) and annotations declare read-only behavior, the description covers the remaining needs: what the tool does, how to identify the position, expected latency, and possible errors. For a read-only single-position query tool, nothing essential 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 coverage is 100%, so the baseline is 3. The description adds value by instructing the agent to pass the position's con_id 'from get_positions' for an exact match, which is a workflow hint beyond the schema's generic ContractSpec description. It also clarifies combo handling with 'ask per leg'.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: 'Return the live P&L of one position' and enumerates the components (daily, unrealized, realized, market value). This clearly distinguishes it from siblings like get_pnl (portfolio-level) and get_positions (positions list).

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 gives concrete usage guidance: pass the con_id from get_positions for an exact match, and it warns that combos (BAG) trigger invalid_request, implying an alternative approach per leg. However, it does not explicitly name alternative tools for aggregate P&L or when not to use this tool beyond the combo case, 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?

Beyond the readOnlyHint and openWorldHint annotations, the description reveals non-obvious behavioral traits: positions are streamed and always current, avg_cost includes commissions and multiplier, and contract.exchange is omitted, directing follow-up via con_id. These are valuable details not derivable from the schema or 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?

Five sentences with zero waste. The core purpose is front-loaded, followed by fast/current behavior, cost details, sibling routing, a caveat about exchange, and the model_code nuance. Every sentence contributes distinct 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?

The description fully equips an agent to select and invoke the tool: it states the resource, outputs, alternatives, an important data caveat, and parameter scoping. An output schema exists, so return-value documentation is not required, and no missing piece undermines a correct 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 100%, and both parameters are fully documented in the schema. The description adds a brief note about model_code meaning 'lists one model's positions', but this largely mirrors the schema's existing explanation. With the schema carrying the parameter burden, a baseline 3 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 opens with a specific verb and resource: 'List an account's positions', and enumerates the key returned fields (contract, quantity, average cost). It further differentiates from siblings by naming get_portfolio and get_position_pnl for related but distinct data, making its purpose unambiguous.

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?

Explicit routing guidance is provided: 'For market value and unrealized P&L use get_portfolio; for today's P&L of one position use get_position_pnl.' It also clarifies when model_code is appropriate, clearly stating the alternative behavior for financial-advisor accounts.

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 only declare readOnlyHint and openWorldHint. The description adds substantial behavior: latency (~11 seconds), that open streams are reused at no cost, that missing permissions produce specific error codes (354, 10089, 10168), that null prices mean IBKR sent no value, and that partial failures still return quotes for valid contracts. No contradiction 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 long but each sentence contributes essential information: purpose, data fields, latency, stream reuse, exclusions, error handling, permissions, and null semantics. It is front-loaded with the primary action and then layers context. While not minimal, it avoids redundancy and is well-paragraphed, making it scannable.

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 tool with two parameters, a rich contract schema, and an output schema, the description covers all critical operational details: error codes and recovery, permission requirements, latency expectations, stream integration, and data availability limits. It also references related tools (get_smart_components, subscribe_quotes, set_market_data_type) to guide the agent. Nothing essential is missing for correct invocation.

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

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

Schema description coverage is 100%: both parameters (contracts and regulatory_snapshot) are fully documented with constraints and cost warnings. The description adds little beyond the schema—it repeats the 25-contract cap and the cost of regulatory_snapshot, which are already in the schema. It does mention return fields (halted, market_data_type) but those are output, not parameters. Baseline 3 is appropriate since the schema carries the semantics.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a clear verb+resource: 'Get a one-time quote for up to 25 contracts' and enumerates the exact data fields (bid, ask, last, sizes, OHLC, volume). It also distinguishes itself from subscribe_quotes by stating what snapshots do not include (generic ticks) and how they differ from streams, so an agent can tell them apart without inspecting 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?

Explicit guidance is provided: when to use subscribe_quotes instead ('Generic ticks ... are not available as snapshots; use subscribe_quotes'), how to expand bbo_exchange with get_smart_components, and the requirement for market data permissions with fallback instructions (set_market_data_type with 'delayed'). It also explains error behavior when contracts fail, so the agent knows how to handle partial failures.

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 only mark readOnly/openWorld, so the description adds real behavioral value: session-level caching, first-call latency, default limit and cap, total-count semantics, and not_found error behavior. All disclosed traits are consistent with 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 front-loads its purpose, then organizes the remaining content into compact, scannable sections: catalogue sections, filtering behavior, limits, latency, and errors. No sentence is redundant or wasted.

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 read-only catalogue tool with an output schema and annotations, the description covers all four sections, query and instrument filtering, default and maximum limits, total counts, network/session latency, and error cases. Nothing needed 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 descriptions already document all four parameters, so this is a baseline-3 situation. The description still adds meaning beyond the schema by specifying the default limit (50), the cap (500), the total-count signal, and that query for filters also matches group and category.

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 action ('Browse'), a concrete resource ('IBKR's market scanner catalogue'), and its goal ('to find valid inputs for run_scanner'). The section list disambiguates it from scanner execution and from other data-listing siblings.

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 positions the tool as the catalogue look-up step before run_scanner, which is the main user of its output. It also tells the agent how to narrow results using query and instrument, so the right context-of-use is 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. The description adds useful behavioral context beyond that: IBKR reports whole seconds)Skip and that a skew under a second or two is normal, helping an agent interpret results correctly. No contradiction 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?

Three tight sentences: the first states what the tool returns, the second gives practical use cases, and the third provides a calibration caveat. Every sentence earns its place and is 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?

With no parametersasi an output schema present, the description supplies exactly what an agent needs beyond structured metadata: purpose, use cases, and interpretation guidance. Nothing significant 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 tool has zero parameters and the schema coverage is 100%, so there is nothing for the description to clarify. As per baseline for zero-parameter tools, a 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 states a specific verb ('Return') and a precise resource: the gateway's current time plus clock skew. This is unique among the sibling toolsebb and immediately tells an agent what the tool provides.

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?

Clear guidance on when to use the tool: as a cheap round-trip health check and before time-sensitive requests such as historical data end times or good-till times. It does not explicitly name alternatives or exclusions, but the context is strong 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 readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds valuable behavioral context: the data source dependency (market data subscription), the failure mode (not_found), and the meaning of the returned codes. It doesn't detail the output schema, but an output schema exists, so that burden is reduced.

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 sentences, each earning its place: the core action, the data dependency and output meaning, and the failure condition. Front-loaded with the main verb and resource, no 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?

For a single-parameter read-only tool with a full output schema, the description covers the source of the input, the failure mode, and the meaning of the output. Nothing an agent needs to decide whether to call it and what to expect 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 100%, so the schema already documents the parameter. The description adds context by explaining where the bbo_exchange code comes from (get_quotes) and giving an example ('9c0001'), which helps the agent understand the parameter's provenance and format beyond the schema's generic description.

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 ('Expand') and resource ('SMART BBO exchange code'), and explains the output: the exchanges behind the code with IBKR's single-letter codes. It clearly distinguishes itself from get_quotes (which produces the bbo_exchange code) and from other market-data 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 the bbo_exchange code comes from market data via get_quotes, and that a market data subscription or delayed data is required. It also states when the call fails (outside trading hours, or for a code not taken from a quote), giving the agent clear conditions for use and failure expectations.

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 readOnlyHint and openWorldHint annotations, the description discloses substantial behavior: data shape depends on subscription kind, time series are ordered oldest-first and truncated by limit/since, stale indicates a dropped gateway connection, notices carry IBKR messages, and idle subscriptions get cancelled and surface as subscription_not_found. This goes well beyond what annotations or schema provide.

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 dense but well organized: purpose first, then kind-dependent payload shapes, then time-series and truncation semantics, then lifecycle/staleness. Every sentence carries useful information and there is no filler or repetition.

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 that an output schema exists, the description does not need to enumerate return fields; instead it covers the cross-cutting behaviors an agent must know: truncation, stale connections, IBKR notices, and subscription expiry. This is complete for a tool of this 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?

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful parameter behavior: default limit of 100, max of 5000, ordering semantics, the meaning of truncated, and how `since` interacts with time-series data. This supplements the schema without redundantly restating it.

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 uses a specific verb ('Read') and resource ('the latest state of any subscription') and enumerates the data types it covers, which clearly distinguishes it from sibling historical/quote tools. It is immediately obvious what this tool does and which tool family it belongs to.

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 clearly frames this as reading the current state of an active subscription, with the keep-alive behavior making the use case concrete. It does not explicitly name alternative tools or exclusion cases, but the context is strong enough that an agent can infer when it 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?

Beyond the readOnlyHint annotation, the description reveals that times are returned with the exchange's offset so holidays, early closes, and overnight sessions appear as they actually occurred. It also discloses a side effect on IBKR historical-data quota and lists the not_found error case. These details are not present in the annotations and materially shape invocation expectations.

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 front-loaded: the purpose is in the first sentence, followed by one behavioral paragraph, one limit note, and one error line. Every sentence adds distinct value—timezone handling, data limits, and failure modes—with no 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?

With an output schema present, the description needs only the behavioral and error context, which it supplies. It explains timezone formatting, rate-limit implications, the not_found error, and the relevant sibling alternative. No key operational detail an agent needs before calling appears to be 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?

All four parameters already carry prose descriptions in the schema (100% coverage), so the baseline is 3. The description does not add parameter-specific guidance beyond restating the 'recent days' notion that maps to end/num_days. No extra meaning is missing.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: 'Return an instrument's trading sessions (start, end, trading date) for recent days.' It clearly defines the output contents and timeframe, and distinguishes itself by naming get_contract_details as a related alternative for upcoming sessions.

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 sentence 'For the upcoming sessions, get_contract_details also lists trading and liquid hours' gives the agent a concrete alternative when future-looking hours are needed. It also flags that the call counts toward historical-data limits, a practical consideration. However, it never explicitly says when not to use this tool or states a hard branching rule.

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 mark the tool as readOnly and openWorld. The description adds useful behavioral context beyond those hints: the white-branding id can be empty for most direct IBKR clients, implying the return value is not always populated. This helps the agent interpret results without contradicting 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 only two sentences and front-loads the core action ('Return details about the logged-in IBKR user') before explaining the white-branding id. Every sentence adds meaningful context, with no filler or repetition of the schema.

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 no-parameter, read-only tool with an output schema and annotations, the description fully covers what an agent needs to know: what is returned, the meaning of the returned field, and the empty-value case. There are no obvious gaps for correct invocation or result interpretation.

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 parameters, so the baseline is 4. The description adds no parameter-specific semantics, but none are needed. It correctly focuses on the tool's output and meaning instead.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: 'Return details about the logged-in IBKR user.' It then pinpoints the key content (white-branding id) and distinguishes it from account summaries or connection info by emphasizing the user identity and white-label context. This makes the tool's purpose unmistakable.

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 establishes clear context for use: it is for retrieving details about the logged-in IBKR user, specifically the white-branding id. It also clarifies when the value will be empty, which helps an agent decide whether this tool is relevant. It does not explicitly name alternatives, but the context is sufficient given the tool's unique role.

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 carry readOnlyHint=true and openWorldHint=true, and the description adds substantial behavior beyond them: the exact return shape (raw WSH JSON plus a request echo), truncated pagination semantics with remediation advice, the automatic metadata fetch IBKR requires, the paid-subscription failure mode (ib_api_error), and a full error-code map with causes and fixes. No contradiction with the read-only annotation.

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 long but dense — roughly 180 words covering scope options, return format, pagination, prerequisites, and errors for a 9-parameter tool with documented failure modes. It is front-loaded with purpose and follows a logical progression from purpose to inputs to behavior to errors; every sentence earns its place even though it is not as terse as the highest-scoring examples.

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 complexity — 9 parameters, pagination, subscription requirements, and multiple error cases — the description leaves nothing an agent needs for correct invocation: what to pass, how paging works, what the response contains, what subscription is required, and how to interpret failures. The output schema covers return-value structure, so the brief mention of the JSON shape is 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?

Schema coverage is 100%, so the baseline is 3, but the description adds real value: concrete default (50) and maximum (100) for limit, which the schema only vaguely calls 'the tool's default' and 'capped'. It also ties error conditions to specific parameters (dates in the wrong order, unknown event type, bad filter_json), helping the agent diagnose invocation mistakes.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource — 'List Wall Street Horizon corporate events' — followed by concrete examples (earnings dates, dividends, splits, meetings). It explicitly differentiates from the nearest sibling by pointing to get_wsh_metadata for the event-type list, so an agent can tell the two tools apart 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?

The description clearly states the invocation modes ('Give a contract, event_types, a raw filter_json, or fill_portfolio/fill_watchlist'), the narrowing parameters, and the subscription prerequisite. It gets close to explicit when/when-not guidance via the error section ('not_found... widen the dates or check event_types'), but it never names a same-purpose alternative to prefer, which is the only step 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?

Annotations only provide readOnlyHint and openWorldHint, so the description carries more weight. It discloses the caching behavior ('fetched once and then served from this server's cache'), the subscription requirement with the resulting ib_api_error, and the meaning of not_found. These are valuable behavioral details not present in 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 well-structured and front-loaded with purpose, but it repeats some schema details (default 30000, max 200000) and weaves parameter behavior into the usage sentence. It is a few sentences longer than strictly necessary, but each sentence carries useful 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?

Given the tool's low complexity, two optional parameters, and an output schema, the description is largely complete. It covers purpose, usage context, caching, prerequisites, and error semantics. Minor gaps such as refresh behavior for the cache are not critical for correct invocation.

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

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

Schema description coverage is 100%, so the baseline is 3. The description mostly restates what the schema already says about query filtering and max_chars truncation, and even the example 'wshe_ed is the earnings date' appears in the schema. It adds slight context by linking event_types and metadata_json to get_wsh_events, but does not meaningfully enhance parameter understanding 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?

The description opens with a specific verb and resource: 'Describe the Wall Street Horizon (WSH) event calendar: event types and filter fields.' It clearly distinguishes this metadata tool from its data-fetching sibling get_wsh_events by explicitly framing it as the assistant for building get_wsh_events queries.

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 gives explicit usage guidance: 'Use it to build get_wsh_events queries,' directly naming the alternative tool and the scenario in which this tool is appropriate. It also specifies prerequisites (paid subscription) and the failure mode without it, which helps an agent decide whether to call the tool at all.

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 openWorldHint=true, so the safety profile is covered. The description adds valuable behavioral context: the default_account behavior, the null case, paper account naming convention (D prefix), and the restriction that non-allowlisted accounts are only counted and never named. This 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 compact and front-loaded: the first sentence states the core purpose, and subsequent sentences add essential behavioral details without redundancy. 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?

For a parameterless read-only tool with an output schema, the description covers everything an agent needs: what the tool returns, how to interpret the default_account field, and the constraints on account usage. The output schema presumably details the return structure, so the description need not repeat 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 zero parameters, so the schema provides no parameter semantics. The description compensates by explaining the output's key fields (default_account, other_managed_accounts) and their implications, which is the relevant semantic content for a parameterless tool.

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 lists IBKR accounts the server may use and identifies the default. It distinguishes itself from sibling account-related tools by focusing on account scope rather than account values or summaries.

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 explains when to use this tool: to determine which account to pass to account-scoped tools, especially when default_account is null. It also clarifies that accounts outside the allowlist cannot be used, providing clear guidance for tool 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 provide readOnlyHint and openWorldHint, so the description only needs to add interpretive context. It does: idle expiration via `idle_expires_at`, `stale` while the gateway connection is down, and capacity relative to server and IBKR limits. No contradiction 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 front-loaded with the core scope in the first sentence and then organizes details logically: per-subscription fields, idle/stale behavior, then capacity and connection type. Every sentence adds useful information without padding.

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 and an output schema exists, the description covers everything an agent needs to invoke it correctly and interpret the result: which subscriptions are included, what fields appear, staleness semantics, and capacity limits. Nothing material 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 tool has zero parameters and an empty input schema, so there is no parameter meaning for the description to augment. The baseline of 4 applies; the description sensibly devotes its space to the response contents instead.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with 'List every open subscription of every kind,' giving a specific verb, resource, and scope, followed by concrete kinds: quotes, depth, ticks, bars, scans, news. This makes the tool's purpose unmistakable and clearly distinct from lower-level retrieve or subscribe 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 makes the usage context clear: this is the tool for an overview of all open subscriptions and their state, including capacity and staleness. It does not explicitly name a per-subscription alternative or give when-not conditions, 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?

Beyond the readOnlyHint/openWorldHint annotations, the description discloses specific failure modes (ambiguous_contract with up to 20 candidates, not_found, invalid_request for combos) and explains the returned `description` field. This gives the agent a precise model of tool behavior.

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 front-loaded with the core purpose, then covers failure modes in two short paragraphs. No wasted words or redundant detail.

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?

Combined with the rich schema and output schema, the description covers the main use case, return value, and error recovery steps. It doesn't explicitly mention alternatives like search_symbols, but the scope is well-defined and practically 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?

The schema is already rich (100% coverage via ContractSpec and field descriptions). The tool description adds targeted guidance about con_id being unambiguous and what to provide for options, which complements rather than repeats 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?

The description states a specific verb ('Resolve') and resource ('contract spec to exactly one IBKR contract') and explains the output (con_id). It clearly differentiates from siblings like get_contract_details and search_symbols by focusing on resolution to a single contract.

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 to use it before quoting/ordering and to turn a symbol into a con_id, and states not to use it for BAG combos (qualify legs by con_id instead). It doesn't name alternative siblings such as search_symbols, but the context is clear and actionable.

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, so the safe-read nature is covered. The description adds substantial behavioral context beyond that: the 50-row limit, the 10-subscription cap and the fact that a run temporarily uses and releases a subscription, the market-data permission requirement, and a detailed error taxonomy (not_found, ib_api_error, subscription_limit). This is exactly the kind of operational nuance an agent needs.

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 organized into clear sections: purpose, example, output shape, limits, permissions, and errors. Every sentence contributes information needed to call the tool correctly or interpret results, and there is no filler or redundancy. It is longer than a one-liner, but the length is justified by the tool's complexity.

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 10 parameters, no enums, and relies on external knowledge (scan codes, locations, filters), the description is complete: it explains how to discover valid values, what the output contains, what the limits are, what permissions are needed, and what errors to expect. The presence of an output schema further reduces the need to describe return values in prose. Nothing essential is missing for correct invocation.

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

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

Schema coverage is 100%, so the baseline is 3 per the rubric. The description adds value beyond the schema by giving a concrete composition example (scan_code=TOP_PERC_GAIN, instrument=STK, location_code=STK.US.MAJOR, above_price=5) and by pointing to get_scanner_parameters for valid values. This helps the agent understand how multiple parameters combine, even though each individual parameter is already documented 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?

The description opens with a specific verb and resource: 'Run an IBKR market scan once and return the ranked instruments, best first.' The word 'once' clearly distinguishes it from the sibling subscribe_scanner, and the example further pins down what the tool does. It also tells the agent what each row contains, making the output expectation clear.

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 directs users to get_scanner_parameters for discovering valid scan codes, locations, and filter tags, which is a clear alternative for parameter selection. It also states 'once', implying a one-shot operation versus ongoing subscription, but it does not explicitly name subscribe_scanner as the alternative for continuous scanning. The guidance is strong but not fully explicit about when not to use this 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 and openWorldHint, lowering the bar, but the description adds substantial behavioral detail: default and typical limit of 16 matches, the truncated flag, exact fields returned, per-second rate spacing, and specific error cases (not_found, request_timeout with a 4-second threshold). This goes well 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 dense but every sentence earns its place: the first line states the core function, the second explains return shape and next steps, and the third covers limits, rate behavior, and error semantics. It is front-loaded with the most important information and contains no filler.

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