fxapis — MetaTrader 5

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

Annotations already declare idempotentHint=true, destructiveHint=false, and openWorldHint=true, so 'safe to repeat' and 'places no trades' largely restate structured data. The genuinely new behavioral information is the asynchronous workflow — the operation is not complete on return, and the caller must poll get_account_status until `ready`.

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 dense sentence plus a short example. The key behavioral fact (poll until ready) is front-loaded, and nothing is wasted.

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

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

An output schema exists so return values need no explanation, and the description supplies the one thing the schema cannot express: that the call is asynchronous and must be followed by status polling. Nothing an agent needs to invoke and complete this workflow is missing.

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

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

Schema description coverage is 100% and the schema already explains that account ids are UUIDs from list_accounts rather than MT5 login numbers. The description adds only a minimal example payload, so the baseline of 3 is appropriate.

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

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

The description gives a concrete verb and resource: it starts each account's MT5 terminal in the cloud and logs it in. It is immediately distinguishable from siblings such as take_account_offline and the read-only get_account_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?

It tells the agent what to do after calling (poll get_account_status until `ready`) and clarifies the effect boundary (places no trades, safe to repeat). It does not explicitly state when to prefer this over alternatives, but the async completion path is clearly prescribed.

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, idempotentHint and destructiveHint=false, so safety is covered; the description adds meaningful context on top — that nothing is opened and that the account must be online — which is a real state requirement an agent must satisfy. Return semantics are left to the output schema, and no rate-limit or failure-mode detail is offered.

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?

One compact sentence covering purpose, scope and precondition, followed by a single example — front-loaded and free of filler.

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

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

With an output schema present, return values need no explanation; the description supplies purpose, the account-state precondition, the non-mutating guarantee, and a worked example against a 6-required-parameter schema that is itself fully documented. Nothing an agent needs before calling is missing.

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

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

Schema description coverage is 100%, so the baseline is 3; the description goes beyond it by supplying a fully-formed example payload that shows the string-encoded numeric conventions and the margin-vs-profit field combination. It does not clarify the close_price requirement for kind=profit in its own words, leaving that entirely to the schema.

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

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

States a specific computation ('the margin an order would need, or its profit between two prices, as the broker computes it') and immediately differentiates itself from the order-placing siblings with 'opens nothing'. An agent can distinguish it from place_market_order/place_pending_order without opening any schema.

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

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

Gives a concrete precondition ('The account must be online') and implies the preview-vs-execute distinction via 'opens nothing', which routes an agent away from the order-placement siblings. It does not, however, name an alternative tool or state exclusions explicitly.

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, idempotentHint=true and openWorldHint=true, so the safety profile is covered. The description adds state-dependent context not in the annotations: it only works before anything is sent, and after dispatch the positions must be closed instead. It does not restate the idempotency-retry contract, which is already in the schema.

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

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

Two tight prose sentences front-load the state constraint, followed by a compact call example. Every element earns its place with no filler.

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

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

With an output schema present, annotations covering safety and idempotency, and full parameter documentation, the description only needs to supply the state-transition rule and an example — both are provided.

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

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

Schema description coverage is 100%, and the idempotency_key description in the schema is richer than anything the tool description offers. The inline example restates the two existing parameters without adding syntax or constraints, so the baseline 3 applies.

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

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

States a specific verb ('calls off') on a specific resource ('multi-account order') and scopes it to the user's real/demo broker accounts before dispatch. An agent can distinguish this from close_position without opening the schema.

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

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

Explicitly names the alternative path: 'Once orders went out, close the positions instead.' That is a clear when-to-use-this vs when-to-use-the-sibling rule, which most definitions lack.

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 destructive/idempotent/openWorld, so the bar is lower; the description still adds real behavioral context beyond them — the tool only applies to un-triggered orders and operates on a live or demo broker account, and it supplies an idempotency_key example.

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

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

Three short sentences with the core action and constraint front-loaded, followed by a compact example. Efficient, though the example largely restates what the schema already shows.

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

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

An output schema exists (so return values need no explanation) and annotations cover the safety profile; the description adds the trigger-state constraint and account-type scope. Fully adequate for calling the tool correctly.

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

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

Schema coverage is 100%, and both parameters (order_id, idempotency_key) are fully described in the schema, including retry semantics. The description only adds a redundant example, so baseline 3 is appropriate.

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

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

States a specific verb and resource ("Cancels a pending order") plus meaningful scope ("on the user's real broker account (or demo) that has not triggered"). It is clear which order type it targets, though it never explicitly distinguishes itself from the sibling cancel_multi_account_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?

