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

The annotations already indicate read-only and idempotent behavior. The description adds a valuable behavioral detail by noting it provides an OrderPreview from ibkr_preview_order, implying an internal call to another service. It does not contradict 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 two sentences, with the core purpose front-loaded ('Compute portfolio-level impact...'). The additional sentence about ibkr_preview_order is informative but could be seen as slightly tangential. Overall, it is concise and well-structured.

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 complex schema with multiple nested definitions, the description is insufficient. It does not explain the optional preview parameter, the account_id, or how the order and preview interact. The output schema is provided, but the description lacks critical context 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 top-level parameters (order, preview, account_id) have no descriptions in the schema (coverage 0%). The description does not explain any of these parameters, their relationships, or how they affect the computation, leaving users to guess their roles.

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 'computes portfolio-level impact' including specific outputs like concentration change, buying-power usage, margin impact, and max-loss estimate. It also distinguishes from siblings like preview_order by focusing on impact analysis rather than just previewing an 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 does not explicitly state when to use this tool over alternatives such as preview_order or get_portfolio_risk. It mentions using ibkr_preview_order for accuracy but does not explain the decision context or contrast with sibling 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 destructiveHint=true, covering the destructive nature. The description adds that it only works on open orders and targets a single order, providing useful context beyond the annotation. 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?

A single concise sentence that front-loads the action and scope. No filler or unnecessary 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?

For a simple operation with one parameter and an output schema present, the description covers the essential scope (single, open order) and the annotation covers destructiveness. It lacks explicit error conditions, but given the simplicity it is adequately complete.

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

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

Schema has only order_id with no description and 0% coverage, so the description must compensate. It mentions 'by order id' which is minimal and largely restates the parameter name. It adds that the id must belong to an open order, but does not explain where to obtain the id or its format.

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 the verb 'Cancel', the resource 'single open order', and the method 'by order id'. Clearly distinguishes from siblings like cancel_order_set (which cancels a set) and cancel_trade_intent (which cancels a trade intent, not an 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 scope is implied as 'single open order', which differentiates it from cancel_order_set for multiple orders. However, it does not explicitly mention alternatives or when not to use this tool, so it falls short of explicit 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?

The destructiveHint annotation already declares that this operation is destructive, so the description doesn't need to repeat that. The description adds that it targets a related set of orders, but it does not disclose additional side effects such as partial failures or what happens to the legs after cancellation. This is acceptable given 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 a single, front-loaded sentence with no filler. It states the action, the object, and a relevant example, earning its place without unnecessary 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?

For a one-parameter destructive tool with an output schema, the description, annotations, and input schema provide enough context to understand and invoke the tool correctly. It could be more explicit about alternatives, but the core behavior and target are clear.

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

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

Schema description coverage is 0%, and the description never mentions the order_ids parameter. The parameter name and type are somewhat self-explanatory, but the description does not compensate for the lack of schema-level descriptions by explaining what the IDs refer to or how they should be provided.

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 ('Cancel') and a precise resource ('a set of related orders'), with a concrete example ('bracket legs') that distinguishes it from sibling tools like cancel_order. It clearly communicates the tool's scope.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

The example 'such as bracket legs' provides clear context for when to use this tool, and the word 'set' implies batch/related cancellations. It does not explicitly mention alternatives like cancel_order or get_order_set_status, so it lacks full when-not 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?

The annotation destructiveHint: true aligns with the description's 'cancel' action. The description adds valuable detail by specifying that it cancels 'all active broker orders', which clarifies the scope beyond a generic destructive flag. It does not mention potential partial failures or idempotency, but the annotation already signals destructiveness, so the description sufficiently enhances transparency.

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 a single, compact sentence with no redundant words. It conveys the essential information efficiently, perfectly matching the tool's purpose without unnecessary elaboration.

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?

While the output schema exists (though not shown), the description leaves some ambiguity about whether the trade intent itself is cancelled or only its orders are cancelled, as the tool name suggests 'cancel trade intent' but the description focuses on orders. It also does not mention preconditions (e.g., intent state) or side effects. This partial ambiguity reduces completeness, though the core action is clear enough for an agent to proceed.

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 only defines intent_id without any description. However, the tool description says the orders are 'associated with a trade intent', which implicitly clarifies that intent_id identifies the trade intent whose orders will be cancelled. This compensation is adequate given the single parameter, though it doesn't explicitly define the ID format or constraints.

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

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

The description clearly states the action: 'Cancel all active broker orders associated with a trade intent.' It specifies the resource (broker orders) and the scope (associated with a trade intent), making the primary purpose unambiguous. The verb 'cancel' is precise and distinct from other sibling tools that create, submit, or fetch intents.

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 this tool (when all orders tied to a trade intent need cancellation) but does not explicitly contrast it with alternatives such as cancel_order (single order) or cancel_order_set (multiple orders). No direct 'use this instead of X' guidance is provided, though the sibling list makes the distinction inferable.

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 readOnlyHint and idempotentHint annotations already establish the safety and side-effect profile, and the description's 'poll' language aligns with that. The description adds the possible status values but does not mention error behavior or response details, so a mid-range score is appropriate.

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 a single focused sentence with no redundant words. It efficiently communicates the tool's purpose and the possible status values.

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 status values are a useful inclusion, and the existence of an output schema means return values need not be spelled out. Given the simple one-parameter nature, the description is largely complete, though it could have briefly noted that approval_id identifies the specific approval being polled.

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

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

Schema description coverage is 0%, and the description does not explain the approval_id parameter beyond its name. Since there is only one parameter and it is not described, the description adds no semantic value over 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 clearly states that the tool polls the status of an approval, and it specifies the three approval types (trade, trade-intent, execution-unlock). The status value list further clarifies the exact result 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 implies this is for checking approval status, but it does not explicitly distinguish it from related tools like get_trade_intent, request_trade_approval, or get_order_status. No condition is given for when to choose this tool over a 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 idempotentHint=true, and the description does not contradict them. It adds the behavioral detail that the tool returns a boolean 'passed' value, which is informative. However, it does not elaborate on side effects (likely none) or error behaviors, but given annotations cover safety profile, this is adequate.

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, consisting of two sentences with no redundant wording. It directly states the purpose and the expected outcome, making it efficient and easy to parse for an agent.

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 the complexity of the input schema (with a detailed OrderSpec and SymbolSpec), the description only offers a high-level overview. It does not clarify how account_id and profile_id interact with the order, what 'position limits' encompass, or how the validation result should be interpreted by the caller. The output schema exists but the input context remains underexplained 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 description coverage is 0% for the three top-level parameters (order, account_id, profile_id), and the description provides no explanation of these parameters or their roles. The only inferred parameter is the 'proposed order' mentioned in the description, but account_id and profile_id are entirely unaddressed, leaving the agent without necessary semantic understanding.

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

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

The description clearly states the tool's function: validating a proposed order against position limits, and explicitly defines the return value (passed=true when no violations). It uses a specific verb ('validate') and specifies the resource ('active agent profile's position limits'), making the purpose unambiguous even among 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 does not provide any guidance on when to use this tool versus alternatives like validate_against_profile, check_approval_status, or assess_order_impact. It implicitly suggests use during order validation but lacks explicit direction, leaving the agent to infer the appropriate context without contrasting sibling 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 carry idempotentHint and destructiveHint; the description confirms idempotency with 'Create or return' and 'idempotent'. It adds the persistence context ('persists the basket and optional previews'). However, it never discloses any destructive behavior that destructiveHint: true implies, and its creation-focused framing could understate the destructive potential. No direct contradiction, but the destructive side is left undisclosed.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences with the core action front-loaded. The second sentence adds the 'before submission' workflow context. Slightly redundant ('create... trade intent' vs 'persists the basket') but overall tight and efficient.

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

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

