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

Annotations already declare the destructive, non-idempotent, open-world nature, so the bar is lower — yet the description still adds substantive context: the auth scope required, the shared rate limit across the trade-write group, and a candid warning that the limit is not a figure to design around. That goes well beyond what the annotations convey.

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

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

The purpose and identifier semantics are front-loaded and the rate-limit caveat is placed last where it belongs. The prose is slightly editorial ('a figure to design around', the em-dash aside), which costs a bit of tightness but does not obscure the core instruction.

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, no-output-schema tool, the description covers scope, identifier semantics, and rate limits adequately. It omits the return value / failure behavior for a destructive operation (e.g. order already filled), which is the one remaining gap an agent might need.

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% for the single parameter, so the baseline is 3, but the description genuinely enriches the id's meaning: it is the identifier carried since filing and before the venue has responded, which clarifies the distinction from a venue-assigned order id. It adds real semantics rather than restating 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 gives a specific verb and resource ('Withdraws one resting order') and pins down the addressing scheme via clientOrderId. The singular scope implicitly separates it from the sibling cancel_orders, but that sibling is never named, so the differentiation relies on the agent noticing the plural/singular 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 states a precondition ('Requires the trade:write scope') and details rate-limit constraints, which is useful context for deciding whether to call it. However, it never states when to prefer this over cancel_orders or what happens if the order is already filled/cancelled, leaving the operational guidance implied rather than 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?

Annotations already flag destructiveHint=true and openWorldHint=true, but the description adds the genuinely important context: unfiltered calls wipe bot-managed orders too, origin=manual is the escape hatch, the trade:write scope is required, and there is a 932 rpm limit shared across the trade-write group with an honest note that it is not a design target.

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 destructive warning before any parameter talk and keeps three tight paragraphs. The rate-limit paragraph is longer than strictly needed and drifts into advisory commentary, but every sentence carries usable information.

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

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

For a high-blast-radius bulk mutation with no output schema, it covers scope of destruction, the safety mitigation, auth requirements, rate limits, and a sketch of the return value. Nothing an agent needs to call this safely is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description goes beyond the schema by tying the origin parameter to its consequence ('spare those' bot orders), which tells the agent what origin=manual actually protects rather than just what it filters.

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 with scope: 'Withdraws every open order matching the filter.' The word 'every' plus 'matching the filter' cleanly separates it from the singular sibling cancel_order, and it also describes the response ('answers with what happened to each one').

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 when-not ('WITH NO FILTER THIS CANCELS EVERYTHING ON THE ACCOUNT') and a concrete mitigation ('pass origin=manual to spare those'), plus the imperative 'Narrow it before calling it.' It does not name the singular cancel_order sibling as the alternative for single-order cancellation, so it falls just short of full routing guidance.

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

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

Adds substantial behavior beyond the annotations: specific 409 (name taken) and 403 (plan bot limit, naming the limit) failure modes, the paper-default mode, the fact that sim settings are refused on a live bot rather than silently ignored, that a live bot trades real funds, the required `bots:write` scope, and the shared rate-limit budget. None of this is derivable from readOnlyHint/destructiveHint/openWorldHint.

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 action and error behavior, then scope, then rate limits, so an agent gets the essentials first. The rate-limit paragraph is somewhat long for its informational payload, but each sentence carries operational content rather than filler.

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

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

For a mutation tool with no output schema, seven params (including nested objects), and open-world behavior, the description covers failure modes, auth scope, and quota — the main gaps an agent needs closed. It does not describe the response shape, though the name schema note ('later tools take the name this answers with') partially covers identity of the created bot.

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 all seven parameters, setting the baseline at 3. The description earns above baseline by clarifying the cross-parameter interaction the schema states only locally — mode defaults to paper and sim settings are refused on a live bot — which is genuine added meaning.

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

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

States a specific verb+resource with scope: 'Creates and starts a bot running one of the account's scripts.' This is clearly distinguishable from sibling mutations like update_bot_config, stop_bot, and create_script 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 real operational context — the 30 req/min shared budget and the advice to make one considered change rather than a sequence of adjustments, which implicitly frames create/reconfigure/stop/delete as competing uses of the same quota. It does not, however, explicitly name a sibling alternative or a when-not-to-use condition.

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

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

