TradeHub

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

Goes well past the annotations: it discloses that new terms re-run every check of a new order, that a limit order is replaced and loses its queue place while a trigger entry is rewritten, and that trade:execute scope is required. The queue-position loss is exactly the kind of non-obvious side effect the destructiveHint=false flag alone would not convey, and it is consistent with idempotentHint=false.

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?

Dense and front-loaded: purpose first, then exclusions, then inputs, then permission caveat, then the natural next call. The telegraphic, colon-chained style ("Inputs:", "Next:") packs a lot but forces the reader to parse fragments rather than sentences, which slightly hurts readability.

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 7-parameter mutation with an output schema present, everything an agent needs is covered: identity, scope, required scope, the non-destructive replacement behavior, an approval-workflow fallback, and a follow-up call. Return values are 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%, so the baseline is 3, but the description adds partial-update semantics — only "what changes" is supplied, and the new terms are validated like a fresh order — which explains why price/size/stop_loss/take_profit are optional and nullable. It does not add format or unit detail beyond the schema, but the update semantics are a genuine semantic contribution.

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 (change price/size/stop-loss/take-profit of an unfilled entry) plus the exact object scope: limit order or trigger entry. It also names what it is not — a held position's stop or take-profit — which separates it from tighten_stop_loss and set_take_profits 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 explicit trigger condition ("Use when the user moves an entry"), two explicit exclusions with the correct sibling named for each, and an alternative path when approval workflows block execution (cancel and preview again). Nothing about when to reach for this tool versus a sibling 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 annotations it discloses two non-obvious behaviors: an unfilled entry being cancelled takes its own stop and take-profit with it, and the tool works while trading is halted. It does not cover permission requirements or partial-failure behavior, so it falls short of fully exhaustive, but it materially exceeds what destructiveHint/idempotentHint alone 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?

Tight, front-loaded prose: the primary action and both modes come first, then side effects, then exclusions and the next step. No filler sentences and no restatement of the title.

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

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

With an output schema, full parameter coverage and descriptive annotations, the description covers the remaining agent-facing gaps: destructive side effects on attached exits, availability during halts, and sibling routing. Only auth/scope expectations are unaddressed, a minor gap for a mutation tool.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds the either/or relationship between order_id and all_waiting_entries and clarifies that the symbol-wide mode targets unfilled entries only. The remaining venue-default and length constraints are left to the schema, which is appropriate.

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

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

States a specific verb and resource plus both operating modes: cancel one resting order by order_id, or every unfilled entry on a symbol via all_waiting_entries: true. It also names what it is not (close_position, tighten_stop_loss), so an agent can separate 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?