For a complex tool with 4 parameters at 0% schema coverage and no nested-object documentation, the description is too sparse. It omits the meaning of required 'reason', the behavior of preview_orders, and the workflow relationship to submit_trade_intent. The presence of an output schema helps but does not offset these gaps.

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

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

Schema description coverage is 0% for the 4 top-level parameters, so the description carries full responsibility. It hints at 'explicit orders' (orders) and 'optional previews' (preview_orders) but never explains the purpose of 'reason' or 'account_id'. The description does not adequately compensate for the total lack of schema-level parameter documentation.

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 (create/return) with a clear resource (basket-style trade intent). It differentiates from siblings by emphasizing 'basket-style' (vs single-order tools like place_order) and 'before submission' (vs submit_trade_intent). An agent can reliably distinguish this 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?

'Before submission' implies this is the create step preceding submit_trade_intent, and 'basket-style' implies multi-order usage vs single-order alternatives. However, it never names a sibling explicitly nor states when NOT to use this tool versus preview_order_basket or place_order. The usage context is implied, not explicit.

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 fully discloses the destructive and side-effect behavior: cancelling all open orders, disabling order placement via control.json (persistent config change), and sending a Telegram alert (external notification). This goes beyond the destructiveHint annotation by specifying exact consequences.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise, using a single short sentence with a strong opening label ('PANIC BUTTON:') to emphasize urgency. It lists exactly three concrete actions with no filler or redundancy.

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

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

Given the tool's simplicity and the presence of an output schema (not shown but assumed), the description covers all essential aspects: scope of cancellation, persistent configuration change, notification side effect, and usage constraint. No additional context is needed for an agent 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?

The only parameter 'reason' is optional with a default, but the description provides no explanation of its purpose or expected content. The schema also lacks a description, so the description adds no meaning to the parameter. Since it is a simple, self-explanatory name, a score of 2 is appropriate rather than 1.

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 ('cancel'), a clear scope ('ALL open orders'), and lists additional actions ('disable order placement', 'send a Telegram alert'). It distinguishes itself from sibling cancellation tools like cancel_order or cancel_order_set by emphasizing the global and emergency nature.

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 states 'Use only in emergency situations' and labels the tool as a 'PANIC BUTTON'. This gives clear guidance on when to invoke it versus normal cancellation tools, leaving no ambiguity about appropriate use.

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 destructiveHint annotation, the description explicitly discloses concrete side effects: applying safety locks to control.json, switching the active connection port in config.json, and automatic reconnection on the next tool call. This gives the agent a strong mental model of what executing this tool will do.

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, front-loaded purpose, and no filler. Every sentence adds essential information about prerequisites, side effects, or postconditions.

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 prerequisites, exact file changes, and reconnection behavior, and an output schema exists so return values do not need explanation. The main gap is the unexplained target_env parameter, which is required and could prevent correct invocation without additional context.

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 description gives meaningful semantics for approval_id by telling the agent to source it from ibkr_request_environment_change. However, target_env is completely undocumented in both the schema and the description; with 0% schema description coverage, the description should have clarified what target_env values look like or where they come from.

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 a specific action ('Apply an approved environment change') and names the exact resources affected (control.json and config.json). This distinguishes it from the sibling request_environment_change tool, which is about requesting rather than executing.

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 by requiring an approval_id from ibkr_request_environment_change, implying this should be used only after approval. It does not explicitly list when-not-to-use cases or name alternatives, but the approved-change framing is enough for correct 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?

Annotations already declare read-only and idempotent behavior, so the description doesn't need to repeat that. However, it adds no extra context about error handling, defaults, or side effects, which is acceptable given the annotations but not enhanced.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, focused sentence with no extraneous words or repetition. It is well-structured and immediately conveys the tool's purpose.

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

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