Annotations only declare the generic safety profile (not read-only, not idempotent, not destructive). The description adds substantive behavior beyond them: the 409 duplicate-name conflict, the 403 plan-allowance failure naming the plan and count, the required `scripts:write` scope, and a shared 30 req/min group budget with the warning that writes are metered tighter than reads.

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

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

Front-loaded with the core action and the two failure modes, then scope, then rate limits — a sensible ordering with no filler. The rate-limit paragraph is group-wide boilerplate rather than tool-specific, 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?

For a non-idempotent write tool with no output schema, the description covers exactly what's missing from structured fields: auth scope, both error conditions, and a quota that constrains retry/batching behavior. An agent has everything needed to call it correctly and to interpret failures.

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

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

Both parameters are fully documented in the schema (100% coverage), including the 'must be unused' constraint on `name`. The description adds no syntax or format detail 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+resource ('Stores a new strategy script') — creation is unambiguous, and the 409-on-duplicate-name detail reinforces that this is a create, not an update. It does not explicitly name or differentiate from its siblings update_script/delete_script, 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?

Usage context is implied rather than stated: the note that 'Editing or deleting a script is never counted' points at update_script/delete_script, and the rate-limit advice ('make one considered change rather than a sequence of adjustments') guides batching. But it never says explicitly when to pick this over those 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?

Annotations already declare destructiveHint=true and readOnlyHint=false, so the core safety profile is covered. The description adds genuinely new behavioral context beyond annotations: the required `scripts:write` scope and the 30 req/min shared budget with a note that mutations are metered far more tightly than reads.

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

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

The purpose and auth scope are front-loaded in two short sentences, which is strong. The rate-limit paragraph is longer and reads as shared group boilerplate, but it is still decision-relevant information, so waste is limited.

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-param destructive mutation with no output schema and annotations covering the safety profile, the description plus annotations give an agent enough to invoke it correctly (scope, rate limits, destructive nature). It does not describe the success response or behavior when the named script is absent, which is a minor 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% for the single `name` parameter, so the schema already documents it fully. The description adds nothing about identifying the target script, so the baseline 3 is appropriate.

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

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

