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

Annotations already declare the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false), lowering the burden. The description adds genuine behavioral context beyond them: it reads a data file, returns performance metrics, and crucially 'does not touch your paper accounts' — an isolation guarantee the annotations do not convey. It is slightly in tension with readOnlyHint=false (the tool runs user strategy code), but the scope claim itself is accurate.

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 waste: purpose first, then the behavioral/scope clarification, then sibling routing. Front-loaded and every sentence earns its place.

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

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

An output schema exists, so return values need not be explained, and the description covers purpose, scope, and alternatives. The only omission is that the tool executes Python strategy code — implied by strategy_path's schema but not surfaced in the description.

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 five parameters (data_path, strategy_path, depth, spread, balance) are fully documented with defaults and constraints in the schema. The description adds no syntax or format details beyond that, 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+scope: 'Replay a strategy over historical price snapshots on synthetic order books.' An agent can distinguish this from pk_battle (live comparison) and stats (real account results) without opening any schema.

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

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

Explicitly names the two alternatives and the conditions that select them: 'Use pk_battle to compare two strategies live, or stats for an account's real results.' Nothing is left to inference about when to pick this tool.

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

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

Annotations already declare the mutation/safety profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false), so the bar is lower. The description adds real value beyond them: immediate fill against the live order book, fee recording, simulated/no-real-order semantics, and that Kalshi fees follow the series fee schedule. It does not mention slippage expectations or auth requirements, 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?

Front-loaded with purpose and scope, then behavior, then alternatives. Four tight sentences with no filler; every clause adds routing or behavioral 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?

With an output schema present, return values need not be explained, and the description covers the remaining burden: what the fill does, that it is simulated, fee handling, and sibling routing. Nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 100%, so the schema already documents slug_or_id (including the 'kalshi:<TICKER>' format), outcome, amount_usd, order_type, and account. The description adds only light framing ('paper money', fee schedule) that overlaps with existing schema text, 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?

States a specific verb (Buy) plus resource (shares of a Polymarket or Kalshi outcome) and scope (paper money). It explicitly distinguishes itself from siblings by naming place_limit_order and sell, so an agent can route without opening schemas.

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

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

Explicitly gives when-to-use: immediate fill against the live order book. It names the alternative (place_limit_order for a resting order at your price) and the exit path (sell), covering both the primary and the exclusionary cases.

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, but the description adds the crucial scope of destruction — only pending limit orders, with filled orders and open positions untouched — plus that it is a local change and that reserved cash is released. It also notes the return payload (count and cancelled orders), which is exactly the extra context expected when annotations carry the safety profile.

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, zero filler, and the effect/scope is front-loaded before the sibling pointer. Every sentence carries information an agent needs.

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?

Return values are already covered by the output schema and the destructiveness/idempotency profile by the annotations; the description fills the one remaining gap, the blast radius of the operation. Nothing needed to call it correctly is missing.

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

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

Schema description coverage is 100% and the single 'account' parameter is fully documented in the schema (naming rules, default). The description adds nothing about the parameter, 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 precise verb and resource ('cancel every pending limit order of an account') plus the side effect ('release the reserved cash'). It also explicitly distinguishes itself from the single-order sibling, so an agent can route between the two 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 the when-to-use condition directly: use this for cancelling all pending limits, and 'Use cancel_order to cancel just one.' The alternative tool is named and the selecting condition is 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 declare destructive=true, idempotent=true and openWorld=false, so the description's added value is the mutation semantics: 'local change only' and the release of reserved cash, plus the not_found failure mode when the order is absent or already filled/cancelled. That is real behavior beyond the annotation flags, though it doesn't quantify anything about timing or concurrency.

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 action and side effect front-loaded, followed by the failure mode and the sibling alternative. No filler or restatement of the tool name.

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 carry the safety profile. The description covers the side effect, the failure mode, and the alternative tool, leaving only minor gaps such as account-scoped behavior for a local multi-account setup.

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%: order_id already documents its origin (place_limit_order or list_orders) and account already documents its naming rules and default. The description only restates 'by ID' and adds no syntax, format, or edge-case detail the schema lacks, 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 verb (cancel), resource (one pending limit order), selector (by ID), and a concrete side effect (release its reserved cash). This distinguishes it immediately from cancel_all_orders and from read-only siblings like list_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 routes the agent to cancel_all_orders for the bulk case and implicitly limits this tool to orders that are still pending. Clear context for selection, though it doesn't state prerequisites such as account scoping or what to do when the order belongs to a different account than the default.

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 (readOnlyHint=false, idempotentHint=false, destructiveHint=false), and the description adds genuinely new context: it mutates the local account by writing fills and cash changes, and it must be polled since resting orders never self-fill. It stops short of stating what happens under concurrent/repeated invocation or any error conditions.

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

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