Given the tool's simplicity and the presence of an output schema, the description adequately covers the essentials. It lacks explicit mention of default behavior or edge cases, but these are not critical for a straightforward read-only retrieval.

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

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

The schema has zero description coverage, and the tool description fails to explain the account_id parameter—whether it is required, what it represents, or what happens when omitted. The description provides no semantic value beyond the parameter name.

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

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

The description clearly states the tool retrieves account balances, buying power, and margin metrics, specifying the exact resource and data types. This distinguishes it from siblings like get_positions or get_pnl.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

No guidance is provided on when to use this tool versus alternatives, nor any context about prerequisites or typical use cases. It simply states what it does without indicating scenarios.

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 idempotentHint, so the description need not repeat that. It adds value by clarifying that the profile is the 'active' one and that it includes constraints, which gives the agent a fuller picture of what to expect beyond the raw schema. No contradictions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences with zero redundancy. The core purpose is stated first, followed by a compact parameter usage note. Every word earns its place; there is no fluff 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 the tool's simplicity (one optional parameter), the existing output schema (which will document return values), and the safety annotations, the description covers everything an agent needs to call it correctly. No critical details are missing.

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

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

Schema description coverage is 0%, so the description must carry the full burden for the single parameter. It clearly explains that profile_id fetches a specific profile and that omitting it loads the default. This directly compensates for the sparse schema, exceeding the baseline requirement.

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 (load and return), a clear resource (agent trading profile), and adds the qualifier 'with its constraints.' It is distinct from the sibling tools like get_trade_intent or get_account_summary, and no ambiguity exists about what it retrieves.

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 parameter-level guidance (use profile_id or omit for default), but it does not explicitly state when to choose this tool over alternatives. Since no sibling tool directly overlaps (e.g., a 'list_profiles' or 'get_profile' does not exist), the lack of exclusion criteria is acceptable, but the guidance is not fully explicit.

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 declare readOnlyHint and idempotentHint, and the description's verb 'Query' aligns with these. The description adds useful behavioral details about the limit default and maximum, which goes beyond the annotations. It does not describe the return format, but that is likely covered by the output schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, focused sentence that directly conveys the tool's purpose and key parameters. No unnecessary words or redundancy.

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

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

Given the output schema is present, the description does not need to detail return fields. It covers the essential query behavior and parameters. The brevity is sufficient for a simple read-only query tool, though it could mention filtering semantics (e.g., AND combination) for full clarity.

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

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

The schema has no descriptions for its 6 parameters, and the description lists the filter names (event_type, symbol, account_id, date range, limit) without explaining their format or interaction. It adds the default/max limit info, but lacks details on date format or allowed event_type values, leaving some ambiguity.

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 'Query' and the resource 'SQLite audit log', providing a specific scope. It does not explicitly name a sibling alternative, but the tool name and description are unambiguous enough to distinguish it from other query tools like get_quote or get_account_summary.

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 mentions filterable fields and the limit parameter, but does not explicitly state when to use this tool versus alternatives, nor does it mention any prerequisites or contextual cues. It is adequate for a straightforward query tool but lacks explicit usage 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?

The annotations declare readOnlyHint and idempotentHint as true, and the description's 'Get' wording is consistent with a non-mutating operation. No additional behavioral context is required, though it could mention that it does not modify 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 a single, concise sentence with no redundant information. It focuses on the core purpose without 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?

The description omits details about the output format (e.g., array of bars, columns) and any error conditions. While the purpose is clear, the sparse information might leave an agent uncertain about the expected response structure or pagination behavior.

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

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

The tool description does not explain any of the top-level parameters (bar_size, duration, rth_only, what_to_show). The schema provides defaults but no format constraints or allowed values, leaving an agent to guess valid inputs such as '1 day' or '1 hour'.

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

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

The description clearly identifies the function as retrieving historical OHLCV bars for a specified instrument, using the verb 'Get' and naming the data type. It distinguishes itself from related read-only tools like get_quote and get_option_snapshot by focusing on historical data.

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 no guidance on when to use this tool versus alternatives. It does not mention that it is for historical analysis rather than real-time data, nor does it state any prerequisites or limitations (e.g., instrument resolution).

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 idempotentHint, so the safety profile is covered. The description adds that results are a bounded list of qualified candidates and that only single-leg contracts are included, which is useful behavioral context. However, it doesn't explain what qualifies a candidate, how bounds are determined, or what the returned list represents beyond being qualified.

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 a single front-loaded sentence with no filler. It communicates the core action and a key result constraint efficiently. Every word 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?

Despite having an output schema, this tool is complex with 10 parameters and 0% schema description coverage. The description does not explain parameter interactions, default behavior for strike_count and max_candidates, how expiry filters combine, or what 'qualified candidates' means. An agent would need substantial external knowledge to 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?

Schema description coverage is 0%, and the description provides no parameter-level meaning. With 10 parameters including rights, expiries, strike filters, strike_count, max_candidates, and option_exchange, an agent gets no help understanding their roles or relationships from the description. The schema itself has minimal descriptions and no enums, so the burden falls entirely on the description, which fails to carry 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 clearly states the tool discovers single-leg option contracts for an underlying and returns a bounded list of qualified candidates. This is more specific than the title alone and gives a distinct sense of the tool's purpose. It doesn't explicitly differentiate from the sibling get_option_snapshot, but the mention of a bounded candidate list helps an agent infer the distinction.

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 no guidance about when to prefer this tool over siblings such as get_option_snapshot or resolve_contract. There are no explicit conditions, exclusions, or alternative tools mentioned. The usage context is only implied by the phrase 'for an underlying,' which is not enough for an agent deciding among many related option 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?

