TradeHub

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

Annotations already declare destructiveHint=true, idempotentHint=true and openWorldHint=true, and the description still contributes real context: the hard rule that a held position's stop-loss cannot be cancelled (and the workaround), why that rule exists, and that cancellation works while trading is halted. These are non-obvious constraints an agent could not infer from the 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?

Purpose and prohibitions are front-loaded, and nearly every clause carries operational weight (the stop-loss exclusion, the halted-trading note). The 'Inputs:' enumeration is the one mildly redundant passage given full schema coverage, keeping it just short of a 5.

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

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

For a destructive mutation tool, the description covers the safety boundary, the exclusion case with its alternative, a surprising availability trait (works while halted), and the follow-up call. With an output schema present, return values correctly need not be described.

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

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

Schema coverage is 100%, so all three parameters — including venue defaults and symbol format — are already documented in the schema. The description's 'Inputs: order_id (from get_my_open_orders), symbol, venue' largely restates that, adding no format or constraint detail 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?

Opens with a specific verb+resource ('Cancel one resting order on an exchange') and immediately scopes it to unfilled limit orders and take-profits. It explicitly names the sibling it is not for (close_perp_position_reduce_only), so the agent can distinguish it without opening either schema.

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

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

Gives explicit when-to-use ('withdraw an unfilled limit order or a take-profit'), an explicit when-not ('Not for closing positions'), and the required alternative. It also closes the loop with a next step ('Next: get_my_open_orders'), so both selection and follow-up are 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 establish that this is a non-read-only, non-destructive, idempotent operation. The description adds useful behavioral context beyond that: the alert is removed so it 'never fires' and 'An app can delete only the alerts it created,' which is an important authorization boundary.

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

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

The description is compact and front-loaded with the effect, followed by usage, exclusion, input source, permission constraint, and next step. Every sentence carries actionable 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 mutation tool with an output schema and annotations, the description supplies the key missing context: ownership restrictions, capacity limit, input origin, sibling exclusion, and follow-up action. Nothing essential is omitted.

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

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

Schema description coverage is 100%, so the single alert_id parameter is already documented. The description adds only that alert_id comes from get_my_price_alerts, while the schema also mentions set_price_alert; appropriate 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?

The description states a specific verb and resource: 'Remove a waiting price alert so it never fires.' It also explicitly distinguishes the tool from cancel_open_order, so the agent can route correctly 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?

It gives clear when-to-use guidance ('user no longer wants it or to make room'), names the exclusion ('Not for orders (use cancel_open_order)'), states a capacity constraint ('at most 20 wait'), and points to the next step ('get_my_price_alerts').

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 destructive/non-idempotent annotations by explaining the reduce-only guarantee (cannot open or flip a position), the third-party permission constraint (only positions the app opened), and that it works while trading is halted. These are exactly the constraints an agent needs before invoking a destructive tool.

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

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

Front-loaded with the core action and guarantee, then usage, exclusions, inputs, and next step in a tight sequence. The 'Inputs:' recap is largely redundant given full schema coverage and slightly dilutes an otherwise efficient paragraph.

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 destructive mutation tool with annotations and an output schema, so return values need no explanation; the description still covers semantics, permissions, exclusion, and follow-up. Nothing an agent needs to call it safely is missing.

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

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

Schema coverage is 100%, so all three parameters are already documented, including the venue fallback chain and the 1-100 close_pct range. The description's 'Inputs:' line only restates those names and defaults rather than adding new meaning, 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 precise verb and resource ('Close all or part of a perpetual futures position with a reduce-only market order') and immediately distinguishes it from cancel_open_order. An agent can identify the operation and its scope without opening the schema.

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

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

Gives explicit when-to-use cases (take profit, cut loss, reduce exposure, undo a filled order) and an explicit when-not-to-use with the named alternative ('Not for cancelling resting orders (use cancel_open_order)'). It also states the follow-up step ('Next: get_my_open_positions').

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

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

Beyond the read-only annotations, the description discloses key behavioral and semantic traits: rates are fractions, positive means longs pay shorts, results are sorted by annualised rate highest first, each reading includes its age, and rates change every interval. It also states that TradeHub takes no rebates, which clarifies neutrality of the comparison.

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

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

The description is front-loaded with the core result and scope, then moves efficiently to usage, caveats, input, and next tools. Most sentences earn their place, though the 'TradeHub takes no rebates' clause is slightly promotional rather than strictly operational.

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 comparison tool with an output schema, the description supplies everything an agent needs: data scope, sorting, sign convention, reading age, when to use it, and what to call next. The annotations already cover safety and idempotency, so the remaining description is complete and appropriately focused.

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

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

Schema coverage is 100% and the schema already defines `symbol` as a base coin such as BTC. The description repeats this with 'Input: symbol (base coin)' but adds no further syntax, format, or edge-case guidance beyond what the schema 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?