Gives a genuine usage condition and exclusion: use it for orders "that have not triggered," and if triggered "there is a position to close instead" — routing toward close_position. Strong, though the alternative tool is described conceptually rather than named.

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 destructiveHint=true and idempotentHint=true, but the description goes beyond them by warning that a duplicate send "opens the opposite position" and explaining the retry-vs-new-action distinction. That is a non-obvious, high-consequence behavioral trait. It does not cover auth/preconditions (e.g. whether the account must be online), so not a 5.

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

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

Three sentences, front-loaded with the action, then the idempotency caveat, then a concrete example. No filler, though the phrase "Sent twice it opens the opposite position" is slightly ambiguous on its own before the following clause clarifies it.

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 rich annotations, an output schema, and 100% schema coverage, the description's main remaining burden is the dangerous double-submit behavior, which it covers. A precondition an agent might need (e.g. does the account need to be brought online first) is not addressed, keeping it from a 5.

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

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

Schema description coverage is 100%, so the schema already documents every parameter in detail. The description only restates the whole-vs-partial volume choice and shows a minimal call example, adding no syntax or format meaning beyond the schema. Baseline 3 is appropriate.

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

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

States a specific verb and resource ("Closes a position") plus scope ("whole or by volume") and the target ("user's real broker account (or demo)"). It is clear what the tool does, but it never distinguishes itself from the similar siblings modify_position or place_market_order, so it stops short of a 5.

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 real conditional guidance about the idempotency key (reuse only to retry the same close, new key for a new action) and notes that omitting volume closes the whole position. However it never says when to pick this tool over modify_position or place_market_order, so usage context is only partial.

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

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

Annotations already declare readOnly=true, idempotent=true, destructive=false, openWorld=false, so the safety profile is covered. The description adds genuinely new behavioral context with 'last-read' balance, equity and free margin, warning the agent that these figures are cached rather than live — information not present in any structured field.

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 compact sentences with no waste: the field list leads, the example follows. Front-loaded and appropriately sized for a single-record getter.

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

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

An output schema exists, so return-value documentation is not required, and annotations carry the safety profile. What remains missing is routing information — nothing tells the agent why to pick get_account over get_account_overview, get_account_status, or get_account_figures, which is the main ambiguity for this dense sibling set.

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

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

Schema description coverage is 100%, so the schema already documents account_id (including the 'not the MT5 login number' warning) and response_format's concise/detailed semantics. The description's example adds only marginal value beyond that documented baseline.

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

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

States a specific resource ('one account') and enumerates the key fields returned (login, broker, state, environment, balance, equity, free margin), which clearly implies single-record retrieval versus list_accounts. However it never distinguishes itself from the many similar siblings (get_account_overview, get_account_status, get_account_figures), so the agent must guess which 'get account' variant is right.

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 only usage cue is the example embedding '<id from list_accounts>', which implies a prerequisite ordering but is not stated as guidance. There is no when-to-use, when-not-to-use, or named alternative among get_account_overview / get_account_status / get_account_figures.

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, idempotent, non-destructive, open-world behavior. The description adds genuinely new behavioral context: the 15-second cache cadence, the on-demand refresh path, and the `ready` precondition. It does not say what error surfaces when the account is not ready.

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?

One dense sentence followed by a concrete example, with the return contents front-loaded. Every clause carries information, though the sentence is packed tightly enough that the refresh mechanics take a second read.

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

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

With an output schema present, return values need no explanation, and the description covers cadence, freshness, and the readiness precondition. The main gap is failure behavior when the account is offline or not ready.

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

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

Schema coverage is 100%, so the baseline is 3. The description goes slightly beyond by restating the fresh semantics in context and by adding the `account must be ready` precondition tied to that flag, plus a concrete example invocation.

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 exact resource and every returned quantity (balance, equity, margin, free margin, margin level), plus the representation (decimal strings in account currency). This is specific enough to distinguish it from siblings like get_account_overview or get_account_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?

Explains the polling cadence ('read every 15 s while online') and tells the agent to set fresh to force a terminal read, with the precondition that the account must be `ready`. It does not name a sibling alternative (e.g. get_account_overview) to route against, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds genuine context beyond them: this aggregates account state plus the largest positions and their aggregate P/L in a single call, and that 'top' defaults to 5. It does not mention whether the account must be online (bring_accounts_online exists as a sibling) or any rate behavior.

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

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

Three short sentences, front-loaded with the payload summary, then the routing cue, then a call example. Nothing is padded and nothing is repeated from the schema beyond the minimal example.

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 document return fields, and it correctly avoids doing so. It is complete for input and purpose; the only real gap is operational state — a hint about account-online prerequisites or what happens if the account is offline would close it out.

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

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