Three tight sentences: the action first, then the side effect, then the operational cadence with the sibling pointer. No filler and nothing buried.

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. With one fully-documented parameter, four annotations, and explicit mutation/polling behavior, an agent has everything needed to decide and invoke 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 the single 'account' parameter is fully documented in the schema (name constraints, default). The description adds nothing about the account parameter, 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 precise compound action (evaluate pending limit orders against live prices, execute fills) on a specific resource. It is immediately distinguishable from siblings like list_orders, place_limit_order, and cancel_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?

Explicitly gives the cadence ('call this periodically' because resting orders never fill on their own) and names the alternative for read-only viewing ('Use list_orders to only view pending orders'). Both when-to-use and when-to-use-something-else 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 declare readOnly, idempotent, non-destructive and open-world, so the safety profile is covered. The description adds genuinely new behavioral context: it reads the local account but prices positions with live market data, implying a network dependency and possible latency that the annotations don't 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?

Two tight sentences: the first front-loads the return contents, the second covers data sourcing and alternative tools. 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?

An output schema exists, so return shape need not be re-explained, and the description already covers data sourcing, scope and sibling routing. Nothing an agent needs to invoke this correctly is missing.

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

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

Schema description coverage is 100%, and the single 'account' parameter is fully documented in the schema, including naming rules and the default. The description adds nothing about the parameter, 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?