The 'Get' wording is consistent with the readOnlyHint and idempotentHint annotations, and the description adds that the tool returns quote, volatility, and greeks. It does not go beyond annotations with side-effect detail, but no contradiction exists and the read-only behavior is clear.

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 a single, focused sentence that front-loads the action and output. It contains no filler or redundant 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 simple read-only snapshot tool with one object parameter and an output schema, the description is largely complete. It could be slightly more explicit about the need for a fully resolved contract (e.g., strike/expiry/right), but 'fully specified single-leg option' covers the main requirement.

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 description does not add specific meaning to the `instrument` parameter beyond saying it must represent a fully specified single-leg option. The schema already describes individual fields like symbol, securityType, strike, expiry, and right, so the description contributes limited additional parameter 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 clearly states a specific action ('Get') and a specific resource ('option snapshot'), and enumerates the returned data (quote, volatility, greeks). The qualifier 'fully specified single-leg option' distinguishes it from chain and multi-leg 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 implies when to use the tool—when a fully specified single-leg option snapshot is needed—but it does not explicitly name alternative tools like get_quote or get_option_chain or state when not to use them. More explicit cross-tool guidance would improve this 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 cover read-only and idempotent behavior, lowering the bar. The description adds the aggregate/list aspect but does not disclose any other behavioral details such as relationship definition, limits, or ordering. It provides minimal additional context 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 a single, front-loaded sentence with no fluff or redundancy. It efficiently states the core purpose without wasting words.

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

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

For a simple read-only tool with an output schema, the description is somewhat adequate, but it leaves ambiguity about when to use this instead of get_order_status and what 'related' means. The presence of output schema mitigates the need to describe return values, but usage context is missing.

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

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

Schema description coverage is 0%, so the description should compensate, but it only paraphrases the parameter name ('list of related order ids') without adding meaning about the 'related' relationship, format, or constraints. The schema already indicates an array of strings, and the description adds little beyond that.

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

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

The description clearly states the action (get aggregate status) and resource (a list of related order ids). It distinguishes itself from the sibling get_order_status by indicating aggregate and plural scope, so an agent can tell them 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?

There is no guidance on when to use this tool versus alternatives like get_order_status or cancel_order_set. It does not mention any conditions, prerequisites, or exclusions, leaving the agent to infer usage.

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

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

Annotations already provide readOnlyHint=true and idempotentHint=true, so the description's read-only nature is redundant. The phrase 'latest status' adds a minor nuance about recency but does not disclose any additional behavioral traits such as caching, staleness, or failure modes. The description aligns with annotations, so 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?

A single concise sentence that front-loads the verb and resource. No wasted words, and it is appropriately sized for a simple lookup tool.

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

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

The tool is simple but the single parameter is completely undocumented in both schema and description, leaving a significant gap in how to call it. While an output schema exists, the input side is lacking. Additionally, no guidance on prerequisites or differentiation from similar tools is given, making the description insufficient for an agent to reliably use it.

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

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

Schema description coverage is 0% and the description merely repeats the parameter name 'order id' without adding any format, source, or validation details. Since the schema provides no description and the tool description does not compensate, an agent has no guidance on how to construct a valid order_id.

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

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

The description clearly states the action ('Get') and resource ('latest status for a single order id'), which is specific and differentiates from siblings like list_open_orders (multiple orders) and get_order_set_status (order sets). The verb and resource are 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 usage is implied: it is for a single order id. However, there is no explicit guidance on when to use this tool versus alternatives like get_order_set_status or list_open_orders, and no exclusion criteria are given. An agent might still be uncertain about edge cases (e.g., order sets).

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 idempotentHint: true, covering the main behavioral traits. The description adds no extra context such as data volume, permission requirements, or any side effects. It merely restates the function, offering no additional transparency beyond what annotations already 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 a single concise sentence that is front-loaded with the core purpose. There is no wasted language, and it is easy to parse. It is not verbose, though it could arguably be more informative without sacrificing conciseness.

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

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

Given the presence of an output schema, the description does not need to explain return values. However, with two undocumented parameters and no usage guidance, the description is incomplete for an agent to call the tool correctly. It lacks any context about how to construct a valid request, making it insufficient for effective 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 0%, and the description gives no information about the 'timeframe' or 'account_id' parameters. It does not explain allowed values, formats, or how they affect the result. With both parameters undocumented, the description completely fails to compensate, leaving the agent without any guidance on how to fill them.

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 'Get' and the resource 'account P&L' with a specific detail 'per-symbol breakdown.' It is unambiguous about what the tool does. However, it does not explicitly differentiate from siblings like get_account_summary or get_positions, so it misses a point for sibling distinction.

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 no guidance on when to use this tool versus alternatives. It does not mention scenarios like 'use when you need profit/loss details' or 'use instead of get_account_summary for P&L.' No exclusions or alternative routing are given, leaving the agent to infer the appropriate context.

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

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

Annotations already declare readOnlyHint and idempotentHint, so the description does not need to repeat those. It adds context about which metrics are computed, which is useful, but it does not disclose behavior such as how account_id null is handled or whether results are aggregated across accounts. The bar is lower given annotations, and the description provides moderate additional 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?

A single, front-loaded sentence with no filler. It lists the key outputs without waste, achieving high information density in minimal space.

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

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

The description covers the core purpose and output metrics, but it lacks parameter semantics and usage context. The output schema presumably documents return values, so that is covered, but the optional account_id is unexplained and no guidance on interpretation or prerequisites is given. For a read-only risk tool with a simple parameter list, it is partially complete but has clear gaps.

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

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

Schema description coverage is 0%, so the description must explain the account_id parameter, but it does not mention it at all. The description entirely fails to compensate for the schema gap, leaving the parameter's meaning and effect (e.g., default behavior when null) completely 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?