Explicit when-to-use (withdraw unfilled orders or a take-profit) and explicit when-not (not for closing positions; not for a held position's stop-loss, which stays until close and is instead tightened with tighten_stop_loss). It also names a concrete follow-up, get_my_open_orders.

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

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

Annotations already declare idempotentHint=true and destructiveHint=false, so the safety profile is covered; the description adds value beyond that with the capacity constraint (at most 20 waiting) and the ownership rule that an app can delete only alerts it created — real permission context. It stops short of stating what happens when the alert has already fired or does not exist, which is the main remaining behavioral gap.

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 effect, then usage, exclusion, input provenance, constraint, and next step — each fragment earns its place with no filler. The telegraphic style is dense but readable.

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 mutation with an output schema and full annotation coverage, nothing an agent needs is missing: what it does, when to use it, what not to confuse it with, where the ID comes from, and the ownership limit. Return values need not be explained because an output schema 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 coverage is 100% and the schema already says the id comes from set_price_alert or get_my_price_alerts, so the description's "Input: alert_id from get_my_price_alerts" is largely redundant. Baseline 3 is appropriate since the schema carries the 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?

Specific verb and resource with scope: "Remove a waiting price alert so it never fires" — the 'waiting' qualifier distinguishes it from cancelling an order or closing a position. It also names the sibling it is not (cancel_order), 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 both when-to-use (user no longer wants it, or to make room under the 20-alert cap) and an explicit exclusion with the alternative ("Not for orders (use cancel_order)"). It also supplies a follow-up action, which is more than most definitions attempt.

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 traits an agent actually needs: persistence past the session end ("TradeHub keeps watching after this session ends"), a hard cap of 5 rules, each rule firing exactly once, the two possible outcomes (notify via Telegram/events/webhooks, or a reduce-only partial close), and replacement semantics ("A new plan replaces the old; rules=[] removes it"). There is a mild tension with destructiveHint=false given that a rule can close position size, but the description's "reduce-only" wording mitigates it and no annotation is directly contradicted.

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 when-to-use condition and examples, then behavior, then the next tool — a sensible order with no filler sentences. The style is telegraphic (sentence fragments, quoted examples), which is efficient but slightly staccato compared with fully formed prose.

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 mutating scheduler with nested rule objects, the description covers the lifetime of the plan, the rule cap, the fire-once semantics, both action modes, and how to clear a plan. Output schema exists and parameters are fully documented in the schema, so nothing an agent needs in order 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 baseline would be 3, but the description earns more by mapping natural-language requests onto concrete parameter combinations: "close half below 94000" ties price_below to action=close with close_fraction, and "funding passes 50% a year" ties funding_above to the yearly-fraction value. It also explains the empty-array case for rules, which the schema notes only in passing.

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

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

The description states a specific action on a specific object: it sets deferred conditional rules on a held position that either notify the person or reduce-only close part of it. It explicitly separates itself from the nearest sibling with "Not a stop-loss" and points forward with "Next: get_my_positions", so an agent can place it among set_stop_loss_rule, set_price_alert, and close_position 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 names the triggering user intents with three literal example quotes ("close it if still open in 3 days", "tell me if its funding passes 50% a year", "close half below 94000"), gives the exclusion ("Not a stop-loss"), and states the capability boundary ("you cannot schedule checks yourself"). The usage conditions and the alternative are both 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 destructiveHint=true, non-idempotent, and open-world, so the safety profile is known. The description still adds real context beyond them: market-order execution, reduce-only enforcement that cannot open or flip a position, third-party permission scoping, and that it works while trading is halted. It omits price-slippage or failure behavior, but with a rich annotation set that gap is minor.

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 dense and front-loaded with the core action, and every clause carries information, but it is a single run-on block mixing purpose, semantics, permissions and a suggested next step. Slight structural cost, no wasted sentences.

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

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

Output schema covers return values, so the description only needs to cover invocation context — and it does: mechanism, reduce-only guarantee, permission scoping, halt behavior, and a follow-up call (get_my_positions). 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 100%, so the schema already documents venue, symbol, size_base and close_fraction, making baseline 3 appropriate. The description adds only the either/or framing between close_fraction and size_base plus the '1 = all' shorthand, which is useful but marginal over the schema text.

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 (close), resource (perpetual futures position), scope (all or part), and execution mechanism (reduce-only market order). It explicitly distinguishes itself from cancel_order and names the sibling to use for the other case, 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 use cases (take profit, cut a loss, reduce exposure, undo a filled order) and an explicit exclusion with the alternative named (not for cancelling resting orders; use cancel_order). It also states a precondition-style rule that third-party apps can only close positions they opened, which changes which calls are legal rather than just which are sensible.

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 adds substantial behavior beyond them: results are sorted by annualised rate highest-first, rates are fractions, positive means longs pay shorts, each reading carries an age, and TradeHub takes no rebates. The 'Not a forecast: rates change every interval' caveat also warns about staleness 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-loaded with the purpose, then usage, then caveat, then input, then output ordering and follow-ups — dense but zero filler. Telegraphic phrasing is intentional and each clause 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?

Despite an output schema existing, the description still discloses ordering, sign convention, and data-age semantics that matter for interpretation. For a one-parameter read tool with full annotation coverage, nothing an agent needs to call or interpret 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 parameter already documents 'Base coin, e.g. BTC'; the description's 'Input: symbol (base coin)' restates it without adding format or constraint detail. Baseline 3 applies since the schema carries the parameter burden.

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 perpetual futures funding rate for one coin on every exchange TradeHub supports') plus the two views returned (per interval and annualised) and the freshness dimension ('age of each reading'). This clearly separates it from the sibling compare_venue_prices, which covers prices rather than funding rates.

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 contexts ('choosing where to hold a long or a short', 'check a funding spread') and explicit next steps ('get_contract_rules(venue, symbol) or size_position'). It lacks an explicit exclusion naming the sibling it should not be used for, so it falls short of full when/when-not routing.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description goes well beyond them: it discloses the ranking formula (price + taker fee + execution cost), that hold_hours adds funding and exit fee, that fees use the account rate or published rate, that rebates are excluded, and the exact criteria separating best_venue (connected, allowed, enough margin) from cheapest_venue. The only residual gap is the undefined nature of the 'cost for poor execution' term, which is the one quantitative behavior left opaque.

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 use case, then conditional behavior, then exclusions and next step — no filler sentences. It is dense to the point of being telegraphic ('No rebates.', 'cheapest_venue: ... best_venue: ...') and relies on field names not present in the input schema, which slightly taxes readability.

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 multi-parameter read tool with an output schema, it covers everything an agent needs: what is computed, how ranking changes with optional inputs, which output field to act on, the constraint set behind best_venue, and which tool to call next. It even resolves the ambiguity of two similar output fields that the output schema alone would not disambiguate.

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 text already explains side, size_base, hold_hours and notional_usd in nearly the same words as the description. The description does add the coupling rule ('With side (and size_base or notional_usd)') and implicitly explains leverage via 'enough margin', but with the schema doing the heavy lifting this sits at the baseline.

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

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

States a specific verb and resource ('choose where to trade one perpetual futures coin') and enumerates exactly what is compared per exchange: bid, ask, spread, trading fee, 7-day execution. It explicitly excludes the nearest overlapping sibling ('Not for one venue's depth (use get_order_book)'), so an agent can discriminate 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 the positive case (picking a venue for one perp), the conditional case (supply side plus size_base/notional_usd to get all-in ranking), the negative case with a named alternative (get_order_book for depth), and the follow-on step (preview_order with best_venue or venue "best"). When-to-use, when-not-to-use and a named alternative 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 flag destructive, idempotent, and open-world behavior, but the description adds real substance: the price is re-checked before execution, the stop-loss is placed at the exchange, approval gates hold the call for wait_seconds, and repeating client_order_id returns the first result. It also discloses irreversibility and names close_position as the only remedy, which is exactly the context an agent needs before a destructive call.

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?

Roughly six short sentences, each carrying distinct information, ordered from what it does through preconditions, approval behavior, inputs, irreversibility, and the next call. The parentheticals are dense but eliminate ambiguity rather than pad.

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, approval-gated order-execution tool with an output schema, everything an agent needs is present: precondition, irreversibility and remedy, approval wait semantics, idempotency, and the follow-up status tool. Return values can be omitted because an output schema 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 coverage is 100%, so the schema already documents all three parameters, including the 0-30 range and idempotency behavior. The description restates rather than extends this (fresh-price re-check and approval waiting appear in the schema descriptions too), 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 and resource: it executes a preview produced by preview_order, re-prices it, and sends it to the exchange with a stop-loss. It explicitly excludes the sibling case ('Not for new or changed orders'), so an agent can separate it from preview_order and amend_entry_order 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 a hard precondition ('Use only after a successful preview') and an explicit exclusion with the remedy ('Not for new or changed orders (preview again)'). It also routes the agent forward to get_order_status(request_id) while pending, covering the follow-up step.

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 instead adds operational constraints the annotations cannot carry, notably that without an account only hyperliquid is available. It also fixes units ('Prices in USD per coin, sizes in the base coin, rates as fractions'), which prevents downstream conversion errors. No mention of caching or rate limits, so 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?

Purpose, exclusions, alternatives, input conventions and the next step are packed into four dense sentences with no filler; the tool's function is front-loaded before the routing guidance.

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

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

With only two parameters, full schema coverage, an output schema and complete annotations, the description covers everything an agent still needs: what the tool returns, when not to call it, where to go instead, and the unit conventions. Nothing relevant to calling 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, but the description goes beyond the schema by pinning down that symbol is a base coin (e.g. BTC) and by adding the venue caveat 'without an account: hyperliquid only', which the venue enum in the schema does not state. That caveat materially changes how an agent picks the 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?

Opens with a specific verb and resource ('Rules and current funding for one perpetual futures contract on one exchange') and enumerates exactly which fields come back: mark price, size step, minimum size, price tick, maximum leverage, funding rate. It is immediately distinguishable from sibling tools like get_order_book or get_my_positions.

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 trigger ('when a limit price or leverage must fit the venue'), an explicit exclusion ('not needed for market orders (sizing and preview round for you)'), and names the correct alternatives for a different intent ('use compare_venue_prices or compare_funding_rates'). It even routes forward ('Next: size_position').

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 safety (readOnly, idempotent, destructive=false, openWorld), so the description's added value is the daily refresh cadence — a real staleness signal an agent needs — plus the third-party source (alternative.me) and the interpretive caveat that it is "a mood figure, not a signal on its own." It does not discuss failure modes if the upstream source is unavailable, 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 what the tool returns, then usage, then exclusion, then caveat and next step — a sensible agent-reading order. It is dense and clause-heavy in a single sentence, but nearly every clause 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 zero-input read tool with an output schema, annotations, and a clearly stated refresh cadence and interpretation caveat, nothing an agent needs in order to call or trust it 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 the baseline of 4 applies; the description correctly and explicitly confirms "No inputs," removing any doubt about whether date ranges or filters can be passed.

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 (the crypto Fear & Greed index), its source, its 0-100 scale, its daily cadence, and exactly which datapoints come back (today, yesterday, week, month, 7-day change, 30-day average). It is impossible to confuse with any sibling such as get_market_positioning or get_signal_score.

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

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

Explicit when-to-use ("gauge the whole market's mood"), explicit when-not ("Not for one coin's positioning") with the alternative sibling named, plus a forward pointer ("Next: get_signal_score"). This is the full when/when-not/alternative triad.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, open-world), so the description's added value is in data provenance and coverage limits: real-market public data also available in the sandbox, and liquidations only 'where published (OKX)'. It also sets expectations that output is 'figures, not a forecast'. It does not mention refresh cadence, caching, or whether an unavailable exchange is omitted versus null, which keeps it from 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?

The content is front-loaded with what is measured, then usage, then exclusion, then input, then next step — a sensible ordering with no filler. Some fragments ('Input: symbol (base coin).' / 'Next: size_position.') are terse to the point of feeling clipped, and the output-unit note slightly duplicates the output schema, but 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?

With an output schema present, the description needn't document return shapes, and it still supplies what the schema cannot: data provenance, per-exchange breakdown semantics, exchange-specific liquidation coverage, and unit conventions. For a one-parameter read-only tool this is everything 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% and the single parameter is already documented as 'Base coin, e.g. BTC', so the description's 'Input: symbol (base coin)' adds essentially nothing beyond the schema. The unit notes ('Changes in basis points, account share 0-1') describe output formatting rather than 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?

The description names a specific verb+resource (positioning in one perpetual futures coin) and enumerates the exact measures returned: open interest in coins and USD with 1h/24h change, share of accounts net long, and last-hour liquidations. It also explicitly separates itself from a nearby sibling by stating it is 'Not for funding (use compare_funding_rates)'.

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 ('judge crowding before a trade or explain a move'), an explicit exclusion ('Not for funding'), the sibling to use instead, and even a downstream step ('Next: size_position'). An agent has no ambiguity about when to select this tool versus compare_funding_rates or size_position.

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

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

Annotations already cover read-only, idempotent, non-destructive, closed-world behavior, so the bar is lower, and the description still adds real value: it discloses that promotion to real money is a human action on TradeHub Web, preventing the agent from attempting it. It does not discuss rate limits or how refusals are aggregated, but the output schema carries return structure.

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 usage, exclusion, parameter range, and next step — each sentence carries a distinct instruction. Slightly dense with the parenthetical '(last N days)' and the promotion note wedged mid-flow, but nothing is redundant.

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

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

For a single-optional-parameter read tool with an output schema and full annotation coverage, this is complete: it says what comes back, when to call it, what it is not for, what it cannot do (promotion), 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 the single 'days' parameter already documents its meaning, default of 30, and 1-90 bounds. The description restates 'days (1-90)' without adding semantics such as how the window interacts with the refusal statistics, 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?

Names a specific resource (this agent's performance) and enumerates its contents: trades, wins, realised P&L in USD, most common refusals with corrective guidance, and a real_money readiness flag. It explicitly excludes the sibling case ('Not for the trades themselves') and points to get_my_trade_history, 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?

Gives concrete triggers — start of session, after rejections, or when asked about trading real money — plus an explicit exclusion routing to get_my_trade_history and a named next step (get_my_trading_permissions). When-to-use, when-not, and alternatives 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 cover the safety profile (readOnly, idempotent, non-destructive, openWorld), and the description adds genuinely useful context beyond them: the call fans out over every connected exchange including a sandbox, and all amounts are normalized to USD with USDC/USDT treated as equivalent. It stops short of noting auth requirements or what happens when an exchange account is disconnected or a venue errors, which is the remaining gap for an openWorld aggregation call.

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 returned fields, then triggers, exclusions, and unit semantics in short declarative sentences. The trailing 'Next: get_my_positions' partially duplicates the earlier 'Not for positions' line, which is the only mild redundancy.

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

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

An output schema exists, so return values need no explanation, and the description still supplies the venue coverage and USD normalization an agent needs to interpret them. For a no-input read tool this leaves nothing material 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?

With zero parameters the baseline is 4, and the description confirms 'No inputs' so an agent won't hunt for a required argument. Nothing further is needed on the parameter side.

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

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

The first sentence names the exact resource (equity, free margin, used margin, open PnL) and its scope (every connected exchange account plus the total), listing the venues by name. It is immediately distinguishable from get_my_positions, which is named as the wrong tool for positions.

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 positive triggers (report balances, compare free margin across exchanges), an explicit when-not ('Not needed before opening: size_position reads equity itself'), and an alternative for a different need ('Not for positions (use get_my_positions)'). An agent can route on this 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?

Goes well beyond the annotations: it discloses server-side cursor memory ('TradeHub remembers where you stopped, so a new session gets only what is new') and the blocking/long-poll behaviour of wait_seconds. That memory semantics is the single most important non-obvious trait here, and the readOnly/destructive hints are already handled by 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 payoff ('what happened while you were away'), followed by the event inventory, the cursor behaviour, usage modes, the exclusion, and the next step. The event list is long but each item is a distinct category that helps an agent decide whether to call it; nothing is redundant 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 needn't be explained. For a 4-optional-parameter read tool, the description covers purpose, cursor semantics, blocking behaviour, exclusion and follow-up, leaving no gap an agent would need to guess.

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

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

Schema description coverage is 100%, so the schema already documents every parameter including the meaning of 'after' and the 0-30 wait cap. The description's inline input hints ('types, limit, after (keep your own place)') largely restate the schema, adding only the framing that 'after' preserves your own place rather than server state.

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 (the account event feed) with an explicit scope: fills, rejections, approvals, closures, plan-rule firings, alerts and warnings. It also names the boundary against the nearest sibling ('Not for current state (use get_my_positions)'), so an agent can select 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 explicit when-to-use ('at the start of a session'), an explicit when-not ('Not for current state'), the sibling to use instead, and a follow-up action ('Next: act on what changed'). The long-poll mode is gated with its cap ('wait_seconds (up to 30)'), which is exactly the routing information an agent needs.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuine context beyond that: which order families are surfaced (triggered protective orders, held TRIGGER_ENTRY records with req_ ids) and the units of the returned sizes and prices (base coin, USD). It stops short of stating pagination or result limits, which is the only remaining behavioral gap.

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 definition, then usage, then exclusions, then inputs, units, and the follow-up call — a clean decision-oriented progression with no filler. Every clause carries information an agent would otherwise have to guess.

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 need not be described because an output schema exists, and the description covers the things structured fields cannot: which order categories appear, id formats to look for, and unit conventions. For a two-optional-filter read tool this is complete enough to invoke confidently.

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 params are optional with descriptions ('Only this venue', 'Only this base coin'), so the description's one line about optional venue and symbol filters largely restates structured data. The units sentence (sizes in base coin, prices in USD) is useful but pertains to output values rather than to parameter meaning, so this lands 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 a specific resource and its exact scope: resting orders across the user's venues, including protective stop-loss/take-profit (is_trigger = true) and TradeHub TRIGGER_ENTRY orders with req_… ids. It explicitly separates itself from get_my_trade_history (filled trades) and implicitly from get_order_status, so an agent can identify 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 concrete when-to-use reasons (find an order_id to cancel, confirm a stop is in place), an explicit exclusion with a named alternative (filled trades → get_my_trade_history), and a handoff to the natural next tool, cancel_order(order_id). Nothing about tool selection 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 and open-world behavior, so the bar is lower; the description still adds scope semantics (all connected exchange accounts), the unit conventions (base coin for size, USD for prices), and recommended follow-on tools. It does not restate annotation claims, which is exactly right.

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

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

Front-loaded with the resource, then usage, then exclusions, then units and next steps — nothing is wasted. The field enumeration is slightly long and partially duplicates the output schema, which keeps it from a 5.

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

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

A zero-argument read tool with full annotation coverage and an output schema needs only scope, units, and routing guidance, and the description supplies all three. 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?

Zero parameters, so the baseline is 4. The description correctly notes 'No inputs', which prevents an agent from hunting for filter arguments, but there is no schema meaning left to clarify.

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

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

States a specific resource (every open perpetual futures position across all connected exchange accounts) and enumerates the salient returned fields. It also explicitly contrasts with the sibling get_my_open_orders, so an agent can distinguish the two 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 when-to-use conditions (first call in a new session, before closing, adjusting a stop, or reporting exposure) and an explicit when-not (resting orders or stops) routed to a named alternative. No inference is required.

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 a closed-world scope, so the safe-read profile needs no restating. The description still adds real context beyond them: per-app visibility ('an app sees only the alerts it created') and the one-day retention window on fired alerts, including that the firing price is returned. Minor gap: it does not clarify what qualifies as 'waiting' versus armed/triggered states.

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

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

Four short sentences, front-loaded with what is returned and the visibility constraint, then usage, then the exclusion, then the next step. Every sentence carries distinct information and none is redundant with the title or annotations.

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

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

For a zero-parameter, read-only list tool with an output schema that documents return shape and annotations that document safety, the description covers everything an agent needs: content, scope, retention window, selection guidance, exclusion, and follow-up.

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

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

The tool takes zero parameters, so the baseline is 4, and the description explicitly confirms 'No inputs', removing any doubt for an agent. There is nothing further to document at this level.

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

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

The description names the resource (price alerts) and its two states — 'waiting' and those that 'fired in the last day' — plus the app-scoped visibility rule, which distinguishes it from set_price_alert and cancel_price_alert. There is no explicit verb ('list'/'get' is only implied), so it falls just short of the top band, but an agent can still tell exactly what this returns.

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 ('before adding one or to find an alert_id to delete'), an explicit when-not-to-use with the named alternative ('Not for orders waiting for a price (use get_my_open_orders)'), and a stated next step ('cancel_price_alert'). 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 read-only, idempotent, non-destructive behavior, so the description's job is to add scoping context — and it does: values are fractions of equity and USD, and real money versus sandbox are counted separately, which materially affects interpretation. It also warns that pending limit increases are included. It stops short of describing freshness or aggregation nuances, but with an output schema present that gap is minor.

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 content is front-loaded with scope, then exclusions, then units, then the next step — a sensible ordering with no filler sentences. The first sentence is dense with a long parenthetical list, which costs a little readability but every element 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 zero-parameter read tool with an output schema and full annotations, the description covers purpose, triggers, exclusion routing, unit conventions, sandbox-vs-real separation, and a follow-up step ('Next: size_position'). 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?

There are zero parameters, so the baseline is 4, and the description confirms 'No inputs' so the agent does not look for filtering options. It also clarifies units (equity fractions and USD) which governs how the returned values should be read.

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 (the person's global risk limits and usage) and enumerates the covered dimensions: per-trade risk, daily/weekly/monthly loss, drawdown, leverage, open positions, plus pending limit increases. It explicitly marks its boundary against the closest sibling (get_my_trading_permissions), 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?

It gives two concrete trigger conditions ('when a trade was rejected by a user-level limit' and 'before planning several trades') and an explicit exclusion with a named alternative ('Not for this agent's own permissions (use get_my_trading_permissions)'). That is the full when-to-use / when-not / alternative triad.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), yet the description adds real behavioral context beyond them: the per-app vs per-user visibility scoping and the pagination protocol (pass next_before back until it is null). It also fixes units (sizes in base coin, money in USD), removing ambiguity about returned numbers. It does not mention ordering guarantees beyond 'recent' or any rate limits, so it falls just short of exhaustive.

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?

Dense and front-loaded: capability first, then scope caveat, then usage routing, then input/pagination/units. Nearly every clause carries information. The trailing 'Next: get_my_positions' partly repeats the earlier exclusion, which is the one redundant element.

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

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

For a 3-parameter read tool with an output schema and full annotation coverage, the description supplies everything an agent needs: what is returned, visibility scoping, pagination handling, units, and the sibling to use instead. 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 coverage is 100%, so the baseline is 3, but the description adds meaning the schema lacks: the pagination loop semantics and the unit conventions for sizes and money. The 'limit (1-200)' restatement duplicates the schema bounds and earns nothing, which keeps it from 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 specific verb+resource ('Recent trades opened through TradeHub') and enumerates exactly what each record contains: entry, stop, take-profit, leverage, realised PnL, fees, funding, net result. It also names the sibling it is not ('Not for live positions (use get_my_positions)'), so the agent can separate it from get_my_positions 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 explicit positive use case ('Use for reviews and reports'), an explicit exclusion ('Not for live positions'), and names the correct alternative tool. It also adds a visibility caveat (third-party apps see only their own trades; the user's keys and Telegram see all), which tells the agent when results may be unexpectedly narrow.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), yet the description still adds substantive behavior: the autonomy-tier semantics (read / propose / preauth), that limits are fractions of equity or USD, and that widening limits requires a human on the Web with a 24-hour delay. That last fact is a governance constraint the agent could not infer 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?

Dense but every clause earns its place: capability inventory first, then usage triggers, then exclusions, then semantic notes, then next steps. No filler and no repetition of annotation data.

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 are covered elsewhere; the description supplies what structure cannot — interpretation of the autonomy levels and limits, the escalation path for widening, and where to go next. Complete for a zero-parameter read tool in a large sibling set.

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

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

The tool takes no inputs and the description says so directly ('No inputs'), which matches the empty schema. With zero parameters there is no semantic gap, though the statement itself is minimal rather than additive — consistent with the baseline for parameterless tools.

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 ('What this agent may do right now on TradeHub') and enumerates the exact contents: autonomy level, allowed venues/symbols/actions, limits, usage, connected venues, halt status. It explicitly distinguishes itself from a sibling by excluding balances and naming get_my_balances.

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 triggers ('Use first in every session and after any rejection that mentions your mandate'), an explicit when-not ('Not for account balances'), and follow-on alternatives ('Next: size_position or get_my_positions'). Nothing is left to inference about routing.

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

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

Annotations already declare read-only, idempotent, non-destructive, open-world behavior, so the safety profile is covered. The description adds value beyond that: sort order (best first), units (USD per coin for prices, base coin for sizes), and the account-dependent venue constraint (unauthenticated calls are hyperliquid only). It does not discuss snapshot timing, throttling, or streaming, but those are minor for a read query.

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

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

Front-loaded with purpose, then exclusion, then inputs, then next step — four short sentences with no filler. The 'Inputs:' clause partly restates the schema, but it carries the extra venue constraint and unit conventions, so most of it earns its place.

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

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

For a 3-parameter read query with a full output schema and clear annotations, the description covers purpose, return shape, ordering, units, venue restrictions, and the downstream call. Nothing an agent needs in order 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 nevertheless adds meaning the schema does not: the 'without an account: hyperliquid only' constraint on venue, the per-side nature of depth, and the units of the returned price/size values.

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

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

States a specific resource (order book levels), scope (one perpetual futures contract on one exchange), and the exact ordering/format returned (best first, [price, size]). It also explicitly distinguishes itself from the sibling compare_venue_prices, so an agent can pick between them 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-to-use ('judge liquidity before a large market order'), an explicit when-not-to-use with the named alternative ('Not for the best price across exchanges (use compare_venue_prices)'), and a workflow pointer ('Next: preview_order'). Nothing about selection 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, so safety is covered. The description adds real value beyond them: the full state machine (pending_approval through declined) and what becomes available once executed (fill price, stop order id). It does not say how long a pending approval stays valid or what happens for an unknown/expired request_id, 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 resource and states, then usage, then the labeled Input/Next cues — dense but efficient. The telegraphic 'Input:' / 'Next:' fragments are slightly terse, and enumerating return fields is somewhat redundant with the output 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 single-param read with annotations and an output schema, everything an agent needs to select and call it is present: prerequisite call, alternative, and next step. The only missing piece is failure behavior for an invalid or expired request_id, which is minor given the output schema covers returns.

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 parameter is already documented as coming from execute_previewed_order. The description's 'Input: request_id' restates the schema without adding format, lifetime, or lookup semantics, 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 resource (order request status) created by a specific sibling (execute_previewed_order) and enumerates the possible states. Explicitly distinguishes itself from 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?

States the when ('use to follow an order that was waiting for a person's approval'), the when-not ('not for listing orders, use get_my_open_orders'), and the follow-up action ('get_my_positions once executed'). All three routing decisions are 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 readOnly/idempotent/openWorld/non-destructive, so safety is covered; the description goes further by disclosing data provenance ('Hyperliquid's public market, the same prices the sandbox trades at'), the 500-candle cap, oldest-first ordering, and units (USD per coin, volume in base coin, UTC times). These are behavioral facts an agent cannot obtain from the annotations and would otherwise have to guess.

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 usage, then exclusions, then inputs — a sensible progression where nearly every clause carries information. The 'Inputs:' recital partly duplicates the schema and the 'Next: size_position' nudge is optional, keeping it just short of maximal efficiency.

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 three-parameter read tool with a full input schema and an output schema, the description supplies everything else that matters: data source, ordering, cap, units, and timezone. Nothing needed to call or interpret the call correctly is left unstated.

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

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

Schema description coverage is 100%, so the schema already documents symbol, interval, and limit with defaults and bounds; the description's 'Inputs:' line largely restates them. It adds only marginal meaning (e.g. 'symbol (base coin)' and reinforcing the default interval/limit) rather than new constraints or semantics.

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

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

States a specific verb and resource ('Price history for one coin as candles') and enumerates the returned fields (open, high, low, close, volume per interval), so an agent immediately knows this is OHLCV retrieval rather than a quote or indicator endpoint. It is clearly separable from siblings like get_order_book, get_technical_indicators, and compare_venue_prices.

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 use cases (look back at price action, find recent highs/lows for a stop, judge the trend) and explicit exclusions with named alternatives: 'Not for the live best price (use compare_venue_prices) or ready-made indicators (use get_technical_indicators).' It also signals the follow-on step ('Next: size_position'), leaving little to inference.

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

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

Annotations already cover the safety profile (readOnlyHint, idempotent, non-destructive), and the description adds genuinely new context: the score derives from fixed, published rules rather than a model forecast, the response includes each component's input and points plus a categorical label from strong_bearish to strong_bullish, and the result should be surfaced to the user. It also explicitly disclaims advisory/forecast status, which is behavioral information absent from the annotations.

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

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

The score range and factor list are front-loaded, and the exclusions plus next-step are packed into short clauses with no filler sentences. The final 'Input: symbol (base coin)' restates the schema and is the one line that does not earn its place.

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

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

An output schema exists, so return shape need not be re-explained, yet the description still signals that components and a label come back. For a single-parameter, read-only analytical tool with a defined downstream workflow (preview_order, size_position), nothing an agent needs in order 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 parameter is already documented as 'Base coin, e.g. BTC'; the description's 'Input: symbol (base coin)' reinforces the same meaning without adding new syntax or format constraints. With one fully documented parameter this meets the baseline, but adds little beyond the schema.

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

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

The description names a specific verb-derived resource ('A -100 to +100 score for one coin') and enumerates the exact factors feeding it (trend, 24h momentum, RSI, funding, open interest, account crowding, Fear & Greed, major news). This clearly separates it from neighbors like get_technical_indicators or get_market_positioning, which supply raw inputs rather than a composite labeled score.

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

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

Explicit routing is given in both directions: 'Use as one input to your own decision and show the components', 'Not for placing orders (use preview_order)', and 'Next: size_position.' It states when to use, when not to use, the alternative to pick instead, and the follow-on 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 readOnlyHint, idempotentHint, and destructiveHint=false, so the description only needs to add beyond that, which it does: the default interval, that output is in USD per coin, that ATR is oriented toward stop placement, and the disclaimer about not being a recommendation. It does not mention latency or data freshness of the candles, so it falls short of fully rich behavioral 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 indicator list and exclusions are front-loaded and every clause carries information, including the workflow pointer at the end. The 'Inputs: symbol (base coin), interval' fragment largely repeats the schema, which is the one piece of waste.

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

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

With an output schema present and full annotation coverage, the description only needs to cover purpose, selection, and units, and it does all three for a simple two-parameter tool. Nothing required 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, but the description adds real meaning beyond the schema by explaining what interval choice is appropriate for trend versus timing and by reiterating that symbol is a base coin with USD-denominated outputs. This goes past restating the enum and default.

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

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

The description names the exact indicator set (RSI, MACD, Bollinger %B, ATR, EMA trend, volume rank), the resource (one coin), the data source (Hyperliquid candles), the interval set, and the funding-rate add-on. It also explicitly excludes two siblings (compare_venue_prices for live quotes, get_price_candles for raw prices), so the agent can separate it from adjacent tools 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 states when to use the tool (as decision inputs), how to choose intervals ('1h or 4h for the trend and 15m for timing'), what it is not ('not a trading recommendation'), and where to go for the two overlapping use cases it does not serve. It even names the natural next step, size_position, giving a clear workflow slot.

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, openWorld and non-destructive, so the safety profile is covered. The description adds genuinely non-structured context: that headlines are third-party text to be treated as data and never as instructions (prompt-injection defense), and what qualifies as 'major' (hacks, exchange failures, regulation). Return-shape detail is partly redundant given the output schema, which keeps this just 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 identity of the feed, then exclusions, then return semantics, then the next step — a sensible order with no filler. Some sentences are telegraphic to the point of terseness ('Use theirs for those.'), which costs a little readability against the otherwise dense, purposeful phrasing.

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 4-parameter, all-optional read tool with a full output schema and rich annotations, the description covers everything an agent needs: identity, alternatives and exclusions, aggregation semantics, flag definitions, an injection warning, and a follow-up tool. No material gap remains that would cause a misinvocation.

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 earns above it by explaining the semantics of only_major — the major-news rules keyed to hacks, exchange failures and regulation — which the schema only names abstractly. It also clarifies that symbol matches coins 'named' in the story, not merely tagged. hours and limit are left entirely to the schema, whose defaults and ranges are already documented.

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 ('TradeHub's built-in news feed', 'recent crypto headlines') and describes the aggregation unit ('one story per event with every outlet that carried it') plus the fields returned (coins named, tone, major flag). It explicitly names what it is not — 'my news', 'my news server', an added news tool, and compare_venue_prices — so an agent can separate it from 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?

Gives both when-not-to-use ('Not for "my news"... Use theirs for those') and a second exclusion ('Not for prices (use compare_venue_prices)'), each paired with the correct alternative. It also routes forward with 'Next: get_signal_score', leaving no ambiguity about sequencing.

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 covered. The description adds real value beyond that: it discloses the auth-dependent split (public data always, account-level detail only 'with an account') and names the specific account metrics returned, which is genuine behavioral context. It stops short of stating freshness/caching or that unreachable exchanges are reported rather than raised as errors, so it is not exhaustive.

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 tightly packed sentences, front-loaded with the core capability, then the when-to-use/exclusion, then the next step. Every clause carries information — the account-vs-public distinction, the named error code, the named sibling, the follow-up action — 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-value explanation is correctly omitted, and with zero parameters the definition is nearly self-sufficient. The only residual gap is that the description doesn't say how an unreachable exchange is surfaced in the response (error vs. field), which matters for a health-check tool whose whole point is failure reporting.

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

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

The tool takes zero parameters, so the baseline is 4, and the description reinforces this by stating 'No inputs', removing any doubt about whether an exchange selector exists. No further parameter meaning is needed or possible.

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

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

States a specific verb and resource ('whether each exchange is reachable right now') plus the two data layers it returns: public price feed per exchange and, with an account, per-account latency, last error and rate-limit headroom. It explicitly carves out the sibling it is not ('Not for prices (use compare_venue_prices)'), so an agent can disambiguate from compare_venue_prices 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 trigger conditions ('after a VENUE_UNAVAILABLE error or before trading on an exchange that misbehaved'), an explicit exclusion routed to a named alternative ('Not for prices (use compare_venue_prices)'), and even the follow-up action ('retry the failed call, or use another venue'). 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 already declare readOnlyHint=true and destructiveHint=false, and the description reinforces this with "sending nothing" while adding genuinely new behavior: the preview_id is valid only 30 seconds, which explains the non-idempotent, ephemeral nature of the call. It does not detail what happens on a failed check or what the caller must do if the preview expires, so it stops 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 purpose and the safety qualifier, then usage, then the parameter recipe, then the return and next step — a sensible order with no filler sentences. The telegraphic fragment style in the entry-styles clause ("market, nothing; limit, ...") is dense but slightly cryptic on first read.

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

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

For a 16-parameter order-preview tool with an output schema, the description covers the essential pieces: validation scope, required inputs per entry style, the ephemeral preview_id, and the handoff to execute_previewed_order. Remaining gaps (what a failing check returns, how to refresh an expired preview) are modest given the output schema 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 coverage is 94%, so per-parameter meaning is largely already documented. The description's real contribution is cross-parameter combination rules by entry style (market needs nothing; limit needs order_type "limit" plus price; a waiting entry uses trigger_price; a ladder uses order_type "limit" plus ladder_prices), which the schema states only partially and scattered per property. This is above a pure baseline but not exhaustive across all 16 parameters.

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 and its stop-loss against the permissions, limits and price band") plus the crucial scope qualifier "sending nothing". This clearly separates it from execute_previewed_order and from close_position without needing 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 when-to-use rule ("Use before every new position"), an explicit when-not with a named alternative ("Not for closing (use close_position)"), and the required follow-up call ("Next: execute_previewed_order(preview_id)"). The workflow position of the tool is fully determined.

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 (readOnlyHint=false, idempotentHint=false, destructiveHint=false), it discloses that the alert is single-fire and self-terminating, the delivery channels including the 'price.alert' event name, the concurrency cap of 20, and the required read scope. These are exactly the facts an agent cannot infer from the hint flags.

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, then the when/exclusion, then inputs, limits, permissions, and the follow-up tool — each clause carries distinct information. No sentence restates another, and the telegraphic style stays parseable.

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 4-parameter mutation tool with annotations and an output schema present, the description covers everything an agent needs: what it does, when to pick it over alternatives, side effects, delivery channels, rate limit, and the logical next call. Return values are 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 description coverage is 100%, so the schema already documents price, venue, symbol and direction including the default behavior. The description restates the same defaults ('optional direction (default: from the current price) and venue') without adding syntax, units, or edge-case guidance the schema lacks. 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 — 'Tell the person when a coin's price reaches a level' — and immediately scopes it as a one-shot notification ('one message ... then the alert is done'). It explicitly separates itself from order placement and from polling, so an agent can distinguish it from preview_order and get_my_price_alerts without opening any schema.

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

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

Gives a positive trigger ('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 names the correct alternative for the excluded case ('for an order that waits for a price use preview_order with trigger_price'). Both branches are resolved.

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: polling cadence (~5 seconds), that every move inherits tighten_stop_loss's rules and is audited, that movement is monotonic toward price, that a rule is one-per-position and replacement semantics, that kind=none removes it, and that it auto-terminates when the position closes. This is exactly the operational context the readOnly/idempotent hints cannot convey.

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

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

Front-loaded with the core behavior, then modes, then lifecycle, then routing to siblings — a sensible order. It is dense but nearly every clause carries a distinct fact; the only mild redundancy is restating mode semantics that also appear in the schema.

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

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

For a stateful, recurring rule with an output schema, the description covers what the agent cannot get elsewhere: polling frequency, lifecycle/termination, replacement behavior, and audit trail. Return values are 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%, so the baseline is 3, but the description adds cross-parameter meaning the schema only implies: it binds kind=trailing to trail_pct and kind=breakeven to activate_at in one sentence. It does not add much beyond that (units, ranges and the venue default are already in 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 specific verb and resource ('Make a held position's stop-loss move by itself') and immediately enumerates the two operating modes, trailing and breakeven, with the parameter each depends on. It also names the sibling it is not (tighten_stop_loss) and the follow-up tool, so an agent can place it precisely among 30 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?

Gives an explicit positive case ('Use to lock in profit on a winning position'), an explicit exclusion with the alternative ('Not for a one-off move (use tighten_stop_loss)'), and a next step ('get_my_positions shows the rule'). Nothing about when to pick this over alternatives 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?

Adds real behavior beyond the annotations: levels become reduce-only exchange triggers so they can only shrink the position, new orders are placed before the old ones are removed (no unprotected gap), and it works while trading is halted. The only gap is what happens on partial failure of the replace sequence, but the ordering note already signals intent to keep the position protected.

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 resource, then usage, exclusions, inputs, execution semantics, and a suggested next call, all in a dense block with no filler sentence. The parenthetical examples carry genuine information rather than padding.

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

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

For a 3-parameter mutation with hidden exchange-side ordering effects, the definition covers replacement semantics, reduce-only behavior, removal, halt behavior, and the follow-up to verify. An output schema exists, so return-value description is correctly 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 already 100%, so the baseline is 3, but the description adds meaning the schema lacks: a worked allocation example ('50% at 98000, the rest at 101000') and the empty-array removal semantics. It does not add trigger-price directionality (long vs short) because the schema already covers 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?

States a specific verb (Replace) and resource (a held position's take-profits), including the shape of the payload ('one level or several'), and distinguishes it from the stop-loss and close_position siblings by name. An agent can pick it out of the 35-tool sibling list 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 timing ('Use after entry'), the mutation cases ('to move or remove them'), and a concrete removal form ('[] removes all'). It also names two exclusions with their correct alternatives: tighten_stop_loss for stops and close_position for immediate exit.

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

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

Annotations already declare readOnlyHint=true, idempotent and non-destructive, and the description reinforces that it places no order. It adds genuinely new behavioral detail beyond the annotations: rounding down to the venue step, capping by every limit, and self-fetching equity, price and contract rules. It stops short of describing failure behavior (wrong-side stop, insufficient equity, venue mismatch), which keeps it from 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 transformation, then the ordering constraint, then the input-uniqueness rule, then a compact example. Every clause carries operational information; nothing 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?

For an eight-parameter, anyOf-constrained sizing tool this covers the essentials: what it computes, what it reads, what caps apply, what it is not, and the exact next call. Since an output schema exists, it correctly avoids explaining return values while still pointing at preview_args from 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?

Schema coverage is 100%, so baseline would be 3, but the description adds real meaning: stop_loss and stop_distance_pct are alternatives (give one), and risk_pct_of_equity versus notional_usd are alternatives, with omission defaulting to the maximum the limits allow. The worked example JSON anchors the units for stop_distance_pct and risk_pct_of_equity.

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 transformation: risk percentage plus stop distance becomes a base-coin size, rounded down to the venue step and capped by limits. This is a specific verb+resource that cannot be confused with siblings like preview_order or get_my_risk_limits, and it names what it reads internally (equity, price, contract rules).

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 sequencing: use before preview_order, then preview and execute afterwards, with preview_args from the result as the handoff. It also warns that this is not an order and instructs the caller to supply the stop once and the amount once, which prevents the most likely misuse.

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

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

Annotations already declare destructiveHint=true and openWorldHint=true, but the description adds concrete behavior the annotations cannot express: cancelling all resting orders, reduce-only position closes across exchanges, blocking new positions, and human-only resume with a verification code. The permission note about third-party apps is genuinely useful context not captured by 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?

The critical scope and emergency framing are front-loaded, and each sentence carries useful information (when to use, resume restriction, sibling exclusion, next step). The 'Input: reason' clause is redundant with the schema and could be trimmed, but the overall structure is efficient and easy to scan.

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 destructive tool with an output schema and rich annotations, the description covers everything an agent needs: intent, scope, alternatives, permission model, and a follow-up confirmation step. Return values need not be explained because an output schema 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 coverage is 100% and the single 'reason' parameter is already documented as 'Why, for the user and the audit log'. The description's 'Input: reason' merely repeats this without adding format, length, or defaulting guidance. Baseline 3 is appropriate because the schema does the semantic work.

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 ('Emergency stop for the whole account') and spells out scope: cancel every resting order, close every position on every exchange with reduce-only orders, and block new positions. It explicitly distinguishes itself from the sibling close_position for single-position closes, so an agent can select 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 criteria ('only when the person asks to stop everything or something is clearly wrong') and a when-not alternative ('Not for closing one position (use close_position)'). It also states the resume path, so the agent knows the action is not self-reversible.

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=false, destructiveHint=false, idempotentHint=true, and the description adds genuinely useful behavior: the new stop is placed before the old one is cancelled, so the position is never unprotected, and the tool works during halts. It does not cover permissions, failure/rollback behavior if the placement fails, or rate limits, so it adds solid context but stops short of full disclosure.

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 key safety invariant, then usage exclusions, then inputs, then a next step. Dense and mostly waste-free, though the trailing 'Next: get_my_open_orders' and the input recap are slightly redundant given the schema and output 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 3-parameter mutation tool with an output schema, the description covers action, direction constraint, exclusion cases, halt behavior, and a verification next step. Nothing an agent needs in order to call it correctly appears to be missing.

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

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

Schema coverage is 100%, so all three parameters are already documented, including the direction rule for stop_loss. The description only restates 'symbol, stop_loss (USD per coin), venue' without adding format or edge-case detail beyond the schema, 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 and resource ('move a held position's stop-loss closer to the current price') plus the concrete outcomes (breakeven, lock in profit). It explicitly distinguishes itself from widening a stop and from closing a position, naming close_position as the sibling to use instead.

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 ('user asks to raise a long's stop or lower a short's'), explicit when-not ('not for widening a stop... or for closing'), and names the alternative tool for the excluded case. Also notes it works while trading is halted, removing a common hesitation.

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