The description states a specific verb+resource ('Removes a script from the account's library'), which cleanly separates it from create_script, update_script, list_scripts and get_script by the delete verb. It doesn't explicitly name a sibling, but the operation 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?

There is no explicit when-to-use vs alternatives guidance, but the rate-limit note ('Creating, reconfiguring, stopping and deleting all share this budget, so make one considered change rather than a sequence of adjustments') effectively tells the agent to be economical with this call. Usage is implied rather than stated.

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?

Goes well beyond the annotations: it discloses the required `bots:read` scope, the exact rate limit (600/min shared across the whole `default` group, ten per second), and explains these are stored-record reads rather than venue calls, hence cheap. That is exactly the operational context annotations cannot carry.

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 outcome (P&L plus fill stats), then constraints. Most sentences earn their place, but 'Ten a second' merely restates the 600/min figure and 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?

With no output schema, the description usefully characterizes the return payload (realized P&L, fill statistics, decimal-string money keyed by asset/symbol) and covers auth plus rate limits. It stops short of describing what the fill statistics contain, leaving a small gap for a data-returning tool.

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

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

Schema description coverage is 100%, so `name`, `since`, and `until` are already documented. The description echoes the optional time window and adds a return-value caveat about decimal strings keyed by asset, but contributes nothing new about the input parameters themselves. 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 resource and scope: 'That bot's realized profit and loss and its fill statistics, optionally over a time window.' An agent can distinguish this from get_bot_config or list_bot_orders by the performance-metrics framing. It does not name a sibling to route away from, so it stays short of the top score.

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 mention of an optional time window implies when to use it (historical performance review), but there is no explicit when-to-use/when-not guidance and no named alternative among the 25 siblings. Adequate but inference-only.

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, safe and open-world, so the bar is lower; the description goes beyond them by stating the required `bots:read` scope and the concrete rate limit (600/min, shared across the default group) and even explains why these reads are cheap. It omits error behavior for an unknown or unauthorized bot name, keeping it out of 5 territory.

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 returned-field inventory is front-loaded and the scope/rate-limit facts follow compactly. The closing sentence ('These read stored records... which is why they are cheap') is explanatory flavor rather than operational guidance, so it is slightly over budget but not wasteful.

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

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

With no output schema, the description usefully enumerates return contents, including the ambiguous loss-limit type, and covers auth scope and rate limits. It does not address failure modes (bot not found, insufficient scope), which is the remaining gap for a simple one-parameter read.

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% for the single `name` parameter, so the schema already carries the semantics and the description adds nothing about the argument. Baseline 3 applies; the note that loss limit can be a number or a {max_loss} object describes output shape rather than input 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 title plus the enumeration of exactly what comes back (script-declared fields, overrides, run mode, simulator settings, loss limit) makes the resource and read scope unambiguous, and it is clearly distinct from update_bot_config or get_bot_analytics. It stops short of naming a sibling for differentiation, so a 4 rather than 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?

Usage is only implied: you fetch a single bot's config when you need its stored settings. There is no explicit when-to-use, when-not-to-use, or pointer to alternatives like update_bot_config for writes or list_bots for enumeration, so it lands at minimum-viable.

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

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

Adds substantial context beyond annotations: it names the required scripts:read scope, gives a concrete rate limit shared across the default group, and explains that reads are cheap because they access stored records rather than a venue. It also discloses the returned metadata (created and last changed).

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 return content, then adds scope and rate-limit context. The rate-limit explanation is useful, though "Ten a second" slightly repeats "600 requests per minute."

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 read tool with no output schema, the description covers what is returned, authentication needs, rate limits, and read-cost behavior. An agent has enough to call it correctly 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?

Schema coverage is 100%, so the single name parameter is already documented by the schema. The description adds only that the result is one script's source, without further syntax or format 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 a specific resource and payload: one script's source plus created and last-changed timestamps. It implicitly distinguishes itself from list_scripts and get_script_config by emphasizing a single script's source, though it does not name those alternatives.

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

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

Usage is implied by "One script's source" and the required script name, but the description gives no explicit when-to-use guidance, exclusions, or sibling alternatives. It focuses on access requirements and rate limits rather than tool selection.

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

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

Annotations already carry the safety profile (readOnly, idempotent, non-destructive, openWorld), and the description adds genuinely new behavioral facts: the required `scripts:read` scope and a concrete rate limit of 600 req/min shared across the `default` group. It also discloses the read path — stored records rather than a venue call — which explains cost/latency in a way annotations cannot. This is exactly the beyond-annotations context the dimension rewards.

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 return shape, followed by auth and rate-limit constraints in descending order of importance. Slightly padded: the rate limit is stated twice ('600 requests per minute... Ten a second') and the closing rationale 'which is why they are cheap' is a nicety rather than load-bearing 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 one-parameter read tool with no output schema, the description covers purpose, return contents, scope requirement and rate limits, which is nearly everything an agent needs. It does not say how a missing/unknown script name is handled or whether declared defaults are versioned, which is a minor residual 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?

There is one parameter with 100% schema description coverage ('The script's name'), so the schema already documents it fully. The description adds no syntax, format, or resolution detail for `name` (e.g. case sensitivity or whether it must correspond to an existing script). Baseline 3 is correct when the schema does the heavy lifting.

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 spells out the returned resource concretely: each declared field's name, type, default and hint, plus the fact that a running bot may override these. That is a clear, agent-usable definition of what 'config' means and how it differs from get_script or get_bot_config. It stops short of naming a sibling outright, so it is clear but not sibling-differentiating.

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 only implied via the clause 'which is what a bot running it may override', which suggests you call this before inspecting or changing per-bot overrides. There is no explicit when-to-use, no when-not-to-use, and no named alternative such as get_bot_config or get_script. Adequate context, but the agent must infer the 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?

With annotations already covering the safety profile (readOnly, idempotent, openWorld, non-destructive), the description still adds substantial context: the required `market:read` scope, a hard 60/hour limit shared across the whole `venue-public` group, and the reason (it serves a cached copy good for the hour). These are exactly the operational facts an agent needs and none are derivable 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?

Purpose is front-loaded in the first sentence and the scope/rate-limit facts follow logically. The rate limit is stated twice ('60 requests per hour' then 'Sixty an hour') for rhetorical emphasis, which is mildly redundant and slightly inflates length, but the rationale sentence earns its place.

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

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

For a two-param read with no output schema, the definition covers purpose, authorization, and rate limits thoroughly. It does not describe the shape of the returned price (field names, timestamp, precision), which an agent guessing blindly might want, but the annotations already certify this as a safe idempotent read, so the gap is minor.

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% with only two parameters, and the schema already documents both venue (with an enum and the 'market half of the name' note) and symbol. The description restates 'one symbol on one venue' without adding format, casing, or enum guidance 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 precisely what is returned: the current price for one symbol on one venue. The resource and cardinality ('one symbol on one venue') are unambiguous, and no sibling tool returns prices, so confusion is unlikely. It stops short of naming or contrasting any sibling explicitly, which keeps it out of 5 territory.

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 real routing advice: 'Read an instrument list once and keep it' and, for higher-frequency needs, 'read the venue's own public API' instead. That is an explicit when-not plus an alternative, which is rare and valuable. It does not frame usage relative to the MCP siblings (e.g. list_instruments), so it falls just short of a 5.

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

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

Goes well beyond the annotations: it discloses the required `portfolio:read` scope, a concrete rate limit (60 rpm) that is shared across the entire `venue-private` group, and the non-obvious fact that each call also consumes the caller's own allowance at the venue. The annotations only declare it as a safe idempotent read; this adds the operational cost profile an agent needs.

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

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

Front-loaded with the core purpose, then scope, rate limit and routing. Every sentence carries information, though the closing clause ('instead of being asked whether one has') is slightly convoluted and could be tightened.

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

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

For a single-parameter read tool with an output schema absent but a very simple return shape, the description covers auth, rate limits, and alternatives. It does not describe the returned balance structure, which is a minor gap given there is no output schema.

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

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

Schema description coverage is 100% and the single `venue` parameter already has an enum plus a clarifying note about the market half of the name, so the schema does the heavy lifting. The description adds only the scoping rationale ('Name a venue when you only need one'), not new format or syntax detail. 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 states a precise verb+resource+scope: balances, restricted to a single named venue. The scope qualifier ('one venue', 'Name a venue when you only need one') implicitly separates it from the sibling list_balances, which an agent can infer covers all venues.

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

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

Explicit when-to-use ('Name a venue when you only need one') and an explicit when-not-use with a named alternative ('For anything you would otherwise poll for, follow the order stream'). It also warns against polling, which is actionable routing guidance rather than generic advice.

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, and the description adds substantial context beyond them: the required `portfolio:read` scope, a 60 req/min limit shared across the entire `venue-private` tool group, and the fact that each call also spends the caller's allowance at the upstream venue. That upstream-allowance warning is exactly the kind of behavioral trait annotations cannot convey.

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

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

Front-loaded with the resource and scope, then scope/rate-limit/alternative guidance in descending priority. Slightly long and the final 'For anything you would otherwise poll for' sentence is a touch circuitous, but every sentence carries actionable information rather than 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 no parameters, no output schema, and annotations covering the safety profile, the remaining burden is prerequisites, throttling, and choosing between sibling endpoints — all of which are addressed. Nothing an agent needs to invoke it correctly is missing.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline for a no-parameter tool applies. No parameter description is needed or possible.

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 plus its distinguishing scope: balances across EVERY venue the account holds keys for. This directly contrasts with the sibling get_venue_balances via 'Name a venue when you only need one,' so an agent can pick between them 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?

Explicitly tells the agent when not to call it ('do not poll it'), what to do instead ('follow the order stream ... reports a fill when it happens'), and the narrower alternative ('Name a venue when you only need one'). This is as close to complete routing guidance as an aggregation endpoint gets.

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?

Goes well beyond the annotations: discloses the required `bots:read` scope, a concrete rate limit (600/min shared across the group, ~10/sec), that results are read from stored records rather than hitting a venue, and two edge-case behaviors (stopped bots still readable, unknown bot returns empty list not an error). Rich, actionable behavioral context beyond readOnlyHint/idempotentHint.

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

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

Four short sentences, front-loaded with what the tool returns and its ordering. Each sentence carries distinct information (scope, edge cases, auth, rate limit) 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?

Covers scope, auth, limits, and edge cases for an 8-param read tool with no output schema. The only gap is the return/pagination shape (page size default, the nextBefore cursor flow), which the agent must infer from the schema's `before` and `limit` parameters.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning the schema does not: results are 'newest first' (sort order is undocumented in the schema) and the default set is open plus historic, clarifying that status filtering is optional rather than implicit.

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 with scope and ordering: 'Every order that bot has placed, open and historic, newest first.' An agent knows this is a per-bot order listing, though the description never explicitly contrasts it with the sibling list_orders/list_open_orders, leaving that differentiation to the tool name.

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

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

Gives clear context for when it applies (works for stopped bots; unknown bot yields an empty list rather than an error), which removes a real decision risk. It stops short of naming alternatives like list_orders or list_open_orders and saying when to prefer 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?

Beyond the readOnly/idempotent annotations, it discloses the required `bots:read` scope, the concrete rate limit (600/min shared across the `default` group), and that the data comes from stored records rather than live venue calls. That is exactly the kind of auth/limit context the annotations cannot convey, though the stored-records claim sits slightly at odds with openWorldHint=true.

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 resource and return payload in the first sentence, followed by scope and rate-limit context. The rate-limit sentence is a touch verbose ("Ten a second." plus rationale), but every sentence carries usable information.

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

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

For a parameter-less list tool with no output schema, the description covers scope, contents, authorization, and cost. It stops short of describing ordering or any result cap, which would be the only 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline of 4 applies. No misleading parameter guidance is present.

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?

"Every bot on the account" states an unambiguous scope, and the description itemizes what comes back (state, run mode, script, fleet summary) plus the extra payload of creatable scripts and run modes. This is specific enough to separate it from get_bot_config (single bot config) and list_scripts.

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 only implied: the note that it returns "the scripts and run modes a new bot can be created with" hints it precedes create_bot, but there is no explicit when-to-use, when-not-to-use, or named alternative. An agent must infer the selection criteria against ~25 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?

Annotations only cover the safety profile (readOnly, idempotent, non-destructive), so the description adds substantial non-obvious context: the required market:read scope, a 60 req/hour rate limit shared across the whole venue-public tool group, and the fact that the response is an hour-cached copy worth keeping rather than polling.

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 what it returns and why it matters, then scope, then limits. Slightly redundant ('60 requests per hour' restated as 'Sixty an hour'), but every sentence carries usable information.

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

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

No output schema exists, yet the description still conveys what comes back (symbols plus tick/lot rules), the auth requirement, and the rate ceiling — the pieces an agent needs to plan a call. Only field-level return detail is absent, which is a minor gap for a single-parameter list 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 single venue parameter already has 100% schema description coverage and a full enum, so the schema does the work. The description adds domain framing (venue id, tick/lot rules) but no extra syntax or value guidance for the parameter itself, which is the baseline-3 situation.

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 (every symbol a venue lists) plus its distinguishing payload (tick and lot rules), and the venue parameter frames scope. An agent can distinguish it from list_venues or get_ticker 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 says when to use it ('read this before placing an order, because a price or quantity off the venue's grid is refused') and names an alternative path for a different need ('For prices more often than this, read the venue's own public API'). Both the when and the when-not are covered.

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, openWorld), yet the description still adds genuinely new operational context: the trade:read scope requirement, a concrete rate limit (600/min shared across the default group), and the reason it is cheap (reads stored records rather than hitting a venue). This substantially exceeds what the annotations convey.

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

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

Front-loaded with what it returns, then scope/alternative, then auth, then rate limit plus rationale. Sentences are short and each carries information; only 'Ten a second' is a restatement of the 600/min figure, a trivial 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?

For a zero-param tool with no output schema, the description carries the return-shape burden and does partially ('each one carrying which bot placed it', account-scoped book view). Auth and rate-limit context are supplied, but pagination or fuller field composition of the returned orders is not described.

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

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

With zero parameters the baseline is 4, and the schema is fully covered (empty object). The description reinforces this ('takes no filters'), clarifying that filtering must happen client-side, which is useful added meaning for a no-arg tool even though there is nothing more to document.

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 every still-tradeable order across the account) with precise scope: bots and manual alike, bot attribution included. It distinguishes itself from siblings by naming list_orders as the filtering variant and by calling itself 'the account's own view of the book', which separates it from the venue-side list_venue_open_orders.

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

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