The description states a specific verb and resource: current perpetual futures funding rates for one coin across every supported exchange, per interval and annualised. It clearly describes the scope but does not explicitly distinguish itself from the sibling `compare_perp_quotes_across_venues`, so it falls short of the strongest possible sibling differentiation.

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

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

It explicitly says when to use it: choosing where to hold a long or short, or checking a funding spread. It also names useful next steps (`get_perp_contract_rules`, `size_position_by_risk`) and cautions that it is not a forecast. It stops short of naming a specific alternative tool or stating when not to use it.

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

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

Goes well beyond the readOnly/idempotent annotations by disclosing the ranking formula (price + taker fee + execution cost), that hold_hours folds in funding at today's rate plus exit fee, that rebates are excluded, and what 'tradeable now' means (connected, allowed, enough margin). It stops short of any note on rate limits, failure modes, or how stale/conditional a quote might be.

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 verb and payoff, then usage modes, then exclusions and next steps. Highly compressed to the point of near-telegraphic phrasing ('cheapest you can trade on now'), which is efficient but risks ambiguity for a weaker reader.

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 6-parameter read-only comparison tool with full schema coverage and an output schema, the description covers selection criteria, conditional parameter interactions, exclusions, and follow-up actions. Nothing an agent needs in order to pick and call this tool is missing.

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

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

Schema coverage is 100% and each parameter already carries a substantive description, so the schema does the heavy lifting. The description adds real value only at the combination level ('with side (and size_base or notional_usd)', 'hold_hours adds funding, exit fee'), which slightly exceeds the baseline but does not redefine any individual parameter.

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

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

Names a specific verb and resource ('choose where to trade one perpetual futures coin') and immediately enumerates the exact return dimensions (bid, ask, spread, fee, 7-day execution) per exchange. It also carves out the sibling boundary explicitly: 'Not for one venue's depth (use get_order_book).'

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 usage modes (side + size_base/notional_usd, hold_hours) and explains what each adds. It also defines the two summary outputs (cheapest_venue vs best_venue) and instructs the agent to report both when they differ, then points to the next call (preview_perp_order with best_venue or venue 'best').

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

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

Goes well beyond the annotations: it discloses the fresh-price re-check, that the stop-loss is placed at the exchange, that approval levels can block execution, and that wait_seconds (0-30) holds the call open. It also states the key irreversible consequence ('a fill cannot be undone') and the idempotency behavior (repeat returns the first result) in plain language.

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

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

Front-loaded with the core action and the usage gate, then parameters, then the safety consequence and next step — every clause is load-bearing. The telegraphic phrasing ('Next: get_order_request_status(request_id) while pending') is dense but not padded.

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 covers return values, and the description covers everything else an agent needs: prerequisite preview, approval-wait semantics, idempotency, irreversibility, and the correct follow-up call. Nothing essential is left to inference for a destructive financial mutation.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds real context by tying preview_id to its source (preview_perp_order), framing client_order_id as a per-agent idempotency key, and explaining that wait_seconds only matters in the human-approval branch. It does not restate the 30-second expiry of preview_id, which the schema carries.

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 ('execute a preview from preview_perp_order') and immediately distinguishes it from the sibling that creates previews and from cancel/close tools. An agent knows exactly which tool this is 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?

Explicit gating: 'Use only after a successful preview' and 'Not for new or changed orders (preview again)' names the exclusion and the alternative. It also names the follow-up tool (get_order_request_status) for the pending case and close_perp_position_reduce_only as the remedy path.

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, so the safety profile is free. The description still adds real value by disclosing currency normalization (USDC/USDT treated as USD), the inclusion of sandbox accounts, and the aggregate-total behavior. It stops short of describing freshness/caching or latency, which would matter for a live-account 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?

Front-loaded with what is returned, then routing, then a 'Next:' handoff. Every sentence carries distinct information — no restatement of the title and no filler — despite the telegraphic style.

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 shape needn't be explained; description covers the remaining essentials for a read-only, zero-arg, open-world call: venue coverage, unit normalization, aggregation, and the follow-up tool. 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?

Zero parameters, so baseline is 4; the description confirms 'No inputs' and clarifies that venue scope is fixed to everything the user connected rather than selectable. No further parameter semantics are possible.

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

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

Names a specific resource (equity, free margin, used margin, open P/L, plus total) and enumerates the exact venues covered (Hyperliquid, Bybit, Binance, OKX, sandbox). It explicitly contrasts with get_my_open_positions, so an agent can separate it from the nearest sibling 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?

Gives positive triggers ('report balances', 'compare free margin across exchanges'), a negative trigger ('Not for positions – use get_my_open_positions'), and an explicit 'not needed before opening' note pointing at size_position_by_risk. That is when-to-use, when-not-to-use, and named alternatives in three compact sentences.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds genuinely non-schema context: the result is scoped to this agent only, while a human sees all agents aggregated, and refusals are surfaced with corrective guidance. It stops short of noting pagination or output shape, which is acceptable given an output schema exists.

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

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