Names a specific verb and resource (get an account's balance) and enumerates exactly what is returned: cash, reserved and available cash, positions value and P&L. It also distinguishes itself from siblings by naming the ones that cover adjacent ground (portfolio, stats).

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

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

Explicitly routes the agent to alternatives: 'Use portfolio for per-position detail and stats for performance metrics.' This gives clear context for choosing between them, though it doesn't state a negative condition (when not to use get_balance).

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 and openWorldHint, so the safety profile is fully carried by structured data. The description's 'reads the live Polymarket API and changes nothing' largely restates readOnlyHint; the only added nuance is that data is fetched live rather than cached. Nothing about rate limits, auth, or failure modes is added.

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, no filler, and the purpose plus the resource definition are front-loaded ahead of the sibling routing. Every sentence earns its place.

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

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

An output schema exists, so return values need no explanation, and the single required parameter is fully specified in the schema. For a one-param read tool with complete annotations, nothing an agent needs in order to call this correctly is missing.

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

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

Schema coverage is 100% and the single slug parameter is fully documented in the schema, including a URL-derived example. The description adds no format, syntax, or validation detail beyond that, 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 ('Get a Polymarket event') and then defines the resource ('the group of related markets sharing one topic'), which is genuinely useful domain framing. It also names the sibling it is not, so an agent can distinguish get_event from get_market 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 routes the single-market case to get_market, giving a real when-to-use alternative. It does not address other plausible alternatives in the sibling list (search_markets, get_markets_by_tag, list_markets), so it is clear context rather than full 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 declare readOnlyHint, idempotentHint and destructiveHint=false, so 'reads live data and changes nothing' largely restates structured data. The one added value is the freshness cue ('live data') and the sibling routing, but no error handling or data-staleness caveats beyond that.

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

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

Two compact sentences, front-loaded with the resource and its scope, then the accepted input forms and the alternative tool. No filler.

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

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

With an output schema present, the description needn't explain return values, and it covers input formats and the main alternative. Only minor gaps remain (behavior on an unknown slug, whether stale/closed markets still resolve), so it 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% and the single parameter's schema already documents the slug/condition-ID/Kalshi-prefix formats with an example. The description repeats this rather than adding new 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 (Get) and resource (one market) and enumerates the returned fields (question, outcome prices, volume, liquidity, status), which makes it clearly distinct from list_markets/search_markets and from sibling get_event.

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

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

Explicitly routes depth/orderbook queries to get_order_book and gives the exact input formats accepted (Polymarket slug, condition ID, 'kalshi:<TICKER>'). No explicit when-not guidance versus list_markets or kalshi_market, 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 declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is fully covered. The description adds the 'live Polymarket API' note, but the 'changes nothing' claim largely restates readOnlyHint. It does not add rate-limit, pagination, or result-ordering behavior beyond structured fields.

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

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

Three short sentences, zero filler: the scoping constraint is front-loaded, the safety note second, and the disambiguation routing last. Every sentence earns its place.

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

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

An output schema exists, so return values need no explanation, and the schema fully documents parameters. Combined with annotations covering the safety profile, an agent has everything needed to call the tool correctly.

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

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

Schema description coverage is 100%, so both parameters (tag_slug, limit) are already documented including the empty-list behavior for unknown slugs. The description only adds provenance for tag_slug ('get slugs from get_tags'), which is a minor value-add over 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 (list), resource (Polymarket markets), and scope qualifier (open, in one category tag). An agent can distinguish this from list_markets and search_markets purely from the first sentence.

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

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

Explicitly routes the agent: get slugs from get_tags, use search_markets for keywords, use list_markets for top markets overall. This names both prerequisites and the sibling alternatives with the conditions that select 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?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is fully covered. 'Reads live data and changes nothing' largely restates that. The one genuinely additive point is the freshness/liveness cue ('live') and the cross-venue capability, which is modest 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?

Three short sentences with no filler; the purpose and scope are front-loaded, venue coverage follows, and the buy/sell cue closes it. Every sentence carries distinct information.

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

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

With an output schema present, the return payload need not be described, and the description covers venue addressing and a timing heuristic. It is nearly complete, though it never clarifies the boundary with the parallel kalshi_book tool, which an agent choosing between them would want.

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 both parameters, including the 'kalshi:<TICKER>' format and the yes/no outcome default, so the schema already documents everything. The description's mention of the Kalshi slug form repeats the schema verbatim and adds no syntax or constraint beyond it. 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 ('Get the live asks and bids (price and size) for one market outcome'), scoping it to a single outcome rather than a whole market. It also covers both venues (Polymarket slugs, Kalshi via 'kalshi:<TICKER>'). It does not, however, draw a line against the sibling kalshi_book, which appears to serve an overlapping purpose.

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

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

Gives a clear usage trigger: 'check it before sizing a buy or sell,' which ties the tool to the buy/sell workflow. It offers no explicit exclusions or guidance on when kalshi_book (or get_market) would be preferred, so the 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, and destructiveHint=false, so 'changes nothing' largely restates structured data. The one genuinely additive detail is that it 'reads the live Polymarket API' (freshness/no caching), which is useful but thin; no mention of result size or rate limits.

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, no filler, and the core purpose plus the follow-on action are front-loaded. Nothing here is redundant 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?

A zero-parameter discovery tool with an output schema and full read-only annotations needs very little prose. The description covers purpose, safety, freshness, and the workflow handoff, so an agent can call it correctly without further inference.

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?

Zero parameters, so the baseline is 4. The description still adds value by characterizing the returned payload ('tags with their slugs'), orienting the agent on what the slug strings it will pass downstream look like.

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 all Polymarket market categories (tags) with their slugs') and clarifies scope as a discovery endpoint for the Polymarket domain. It also implicitly distinguishes itself from the many list/search siblings by naming the downstream tool it feeds.

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 what to do next: 'Pass a returned slug to get_markets_by_tag.' That is real routing guidance toward the consumer tool. It lacks an explicit 'when not to use / use search_markets instead' exclusion, which keeps it 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, and destructiveHint=false, so safety is covered. The description adds value beyond annotations by disclosing 'Reads the local database only (no network) and changes nothing', which explains the data source and connector behavior that annotations don't convey. It stops short of mentioning ordering beyond the schema's 'newest first' or pagination limits.

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

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

Two sentences, front-loaded with what the tool does, followed immediately by the behavioral note and the sibling routing. 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?

Output schema exists, so return format needn't be described; annotations cover safety; schema covers parameters. The description completes the picture with the local-DB/no-network behavioral fact and sibling routing, leaving no meaningful 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 description coverage is 100% (limit clamping, account naming constraints are fully documented in the schema), so the description needn't explain parameters. Baseline 3 is appropriate; the description adds no parameter detail beyond what the schema already provides.

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

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

States a specific verb and resource ('List an account's recent trades') and enumerates the returned fields, so an agent knows exactly what it gets. It does not name sibling tools in the purpose sentence itself, though it does distinguish from portfolio/stats later.

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

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

Explicitly routes the agent: 'Use portfolio for open positions or stats for aggregate performance.' This names the alternatives and the conditions that select them, which is exactly the when-to-use guidance needed among 30+ 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?

Adds real behavioral context beyond the annotations: it writes the local account database and re-calling on an existing account replaces its balance (consistent with idempotentHint=true). It also states local/filesystem scope, matching openWorldHint=false. It does not describe return format or failure modes, but with destructiveHint already flagging mutation, 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, with the destructive re-run caveat and the ordering requirement front-loaded before the alternative tool reference. No wasted text.

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

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

With an output schema present, return values needn't be explained, and both parameters are documented. The description covers the mutation semantics and the sibling alternative; only minor gaps like auth/permission needs remain.

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 naming rules and the balance default are fully documented in the schema. The description adds no additional parameter syntax or meaning, 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 verb and resource ('Create a paper trading account') plus the key parameter effect ('with a starting USD balance'). It is clearly distinguishable from reset_account and the trading siblings.

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

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

Explicitly says when to use it ('Run it before any trade') and names the alternative with its condition ('use reset_account to wipe trades and positions instead'). 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 declare readOnlyHint, idempotentHint, non-destructive and openWorld, so the safety profile is covered, and the description's 'read-only' merely repeats it. However, it adds genuinely non-obvious domain behavior: Kalshi publishes bids only and asks are derived from NO bids via 1 - p, which materially affects how the returned book must be interpreted.

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 core purpose front-loaded and no filler. The mid-sentence line break in the NO-bid/YES-ask explanation slightly disrupts readability but costs no real length.

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

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

An output schema exists, so return values need not be restated, and the description supplies the one interpretive fact an agent needs (asks are synthesized from NO bids). The only gap is that it never clarifies the practical choice between this tool and get_order_book, which is the main decision an agent faces.

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 'depth' (clamped 1-100, default 10) and 'ticker' (format example) are fully documented in the schema. The description adds no syntax, format, or edge-case detail about either parameter, 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 verb and resource ('Get the live YES order book for a Kalshi market, best levels first') and explicitly contrasts with the closest sibling, get_order_book, noting it returns the same book for the slug 'kalshi:<TICKER>' and also covers the NO side. An agent can tell kalshi_book (YES side only, Kalshi-native) apart from get_order_book 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 comparison to get_order_book implies when the sibling is the better choice (when the NO side is needed), but it never states a positive condition for choosing kalshi_book instead. There is no explicit when-to-use/when-not guidance, only an inferred one.

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 fully covered. The description adds that it reads the live Kalshi API and that no trade is placed, plus the ticker-to-slug convention used by the trade tools, but it says nothing about auth requirements, rate limits, or error behavior on an unknown ticker.

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 clause and the follow-up sentences are short and functional. The line break mid-sentence ('Reads the live Kalshi API. To trade it...') is slightly fragmented but costs nothing in comprehension.

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 a rich annotation set and an output schema covering return values, the description only needs to disambiguate purpose and hand off to the trade path, which it does. Minor gaps (auth expectations, behavior for an invalid ticker) remain but are peripheral for a single-parameter read tool.

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

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

Schema coverage is 100% and the single ticker parameter carries its own example, so baseline is 3. The description goes further by explaining that the same ticker acts as the 'kalshi:<TICKER>' slug_or_id across buy/sell/get_market, which gives the parameter cross-tool meaning beyond the schema's local format.

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

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

States a specific verb+resource+scope: 'Get one Kalshi market by ticker', with an explicit read-only qualifier. The singular 'one market' distinguishes it from the sibling list tools (kalshi_markets, list_markets, search_markets) without the agent needing to open any schema.

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

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

Gives concrete routing guidance: to trade, pass 'kalshi:<TICKER>' as slug_or_id to buy or sell, and notes the same slug works in get_market. This tells the agent how this tool chains into action tools. It stops short of saying when to prefer this over get_market or kalshi_markets, so no explicit exclusion.

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 safety is largely covered. The description adds value beyond them by noting it 'Reads the live Kalshi API' (live external data) and by surfacing the cross-tool path to trading, though the 'read-only and places no trade' line largely restates 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 and the text is short and scannable. The 'this tool is read-only and places no trade' clause is mild redundancy against the annotations, preventing 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?

With an output schema present, return values need no explanation; parameters are fully documented in the schema and safety is covered by annotations. The description supplies the remaining context an agent needs: live-API behavior and the trading handoff.

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, status, event_ticker, and series_ticker with defaults and ranges. The description adds no filter syntax or format detail beyond what the schema provides, 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?

States a specific verb+resource ('List Kalshi markets for discovery') and explicitly differentiates the sibling set: it names search_markets and list_markets as the Polymarket counterparts, so an agent can route between the two exchanges without opening schemas. The plural 'markets' plus 'for discovery' distinguishes it from the singular kalshi_market detail tools.

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

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

Explicit when-to-use (discovery/listing) and a concrete handoff for the trading case: pass 'kalshi:<TICKER>' as slug_or_id to buy, sell, or place_limit_order. It also states the alternative for the other venue ('Use search_markets or list_markets for Polymarket instead'), covering both the when and the when-not.

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 by disclosing data source resolution ('~/.pm-trader locally, the caller's own directory in remote mode') and valuation semantics ('Open positions are valued at live midpoints (0 if a lookup fails)'), which tells the agent results are live-marked and degrade gracefully rather than erroring. The annotations already cover the safety profile, so this is pure added context.

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

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

Front-loads the core action and ranking rule, then layers scoping, source resolution, and edge-case behavior compactly with no filler. The line breaks around the sibling pointer read slightly awkwardly, but every sentence carries information.

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

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

For a read-only, output-schema-backed card tool, the description covers ranking metric, inclusion threshold, data root scoping, and mark-to-market behavior with failure fallback — everything needed to call it and interpret results. Return format is delegated to the output schema, which exists.

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 parameter is fully documented in the schema, so the description need not restate it. The description adds only the 10+ trades ranking threshold, not account-name syntax or ordering semantics, so 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 chain and resource: 'Rank accounts with 10+ trades by ROI% and return a Top 10 leaderboard card.' The inclusion threshold and ranking metric let an agent distinguish it from stats/stats_card and the entry/battle card siblings without opening any schema.

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

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

Explicitly routes to alternatives: 'Use leaderboard_entry for one account's record or pk_card for two,' which cleanly partitions the three card tools by scope. The 10+ trade inclusion rule and the empty-accounts default define when the call is applicable.

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 safety is covered; the description adds genuine behavioral context beyond them by noting it reads the local account and that open positions are valued at live midpoints with a 0 fallback on lookup failure, plus the 'qualified' (10+ trades) semantics.

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

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

Front-loads the core action ('Return one account's standardized leaderboard record as JSON') before fields, behavior, and alternatives. It is tight though mildly redundant, since enumerating the record's fields overlaps with what the output schema already conveys.

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 read tool with an output schema and full annotation coverage, the description supplies everything needed: scope (single account), data semantics, the live-midpoint valuation caveat, and explicit sibling routing.

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 'account' parameter is fully documented there, including the default and naming constraints. The description adds nothing about the parameter, so the baseline 3 for schema-heavy documentation 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 ('Return') and resource ('one account's standardized leaderboard record as JSON'), plus enumerates the fields included. It explicitly distinguishes itself from leaderboard_card (ranking) and stats (analysis), so an agent can disambiguate among siblings without opening schemas.

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

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

Names the alternatives and the condition selecting each: 'Use leaderboard_card to rank many accounts, or stats for analysis.' This gives explicit when-to-use and when-to-use-otherwise guidance rather than leaving routing 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?

'Queries the live Polymarket API and changes nothing' largely restates the existing readOnlyHint=true and openWorldHint=true annotations, so it adds little beyond structured data. The one genuinely additive detail is the ordering guarantee ('highest volume or liquidity first'), though that mostly mirrors the sort_by default. No pagination or rate-limit context.

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

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

The critical scoping information is front-loaded in sentence one, and the routing sentence is dense and useful. The middle sentence about the live API and no side effects is the weakest link, partly duplicating annotations, but it costs little.

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

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

With an output schema present and 100% schema description coverage on both parameters, the description only needs to cover purpose, scope, and sibling routing – all of which it does. Nothing required to call the tool correctly is missing.

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

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

Schema description coverage is 100% – both limit (clamped 1-100, default 20) and sort_by ('volume'/'liquidity', default 'volume') are fully documented in the schema. The description's re-statement of the volume/liquidity ordering is consistent but not additive, 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 ('List active Polymarket markets') plus the default ordering, which alone separates it from get_market, search_markets, and kalshi_markets. An agent can identify the tool's output shape (a ranked list of active markets) 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 routes to alternatives with the selecting condition: search_markets for a keyword, get_markets_by_tag for a category, kalshi_markets for the other exchange. This is a complete when-to-use-this-vs-that map, including the sibling that covers a different venue.

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 (readOnlyHint=true, destructiveHint=false, idempotentHint=true), so the bar is lower. The description still adds real value by disclosing that it reads the local database only and does not touch live market state, a distinction annotations do not 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 sentences, zero filler, with the core purpose front-loaded and the alternatives trailing. Every sentence earns its place.

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

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

An output schema exists, so return values need not be described, and annotations carry the safety profile. The description supplies the local-only read semantics and the sibling routing, leaving nothing an agent needs to call it correctly.

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

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

Schema coverage is 100%, so the schema fully documents the single 'account' parameter and its naming rules. The description adds nothing about parameters, which is the expected baseline 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?

States a specific verb and resource: 'List an account's pending limit orders.' It scopes the operation to local pending limit orders and names the two siblings an agent might confuse it with (check_orders, cancel_order), so it is distinguishable without opening a schema.

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

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

Explicitly routes to alternatives: check_orders for live-price evaluation and cancel_order for removal, giving the condition that selects each. It stops short of stating when to reach for list_orders itself beyond the implied 'you want to see pending orders', 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 declare openWorldHint=true and destructiveHint=false, so the agent already knows this touches live external data non-destructively. The description adds valuable context the annotations do not: execution happens on live market data, in temporary accounts, with equal starting balances. It stops short of noting runtime/cost, so not quite a 5.

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

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

Front-loaded with the core action in the first sentence, then sibling routing. Three sentences with no filler, though the line break mid-sentence makes it marginally less tight.

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

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

Output schema exists, so return values need no elaboration, yet the description still names them. For a live-execution tool the description covers scope, accounts used, and the alternative tools, leaving only performance/cost characteristics 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 coverage is 100%, so all five parameters are already documented, including the 'examples.'-only path restriction. The description adds only the implicit 'equal balances' framing, so the schema does the heavy lifting and 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?

Specific verb+resource: 'Run two strategies from scratch on equal balances and return stats, a PK card and the winner.' It clearly distinguishes this head-to-head live run from pk_card and backtest by naming both siblings.

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

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

Explicitly routes the agent: 'Use pk_card to compare accounts that already exist, or backtest to test one strategy on historical data.' The when-to-use and when-to-use-something-else conditions are both 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?

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), but the description adds real behavioral context beyond them: the compared metrics (ROI, Sharpe, win rate, trades, tier), the data source (local accounts), and the valuation rule for open positions at live midpoints with a documented failure fallback of 0. It does not mention any auth or rate considerations, but none are plausibly needed for this local read.

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 action and deliverable, with the alternatives packed into the final line. Every sentence carries information.

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

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

An output schema exists, so return format need not be explained; the description still covers inputs' nature, data sources, valuation edge case, and sibling routing. Nothing needed to invoke the tool correctly is missing.

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

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

Schema description coverage is 100% and both parameters (account_a, account_b) are fully documented with defaults, so the schema carries the burden. The description only implies that two accounts are supplied and adds no naming, format, or defaulting detail beyond it.

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

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

States a specific verb (compare) and resource (two existing accounts) plus the deliverable (a card naming the winner). It also names the two closest siblings, pk_battle and stats_card, so an agent can distinguish this tool without opening any schema.

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

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

Explicitly routes the agent: use pk_battle to run two strategies from scratch, or stats_card for a single account. Both the when-to-use and the when-to-use-something-else conditions are 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?

Annotations only say this is a non-read-only, non-idempotent, non-destructive open-world write. The description goes well beyond that: the order is stored locally, cash is reserved for buys, crossing orders fill immediately as taker, and resting orders fill only when check_orders runs. That lifecycle detail is exactly the behavioral context 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?

Three tight sentences: what it does, how it behaves (storage/reservation/fill mechanics), and the alternative. Behavioral nuance is front-loaded and there is no filler.

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

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

With an output schema present, return values need not be described, and the description covers the core lifecycle plus slippage/fill semantics. Minor omissions remain, such as what happens on invalid tick-grid prices or how a resting order is later cancelled, but nothing essential to correct invocation is missing.

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

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

Schema description coverage is 100%, so the schema already documents side, amount, limit_price, order_type, expires_at, account and slug_or_id. The description adds no parameter-level meaning beyond what is already in the structured fields, 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?

The description opens with a specific verb+resource ('Place a resting paper limit order') and a concrete domain (Polymarket / Kalshi markets with the 'kalshi:<TICKER>' convention). It explicitly distinguishes itself from the sibling market-order tools by stating that buy/sell are for immediate fills.

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 alternative path ('Use buy or sell for an immediate market-price fill'), which is exactly the routing decision an agent faces. It does not spell out when a limit order is preferable over a market order (price control vs. fill certainty), so the guidance is clear 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 readOnly, idempotent, non-destructive and openWorld, so the safety profile is covered. The description adds genuinely new context: it reads the local account and pulls live market data, which explains the openWorld behavior and warns that a network fetch is involved. It stops short of noting latency, staleness, or failure behavior when live pricing is unavailable.

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 of substance plus one routing sentence. The output shape is front-loaded before the disambiguation guidance, 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 not be re-explained; the description still summarizes them usefully. For a one-parameter read tool with full annotation and schema coverage, the definition gives the agent everything needed to select and invoke it.

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

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

Schema description coverage is 100% and the single 'account' parameter is fully documented there, including naming constraints and the default. The description's phrase 'an account's open positions' only implies the parameter's role, adding no syntax or format detail. Baseline 3 applies 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?

States a specific verb and resource (list an account's open positions) plus what data is attached (live prices, unrealized P&L). This distinguishes it from get_balance, history, and stats, which all touch the same account but return different things.

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

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

Explicitly names three alternative tools and the condition that selects each (cash totals, past trades, performance metrics). An agent can route correctly without opening any schema.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=true, so safety is largely covered. The description still adds real value: it enumerates the destroyed entities (trades, positions, orders, balance) and flags irreversibility plus the local-only scope. It stops short of stating what the post-reset state looks like (empty account vs. zero balance) or any permission requirements.

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, zero filler, with the destructive scope leading and the routing hints following. Every sentence carries distinct information.

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

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

For a one-parameter destructive tool with an output schema present, the description covers scope of deletion, irreversibility, and the natural follow-up tool. An agent has everything needed to invoke it correctly and safely.

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 'account' parameter is fully documented in the schema (100% coverage), including naming constraints and the 'default' fallback. The description adds nothing beyond that, 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 ('Delete an account's trades, positions and orders and reset its balance') with the exact scope of what is cleared. An agent can distinguish it from init_account, cancel_all_orders, and cancel_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?

Explicitly names two alternatives and the conditions that select them: init_account for setting a new starting balance afterwards, and cancel_all_orders when only pending orders should be removed. The 'Irreversible local change' note further frames when to reach for it.

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

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

Annotations cover the safety profile (readOnly=false, idempotent=true, destructive=false), but the description adds real behavioral context beyond them: payouts are written to the local account and resting orders on that market are cancelled. The enumerated failure modes further reduce ambiguity. Slightly short of 5 only because it doesn't say whether cancelling resting orders is reversible or how the payout is recorded.

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, no waste, front-loaded with the core action and payout rule before side effects and the alternative. Every sentence carries distinct information.

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

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

Output schema exists so return values needn't be described. Between the failure conditions, side effects, payout rule, and the resolve_all pointer, an agent has everything needed to decide and call correctly.

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

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

Schema description coverage is 100%, so both parameters (account, slug_or_id) are already fully documented in the schema. The description adds only the payout rate, nothing about the slug formats or account semantics. Baseline 3 for high coverage.

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 ('Settle an account's positions in one closed market') with the payout rule ($1 per winning share). This clearly distinguishes it from sibling resolve_all, which is scoped to all closed markets at once.

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

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

Explicitly routes the agent: use resolve_all to settle every closed market at once, and names the failure conditions (market not closed, ambiguous winner, no position held) that gate a valid call. Alternatives and prerequisites are both present.

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 the mutation profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false), so the bar is lower, but the description still adds real substance: $1-per-winning-share payout semantics, writes to the local account, open markets skipped, network-failed markets skipped with a retry-later note. It does not mention permission/auth requirements or any cap on the number of markets processed, so it falls short of 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 tight sentences with zero waste; the core behavior and payout rule are front-loaded, and the sibling routing is placed last where it belongs. Nothing extraneous.

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 explain return values, and the annotations cover the safety profile. What it does explain — payout semantics, skip conditions, retry guidance, and the resolve alternative — is exactly what an agent needs; only the absence of any note on scale or partial-failure reporting keeps 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% and there is only one parameter, so the schema already fully documents the paper-account naming rules. The description adds nothing about the account parameter beyond implying 'local account', which matches 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?

Specific verb+resource ('settle every open position whose market has closed') with scope made explicit ('every'), and it distinguishes itself from the sibling resolve by naming that sibling directly. An agent can tell it apart from resolve 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?

States the selection condition (markets that have closed), the exclusion (open markets are skipped), the failure mode (transient network error → retry later), and names the alternative tool ('Use resolve to settle a single market'). Routing between resolve_all and resolve is unambiguous.

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 fully covered. The description's 'queries the live Polymarket API and changes nothing' largely restates readOnly/non-destructive, though 'live' hints at real-time data freshness. No pagination, rate-limit, or error behavior is disclosed, so this adds only marginal value over 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 action and return fields, followed by the routing guidance. Every sentence carries information; 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-value explanation is not strictly required, yet the description usefully names the key fields. Inputs, scope, and alternatives are all covered, leaving only freshness/pagination details unstated, which is acceptable for this complexity level.

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 query (free-text examples) and limit (clamped 1-100, default 10) are documented in the schema itself. The description adds only 'by text', which does not extend parameter 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 verb (search), resource (Polymarket markets), and the input axis (free text), plus the fields returned. It also explicitly names what it is not (Kalshi, browse-by-volume, browse-by-tag), so an agent can select it 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 explicit routing: use kalshi_markets for Kalshi, list_markets to browse by volume, get_markets_by_tag to browse a category. All three alternatives and the conditions that select them are 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 already declare readOnly=false, destructive=false, idempotent=false, openWorld=true, so the mutation profile is covered. The description adds real value beyond that: it fills immediately against the live order book, records the trade and fee, and is simulated (no real order). It does not discuss fill failure behavior for the default 'fok' order type, which would be the next useful detail.

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 in the first sentence, followed by behavioral detail and then sibling alternatives. Two short paragraphs with essentially no waste, though the parenthetical '(simulated; no real order)' partially duplicates the paper-cash framing of the first line.

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 the mutation semantics, execution model, and sibling routing. Nothing an agent needs to invoke this correctly is missing.

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

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

Schema description coverage is 100%, so all five parameters, including the 'fok'/'fak' order_type and the 'kalshi:<TICKER>' slug convention, are already documented in the schema. The description repeats the Kalshi slug example but adds no syntax or constraint beyond it, so this is 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 (sell) and resource (held shares of a Polymarket/Kalshi outcome) for paper cash, and it is trivially distinguishable from the sibling 'buy', 'place_limit_order', and 'resolve'. An agent knows exactly what operation this performs 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 routes away from the two plausible alternatives: use place_limit_order with side 'sell' to rest an exit at your price, or resolve to collect payout on a closed market. This gives both the alternative name and the condition selecting it, leaving nothing to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, but the description adds real context beyond them: 'Reads the local account and posts nothing' and the valuation rule 'Open positions are valued at live midpoints (0 if a lookup fails).' That failure-fallback behavior is not derivable from 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-loaded with the core action, then side-effect and valuation facts, then routing. The sentence fragments ('use stats_card for...') are terse and earn their place, though the line breaks make the structure slightly ragged.

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 formatting needn't be explained. Purpose, side-effect profile, valuation behavior and sibling routing are all covered; the only small gap is not naming the default 'performance' template in the prose.

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, platform and template with defaults and allowed values. The description adds only partial semantics (milestone/daily templates) and omits the default 'performance' template, so it doesn't meaningfully exceed 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?

Specific verb+resource: 'Generate post-ready text for a platform and template from one account's stats.' It explicitly distinguishes itself from the sibling tools stats_card and stats, so an agent can route correctly without opening any schema.

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

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

Names the alternatives and the condition that selects each: 'use stats_card for a plain stats card or stats for raw numbers,' and scopes this tool to templated output (milestone, daily). Routing is unambiguous.

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/idempotent/destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds non-obvious context: it reads the local account but 'prices positions live', which hints at network I/O and possible latency not conveyed by the annotations. It stops short of stating latency or rate-limit behavior, 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 short sentences, front-loaded with the metric list and the routing guidance. 'Changes nothing' is mildly redundant with readOnlyHint, which keeps it from a 5, but nothing else is wasted.

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

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

For a one-parameter read tool with an output schema, the description is complete: it names the metrics, the account scope, the live-pricing behavior, and the two alternative tools. Nothing needed to invoke it correctly is missing.

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

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

Schema description coverage is 100% and the single 'account' parameter is fully documented in the schema (naming rules, default). The phrase 'one account's' only implies the parameter, adding no syntax or naming detail 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 ('Get') plus the exact resource ('one account's raw performance numbers') and enumerates the metrics returned (win rate, ROI, profit, Sharpe, max drawdown). It also names the two sibling tools it is not, so an agent can distinguish it without opening schemas.

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

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

Explicitly routes the agent: 'Use this for analysis, stats_card for a postable text card, or leaderboard_entry for the ranking record.' The when-to-use and the alternatives with their distinguishing conditions are all present.

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 safety is covered. The description still adds real behavior beyond that: 'posts nothing' confirms the local, non-mutating scope, and the live-midpoint valuation with a 0 fallback on lookup failure is a genuine operational detail. It stops short of describing output shape, but the output schema covers that.

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

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

Front-loaded with the deliverable, then behavior, then routing alternatives — a sensible order and no filler. The 'Reads the local account' fragment is mildly redundant with readOnlyHint, which is the only slack in an otherwise tight definition.

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

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

An output schema exists, so return formatting need not be explained, and the schema fully documents both parameters. The description supplies purpose, mutation behavior, valuation semantics and sibling routing — everything an agent needs to select and call it.

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

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

Schema description coverage is 100%, so both 'format' (with its enum-like choices) and 'account' are fully documented in the schema, and the description adds no param-level meaning. A baseline 3 is appropriate 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?

States a specific verb and resource ('Render one account's ROI, Sharpe, win rate and P&L as a postable text card') and immediately names the scope ('one account'). It is clearly distinguishable from stats, pk_card and share_content, which are 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?

The final sentence routes the agent explicitly: 'Use stats for raw numbers, share_content for platform and template choices, or pk_card to compare two accounts.' This tells the agent which sibling to pick and under what condition, leaving nothing to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so 'Reads live data and changes nothing' largely restates structured data. The useful addition is the bulk semantics (multiple markets in one call), but it omits anything about freshness, latency, or partial-failure reporting beyond what the schema already says about skipped markets.

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 short sentences, front-loaded with what it retrieves before the routing guidance. Every clause 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?

Output schema exists, so return-format explanation is unnecessary. Scope, safety, batch behavior, and sibling alternatives are all covered, which is everything an agent needs to call this correctly.

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

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

Schema description coverage is 100% with clear examples for both parameters, so the schema already carries the syntax burden. The description's 'several markets and outcomes' merely echoes those fields without adding format or edge-case detail, so 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 (get), resource (live midpoint prices), and scope (several markets and outcomes in one call), which immediately differentiates it from the single-market and position-oriented siblings. An agent can identify the tool without opening the schema.

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

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

Explicitly routes the agent: get_order_book for depth on one market, portfolio for prices of held positions. It names the alternatives and the condition that selects each, leaving nothing to inference.

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