Schema description coverage is 100%, so account_id, top, and response_format are all fully documented in the schema — baseline 3 applies. The description's 'largest open positions' hints at the top parameter and its example confirms the account_id key, but adds no format, bound, or uuid-vs-login detail beyond what the schema already states.

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 concrete resource ('one account in one call') and enumerates its payload: state, environment, balance and equity, top open positions with total P/L. That is far more specific than a bare 'get account', though it never names the sibling tools it overlaps with (get_account, get_account_figures, get_account_status), leaving the agent to infer the split.

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?

'Start here when asked how an account is doing' gives a clear entry-point condition, which is real routing guidance against a 29-tool sibling set. It stops short of explicit exclusions (when to prefer get_account_status or get_account_figures instead), so the agent knows when to use it but not when not to.

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 establish read-only, idempotent, closed-world behavior, so the description adds genuine extra context: call cost ('cheap enough to poll every few seconds') and a stop condition tied to user-blocking states. It does not describe return payload shape or any rate limits, but the polling cadence and terminal-state semantics are the useful additions.

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 compact sentences with the purpose and polling loop front-loaded, followed by an example. The example is largely redundant given the required single UUID parameter, but overall there is little wasted text.

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

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

With an output schema present, return values need not be explained, and the description covers the polling lifecycle and the notable state values well. It stops just short of clarifying how callers should interpret 'ready' versus other non-terminal states, but nothing critical for invocation is missing.

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

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