Front-loaded with what the tool returns before moving to usage, exclusions, input and next step — a sensible order for an agent scanning for relevance. Slightly dense as a single run-on block, and "Input: days (1-90)" duplicates the schema, but no sentence is wasted.

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

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

For a single-parameter read tool with an output schema, the description covers scope, trigger, exclusion, sibling alternative and follow-up call. Return values need not be explained because the output schema carries them.

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 `days` property already carries a description plus 1-90 bounds and a default of 30. The description's "Input: days (1-90)" merely restates the schema, adding no syntax, default behavior, or window-selection guidance, 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 resource and enumerates exactly what it returns: trades opened/closed, wins, realised P&L in USD, and most common refusals, over a look-back window. It explicitly distinguishes itself from the nearest sibling (get_my_trade_history) so an agent can route 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 concrete trigger conditions ("at the start of a session or after a run of rejections"), an explicit exclusion ("Not for the trades themselves (use get_my_trade_history)"), and a follow-on step ("Next: get_my_trading_permissions"). Nothing about when to select this tool 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?

The annotations already cover the read-only and non-destructive profile, but the description adds substantial behavioral context: TradeHub remembers the last position, new sessions return only new events, and waiting is capped at 30 seconds. It also describes the event categories and warning scenarios, which goes well beyond the annotations.

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

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

The description is front-loaded with the core purpose and event types, then moves into usage and alternatives. It is clear and useful, though the event list and the short 'Inputs' recap make it slightly longer than strictly necessary given the complete schema.

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

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

For a read-only event-feed tool with a complete schema, annotations, and an output schema, the description supplies everything an agent needs to select and invoke it correctly. It covers what it returns at a high level, when to use it, when not to use it, and how the cursor and wait behavior work.

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 input schema already documents after, limit, types, and wait_seconds thoroughly. The description briefly mentions the inputs and explains that after keeps your own place, but it largely repeats what the schema already says rather than adding materially new parameter semantics.

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

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

The description clearly states a specific resource and scope: account events that occurred since the last check, including the concrete event categories it returns. It explicitly distinguishes this from sibling tools by saying it is not for current state and naming get_my_open_positions as the alternative.

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

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

It gives explicit timing guidance: use at the start of a session, or use wait_seconds to wait for the next event. It also states when not to use it and names the better alternative for current-state queries, leaving little ambiguity.

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

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

Annotations already cover read-only/idempotent safety, but the description adds domain behavior annotations cannot express: that trigger-based orders are folded into the result set under specific type and order_id conventions, and that sizes are denominated in the base coin while prices are in USD. Those are exactly the facts an agent needs to interpret results correctly.

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

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

Four short sentences, each carrying distinct information: scope, inclusions, usage/exclusion, inputs/units, and the follow-up call. Scope and routing information are front-loaded with no filler.

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

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

An output schema exists, so return values needn't be described. Given that, the description covers everything an agent needs for a read-only, zero-required-parameter query: what is included, how to filter, what units to expect, when not to use it, and what to call next.

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

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

Schema coverage is 100% and both properties already carry descriptions ('Only this venue', 'Only this base coin'), so the baseline is 3. The description adds that both filters are optional and reinforces that symbol is a base-coin filter, but contributes no format, casing, or combining-behavior detail beyond that.

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

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