Explicitly declares the key behavioral constraint ('takes no filters: filter the result yourself') and routes the agent to the alternative ('use list_orders, which does filter'), with the selecting condition spelled out. Prerequisites are also stated via the required trade:read scope.

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 open-world, so the safety profile is covered; the description still adds real value beyond them by naming the required `trade:read` scope, the 600 req/min budget shared across the `default` tool group, and the fact that reads hit stored records rather than a venue. It stops short of describing result ordering or default page size.

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

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

Purpose is front-loaded in the first sentence and the rate-limit/scope facts are compact and useful. One sentence ('Page with the nextBefore the response carries.') is grammatically awkward, but nothing here is filler.

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

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

With ten optional filters and no output schema, the description covers pagination direction and the cost/scope model, which is the most important operational context. It leaves gaps an agent would want: result ordering, what an unfiltered call returns, and default/max page size for `limit`.

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 all ten parameters are already documented in the schema and this is the baseline case. The description only adds one small piece of linking context — that paging uses the `nextBefore` value carried in the response — which the `before` parameter description partly covers already.

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

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

The first sentence names the resource (the account's order history) and states its two defining behaviors: filtering and pagination. It is clear what the tool returns, though it never explicitly distinguishes itself from close siblings like list_open_orders or list_bot_orders, which an agent could plausibly confuse it with.

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 explains mechanics (paging, scope, rate limit) but gives no when-to-use guidance: nothing says this covers historical/filled/canceled orders versus list_open_orders, nor when to reach for list_bot_orders instead of the `bot` filter. The agent must infer the boundary entirely from the sibling names.

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 cover the safety profile (readOnly, idempotent, non-destructive), but the description adds substantive operational context the annotations cannot convey: the required `portfolio:read` scope and the concrete 60 req/min rate limit shared across the `venue-private` group, including that these calls also consume the venue's own allowance. It is slightly thin on what a position record contains, which is the only reason this is 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?

Front-loads the resource being listed in the first sentence, then layers auth and rate-limit context as separate ideas. The rate-limit paragraph is a long compound sentence, but each clause (shared allowance, avoid polling, prefer venue filter, use the stream) carries distinct guidance.

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 authorization, rate limits, and polling strategy for a zero-parameter read tool, and the safety profile is already declared in annotations. With no output schema, it stops short of indicating the return shape (e.g. instrument, size, entry price), which would help an agent consume the result.

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

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

The tool takes no parameters (0 params), so the baseline expectation is 4. The description adds nothing parameter-related, but there is nothing to describe.

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 derivative positions') and scopes it ('across the account'), which cleanly separates it from list_balances and list_open_orders. The line 'Name a venue when you only need one' implicitly routes to the venue-scoped sibling, sharpening the distinction further.

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 when/when-not guidance: use a venue-specific call when only one venue is needed, and follow the order stream instead of polling this endpoint. It even names the alternative mechanism (fill reporting on the stream) rather than leaving the agent to infer it.

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

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

Although annotations already mark it read-only and idempotent, the description adds substantial context: the required `scripts:read` scope, a concrete rate limit, and the fact that it reads stored records rather than calling a venue. This is exactly the kind of operational context annotations do not provide.

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

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

The description is short and front-loads the purpose, then adds auth, rate-limit, and behavioral context. The phrase 'Ten a second' slightly restates the rate limit, but the overall structure is 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?

With no output schema and no parameters, the description gives enough conceptual detail about what is returned: the account's scripts plus editor-enforced limits. Pagination or exact response shape is not described, but for a simple list tool 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?

The tool has zero parameters, so there are no parameter semantics to explain. The baseline for a parameterless tool is 4, and nothing in the description creates confusion about inputs.

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 resource as the account's strategy scripts and notes that it includes editor-enforced limits. It does not explicitly differentiate from the sibling `get_script`, but the listing purpose is still evident from the name and wording.

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 explains auth scope and rate limits but never says when to use this tool instead of `get_script` or other list tools. There is no explicit routing guidance or when-not condition.

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 the description layers on facts the annotations cannot carry: an auth prerequisite ("Requires the key to be valid"), a concrete rate limit ("60 requests per hour ... shared across every tool in the ws-ticket group"), budget contention with stream opening, and the non-obvious behavior that streams cannot be read via a tool call at all.

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

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

Front-loaded with purpose, then usage, then constraints, and every sentence carries information (discovery-only framing, auth, rate limit, caching). It runs slightly long with three separate short constraint sentences, but there is no filler or repetition.

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

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

With no parameters, no output schema and a safety profile already covered by annotations, the description supplies exactly the missing pieces an agent needs: that this is discovery-only, how to actually read the data, auth requirements, and the shared rate budget.

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

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

The tool takes zero parameters, so the baseline is 4. There are no arguments whose semantics the description could enrich, and it correctly avoids inventing parameter guidance where none is needed.

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 live streams this deployment serves and the scope each needs") and immediately carves out what it is not: "Discovery only — a stream is a long-lived connection and cannot be read through a tool call." This clearly separates it from siblings like list_bots, list_orders and the rest of the listing family.

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 prescribes when to use it ("use this to find out what exists") and the alternative path ("read the same data through the list tools"), plus a caching directive ("Read it once; it does not change while a key lives"). Nothing about routing 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 cover the safety profile (readOnly, idempotent, non-destructive, open-world), but the description adds materially: the required `trade:read` scope, a 60 rpm rate limit shared across the whole `venue-private` group, the fact that each call also spends allowance at the venue with the caller's own key, and an explicit 'do not poll' instruction. This is exactly the context annotations cannot convey.

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

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

Front-loads the purpose and the sibling contrast before auth and rate-limit details, and every sentence carries operational value. It runs a little long with the trailing stream-recommendation sentence, but that sentence is genuinely actionable rather than filler.

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

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

For a two-parameter read tool with no output schema, the description covers everything an agent needs: identity of the data source, the sibling relationship, required scope, rate-limit budget, and the preferred non-polling alternative. The return shape is implied by the resource and title.

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 `venue` (enum with its own description about the market half of the name) and `symbol` are fully documented in the schema. The description's 'Name a venue when you only need one' adds marginal framing but no syntax or format detail 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+resource with scope: 'One venue's own view of the account's resting orders.' It explicitly names the sibling it differs from (list_open_orders) and explains the distinction, so an agent can route correctly without opening either schema.

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

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

Gives explicit when-to-use (comparing against list_open_orders to surface disagreements), when to narrow ('Name a venue when you only need one'), and a when-not-to-use alternative ('For anything you would otherwise poll for, follow the order stream'). Nothing 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 cover the safety profile (readOnly, idempotent, non-destructive), and the description adds genuinely new operational context: the required `trade:read` scope, a concrete rate limit (600 rpm, shared across the `default` group), and why the call is cheap (reads stored records rather than hitting a venue). This is exactly the kind of auth/rate-limit/cost disclosure that structured fields cannot convey.

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

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

The description is short, front-loads what the tool returns, then layers on scope and rate limit. It is slightly repetitive in justifying cost twice ('which is why it costs trade:read' and 'which is why they are cheap'), which costs a point but does not obscure the content.

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

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

With no output schema, the description must carry the return-value burden, and it does describe the shape at a high level (venue list plus per-venue key/plan state). It omits concrete field names or ordering, but for a parameterless read of this kind that is a minor gap.

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

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

The tool takes zero parameters, so per the rubric the baseline is 4. There is nothing for the description to disambiguate on the input side, and it correctly does not invent parameter detail.

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 concrete verb+resource (list venues) and goes further by spelling out the per-venue payload: whether keys are stored and whether the plan permits it. That is specific and unambiguous. It does not, however, explicitly differentiate itself from siblings like list_instruments or get_venue_balances, so it lands just 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?

There is no when-to-use guidance and no named alternative. The description states a required scope and rate limit, but never tells the agent under what circumstances it should reach for list_venues rather than get_venue_balances or list_instruments, so usage must be 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 only say it is a non-idempotent, non-read-only, open-world write. The description goes well beyond that: real funds are committed, off-grid prices/sizes are refused, decimal strings are used to avoid floating-point loss, and it discloses the exact shared rate limit with the caveat that it is not a design target.

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

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

Four sentences, front-loaded with what the tool does and its cost, then conventions, then preconditions, then limits. The rate-limit sentence is long but the closing caveat ('not a figure to design around') is load-bearing guidance rather than 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?

With no output schema, the description still characterizes the response ('answers with it as the venue acknowledged it'), and it covers auth scope, validation failure mode, numeric encoding, and rate limits. Nothing an agent needs to call this safely is missing.

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

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

Schema coverage is already 100%, so the baseline is 3, but the description adds real value: it explains the string-not-number convention globally and the conditional requirements for price and stopPrice, reinforcing the schema's per-field notes with a rule-based summary.

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 ('Submits one order') plus the material consequence ('with real funds'), and the phrase 'one order' distinguishes it from batch/bot siblings like create_bot and cancel_orders. An agent can identify the operation without opening the schema.

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

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

Gives a concrete prerequisite ('Check list_instruments first') and states which order types require price vs stopPrice, plus the required trade:write scope. It stops short of naming an alternative tool or an explicit when-not-to-use condition, but the operational 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 carry destructiveHint=true, idempotentHint=false and openWorldHint=true, and the description adds meaning beyond them: exactly what persists after the stop (orders and analytics remain readable), the required `bots:write` scope, and a concrete rate limit with the shared `control-plane` budget. This is the kind of side-effect and authorization detail annotations cannot express.

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 behavioral core is front-loaded in the first two sentences, and the scope/alternative routing comes before the operational caveats. The rate-limit paragraph is longer than strictly needed for tool selection, but it earns its place as non-obvious shared-budget guidance.

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 mutation with no output schema, the description supplies everything an agent needs: authorization scope, post-state of related data, the boundary against cancel_orders, and throttling behavior. 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?

Only one parameter and schema description coverage is 100%, so the schema fully documents `name`. The description adds no naming, format, or resolution semantics beyond what the schema states, 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?

States a specific verb ('Stops') plus resource ('the bot') and adds scope detail ('and retires it'), then distinguishes the action from the adjacent one (cancelling resting orders). An agent can separate this from delete_script, cancel_orders, and update_bot_config without opening another 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 condition under which this tool is the wrong choice: it does not cancel resting orders, and it routes to cancel_orders for that. It also gives operative context for when to call it (a single considered change rather than a sequence) tied to the shared rate-limit budget.

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

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

Annotations already mark it destructive, idempotent, and open-world, yet the description adds substantial value beyond them: a full-replace-vs-merge contract, an explicit restart side effect, a guarantee that resting orders are not cancelled, the required `bots:write` scope, and a concrete shared rate limit of 30 req/min. This is exactly the behavioral context annotations cannot carry.

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?

Well front-loaded with the replacement/restart contract first, then scope, then rate limits. The rate-limit block is slightly redundant ('shared across every tool in the control-plane group' restated as 'Creating, reconfiguring, stopping and deleting all share this budget'), but no sentence is purely filler.

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

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

For a destructive, restart-triggering mutation with no output schema, the description supplies the essential gaps: replacement semantics, side effects, order preservation, auth scope, and throttling. Nothing an agent needs to invoke this correctly appears to be missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description meaningfully reframes the `config` parameter as a complete replacement rather than a patch, which changes how the agent must construct it. The killSwitch and sim nuances remain in the schema, so it is not fully additive.

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 precise verb+resource relationship ('Replaces the overrides... and RESTARTS the bot') and immediately clarifies the scope of the operation (full replacement, not a merge). An agent can distinguish this mutation tool from get_bot_config, create_bot, and update_script without reading further.

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

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

Gives clear operational context: you must send every override to keep, the bot restarts, and resting venue orders survive. It also nudges toward a single considered change via the rate-limit note. It does not explicitly name the read counterpart (get_bot_config) as the way to fetch current state, so routing is still partly 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=true, idempotentHint=true, and openWorldHint=true, but the description adds substantial context beyond them: running bots keep the old version until restarted, a 409 is returned when declared settings change, the required scripts:write scope, and the shared 30/min control-plane rate budget. These are exactly the operational facts annotations cannot convey.

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

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

Three short, front-loaded paragraphs: what it does, the operational caveat, then the scope/rate constraints. Every sentence carries information, though the rate-limit paragraph is longer than strictly needed and could be tightened without losing 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?

With no output schema and a fully covered input schema, the description supplies everything else an agent needs for a destructive mutation: auth scope, concurrency behavior of running bots, the failure mode (409), and the rate ceiling. 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% (both `name` and `script` documented), so the schema carries the parameter burden and the baseline is 3. The description marginally reinforces that `script` replaces the stored source wholesale, but adds no format, syntax, or constraint detail 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?

States a specific verb and resource ('Replaces a script's whole source'), and the phrase 'whole source' distinguishes it from an in-place edit or the sibling create_script path. An agent can unambiguously tell it apart from get_script, create_script, delete_script, and list_scripts.

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 when-not condition ('An edit that changes the settings the script declares is refused with a 409; save it under a new name instead') which routes the agent to create_script for that case, plus the scripts:write prerequisite. It stops short of naming the sibling tool explicitly or stating 'call this only when X'.

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