The description uses a specific verb ('Compute') and resource ('portfolio-wide risk metrics'), and enumerates exact metrics (margin utilisation, concentration by symbol, unrealised P&L, overall risk level). This clearly distinguishes it from sibling tools like get_pnl or get_positions, which are narrower in scope.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

The description implies usage for risk assessment but provides no explicit guidance on when to choose this tool over alternatives (e.g., get_account_summary, get_positions) or any exclusion criteria. It lacks 'when not to use' or naming of alternatives, leaving the agent to infer.

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 idempotentHint, and the description 'List' aligns with those. It adds no significant behavioral details 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?

Single concise sentence with no redundant wording or unnecessary 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?

Adequate for a simple read-only list, but does not describe return format or default behavior when account_id is omitted. Not a significant gap for such a straightforward tool.

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

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

The description mentions 'for an account' implying account_id selects the account, but it does not explain the optional/null default behavior. Schema coverage is minimal.

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?

Explicit verb 'List', resource 'open positions', and scope 'for an account' clearly identify the tool's purpose and distinguish it from account summary, PnL, and risk 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?

No usage guidance or comparison with sibling tools; it does not state when to prefer this over get_account_summary or get_portfolio_risk.

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 and annotations align: readOnlyHint and idempotentHint are consistent with the term 'snapshot'. However, the description adds little beyond the annotations about side effects or failure modes.

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 a single, focused sentence with no redundant wording. It front-loads the action and object clearly.

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

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

Given the presence of an output schema and read-only/idempotent annotations, the one-sentence description is largely sufficient for typical usage. It could be slightly more explicit about what 'fully specified' entails, but it is not incomplete in a harmful way.

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 top-level 'instrument' parameter lacks a direct description, though the nested SymbolSpec definition provides some field-level detail. The phrase 'fully specified instrument' hints at required completeness but does not fully explain which fields are essential for a quote.

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

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

The description clearly states the action ('Get') and the resource ('market-data snapshot') for a fully specified instrument. It is not overly broad, though it does not explicitly distinguish itself from siblings like get_option_snapshot.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

The phrase 'fully specified instrument' loosely implies a precondition but gives no explicit direction on when to use this tool versus alternatives such as get_option_snapshot or resolve_contract. No when-not guidance is provided.

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

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

Annotations already declare readOnlyHint and idempotentHint, so the tool's safety profile is known. The description adds the context that it inspects a 'configured' schedule window, which implies it returns configuration details rather than dynamic state. This is a minor addition beyond annotations, so a 3 is appropriate.

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 a single, concise sentence that front-loads the action. It contains no filler or redundant wording, making it highly efficient for an agent to parse.

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

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

Given that the tool has an output schema (which is not shown here but is indicated as present) and no parameters, the description is largely sufficient. It conveys the purpose clearly. The only gap is the absence of context about when to use it, but that falls under usage guidelines, not completeness of the operation itself.

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 schema coverage is trivially 100%. The description does not need to explain parameters, and the baseline for no-parameter tools is 4. No additional parameter information is required.

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 a specific action (inspect) on a specific resource (configured trading schedule window). It is more specific than the name alone and implies what the tool returns. However, it does not explicitly differentiate from sibling tools like get_trading_status or health, which could also relate to trading state.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

No guidance is provided on when to use this tool versus alternatives. There are many sibling tools (e.g., get_trading_status, health) that might be confused with this one, and the description does not clarify under what circumstances an agent should choose this over them.

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

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

The annotations already declare readOnlyHint and idempotentHint, and the description aligns with a safe, read-only summarization behavior. It adds useful context about session scope and recent orders but does not elaborate on data freshness or potential variations.

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 a single, focused sentence with no redundant wording. It efficiently conveys what the tool does and what it returns.

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 adequately explains the tool's output categories and the inclusion of recent orders. However, it does not define 'today's session' boundaries or timezone, which could be mildly ambiguous in a trading context.

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?

There are no parameters in the schema, so the description does not need to explain parameter behavior. The baseline for zero parameters is appropriate 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 clearly states the tool's purpose with a specific verb ('Summarise') and resource ('trading activity for today's session'), including the categories of orders and a list of recent orders. It distinguishes itself from related order and account 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 implies usage for getting a session-level summary of trading activity, but it does not explicitly state when to use this tool versus alternatives like list_open_orders, get_order_status, or get_pnl.

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

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

The annotations already declare readOnlyHint and idempotentHint, and the description is consistent with these. No additional behavioral context is provided, but this is acceptable given the annotations cover safety aspects.

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 a single, concise sentence with no unnecessary words or repetition. It is well-structured and directly to the point.

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 is adequate for a simple fetch operation. It states what will be returned (state and orders). While it does not detail the exact return structure, no output schema is provided, so the description covers the essential context needed for basic usage.

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

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

The schema provides only the parameter name 'intent_id' with no description. The tool description does not elaborate on what the intent_id represents, its format, or any required conventions. Since schema coverage is 0%, the description should compensate but fails to do so beyond the implicit meaning of the parameter name.

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 fetches the persisted state of a trade intent and its orders, using a specific verb 'Fetch' and a specific resource. It is easily distinguished from sibling tools like list_trade_intents or get_order_status.

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 lacks any guidance on when to use this tool versus alternatives such as list_trade_intents or get_order_status. There is no mention of typical scenarios or conditions that would make this tool the preferred choice.

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 idempotentHint, so the safety profile is covered. The description adds the detail that it reads from control.json, which is useful but minimal. It does not describe the response content or any other behavioral traits, though the output schema presumably covers that.

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 a single sentence with no filler. It is front-loaded with the verb and resource, and every word earns its place. Excellent conciseness.

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

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