The description names a specific resource (resting orders on the user's exchange accounts) and immediately disambiguates the non-obvious inclusions: protective stops/takes (is_trigger = true) and TradeHub trigger entries (type TRIGGER_ENTRY, order_id req_…). An agent can distinguish this from get_my_open_positions and get_my_trade_history 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?

It gives two concrete use cases ('find an order_id to cancel', 'confirm a stop is in place'), an explicit exclusion with the correct alternative ('Not for filled trades (use get_my_trade_history)'), and a next-step pointer to cancel_open_order. When-to-use, when-not, and the alternative are all 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?

The annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds real context beyond them: cross-account coverage, that there are no inputs, and that sizes are in the base coin while prices are in USD — unit conventions the annotations do not convey. It does not mention authentication or latency, which is a minor gap for a read-only tool.

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

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

It is front-loaded with the scope and returned fields, then usage, exclusions, and follow-ups — a logical order with no filler. The only redundancy is that get_my_open_orders appears twice, once as the excluded alternative and again in the 'Next:' list, which slightly muddies the routing signal.

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 still summarizes the payload shape. With no parameters, a complete safety annotation set, and covered units, scope, exclusions, and follow-up actions, an agent has everything needed to select and call this tool correctly.

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

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

There are zero parameters, so the baseline is 4 and nothing needs compensating for. The description confirms 'No inputs' explicitly, removing any doubt that the call takes arguments and reinforcing the unit conventions used in the response.

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

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

The description names a specific resource (open perpetual futures positions), its scope (every connected exchange account), and enumerates the fields returned: side, size, entry, mark, P&L, leverage, liquidation price and distance, and attached trade plan. It explicitly separates itself from resting orders and stops, which are handled by get_my_open_orders. An agent can distinguish it from every sibling without reading 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?

It gives explicit when-to-use cues ('Use first in a new session, and before closing, adjusting a stop or reporting exposure'), an explicit when-not ('Not for resting orders or stops (use get_my_open_orders)'), and names the recommended follow-up tools. Both the alternative and the condition that selects it are stated, so 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 readOnly/idempotent/non-destructive, but the description adds genuinely new behavioral context: per-app visibility scoping (an app sees only alerts it created) and a one-day retention window for fired alerts. It stops short of auth or volume details, but the critical access-scoping trait is disclosed.

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

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

Four short fragments, each carrying distinct information: return contents, visibility scope, use cases, exclusion, and next step. Nothing is repeated from the title or annotations, and the most important content leads.

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 covers return shape, so the description's job is routing and scoping, both of which it handles fully. An agent has everything needed to decide to call it and interpret the result.

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

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

Zero parameters, so the baseline is 4; the description also states 'No inputs' explicitly, removing any doubt. There is no further parameter meaning to convey.

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

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

States a specific resource (price alerts) and precise scope: pending alerts plus those that fired in the last day, including the triggering price. It explicitly separates itself from get_my_open_orders, so no sibling ambiguity remains.

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

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

Gives concrete when-to-use triggers (before adding an alert, to find an alert_id to delete), an explicit when-not-to-use with the alternative named (get_my_open_orders for orders waiting on price), and even a next-step pointer to cancel_price_alert.

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, so the bar is low, and the description still adds real context: no inputs, values reported as fractions of equity and USD, real money and sandbox counted separately, and pending limit increases included in the result. It stops short of describing how stale the usage figures are or when limits reset, which would be the remaining behavioral 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?

The covered limit types are front-loaded in the first clause, followed by units, scope, exclusion and next step as compact fragments. No sentence is redundant 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?

An output schema exists so return values need not be explained in prose. Between the enumerated limit types, usage fractions, units, sandbox separation, pending increases, the permission-tool exclusion and the next-step pointer, an agent has everything needed to call and interpret this 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?

Zero parameters, so the baseline is 4. The description confirms 'No inputs', which is consistent with the empty schema and prevents an agent from inventing arguments.

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

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

The description names a specific resource (global risk limits) and enumerates exactly what it covers: per-trade risk, daily/weekly/monthly loss, drawdown, leverage, open positions, with usage fractions per limit plus pending limit increases. It also explicitly separates itself from get_my_trading_permissions, so an agent can distinguish it from siblings 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?

It gives concrete trigger conditions ('when a trade was rejected by a user-level limit or before planning several trades'), an explicit exclusion with the correct alternative ('Not for this agent's own permissions (use get_my_trading_permissions)'), and a follow-up step ('Next: size_position_by_risk').

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

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

Beyond the annotations (which already declare readOnly/idempotent), it discloses a non-obvious access-scoping rule: third-party apps see only trades they opened, while the user's own keys and Telegram see all. It also explains pagination behaviour ('pass next_before back until it is null') and unit conventions (sizes in base coin, money in USD), which are not derivable from the schema.

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

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

Purpose, visibility scope, usage/exclusion, input contract and next step all appear in a short, front-loaded block with no filler. Every clause carries information an agent needs at call time.

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

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

An output schema exists, so return values needn't be detailed, and the description nonetheless names the key fields. Pagination and unit conventions are covered, leaving only minor gaps such as ordering guarantees or default-range behaviour if closed_since is omitted.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real value: it restates the limit bounds and, more importantly, explains that `before` is a cursor fed from the previous response's next_before and must be followed until null. Units for returned sizes/prices are also clarified, though per-parameter edge cases are left to the schema.

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

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

States a specific verb and resource ('Recent trades opened through TradeHub') and enumerates the returned fields (entry, stop, take-profit, leverage, realised PnL). It explicitly contrasts itself with the sibling get_my_open_positions, so an agent can distinguish 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?

'Use for reviews and reports. Not for live positions (use get_my_open_positions)' gives both the when and the when-not with a named alternative. It also closes the loop with 'Next: get_my_open_positions', routing the agent onward for a natural follow-up.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description goes well beyond them: it defines the three autonomy levels (read, propose, preauth), states that limits are fractions of equity or USD, and discloses a key authorization constraint — only a person can widen limits, on the Web, with a 24-hour delay. That is exactly the governance context an agent needs before deciding whether to attempt a trade.

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 definition, then usage trigger, exclusion, input expectation, limit semantics, governance constraint, and next steps. Despite the density, every clause carries distinct information and nothing is repeated from the annotations or schema.

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

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

An output schema exists, so return values need not be spelled out — yet the description still signals the shape of the response. Combined with the mutation-free annotations and the zero-parameter schema, an agent has everything needed to call this correctly on the first turn of a session.

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

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

The tool takes no inputs, and the description confirms this with "No inputs." That is the correct baseline for a zero-parameter tool; there are no parameter semantics beyond that to add.

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 and then enumerates exactly what is returned: autonomy level, allowed venues/symbols/actions, per-trade and daily limits, today's usage, connected venues, and halt status. It explicitly distinguishes itself from get_my_account_balances, so an agent can separate it from the closest sibling 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?

"Use first in every session and after any rejection that mentions your mandate" gives an explicit trigger condition, and "Not for account balances (use get_my_account_balances)" names the alternative and the exclusion. It also chains forward to size_position_by_risk and get_my_open_positions, 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 read-only/idempotent semantics, but the description adds ordering (best first), return tuple shape, unit conventions (USD per coin, sizes in base coin), and an auth-related constraint (venue without an account: hyperliquid only). These are exactly the traits an agent needs that annotations can't express.

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

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

Three tight sentences: purpose first, exclusion second, inputs/units/next-step last. 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?

Output schema exists, so return-value documentation is optional; the description still covers ordering and units, plus the auth constraint and sibling routing. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description goes further by disclosing the unauthenticated venue restriction and clarifying what price and size mean, though depth's 1-50 range merely repeats the schema bounds.

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 (order book levels for one perp contract on one exchange) and immediately differentiates from the closest sibling compare_perp_quotes_across_venues. An agent can distinguish it without opening the schema.

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

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

Gives an explicit use case ('judge liquidity before a large market order'), an explicit exclusion with a named alternative ('Not for the best price across exchanges'), and a next-step routing ('Next: preview_perp_order').

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior, so the bar is lower. The description adds useful lifecycle context: the full set of terminal states and the fact that fill price and stop order id appear once executed. It does not cover error handling for unknown request ids, but the state enumeration is meaningful 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?

Front-loads the core meaning, then packs statuses, exclusion, input, and next step into compact clauses with no filler. Every sentence contributes 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?

An output schema exists, so return values need not be explained in depth, and the description still names the key returned fields and all states. Combined with explicit sibling routing and a follow-up action, nothing essential is missing for correct invocation.

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

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

Schema description coverage is 100%, so the single request_id parameter is already fully documented, including its origin in execute_previewed_order. The description's 'Input: request_id' restates the schema rather than adding format or lookup guidance; 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 ('current state of an order request made with execute_previewed_order') and enumerates the possible states plus execution details. It explicitly distinguishes itself from the sibling get_my_open_orders, so an agent can route correctly without opening either schema.

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

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

Gives the exact scenario ('follow an order that was waiting for a person's approval'), an explicit exclusion ('Not for listing orders (use get_my_open_orders)'), and a next step ('get_my_open_positions once executed'). Both the alternative and the follow-up path 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/idempotent/non-destructive, so the description focuses on what annotations cannot express: the account constraint ('without an account: hyperliquid only'), the venue-resolution default, and the units conventions for prices, sizes and rates. That is real added context, though it does not mention rate limits or caching freshness of the funding figures.

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

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

Front-loads purpose, then usage, then exclusions/alternatives, then input conventions, then the next step, in a tight set of sentences. The field enumeration is dense but each item carries information an agent needs to interpret the response.

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

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

For a two-parameter read tool with an output schema and full annotation coverage, everything an agent needs is present: scope, exclusions, auth/venue constraint, unit conventions and a follow-up tool. Return-value formatting is correctly left to the output schema.

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

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

Schema coverage is 100% and the schema already spells out the venue resolution order, so the baseline is 3. The description goes further by fixing the semantics of the values involved ('symbol (base coin, e.g. BTC)', 'prices in USD per coin, sizes in the base coin, rates as fractions'), which prevents unit mistakes even though it partly describes output rather than inputs.

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

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

States a specific verb and resource: 'Rules and current funding for one perpetual futures contract on one exchange', then enumerates the exact fields returned (mark price, size step, min size, price tick, max leverage, funding rate). It explicitly distinguishes itself from the comparison siblings by name, so an agent can pick it 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?

Gives an explicit when ('when a limit price or leverage must fit the venue'), an explicit when-not ('not needed for market orders (sizing and preview round for you)'), and names two alternatives for the adjacent comparison task. It also adds a 'Next:' pointer to size_position_by_risk, which routes the follow-up call.

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, so the description is free to add the non-obvious context it does: data provenance ('Hyperliquid's public market, the same prices the sandbox trades at'), the 500-row ceiling, oldest-first ordering, and units (USD per coin, volume in base coin, times UTC). Those are behavioral facts an agent could not infer from structured fields and they materially affect interpretation of results.

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 payload shape, then usage, then exclusions, then inputs — a sensible order with no filler. The one redundant element is the trailing 'Inputs:' sentence, which repeats what the schema already declares verbatim.

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 still covers provenance, units, ordering, and caps; annotations cover the safety profile and the schema covers parameter details. 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 description coverage is 100%, so the schema already documents all three parameters including the enum and defaults. The description's 'Inputs:' line largely restates the schema defaults (symbol, interval default 1h, limit default 100) without adding format or constraint nuance, so the baseline of 3 is appropriate.

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

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

States a specific verb+resource ('Price history for one coin as candles') and enumerates exactly what each candle contains (open, high, low, close, volume), the supported intervals, the 500-candle cap, and ordering. It also explicitly differentiates itself from two named siblings, so an agent can place it precisely 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?

Gives concrete use cases ('look back at price action, find recent highs and lows for a stop, or judge the trend') plus explicit exclusions routed to alternatives: live best price goes to compare_perp_quotes_across_venues, ready-made indicators to get_technical_indicators_15m. It even names the natural next step, size_position_by_risk.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds genuinely non-structured context: the numeric units (USD per coin), the presence of a funding rate alongside the candle indicators, the ATR-stop-placement affordance, and the disclaimer that output is not a recommendation. It does not discuss candle staleness beyond 'not live quotes', which keeps it 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?

Front-loaded with the indicator inventory, then the caveats and routing in short clauses — dense but scannable. The liability disclaimer is arguably padding, though it does affect how an agent should present results.

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 one required parameter, an output schema, and full annotation coverage, the description only needs to convey scope, units, exclusions, and the follow-up step — all present. Minor gap: nothing says how recent the 15-minute bar is or whether indicators are computed on the latest closed candle.

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 symbol property is already documented as 'Base coin, e.g. BTC', so 'Input: symbol (base coin)' largely restates the schema. The added unit note ('Prices in USD per coin') describes output values rather than parameter semantics, so this stays at the baseline.

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

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

Names the exact indicator set (RSI, MACD, Bollinger %B, ATR, EMA trend, volume rank), the candle interval, the venue (Hyperliquid), the scope (one coin), and the extra funding-rate field. It also explicitly separates itself from the live-quote sibling, so an agent can pick it 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?

Gives an explicit exclusion with the alternative ('Not for live quotes (use compare_perp_quotes_across_venues)') and a downstream next step ('Next: size_position_by_risk'). It also states the interpretive frame ('inputs to your own decision; not a trading recommendation') and a concrete use case for ATR in stop placement.

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 read-only/idempotent/non-destructive safety profile, and the description adds the key behavioral distinction that the account-scoped fields only appear 'with an account', i.e. an auth prerequisite. It also frames the result as a point-in-time snapshot ('right now') and supplies remediation guidance. It stops short of disclosing freshness guarantees, caching, or cost/latency of the call itself.

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 what, then the when, then the exclusion, then the next step — three tight sentences with zero filler. Every clause carries distinct information; the 'Not for prices' pointer and 'Next:' line both earn their 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-value detail is unnecessary, and with no parameters the input side is trivially complete. What remains — when to call it, what scope of data appears under each auth level, and what to do afterwards — is all present.

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

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

The tool takes zero parameters and the description says so explicitly ('No inputs'), which is the correct baseline handling for a no-arg tool. There is nothing further to disambiguate beyond the schema.

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

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

States a specific resource (exchange reachability) plus exactly what it returns: the public price feed per exchange and, when authenticated, per-account latency, last error, and rate-limit headroom. It also explicitly separates itself from compare_perp_quotes_across_venues, so an agent can pick it 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 both a trigger ('after a VENUE_UNAVAILABLE error') and a preventive use ('before trading on an exchange that misbehaved'), plus an explicit exclusion routing price lookups to compare_perp_quotes_across_venues. It even names the follow-up action, 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 only say readOnlyHint=true and destructiveHint=false; the description adds substantive behavior beyond that — the checks performed, that a rejection names the failing check and may return suggested_args, and that preview_id expires in 30 seconds. That expiry constraint is the kind of operational detail an agent cannot infer from the schema and is essential for sequencing the two-step preview/execute flow.

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 usage, then parameters, then returns and next step — a clean ordering with no filler sentences. The heavy parenthetical nesting ('(optional take-profit)', '(trigger_price)', '(USD)') makes it dense, but every clause 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 14-parameter, two-step preview tool the description covers what is checked, what comes back, the 30 s validity window, failure shape, and the follow-up call. An output schema exists, yet the return summary is well-scoped rather than exhaustive, and 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 coverage is already 93%, so most parameter meaning is carried by the schema. The description still adds cross-tool provenance ('size_base: from size_position_by_risk') and the stop-loss/stop-pct either-or plus the trigger_price waiting semantics, though parts of that restate schema text. Slight redundancy keeps it below 5.

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 ('Check a perpetual futures order ... against permissions, limits and the price band') with the crucial qualifier that nothing is sent. It explicitly excludes the closing case and names the sibling to use instead, so an agent can distinguish it from close_perp_position_reduce_only 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?

'Use before every new position, also one that waits for a price (trigger_price)' gives a clear invocation policy, and 'Not for closing (use close_perp_position_reduce_only)' names the alternative and the condition that selects it. The next step, execute_previewed_order(preview_id), is spelled out.

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

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

Beyond the annotations, it discloses the 5-rule cap, that each rule fires exactly once, that a new plan overwrites the old and an empty array removes it, that notify routes to Telegram/events/webhooks, and that close is reduce-only with a percentage. This is the kind of consequence-level detail an agent needs before committing a position to a deferred automation.

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 examples, and the operative constraints (when to use, what it is not, replacement semantics) come before the trailing navigation hint. It is dense with quoted example strings that partially restate the same semantics as the rule fields, which costs a little economy but not clarity.

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. Combined with full schema coverage and annotations, the description covers timing, alternatives, side effects, replacement/removal, and the next call an agent should make.

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?

At 100% schema coverage the baseline is 3, and the description still adds meaning: it clarifies that price triggers use the mark, that funding is a yearly fraction (0.5 = 50%), and illustrates partial exit with "close half below 94000". It does not add anything about the venue or thesis parameters beyond the schema, so it stops short of a 5.

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

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

States a concrete verb and resource: have the system act on a held position at a later time while no agent is connected, and backs it with three quoted example rules. It also explicitly rules out the nearest sibling concept ("Not a stop-loss"), so an agent can separate it from set_stop_loss_rule and set_price_alert at a glance.

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 timing ("Use right after entry, not your own timers"), an exclusion ("Not a stop-loss"), replacement semantics ("A new plan replaces the old; rules=[] removes it"), and a next step ("Next: get_my_open_positions"). Nothing about when to select this tool 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 declare a non-read-only, non-idempotent, non-destructive write; the description explains why — it fires exactly once and is then done, which accounts for the non-idempotent hint. It also discloses a concrete quota ('At most 20 wait at once') and the delivery channels (Telegram, event stream, webhooks get a price.alert event), which annotations cannot express.

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

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

Front-loaded with the action and its one-shot semantics, then the when-to-use, then the non-order exclusion, then inputs and the cap. Dense with parentheticals, but every clause carries information; only the 'Inputs:' sentence is arguably redundant with the schema.

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

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

Covers the lifecycle (single fire), the delivery mechanism, the concurrency cap, the non-trading guarantee, and the follow-up tool. An output schema exists, so return values need not be explained, and nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so the schema already documents price, symbol, venue and direction including defaults and enum values. The description only restates the parameter list and the direction default, adding no format or edge-case detail beyond the structured fields. 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: notify when a coin's price reaches a level, firing one message then completing. It distinguishes itself from the sibling tools cancel_price_alert, get_my_price_alerts and preview_perp_order by name and by scope, so an agent can route correctly 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?

Gives explicit triggering conditions ('when the user asks to be told or woken at a price, instead of polling prices'), an explicit exclusion ('Not an order: nothing is traded'), and a named alternative with the parameter to use instead (preview_perp_order with trigger_price). It even names the follow-up 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?

Goes well beyond annotations by disclosing the polling cadence (~every 5 seconds), that each move inherits tighten_stop_loss's rules and is audited, the one-rule-per-position replacement semantics, removal via kind=none, and automatic termination when the position closes. Annotations only supply the generic safety profile (idempotent, non-destructive, open-world); the lifecycle behavior here is genuinely additive.

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 and mode definitions are front-loaded, and every sentence carries operational information (cadence, lifecycle, sibling routing). It is dense and leans on nested parentheticals, which slightly impedes scanning, but 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?

For a stateful mutation tool with an output schema, high schema coverage, and safety annotations, the description supplies what structured fields cannot: timing, replacement/removal semantics, rule lifetime, and the audit trail. The only unaddressed area is error behavior when no held position exists, a minor omission.

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 kind enum and the trail_pct/activate_at ranges) are already fully documented. The description restates the same trailing/breakeven mechanics rather than adding new semantics, so the baseline of 3 applies. The one mild addition is signaling that breakeven depends on activate_at reaching the entry.

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 ('make a held position's stop-loss move by itself') and immediately enumerates the two operating modes (trailing, breakeven) with their mechanics. It explicitly distinguishes itself from the sibling tighten_stop_loss, so an agent can select between them without opening either schema.

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

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

Gives an affirmative use case ('lock in profit on a winning position'), an explicit exclusion with the correct alternative ('Not for a one-off move (use tighten_stop_loss)'), and a follow-up call ('get_my_open_positions shows the rule'). When-to-use, when-not-to-use, and the alternative are all 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?

Goes well past the annotations by disclosing reduce-only enforcement, the ordering guarantee ('new orders are placed before the old ones go'), and that it works while trading is halted. It does not cover permission/authorization requirements or what happens on partial failure mid-replacement, which keeps it at 4 rather than 5.

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

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

Front-loads the replace semantics, then exclusions, then inputs, then the follow-up call. Every sentence carries information the schema doesn't, including the ordering guarantee and the halt tolerance.

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 mutation tool with an output schema, so return values need no explanation. The description covers replacement semantics, removal, ordering, halted-trading behavior, sibling exclusions, and the natural next call, leaving no gap an agent would need to guess at.

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

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

Schema coverage is 100% so the baseline is 3, but the description adds a worked example of level semantics ('50% at 98000, the rest at 101000') and restates the empty-list removal case, giving the agent a concrete mental model of how price/close_pct interact.

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 ('Replace a held position's take-profits') plus the concrete mechanism (reduce-only triggers on the exchange). It explicitly distinguishes itself from tighten_stop_loss and close_perp_position_reduce_only, so an agent can route correctly without opening a sibling 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 timing ('after entry'), the mutate case ('to move or remove them'), the removal syntax ('[] removes all'), and negative routing for both stop-loss and immediate close. Nothing about when-to-use 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?

Beyond the readOnly/idempotent annotations it discloses the real behavioral traits: rounding down to venue step size, capping by three distinct limit layers (agent, person, TradeHub), self-fetching of equity/mark/contract rules, and the default of risking the maximum allowed when neither risk input is given. This is exactly the context an agent cannot infer from annotations.

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

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

Front-loaded with the core purpose, then exclusions, then inputs, then the next step. Dense but every clause carries information; no filler or marketing language.

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 calculation tool with an output schema, the description covers purpose, required inputs and their alternatives, defaults, safety framing, and the downstream call. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the parameter meanings are already fully documented in the input schema. The description's "Inputs:" line mostly restates that, though it does compactly surface the either/or relationships (stop_loss vs stop_pct+side, risk_pct vs risk_usd) and the mark default for entry_price. Baseline 3 is the right level given 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?

Opens with a concrete transformation (risk % + stop distance -> size in base coin) and names the resource (position size), then explicitly separates itself from order-placing siblings: "Not an order: nothing is sent." An agent can distinguish this from preview_perp_order and execute_previewed_order without reading 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 an explicit placement rule ("Use before every preview_perp_order") and an explicit exclusion of redundant prerequisite calls ("no need for get_my_account_balances or get_perp_contract_rules first"). It even names the follow-up call and which returned fields to pass along.

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 destructive/idempotent/openWorld, but the description adds what the annotations cannot: what actually executes (cancel all orders, reduce-only closes, position blocking), who can reverse it (a human on Web with a verification code), and that third-party apps are denied the permission. That is exactly the operational context an agent needs before an irreversible account-wide action.

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 blast radius in the first sentence, then trigger condition, then exclusions, then the follow-up check. No repetition of the title and every clause carries new 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, high-stakes tool with an output schema already documenting returns, the description covers scope, authorization, reversibility, exclusion, and a recommended verification step (get_my_open_positions). Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100% and the single `reason` field is already documented as "Why, for the user and the audit log." The description only restates it as "Input: reason," adding no format, length, or default guidance beyond the schema, 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?

Specific verb + resource + scope: cancels every resting order, closes every position on every exchange with reduce-only orders, and blocks new positions. It explicitly distinguishes itself from the nearest sibling by naming close_perp_position_reduce_only as the tool for single-position exits.

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 trigger condition ("only when the person asks to stop everything or something is clearly wrong") and the exclusion ("not for closing one position") with the exact alternative tool named. It also adds a resume constraint that governs whether the agent should call it at all.

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

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

The description adds important behavior beyond the annotations: the new stop is placed before the old one is cancelled, so the position is never unprotected, and it works while trading is halted. These details are operationally significant for a non-read-only trading mutation and are not captured by the annotations or schema.

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

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

The description is front-loaded with the core action and safety property, then covers usage, exclusions, inputs, and a useful next step. Every sentence carries actionable information 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?

Given full schema coverage, annotations, and an output schema, the description supplies everything else an agent needs: purpose, when to use it, when not to use it, the safety mechanism, halted-trading behavior, and a follow-up tool. No material gap remains for correct invocation.

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

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

Schema description coverage is 100%, and the schema already documents symbol, stop_loss, and venue in detail, including the stop-loss side and proximity constraints. The description briefly lists the inputs and repeats that stop_loss is USD per coin, but adds no meaning beyond the schema, so the baseline of 3 applies.

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

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

The description states a specific verb and resource: moving a held position's stop-loss closer to the current price. It also distinguishes the operation from widening a stop and from closing a position, naming close_perp_position_reduce_only as the alternative for closing.

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

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

It gives explicit use conditions: when the user asks to raise a long's stop or lower a short's stop. It also states exclusions, namely widening a stop (never allowed while open) and closing (use close_perp_position_reduce_only), so the agent can route correctly among siblings.

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