Schema coverage is 100%, so the schema already documents account_id (UUID from list_accounts, not MT5 login) and response_format's concise/detailed enum; baseline 3 applies. The description's example only restates account_id and adds no new parameter semantics such as what 'concise' actually returns.

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 resource and result ('Just an account's state') and frames itself as the cheap polling variant, which implicitly distinguishes it from heavier siblings like get_account and get_account_overview. It never names a sibling explicitly, so an agent must infer the boundary.

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

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

Gives concrete when-to-use guidance (poll every few seconds after bring_accounts_online until `ready`) and when-to-stop guidance (terminal states invalid_credentials, needs_2fa, needs_certificate, trading_disabled need the user). No sibling alternative is named, so it falls short of a full when/when-not/alternatives statement.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world, so the safety profile is settled. The description still adds real behavioral context: results are per the account's broker, times are normalized to UTC, and a broker holiday absent from the schedule does not mean orders will be accepted. It stops short of stating caching or freshness, but the holiday caveat is genuine added value.

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 plus a compact example, with the core answer ('whether a market is open now') front-loaded before the scoping and caveat details. Nothing is padding.

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

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

An output schema exists, so return values need no explanation, and the description covers broker scoping, UTC normalization, the holiday caveat, and a usage example. The only omission is any mention of response_format, which the schema handles, so the definition is essentially complete for calling the tool.

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

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

Schema coverage is 100% and the schema already documents account_id, symbol vs instrument, and the response_format enum in detail. The description's example adds a concrete call shape and reinforces the account-scoped broker context, but supplies no syntax or constraints beyond the schema. 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?

States a specific verb and resource: reports whether a market is open now on the account's broker and when it next opens or closes, with UTC called out explicitly. No sibling tool covers market hours, so the scope is unambiguous without needing to name an alternative.

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

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

Usage is implied rather than stated – an agent infers it should be called before placing or modifying orders. The holiday caveat ('a broker holiday missing from its schedule still refuses orders') is about interpreting the answer, not about when to select this tool over a sibling. No explicit when/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?

Annotations already cover the safe/idempotent read profile (readOnlyHint, idempotentHint, destructiveHint=false). The description adds genuinely new behavior: this is a polling/eventually-consistent endpoint and an `unresolved` account must not be re-sent but instead have its own order polled. That is real operational 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?

Front-loads the core purpose and the polling instruction in two tight sentences. The inline JSON example is mildly redundant given the required param is already in the schema, but it is short and harmless.

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

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

An output schema exists, so return values need no explanation, and the description supplies the key async/polling workflow. What remains thin is the relationship to non-multi-account order tools, but for a single-resource fetch this is close to complete.

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

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

Schema description coverage is 100%, including the UUID pattern and the response_format enum, so the schema carries the parameter burden. The description's inline example only restates multi_account_order_id without adding format or constraint detail, so baseline 3 is appropriate.

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

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

States the resource (a single multi-account order) and what it returns (each account's result), which is enough to separate it from the sibling list_multi_account_orders. The verb is implicit in the clipped phrasing 'One multi-account order and each account's result,' but the resource is unambiguous.

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

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

Explicitly tells the agent when to call it: poll after placing a multi-account order, and poll the child order instead if an account is left `unresolved`. It does not explicitly name competing siblings like get_order or get_multi_account_order variants, so 4 rather than 5.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description adds real operational context on top: it is the authoritative record, the order can sit in an `unknown` state, and it is meant to be polled. That polling/status behavior is not derivable from the annotations, though no rate-limit guidance is given.

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 the core purpose front-loaded and the polling instruction plus a concrete example at the end. Nothing is padded, though the example is somewhat redundant with the schema.

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

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

With an output schema available, the description need not explain return values, and annotations carry the safety profile. Between them the agent knows what the tool returns, when to call it, how to poll it, and every parameter, so nothing material is missing.

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

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

Schema description coverage is 100%, so order_id, include_deals and response_format are already documented in the schema, including the history:read scope requirement. The description only adds a sample invocation with include_deals=true, which is illustrative but not new 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?

States a specific verb and resource ('the authoritative record of one order') and enumerates what it returns: the request, the broker's answer, fill volume and price. This clearly distinguishes it from the plural sibling list_orders without the agent needing to open either schema.

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

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

Gives an explicit usage trigger: poll after ORDER_UNRESOLVED until the order leaves `unknown`. That is concrete when-to-use guidance tied to a status value. It stops short of naming alternatives such as list_orders, so it is clear context rather than full 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 readOnly/idempotent/non-destructive/openWorld, so the safety profile is covered. The description adds real behavioral context beyond them: the 20-symbol cap, the account-must-be-online requirement, and the closed-market fallback that returns last price with marketOpen false. It stops short of noting rate limits or partial-failure behavior across a mixed symbol list.

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

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

A single dense sentence front-loads the core capability, then appends operational caveats and a concrete call example. Nothing is padded, though the semicolon-chained clauses pack several independent facts into one sentence, which slightly hurts scannability.

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

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

An output schema exists, so return values need not be enumerated, yet the description still surfaces the one field that changes agent behavior (marketOpen false on a closed market). Combined with the online precondition and symbol cap, an agent has everything needed to call this correctly.

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

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

Schema description coverage is 100% and each of the four parameters is documented in-schema, so the baseline is 3. The description echoes instruments being resolved to the account's own symbol wording but adds no syntax, defaults, or clarification of how `symbols` and `instruments` differ — the one genuinely ambiguous pair an agent must choose between.

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

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

States a specific verb+resource (live bid/ask quotes) plus scope (up to 20 symbols/instruments, this account's broker). That is enough to tell an agent what it retrieves. It does not differentiate itself from the nearby sibling get_symbol_snapshot, which plausibly competes for the same 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?

Useful preconditions are given — the account must be online, and closed markets return last price with marketOpen false. However there is no explicit when-to-use or when-not-to-use guidance versus get_symbol_snapshot or list_account_instruments, so routing between siblings is left to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds that this is a single-call aggregate of live broker data and that margin is computed for a given volume/side, but says nothing about data freshness, latency, or failure modes when the symbol is unknown.

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 front-load the payload, with a call example appended. Slight redundancy in re-listing return contents that the output schema already covers, but no sentence is wasted.

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

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

With an output schema present, the description needn't document returns, yet it usefully summarizes them and points account_id at list_accounts and instrument at list_instruments. The main omission is routing guidance against the many sibling read tools (get_quotes, get_market_hours, list_instruments).

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

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

Schema coverage is 100%, so the baseline is 3. The example call goes beyond the schema by demonstrating the practical pairing (account_id + instrument + volume as the string "0.10" + side), which clarifies the symbol/instrument alternative and string-lot convention in 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 names a specific resource (one symbol on one account) and enumerates the payload: specification, live quote, market-open status, and margin for a volume. That scope is clear enough to separate it from point tools like get_quotes or get_market_hours, though no sibling is named explicitly.

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

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

"Use it before proposing a trade" gives a concrete usage context rather than leaving timing to inference. It stops short of naming alternatives (e.g. when to prefer get_quotes or get_market_hours instead) or stating when-not-to-use, so it is strong but not exhaustive.

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, idempotent, non-destructive. The description adds two valuable behavioral details not captured elsewhere: cost is in minor units (9900 = $99.00) and that opening is refused over quota while closing is not. This goes beyond the annotations.

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

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

Three short sentences, front-loaded with the core purpose. The example '{}' is slightly unnecessary but harmless; overall efficient.

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

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

For a read-only tool with an output schema and one optional parameter, the description covers purpose, cost units, and quota behavior. Nothing critical for invocation is missing.

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

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

Schema coverage is 100% and the single optional enum parameter (response_format) is fully documented in the schema. The description adds no parameter-level meaning beyond the schema, so the baseline of 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?

States a specific resource (this month's usage against the plan) and the metric (cost in minor units). It does not explicitly differentiate itself from sibling account/trading tools, but the resource is unambiguous.

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

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

Provides no when-to-use guidance or alternatives. It states a behavioral rule about quota, but does not tell the agent when to call this versus other read tools.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive, and closed-world, so the safety profile is covered. The description adds the useful fact that the result reveals whether trading is switched off, but says nothing about freshness, caching, or permissions. With annotations carrying the safety burden, this is adequate but not rich.

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?

One dense sentence covering contents followed by a usage cue and a literal call example — front-loaded with zero filler. The example string is a small but genuine convenience for an agent constructing the call.

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

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

An output schema exists, so return values need not be described, and the description covers scope plus when to invoke. Nothing critical is missing for a zero-required-parameter read tool, though it could note what to do when the workspace data looks stale or restricted.

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

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

Schema description coverage is 100%, and the single response_format parameter is fully documented in the schema including its default and the concise/detailed distinction, so the baseline of 3 applies. The description adds nothing about the parameter, though "Example: {}" hints that no arguments are 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?

States a specific resource (this connection's workspace) and enumerates what it surfaces: plan, plan limits/features, and whether trading is disabled. This is clearly distinct from the account/order siblings, though it does not explicitly contrast itself with possibly-overlapping tools like get_usage or get_account_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?

"Call it first when unsure what the user can do" gives a concrete trigger and a priority ordering, which is real guidance. It stops short of naming alternatives or when-not-to-use conditions, but the context is clear.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the description's job is to add behavior. It does: results are tri-state (mapped / ambiguous with candidates / missing), which is important for the agent to handle correctly, and it implies the correct follow-up action. It does not expand on what causes ambiguity or missing entries, or on pagination.

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

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

Three short sentences plus a compact example, with no redundant filler. Slightly output-first rather than action-first, but the example earns its place by anchoring the required parameter, so it stays tight overall.

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 explain return fields, and full schema coverage handles parameters. The tri-state result summary plus the trade-the-mapped-symbol guidance cover the essentials for a 5-parameter read tool; only the relationship to the sibling list_instruments is left unstated.

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

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

Schema description coverage is 100%, so the schema already documents limit, query, cursor, account_id, and response_format thoroughly (including the note that account_id is not the MT5 login). The description's example only spotlights account_id and query, adding no new semantics. Baseline 3 applies.

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

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

The title and first sentence make the resource and transformation clear: it resolves each instrument's symbol on a specific account's broker, classifying results as mapped, ambiguous (with candidates), or missing. That is a distinct operation from the sibling list_instruments, but the description never names that sibling or explicitly contrasts the two, so differentiation is left to inference.

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?

'Trade the mapped symbol' gives one concrete downstream usage hint, which is genuinely helpful. However, there is no guidance on when to reach for this tool versus list_instruments or get_symbol_snapshot, and no exclusions or preconditions stated beyond the account_id requirement.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower, and the description still adds real domain context: the `ready` state gate for trading and the warning that the login must not be used as an identifier elsewhere. It does not mention pagination limits or the practical size of a workspace's account list, but what it does add is behaviorally useful.

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

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

Three tight clauses: what is returned, how to reference an account, and the state caveat, followed by a minimal example. Every sentence earns its place and the field list is front-loaded. The trailing example is slightly redundant given the fully documented schema, which keeps it from a 5.

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

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

An output schema exists, so return-value documentation is not the description's burden, and the description nonetheless previews the key fields an agent will need. With annotations covering safety, a complete schema, and the `ready`-state caveat plus the id-vs-login rule supplied, nothing required to call this tool correctly is missing.

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

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

Schema description coverage is 100% and all three parameters carry their own descriptions (range, default, cursor provenance, response_format enum), so the schema does the heavy lifting and a 3 baseline applies. The inline example {"limit": 25} illustrates the call but adds no semantics beyond the documented default of 25. No parameter meaning is clarified further in prose.

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

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

The description names the resource (the workspace's MT5 accounts) and enumerates the identifying fields returned (id, login, server, state, environment), so an agent knows exactly what this call yields. The explicit 'use the id, not the login, everywhere else' rule also draws a clean boundary against get_account-style lookups. It never uses the verb 'list' outright, but the noun phrase plus the title make the read-all intent 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?

Usage is implied rather than stated: the agent learns that only `ready` accounts trade and that others must be brought online first, which gestures at bring_accounts_online without naming it. There is no explicit comparison against get_account, get_account_status or get_account_overview, so the agent must infer when listing beats fetching one account. Adequate but with a clear gap on exclusions and named alternatives.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds genuinely new behavior: rows come back newest-first, and the scope includes closed/fired stops, swaps and manual trades as 'the broker recorded it'. It stops short of describing pagination or result shape, but with annotations carrying safety this is solid.

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 front-loaded with what the tool returns, followed by a compact invocation example. Every element earns its place, though the example is somewhat redundant given the fully documented schema.

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

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

With an output schema present, return values need no explanation, and the description still usefully signals sorting order and that realised profit is included. Pagination, filtering by symbol, and the concise/detailed response_format are only covered by the schema, which is acceptable but leaves the description short of fully self-sufficient.

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

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

Schema description coverage is 100%, so the schema already documents limit, since, until, cursor, symbol, account_id and response_format in detail. The description's inline example shows how account_id and since combine, which is mild added value, but nothing beyond the schema is explained. 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?

States a specific verb and resource (list an account's deal history) and goes further by characterizing the contents: stops that fired, swaps, manual trades, and realised profit. That content profile implicitly separates it from list_positions and list_orders, though neither sibling is named explicitly.

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

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

'Realised profit is here' hints that this is the right tool when the agent needs realised rather than unrealised P&L, but the description never states when to use it over list_positions or list_orders, nor any exclusions or prerequisites. Usage is implied rather than directed.

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, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered structurally. The description adds the conceptual point that names are canonicalized across brokers plus a sample filter value, but says nothing about pagination, scope (all brokers vs. current workspace), or result volume.

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

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

Three short sentences with no filler, and the core differentiator (canonical naming) is front-loaded. The wording is slightly elliptical, but nothing is redundant.

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

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

An output schema exists, so return-shape explanation is unnecessary, and annotations cover the safety profile. The description supplies the one thing structured fields cannot: the relationship to list_account_instruments and the canonical-vs-broker naming distinction.

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

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

Schema description coverage is 100% and both parameters are enums with their own descriptions, so the schema carries the semantics. The example {"category": "metals"} shows a valid usage but adds no constraints (defaults, multi-value, required-ness) beyond the schema.

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

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

The description conveys the resource clearly — canonical market names (XAUUSD, US30, BTCUSD) as opposed to each broker's own naming — and explicitly contrasts it with list_account_instruments. It never states the verb outright ('list'/'returns'), so the action is inferred from the tool name rather than the prose.

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 names the sibling alternative list_account_instruments and what that sibling returns ('one account's own symbol for each'), which effectively tells the agent which of the two to pick. There is no explicit 'use this when / not when' framing, and no mention of prerequisites, but the selection context is clear.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=false and destructiveHint=false, so the safety profile is fully covered by structured data. The description adds pagination behavior and the per-account result shape, which is useful, but nothing about ordering guarantees, rate limits, or retention window for 'recent'.

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

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

Three short sentences, front-loaded with the resource scope and free of filler. The trailing 'Example: {}' is cryptic and arguably adds nothing, which keeps it from a 5.

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

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

An output schema exists, so return values need not be explained, and all params are schema-documented. The description supplies the remaining context an agent needs: what a row means (per-account result) and that the listing is paginated and time-bounded.

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

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

Schema description coverage is 100%, so limit, cursor and response_format are already documented in the schema with defaults and ranges. The description only restates that paging uses limit and cursor and ignores response_format entirely, adding no meaning beyond the schema. 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?

States a specific resource (recent multi-account orders, one trade across many accounts) and what each item contains (per-account result), which meaningfully separates it from the sibling list_orders. It never explicitly names list_orders or get_multi_account_order as the alternative, but the scope is unmistakable.

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

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

The word 'Recent' implies the retrieval intent and pagination is described, but there is no explicit when-to-use guidance or when-not-to-use (e.g., use get_multi_account_order for a single order id, list_orders for single-account orders). Usage must be inferred from the scope phrasing.

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, idempotent, non-destructive safety. The description adds behavior beyond that: orders are returned newest first, pagination uses a cursor, and the 'unknown' state has a special operational meaning that prevents resending. Missing rate-limit or auth details, but strong added context for a read-only list tool.

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

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

One dense sentence plus two short follow-ups. The resource and ordering are front-loaded, then the critical 'unknown' caution, pagination note, and a concrete example. Every part earns its place without padding.

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

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

For a read-only list tool with full schema coverage, an output schema, and safety annotations, the description supplies the missing behavioral context: ordering, pagination, account scope, and the important unknown-state warning. Nothing essential to correct invocation is absent.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by clarifying that account_id is optional (one account or all) and by explaining the special 'unknown' state and showing an example filter, which helps an agent use the state parameter correctly.

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

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

The description names the resource (orders placed through fxapis) and adds scope and ordering (newest first, for one account or all). It does not explicitly distinguish itself from sibling tools such as get_order or list_multi_account_orders, so it falls short of full sibling differentiation.

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 operational guidance: state 'unknown' means still being confirmed, so those orders must not be resent, and it notes that results page with a cursor. It does not state when to use this tool versus alternatives like get_order or list_multi_account_orders, so it is not a full 5.

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

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

Annotations already carry readOnly/idempotent/non-destructive, so the bar is low, and the description adds 'as last observed' — a real behavioral disclosure that the data is a snapshot rather than a live broker read. Pagination behavior is also noted. It does not state any auth/permission requirements, but nothing contradicts 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?

Three compact clauses, front-loaded with purpose, then the ID linkage, then pagination. Nothing is redundant or padded. The trailing example ({"account_id": "<id>"}) is near-zero value since the schema already marks account_id required, which is the only slight waste.

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

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

With an output schema present, return shape need not be described, and annotations cover the safety profile. The description covers purpose, the staleness caveat, pagination, and the ID's downstream use. The gaps (include_closed and response_format semantics, account_id disambiguation) are already fully handled by the schema, so little is missing.

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

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

Schema description coverage is 100%, so the schema already documents limit range, cursor source, account_id (including the UUID-vs-MT5-login warning), include_closed and response_format. The description only restates that pagination uses limit and cursor, adding no meaning beyond structured data — baseline 3.

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

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

States a specific verb+resource ('Open positions on one account') and scopes it precisely to a single account and a point-in-time observation. It also names the sibling consumers (close_position, modify_position) that the returned brokerPositionId feeds, which lets an agent distinguish this from list_orders/list_deals without opening either schema.

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

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

The cross-reference to close_position and modify_position effectively tells the agent this is the discovery step before position mutation. The 'as last observed' caveat signals a freshness limitation. It stops short of explicitly saying when NOT to use it versus list_deals or list_orders, so it is clear context but not full routing guidance.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true and openWorldHint=true, so the bar is lower. The description still adds real value: it discloses that changes land on the user's live broker account, that null deletes a protective level, and warns against removing stops unprompted.

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

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

Front-loaded with the action and its target, followed by the one safety caveat and a compact example. Only mild redundancy: the JSON sample largely restates field names already visible in the schema.

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

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

For a mutation tool with an output schema (so returns need no explanation) and annotations covering safety and idempotency, the description covers the remaining agent-facing concerns: live-account impact, removal semantics, and the caution about deleting stops.

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

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

Schema coverage is 60% and the schema itself documents every parameter, including the null-removes-it semantics and the absolute-price rule. The example payload maps names to sample values but adds no syntax or format detail beyond the schema, so this sits at the baseline.

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

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

States a specific verb and resource: moving a position's stop loss or take profit on a real (or demo) broker account. The scope sentence makes clear it mutates an existing position rather than opening or closing one, though no sibling is named for contrast.

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 supplies one explicit conditional ('Remove a stop loss only when the user asks') and an example call, which implies usage. But it never says when to use this versus close_position or place_pending_order, so alternatives remain inferred.

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, idempotentHint and openWorldHint, so the bar is lower. The description still adds real value beyond them: it discloses that the call blocks/waits for the broker and prescribes never resending on ORDER_UNRESOLVED but polling get_order instead — non-obvious retry behavior not encoded in any structured field.

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

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

Front-loads purpose, then preconditions, then error handling, then an example — a sensible ordering with no filler sentences. The semicolon-joined clauses are dense but each carries distinct operational information.

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

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

An output schema exists, so return-value documentation isn't required, and the description still covers the key edge state (ORDER_UNRESOLVED). For a destructive real-money order on a 10-param tool, it is nearly complete; margin/permission prerequisites would close the remaining gap.

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

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

Schema coverage is 100%, so the baseline is 3. The description goes slightly further by naming the four fields the agent must confirm with the user and by showing a complete valid payload including the fresh-UUID idempotency_key, illustrating how the required fields combine in practice.

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

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

States a specific verb and resource ('opens a position at market on the user's real broker account') and names the environment (real or demo). An agent can distinguish this from place_pending_order and place_multi_account_order by the 'at market' + single-account scope.

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

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

Gives an explicit precondition ('confirm account, symbol, side and volume with the user first') and routes the agent to get_order on ORDER_UNRESOLVED. It stops short of explicitly contrasting itself with the sibling order-placement tools (pending vs multi-account), which would have made it a 5.

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

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

Annotations already declare destructive/idempotent/openWorld, but the description adds genuinely useful behavior beyond them: the call 'returns at once' (asynchronous dispatch that must be polled via get_multi_account_order), and that it targets real broker accounts or demo. It stops short of 5 because it doesn't state what triggers the all-or-nothing refusal or partial-failure outcomes.

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

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

Front-loads the action, then the follow-up call, then the confirmation requirement, then an example. Each sentence earns its place and there is no filler; the embedded JSON example makes the last clause dense but it is directly actionable.

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

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

An output schema exists so return values needn't be explained, and annotations cover the safety profile. The description still supplies the confirmation prerequisite and the polling follow-up, making it largely complete for a 14-parameter, high-impact multi-account mutation, though it could note error/partial-fill handling.

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

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

Schema description coverage is 100%, so the baseline is 3, and the description's concrete example adds value by showing the exact required-parameter shape (account_ids, instrument, side, volume, idempotency_key as a new uuid) in a realistic invocation. It does not add semantics for the optional advanced params (weights, barrier_policy, expires_at), which the schema handles.

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 (places), resource (market order), and a distinguishing scope (the same order on many of the user's real broker accounts at once). The 'many accounts at once' framing separates it from the single-account sibling place_market_order without needing to inspect either schema.

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

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

Gives a clear when-to-use context plus an explicit workflow and prerequisite: 'follow it with get_multi_account_order' and 'Confirm the accounts, symbol, side and volume with the user first.' It does not name the single-account alternative (place_market_order) or state a when-not-to-use, so it stops short of a 5.

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

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

Annotations already declare destructive/openWorld/idempotent, but the description adds value they don't carry: that this touches a real (or demo) broker account and that a successful response means a working order, not a filled one. It does not restate the idempotency behavior, which the idempotency_key parameter already documents thoroughly.

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

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

Three tight sentences with the most consequential facts front-loaded (real account, working-not-filled), followed by a compact example. The example earns its space by showing the call shape, though it is the one non-sentence element.

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, full param coverage, and annotations covering the safety profile, the description only needed to supply the semantic gaps, which it does: real-vs-demo account, working-not-filled outcome, and the user-confirmation requirement. Coverage is strong, with only optional-field edge cases left to the schema.

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

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

Schema coverage is 100%, so the baseline is 3; the description goes beyond that by giving a complete worked example payload, showing the required-field shape and format for a successful call. It does not add semantics for the optional fields, but the schema covers those.

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

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

States a specific verb and resource ('places a limit or stop order') plus the critical scope distinction that it 'waits at the broker' and 'success means working, not filled'. This differentiates it from place_market_order and place_multi_account_order without needing the schemas.

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

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

Gives an explicit workflow prerequisite ('Confirm it with the user first') and implies the pending-vs-immediate distinction against the market-order siblings. It stops short of naming an alternative tool or stating when-not to use it, so it is clear context without explicit 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 readOnly/idempotent/non-destructive and a closed-world search. The description adds behavior beyond that: results are ranked with 'servers seen working on fxapis first,' and absence from results is explicitly non-blocking. Those are non-obvious traits not captured 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?

Three short clauses plus an example, with the resource and matching rule front-loaded. The example is mildly redundant with the schema's own example but is cheap and useful; no filler sentences.

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

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

An output schema exists, so return shapes need not be described. Combined with full schema coverage, the description supplies the remaining essentials: what is matched, ordering, and the caveat about unlisted servers. Only result limits/pagination behavior are left unstated, which is a minor gap for a search tool.

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

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

Schema coverage is 100%, so both parameters are fully documented in the schema, including the query format and the concise/detailed response_format enum. The inline example restates what the schema already says and adds no new syntax or constraint information.

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

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

The description states a specific verb and resource ('MT5 broker servers matching a broker or server name') and clarifies the matching semantics. No sibling tool overlaps with this lookup function, so differentiation is not needed, but the phrasing is precise rather than a restatement of the title.

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 for use — matching by broker or server name prefix — and adds a valuable caveat that 'a server not listed can still be used,' which prevents an agent from wrongly concluding a broker is unsupported. It does not, however, name a workflow or alternative to compare against.

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 disclose the safety profile (not read-only, not destructive, idempotent, open world), so the bar is lower. The description still adds value beyond them: it states that positions and their stops persist at the broker, and that the call is refused mid-flight — both behavioral facts absent from 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?

Three tight sentences with zero filler: scope and side-effect first, the failure condition second, a call example third. Nothing is redundant and the critical constraint 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?

Covers the two things an agent most needs for this mutation: what persists (positions/stops) and the blocking condition (in-flight order). An output schema exists so return values needn't be described, and annotations carry the idempotency/destructiveness profile. Minor gap: no mention of whether the account can be brought back online or what states are invalid.

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

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

Schema coverage is 100% and the single UUID parameter is fully documented in the schema, including the important "not the MT5 login number" disambiguation. The description only repeats the parameter inside a JSON example, adding no syntax or meaning beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ("Stops an account's terminal") and immediately clarifies scope by noting open positions and stops stay at the broker, which distinguishes it from closure tools like close_position. It does not explicitly name the sibling it inverts (bring_accounts_online), so it stops short of full sibling differentiation.

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?

"Refused while an order is in flight" is an explicit precondition that tells the agent when the call will fail, which is genuine when-not guidance. It does not name an alternative tool or describe when this should be preferred over simply leaving the account online.

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