For a zero-parameter tool with an output schema, the description is adequate but could be more specific about what 'trading-control state' includes. It does not clarify whether it covers trading enabled/disabled, circuit breakers, or other control flags. The output schema likely fills this gap, but the description alone is slightly vague.

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?

There are zero parameters, so the schema is trivial. The description does not need to explain parameters. With no parameters, a baseline of 4 is appropriate because the tool cannot have parameter ambiguities.

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 (inspect) and resource (trading-control state) and even names the source (control.json). It distinguishes from siblings like get_schedule_status by focusing on trading-control state, but does not elaborate on what that state encompasses, leaving some ambiguity.

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 no guidance on when to use this tool versus the many sibling status tools (e.g., get_schedule_status, get_order_status). It does not mention alternatives or exclusions, leaving the agent to infer context from the name alone.

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

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

Annotations already indicate read-only and idempotent behavior. The description adds context about the scope ('basic' health) and the specific target ('gateway connectivity'), which provides useful behavioral nuance 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 a single, clear sentence with no redundant words. It is perfectly sized for the simplicity of the tool.

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

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

Given the tool's simplicity and the presence of an output schema (as indicated in context signals), the description is sufficient. It does not describe the output format, but with an output schema present, that is not required.

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

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

The tool has zero parameters, so there is nothing to explain. The baseline score of 4 applies, and the description appropriately avoids irrelevant parameter details.

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

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

The description clearly states the tool's function with a specific verb ('Check') and resource ('gateway connectivity and basic runtime health'), distinguishing it from sibling tools that perform other actions.

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?

While not explicitly naming alternatives, the purpose is so straightforward that the appropriate usage is implied. It is evident this should be used to verify system status, and no other tool in the list serves this exact function.

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 idempotentHint=true, covering the safety profile. The description adds the 'active IBKR connection' context and the 'currently open' temporal scope, which are useful beyond annotations. No contradictions and no missing behavioral disclosures.

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?

A single sentence that is front-loaded with the action and resource, with no filler. Every word 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 list with an output schema available, the description fully specifies the scope and context. An agent can invoke it correctly without additional details.

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?

There are zero parameters, so the description has nothing to add about parameters. With an empty schema and 100% coverage, the baseline of 4 is appropriate; the description does not need to compensate for any undocumented params.

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 action (list), a clear resource (currently open orders), and a context (active IBKR connection). It is distinct from siblings like get_order_status (single order) and list_trade_intents (trade intents), so an agent can easily tell 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?

The description implies when to use it (to see current open orders) but does not explicitly contrast with alternatives or mention when not to use it. For a zero-parameter read-only list, the context is clear enough, but explicit guidance on selecting it over get_order_status would improve the 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?

The annotations already declare readOnlyHint and idempotentHint, so the safety profile is covered. The description adds no extra behavioral details (e.g., side effects, errors), but it does not contradict the annotations either.

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 a single, efficient sentence that conveys the essential purpose without extraneous words. It is well-structured and immediately understandable.

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 simple list operation, the description provides the core intent but lacks contextual details such as the output format, pagination behavior, or relationship to other list operations. It is minimally adequate but not richly contextual.

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

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

The schema has two parameters (limit and status) with no per-parameter descriptions. The description mentions only 'status' filtering, leaving 'limit' unexplained and the allowed values or format of status unspecified. Parameter coverage is incomplete.

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

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

The description clearly states the action (list), the resource (trade intents), and specific modifiers (recent, persisted) along with an optional filter (status). This uniquely identifies the tool among siblings like create_trade_intent and get_trade_intent.

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 is given on when to use this tool versus alternatives. While it is clear as a listing operation, there is no mention of when to prefer it over get_trade_intent or list_open_orders, nor any indication of constraints or prerequisites.

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

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

Annotations already declare destructiveHint=false and openWorldHint=true. The description adds value by stating that the notification is purely informational and requires no approval, which is an important behavioral caveat in a toolset full of approval-requiring trade actions. 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 two short sentences with no filler. The core purpose and the key approval caveat are front-loaded, and every phrase adds meaning.

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 simple notification tool, the description plus annotations and output schema cover most invocation needs. The main gap is parameter semantics, especially the level field, but an agent can still safely call the tool with the required title and body.

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

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

Schema description coverage is 0%, and the description does not explain title, body, or level. The parameter names are somewhat intuitive, but the description provides no compensation for the lack of schema descriptions, especially for the level field and its valid values.

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 ('Send'), identifies the recipient ('operator'), the channel ('Telegram'), and the content type ('informational'). It is clearly distinguishable from the trading and approval sibling tools, none of which send operator notifications.

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 when to use the tool: for purely informational operator notifications. It also explicitly excludes approval requirements ('No approval required'), which is relevant given the many approval-oriented sibling tools. It does not name alternatives, but no notification-related sibling exists.

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 idempotentHint=true and destructiveHint=true, and the description's insistence on clientOrderId aligns with the idempotency profile. The description adds the conditional approval-mode behavior, which is useful beyond annotations, but does not describe side effects such as order transmission or partial-fill behavior. 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?

Two tight sentences with zero filler. The core purpose is front-loaded, and the prerequisite constraints follow immediately. Every word 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 complex order-placement tool with an output schema and rich nested OrderSpec documentation, the description covers the two most decision-relevant facts: idempotency requirement and the conditional approval gate. It does not enumerate order types, but those are documented in the schema, so nothing critical is missing.

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

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

Schema description coverage is 0%, yet the description explicitly names two critical parameters (clientOrderId and approval_id) and their roles. However, the nested OrderSpec carries the heavy burden of the other parameters, and the tool description does not compensate for the many order-type-specific fields (stopPrice, limitPrice, bracket legs) beyond what the schema already documents.

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

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

States a specific verb ('Place'), a resource ('order'), and scopes the tool to 'single-leg or bracket order', which distinguishes the two supported shapes. This is immediately differentiated from siblings like cancel_order and preview_order by the action it performs.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

Gives explicit prerequisites: 'Requires a clientOrderId' and the conditional approval requirement when MCP_ORDER_APPROVAL_MODE=telegram, pointing to ibkr_request_trade_approval as the source of approval_id. It gives clear context for invocation, though it does not state when NOT to use it versus preview_order or the trade_intent flow.

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 annotation readOnlyHint: true already indicates no side effects, and the description reinforces this with 'without placing it.' The description adds clarity about the scope (single-leg or bracket) but does not disclose any other behavioral details such as validation or simulation behavior, which is acceptable given the 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 a single, concise sentence with no redundant words. It conveys the core purpose and scope efficiently.

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

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

The description covers the basic purpose and differentiates from actual order placement. Since an output schema exists, omitting return value details is acceptable. It lacks guidance on when to use it or what a preview entails, but it is sufficient for a straightforward read-only validation tool.

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

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

The description refers to the 'order' parameter indirectly by stating 'single-leg or bracket order,' which adds some context. However, it does not explain the structure or required fields of the order object, and the top-level schema has no description coverage. The nested schema provides details, so the description offers marginal added meaning beyond the parameter name.

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

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

The description clearly states the action: preview an order without placing it. It also specifies the scope (single-leg or bracket) and explicitly contrasts with placing, which helps distinguish it from place_order and related 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 implies usage for validation or pre-submission review, but it does not explicitly say when to use this tool versus alternatives. No mention of alternatives or scenarios where preview should be preferred over place_order or assess_order_impact.

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 the description reinforces that orders are not placed. This aligns with the annotation. However, it adds no further behavioral context—such as whether the preview validates orders, what data it returns, or any side effects beyond being read-only. Given the annotation already covers safety, this is adequate but minimal.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single, front-loaded sentence with no redundant phrasing. It is appropriately concise, though it sacrifices depth—but conciseness itself is excellent.

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 the complexity (a basket of orders with many advanced order types and nested symbol specs), the description provides no guidance on what the preview returns, whether it validates orders, or how errors are surfaced. The output schema exists, but the agent still lacks context on the preview's purpose and behavior. This is a significant gap for a tool with this much input complexity.

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

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

The only parameter is 'orders', whose schema is rich with nested OrderSpec and SymbolSpec definitions, including detailed field descriptions. The tool description adds nothing beyond the schema; it does not explain how the basket is processed or what constitutes a valid input beyond the schema. Since schema coverage is high (the nested schema is thorough), 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 (Preview), the resource (a basket of explicit orders), and the key behavior (without placing them). This distinguishes it from placement tools and from a single-order preview tool like preview_order, even without naming 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 implies usage for a batch of orders ('basket'), but does not explicitly state when to use this over preview_order or how it differs from place_order. No exclusions or alternative routing are given, leaving the agent to infer the batch use case.

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 provide readOnlyHint and idempotentHint, which cover side-effect transparency. The description adds context about comparing against current order status and positions, clarifying the read-only nature. However, it does not explicitly state that no modifications occur, though the annotations compensate.

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 focused, using one sentence to convey the tool's purpose. It avoids unnecessary details and is well-structured for quick understanding.

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 simplicity of the tool (one parameter, read-only) and the presence of an output schema, the description is sufficient. It does not explain the output format, but the schema likely covers that, and the tool's role is clear within the trading context.

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 only parameter, intent_id, has no schema description. The tool description mentions 'trade intent' but does not explicitly define what intent_id represents or its format. The name is somewhat self-explanatory, but the description could clarify the expected value.

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

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

The description uses the verb 'Refresh', which is specific to updating the state of a trade intent. It identifies the resource ('trade intent') and the context ('against current broker order status and positions'), distinguishing it from other trading tools. However, it could be more explicit about the outcome of the refresh.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

The description does not specify when to use this tool compared to alternatives, such as get_trade_intent or get_order_status. It lacks guidance on prerequisites or scenarios where this tool is preferable, leaving the agent to infer usage.

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

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

Annotations indicate openWorldHint (external side effects) and destructiveHint false; the description goes beyond these by explaining that the tool sends a message via Telegram, returns an approval_id for polling, and does not directly apply the change. It also discloses that safety locks will be enabled, providing meaningful behavioral context 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 compact and front-loaded, stating the core action in the first sentence and following with essential workflow steps. Every sentence adds value, with no filler or repetition of schema 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?

With an output schema present, the description need not detail return values, but it does mention the approval_id and the polling step. It covers the key workflow and safety implications, though it omits potential error conditions or prerequisites such as operator availability. Overall, it is sufficiently complete for an agent 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 0%, so the description must explain parameters. It clarifies target_env by mentioning 'live' and 'paper' environments, but it does not explicitly define the allowed values or that the parameter is required. The reason parameter is not explained at all, leaving ambiguity about its purpose or format.

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

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

The description clearly states the tool's purpose: sending a request to an operator via Telegram to switch the IBKR connection between live and paper environments. It distinguishes itself from related tools like ibkr_execute_environment_change by explicitly noting that this tool only requests the change and does not apply 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 provides explicit guidance on the workflow: after requesting, poll ibkr_check_approval_status until resolved, then use ibkr_execute_environment_change with the approval_id to apply the change. It also mentions the safety locks that will be engaged, giving clear context for when this tool should be used.

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

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

Beyond the annotations (openWorldHint=true, destructiveHint=false), the description discloses that this sends an external Telegram message to a human operator, returns an ID rather than executing the order, and has a mode-dependent handoff. It omits failure, timeout, or rejection behavior, but adds meaningful workflow 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?

Three sentences with no fluff: the action and channel, the returned approval_id and polling target, and the conditional handoff to place_order. Everything earns its place and the most important 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?

The schema and output schema carry much of the order-structure detail, so the description need not restate those. However, it leaves gaps around the required 'reason' parameter, the tool-name mismatch (ibkr_* vs sibling names), and when approval is unnecessary, which an agent would need for fully confident 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 0%, so the description must compensate, but it never explains 'order', 'reason', or 'preview' at the top level. The OrderSpec and OrderPreview $defs are rich, yet the agent is not told what 'reason' should contain or how 'preview' affects the approval request.

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

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

Clearly identifies the action ('Send a trade approval request'), the channel ('via Telegram'), and the key return value (approval_id) that feeds into polling and order placement. It differentiates the approval step from check_approval_status and place_order by describing the workflow, though it references tool names with an 'ibkr_' prefix that do not exactly match the sibling list and does not distinguish from request_trade_intent_approval.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

Gives an explicit conditional: when MCP_ORDER_APPROVAL_MODE=telegram, the returned approval_id must be passed to ibkr_place_order. This provides clear context for when this tool fits into the flow, but it does not mention alternatives or when approval is not needed.

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 are minimal (openWorldHint=true, destructiveHint=false), so the description carries most of the burden. It discloses the YOLO auto-approval behavior and that it sends a single approval request, adding value beyond annotations. However, it does not mention side effects, required permissions, or what happens outside YOLO mode beyond the implied manual approval.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences with no redundancy. The first sentence front-loads the core purpose, and the second adds a key behavioral detail. Every word 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 simple one-parameter tool with an output schema, the description is largely sufficient. It covers purpose and a critical mode (YOLO). It doesn't explicitly state that the intent must exist, but 'persisted' implies that. It also doesn't mention when to choose this over the similar sibling, but the description's scoping partially addresses 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?

The schema has one parameter (intent_id) with no description, and schema description coverage is 0%. The description clarifies that the parameter refers to a 'persisted trade intent', giving it needed semantic meaning. This compensates for the lack of schema documentation, though it doesn't specify format or source.

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

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

The description states a specific verb ('Request') and a precise resource ('a single Telegram approval covering a persisted trade intent'). It differentiates from the sibling 'request_trade_approval' by scoping to persisted trade intents, so an agent can tell them apart.

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 the tool is used after a trade intent has been persisted, but it does not explicitly state when to use this tool versus alternatives like 'request_trade_approval', nor does it give when-not-to-use guidance. The YOLO mode note is behavioral context, not 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 and idempotentHint, and the description's 'Resolve' wording is consistent with a side-effect-free lookup. It does not describe failure modes, but the annotations lower the bar and no contradiction 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 a single, direct sentence with no redundant wording or unnecessary 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?

The description plus the detailed schema and output schema are sufficient for invoking the tool correctly. It does not mention error behavior, but that is not essential for a straightforward resolution operation.

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 top-level description does not explain the 'instrument' parameter, but the nested SymbolSpec schema provides detailed descriptions for all fields. Since the schema carries the parameter documentation, the description adds little beyond identifying the parameter as a SymbolSpec.

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 ('Resolve') and names the input (SymbolSpec) and output (fully qualified IBKR contract), making the tool's purpose unambiguous relative to 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 clearly implies when to use the tool: whenever a SymbolSpec needs to be converted into a concrete IBKR contract. It does not explicitly contrast with alternatives, but no close alternative exists among siblings.

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 beyond the idempotent and destructive hints by disclosing a conditional approval requirement based on environment mode. It does not detail all side effects, but the added condition is meaningful and non-obvious.

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 a single, focused sentence with no redundant words. It efficiently conveys the core action plus an important conditional, making it well-structured and easy to parse.

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

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

Although the approval-mode condition is helpful, the description omits critical context such as how approval_id relates to the approval requirement, expected output, or failure scenarios. Given the tool's complexity as an execution step with conditional approval, the description is incomplete.

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

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

The schema provides no descriptions for intent_id or approval_id, and the description does not explain either parameter. The optional approval_id's role in satisfying the approval requirement is not addressed, leaving the agent without necessary parameter 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 clearly states the action ('Submit the planned orders') and the object ('a persisted trade intent'), distinguishing it from create, cancel, reconcile, and place_order tools. It also adds the key condition about approval mode, making the 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?

The description implies usage after a trade intent has been persisted and suggests an approval prerequisite in certain modes ('Requires a trade-intent approval when MCP_ORDER_APPROVAL_MODE=telegram'). However, it does not explicitly name alternatives or state when not to use this tool, so it falls short of full explicit 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?

The description adds value beyond the readOnlyHint and idempotentHint annotations by disclosing the success return shape: 'passed=true and an empty violations list.' This implies the failure mode (passed=false with violations) and clarifies the tool's non-mutating, purely diagnostic nature.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences with no filler. The action is front-loaded and the return behavior is stated efficiently, making every word earn its place.

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

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

For a read-only validation tool with an output schema and safety annotations, the description covers the essential behavior. The only notable gap is the lack of guidance on which profile_id or account_id to use, but the schema and annotations make the call safe and the purpose clear.

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 description provides no information about the parameters, and the top-level schema has no descriptions for account_id or profile_id (0% coverage). While the nested OrderSpec definition is rich, the tool description itself does not compensate for the top-level schema gaps or clarify how profile selection works.

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 ('Check') and a clear resource ('a proposed order against the agent's trading profile constraints'), making the tool's function immediately understandable. It does not explicitly differentiate from siblings like assess_order_impact or preview_order, but the validation-specific framing is distinct enough.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

No guidance is given on when to use this tool versus alternatives such as assess_order_impact or check_position_limits. The description states what it does but provides no context about when validation should be invoked in the order workflow.

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