TradingCalc MCP: Options, Forex, Risk Stats, Prediction Markets, On-Chain & Crypto Futures

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

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=false, so safety is covered; the description adds useful scope disclosure beyond that — it returns only the bare average figure and deliberately omits breakeven and per-fill breakdown. It also enumerates the returned fields, which annotations do not. It stops short of any caveats about missing/invalid fills, hence not a 5.

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

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

Three short sentences, zero waste, with the core purpose front-loaded before the routing alternative and the return shape. Every clause 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?

No output schema exists, but the description enumerates the return fields (averagePrice, totalSize, totalCost), and the nested input is documented by the schema. Between description, schema, and annotations, an agent has everything needed to call this pure-computation tool correctly.

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

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

Schema coverage is 75%, so the schema already documents symbol, contractType (including the arithmetic vs harmonic mean distinction) and the nested fill fields. The description only adds that fills are 'buy/sell' DCA fills and implies price+quantity weighting; it never mentions contractType, which is the parameter with the most consequential semantics. Baseline 3 is appropriate.

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

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

States a specific verb and resource ('calculate the weighted average entry price from multiple buy/sell fills') and immediately scopes it as the bare number. It distinguishes itself from workflow.run_dca_entry by name, 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 an explicit when-to-use condition (user asks only "what's my average entry?" and wants just that figure) and names the alternative tool plus the condition that selects it (breakeven and per-level summary too → workflow.run_dca_entry). 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 cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false), so the description's main added value is the disclosure of the three return fields (hedgeNotional, requiredMargin, estimatedFundingCost) — important since no output schema exists. It doesn't note assumptions such as default leverage or funding-rate behavior, so it is not fully rich.

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

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

Three tightly packed sentences: purpose first, usage triggers second, return values last. No filler, and the most decision-relevant content is front-loaded.

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

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

For a single-purpose calculation tool with no output schema, the description supplies the return shape and usage triggers, and annotations cover safety. It omits behavioral edge cases (e.g., what happens with omitted optional params or negative/zero spotSize), so it is nearly but not fully complete.

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

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

Schema description coverage is 100% and each parameter (spotSize, leverage, hedgeRatio, fundingRatePct) has an inline description with units and defaults. The description adds no syntactic or semantic detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb (Calculate) and a precise resource: the short perpetual futures position size needed to hedge a spot holding. This is clearly distinguishable from generic siblings like run_position_sizing or run_liquidation_safety, which do not compute a hedge against spot.

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

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

Gives concrete trigger phrasing ("how much should I short to hedge my BTC?", "what margin do I need for a 100% hedge?"), which tells the agent the user intents this tool serves. It stops short of naming when not to use it or pointing to an alternative sibling.

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, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds genuinely new behavioral context: every tools/call result carries a signed second content block when signing is configured, which tells the agent where signatures come from and when they exist.

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

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

Two sentences, front-loaded with the concrete return payload before the usage rationale. Dense but every clause (PEM + JWK, canonical format, offline verification, signed second block, HTTP mirror) carries information; only the HTTP endpoint mention is arguably secondary.

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

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

No output schema exists, so the description must convey the return value, and it does (PEM + JWK key plus canonical signing format). With annotations covering the safety profile and no parameters to document, an agent has enough to call and use it correctly; a brief note on key rotation or cache lifetime would make it fully complete.

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

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

The tool takes zero parameters, so baseline is 4 per the rubric. The description correctly implies no inputs are needed and instead describes the returned key formats, which is the relevant information here.

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: returns the ECDSA P-256 public key (PEM + JWK) plus the canonical signing format. An agent can immediately distinguish it from siblings like system.verify and the many workflow.run_* tools, since it is the only key-material provider.

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 purpose-driven context for use: verifying signed tool responses offline without calling back to TradingCalc, and notes the alternate access path GET /api/mcp/pubkey. It does not explicitly name system.verify as a complementary/alternative tool, so it stops short of a full when/when-not routing statement.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=false, destructiveHint=false, so safety is covered. The description adds real behavioral context beyond that: exactly what is exercised (43 vectors across linear and inverse/coin-margined calculators) and what comes back (pass/fail with counts and timestamp).

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

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

Two sentences, front-loaded with the action and scope, then the use case. The parenthetical 'linear and inverse/coin-margined' is genuine scope information, not filler.

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

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

For a parameterless, read-only tool with no output schema, the description covers everything an agent needs: what runs, what it validates, what is returned (pass/fail, counts, timestamp), and when it is worth calling. An agent can invoke it blind and interpret the result.

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

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

Zero parameters, so there is nothing to document and the baseline is 4. The description correctly implies the tool is parameterless, running the fixed suite unconditionally.

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 ('run the full regression suite') plus concrete scope (43 test vectors, 12 calculators) and the return shape. This is unmistakably the meta/health-check tool, cleanly distinguishable from every workflow.run_* calculator sibling.

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

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

Provides a clear usage context: 'a health check before relying on results in production workflows.' It does not name an explicit alternative or when-not-to-use condition, but the sibling set makes the role unambiguous, so guidance is strong without exclusions.

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/non-destructive behavior, but the description adds substantial behavioral context: it explains the outputs, the meaning of risk_penalty_pct, the provable relationship between pyramid_risk and clean_entry_risk, and the liquidation_before_stop condition. No contradiction with 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 purpose is front-loaded and the dense output explanations are relevant for a tool with no output schema. It is longer than ideal, but nearly every clause adds decision-useful semantics rather than filler.

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

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

For an 11-parameter analytical workflow with no output schema, the description carries the return-value burden well: it names and explains the blended average, liquidation/breakeven, margin_added, risk figures, risk_penalty_pct, and liquidation_before_stop. Enough context is provided to call and interpret the tool.

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

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

Schema description coverage is 91%, so parameter semantics are already well documented. The description adds only marginal context for add_price, stop_loss, and existing_entry_price, mostly repeating what the schema already says.

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 decision-analysis purpose: comparing an average-down add against a fresh entry for the same final size. It specifies the inputs it reasons over and the metrics it produces, which clearly separates it from generic entry/sizing 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?

It gives explicit user-phrasing triggers ("should I add to this losing position?" and "what does averaging down actually cost me here?") and scopes the tool to already-open positions. It does not explicitly name sibling alternatives or state when not to use it.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=false, destructiveHint=false, so the safety profile is covered. The description adds genuinely useful behavior beyond that: no live data fetch (pure manual-input computation) and the coin-denomination convention that divides price by spot. It stops short of noting edge cases (e.g. zero/negative time to expiry, vol validation), so not a 5.

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

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

It is dense and front-loaded — the core purpose, the sibling routing, and the unit convention all appear before the return list. The final sentence is a long output enumeration, but since there is no output schema it earns its place; the prose is slightly heavy overall.

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

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

No output schema exists, so the description usefully enumerates return fields and clarifies per-unit conventions (vegaPerPct per 1 vol point, theta per day, rho per 1 rate point) and USD vs coin quoting. Combined with annotations covering safety, an agent has enough to call it correctly; minor gaps remain around input validation/edge cases.

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 every parameter (spot, strike, daysToExpiry, volatilityPct, riskFreeRatePct) is already documented, including volatility units and the risk-free default of 0. The description restates the input set rather than adding new syntax or constraint detail, 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 method (Black-Scholes), the exact resource (theoretical European option price and Greeks), and enumerates the output set. It explicitly distinguishes itself from run_black_scholes_live, so an agent can route between the two without opening either schema.

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

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

It states the concrete trigger ("what should this option be worth at X% IV?", raw Greeks for a hypothetical), the alternative (run_black_scholes_live), and the condition that selects the alternative (checking a real Deribit BTC/ETH instrument with a quoted price). When-to-use and when-not are both covered.

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

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

Annotations already cover the safety profile (readOnlyHint, destructiveHint false, openWorldHint). The description goes beyond them by disclosing data provenance (spot/strike/DTE/IV pulled live from Deribit), the semantic intent of the discrepancy metric, and the failure mode ('available: false + error if the instrument name doesn't resolve'). It stops short of stating rate limits or freshness/latency caveats for the live pull.

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 and the trust-check framing, and every clause carries information. The trailing enumeration of return fields is a long run-on list, but given there is no output schema it is mostly earning its place 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?

No output schema exists, and the description compensates by naming the returned fields (instrumentName, currency, optionType, deribitMarkPriceCoin, deribitMarkIvPct, bsPriceCoin, priceDiscrepancyPct, available) and the error path. Combined with clear usage triggers and a 100%-covered schema, an agent has everything needed to call and interpret it correctly.

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

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

Schema coverage is 100%, so the parameter documentation burden is already met; the description adds context beyond that by giving a concrete instrument format and clarifying that the name must come from an external options chain. It does not elaborate on riskFreeRatePct semantics, but the schema's default-0 convention note 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+resource (Black-Scholes theoretical price and Greeks for a live Deribit instrument) and explicitly positions itself against its nearest sibling: 'Returns everything workflow.run_black_scholes does, plus...'. It also names the shape of the answer (priceDiscrepancyPct trust-check), so an agent can distinguish it from both the static BS tool and adjacent option workflows like run_implied_volatility.

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 and quoted user phrasings ('is this option fairly priced?', 'what are the Greeks on this contract?') plus the required precondition that the user supply a specific instrument name. It also states what this tool does NOT do ('this tool does not browse the chain, it prices one named instrument'), which routes the agent away from 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 readOnlyHint=true, destructiveHint=false and openWorldHint=false. The description adds real value beyond that: no live lookup is required (pure constant-product math with pump.fun's official virtual-reserve constants) and it discloses the partialFill edge case when a buy exceeds remaining capacity.

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 identity and mechanics before the usage examples and return list. The return-field enumeration is dense but every element earns its place given there is no output schema; slightly list-heavy.

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

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

With no output schema, the description enumerates the return values (tokensOut, priceImpactPct, progressPctBefore/After, willGraduate, partialFill) and explains partialFill's meaning. Inputs, scope, and outputs are all covered for a two-parameter pure-math tool.

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

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

Schema description coverage is 100% and both parameters are documented there, so baseline 3 applies. The description clarifies the model context (virtual-reserve constants) but adds no format, range, or unit detail for solToSpend or solRaisedSoFar beyond what the schema already states.

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

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

States a specific verb and resource ('Pump.fun-style bonding curve calculator') with sub-capabilities named: exact tokens out, price impact, graduation progress. It clearly distinguishes itself from the many AMM/pool siblings by scoping to tokens 'still on the curve (not yet graduated to a real AMM pool)'.

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 phrasing ('how many tokens do I get buying X SOL on this curve?', 'will this buy graduate the token?') plus an explicit scope boundary: works for curve tokens, not graduated AMM pools. An agent can route to it without 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 this a safe, read-only, closed-world computation, so the safety profile is covered. The description adds genuine value by disclosing the returned fields (breakevenPrice, totalFees), which matters because there is no output schema. It does not discuss fee defaults or numeric behavior, but that is largely delegated to the schema.

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

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

Front-loads the core purpose, then the usage rule, then the alternative routing, then the returns. Every sentence earns its place and nothing is redundant with structured fields.

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

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

With no output schema, the description compensates by naming the return fields. Combined with explicit scope boundaries and sibling routing, an agent has everything needed to select and invoke the tool correctly for a 6-parameter computation.

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 83%, so the schema already documents side, sizeBase, entryPrice, and the fee/contract-type parameters well. The description adds no syntax, units, or default information beyond what the schema provides ('covers all trading fees' only hints at the fee params). Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

States a specific verb and resource ('calculate the break-even exit price that covers all trading fees') and immediately constrains scope ('this alone, nothing else'). It also names the sibling tools it must not be confused with, so an agent can distinguish it without opening any schema.

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

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

Gives explicit when-to-use ('user asks only what price do I need to just break even') and when-not-to-use ('if the user also gave a stop/target or wants a full trade-safety check'), naming workflow.run_risk_reward and workflow.run_pre_trade_check as the alternatives. Routing is fully specified.

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, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description then adds genuinely new context: the return payload (state, accepted, direction, confidence, key_levels with VAH/VAL/VPOC, scenario_framing, invalidation level) and the delta option. It does not discuss cost/reproducibility tradeoffs of the candle-fetch path, which is a minor 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?

The definition is front-loaded with the concept and the accept-vs-fakeout framing, then the example, then the return contract. Every clause carries information; the return-field list is dense but functional. Slight compression could improve it, but there is no wasted filler.

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

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

For a read-only analytical tool with a fully documented input schema and no output schema, the description covers purpose, invocation context, and return shape, which is what an agent needs to call it. The absence of a stated alternative for overlapping 'breakout' questions is the only notable gap.

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

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

Schema description coverage is 100%, so the schema already documents all eight parameters, including enums and defaults. The description only echoes the optional buy/sell delta concept, adding little syntax or format meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description names a specific analytical concept (Market Profile breakout acceptance) and defines it precisely: did price hold beyond the value area/range or reject back inside (fakeout). This is far more specific than a generic verb+resource and clearly separates it from unrelated siblings like run_open_analysis. It stops short of naming a sibling it could be confused with, so 4 rather than 5.

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

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

The quoted example question ("did the break above VAH get accepted?") implies the triggering scenario, which is useful. However there is no explicit when-to-use vs when-not, no prerequisites, and no pointer to an alternative workflow for related questions (e.g., session structure). Usage is implied, not stated.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description usefully confirms this is a deterministic computation layered on an existing primitive and enumerates the computed outputs, though it says nothing about edge cases (e.g., zero/negative spread handling).

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

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

Front-loaded with purpose and trigger, but the 'compared with primitive.funding_arb' clause restates the first sentence, the math-primitive reference is an awkward sentence fragment, and the Returns list partly duplicates what the schema/verdict already implies.

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

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

With no output schema, the description correctly fills the gap by naming the returned fields (netYieldPct, grossProfit, netProfit, breakevenDays, verdict). It omits any note on expected input units beyond the schema or on what drives a 'marginal' classification, but is otherwise sufficient to call the tool.

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

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

Schema description coverage is 100%, so all six parameters (including the interval_hours enum and fee defaults) are already documented in the schema. The description only gestures at the funding-rate spread concept and adds no syntax or format detail beyond the schema.

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

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

States a specific analysis (delta-neutral carry trade / funding arbitrage) plus its distinguishing output (profitable/marginal/loss verdict), and explicitly names the sibling whose math it reuses. An agent can tell it apart from primitive.funding_arb and from workflow.run_funding_arbitrage 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 concrete trigger ('use when user asks "is this carry trade worth it?"') and a discriminator against primitive.funding_arb (plain-English verdict vs raw numbers). The named alternative, however, is not in the sibling list shown, so the routing hint is slightly off-target and there is no explicit when-not guidance.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=false, so safety is covered. The description adds genuine behavioral context beyond that: the two-step method, that residual ADF stats are compared to 1/5/10% critical values, and the exact returned fields (alpha, beta, t_stat, critical_values, cointegrated).

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

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

Three sentences, front-loaded with the method and the question it answers, then the return payload. Slightly verbose with the rhetorical parenthetical, but every clause carries information an agent would want.

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

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

With no output schema, the description responsibly enumerates the returned fields and the interpretation threshold logic, and the required parameters are fully documented in the schema. An agent can call and interpret this tool without further reference.

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

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

Schema coverage is 100% with only two parameters, and the schema descriptions already state the role of y (dependent variable) and x (second series, same length/dates). The description adds no format or ordering guidance beyond what the schema provides, so the baseline of 3 applies.

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

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

Names a specific statistical procedure (Engle-Granger two-step cointegration test) applied to a specific resource (a pair of price series), and frames the exact question it answers (shared long-run equilibrium / stationary spread). This distinguishes it cleanly from siblings like run_forex_correlation and primitive.hedge_ratio.

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 phrasing: 'are these two assets cointegrated?' and 'is this a valid pairs trade?' — a clear usage context. It does not, however, name sibling alternatives or state when not to use it (e.g. vs a plain correlation tool), so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds value beyond that by naming the return payload (finalCapital, totalEarned, apy, growthTable), which matters since no output schema exists. It does not mention rounding, interval assumptions, or error behavior, so it is short of excellent.

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

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

Three short sentences, zero waste, front-loaded with the operation and followed by usage triggers and return keys. Every sentence earns its place.

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

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

For a read-only projection tool with no output schema and a fully documented 5-param schema, the description covers purpose, triggers, and the four return keys, which is what an agent needs to invoke it correctly. Minor gaps remain around assumptions (e.g. that funding rate is held constant across intervals), preventing a 5.

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

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

Schema description coverage is 100%, so all five parameters are already documented in the schema, including the 8/1 interval enum and the reinvestPct default. The description only echoes units through its example ('0.01% funding for 90 days'), adding no real semantics beyond the schema. Baseline 3 applies when the schema carries the load.

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 ('Project capital growth from reinvesting perpetual futures funding income (compounding carry)'), which cleanly separates it from nearby siblings like run_carry_trade, run_funding_cost, and run_funding_arbitrage. An agent can identify the operation without reading 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?

Provides two concrete trigger utterances ('how much will I make compounding 0.01% funding for 90 days?' and 'what's my APY on this carry position?') that map directly to the intended use case, which is strong context. It stops short of naming when-not-to-use or pointing at an alternative sibling such as run_funding_breakeven, so it is not a full 5.

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

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

Annotations already mark this read-only, non-destructive and closed-world, but the description adds real behavioral context beyond them: the yield metric is price-scenario independent, covered-call upside is capped by a coin-denominated premium that still scales with price, and the protective-put floor is the true minimum across all settlement prices. That is substantive disclosure the annotations do not carry.

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

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

It is front-loaded with the strategy definition and the key yield metric before the scenario math, so the agent gets the gist immediately. The dense parenthetical formulas are informative but make it longer than strictly necessary, keeping 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?

With no output schema, the description compensates by enumerating the return fields (staticYieldPct, annualizedYieldPct, valueAtScenarioUsd, breakevenPrice, floorValueUsd, vsHoldingUsd). All 7 required params are documented, and the two strategy modes are explained, so an agent has everything needed to call and interpret it.

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

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

Schema coverage is high (88%), so the baseline is 3, but the description adds meaning the schema text lacks — it explains that the annualization uses 365/daysToExpiry, that spotEntry drives the covered-call breakeven, and that premium is coin-denominated and scales with scenarioPrice. This lifts it slightly above the schema-only 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?

The description names a specific verb and resource — computing covered-call yield / protective-put protection value for a Deribit BTC/ETH position — and explicitly distinguishes the two strategies it handles. An agent can tell it apart from siblings like run_options_payoff or run_spread_payoff from the text alone.

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

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

It gives concrete trigger phrases ("what annualized yield do I get selling covered calls on my BTC?", "how much does insuring my BTC with a put cost me?"), which clearly establishes when to reach for it. It does not, however, name alternative tools or state when-not-to-use it, so it stops short of a 5.

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

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

Annotations only declare read-only/no-destruct/open-world; the description adds genuinely load-bearing behavior: the complementary-binary assumption for the 'No' price, that fees can erase a spread and this is reported honestly via isArbitrage, and the critical caveat that the tool does not verify the venues quote the same bet. That last point is exactly the kind of limitation an agent must know before invoking.

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

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

Front-loaded with the core action, then the convention assumption, then the return fields, then the trigger phrase and the caveat. Dense but every clause carries information; the parenthetical about the 'No' convention is long but necessary.

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

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

With no output schema, the description carries the return burden and does so: it names isArbitrage, cost per $1 payout, guaranteed profit, ROI, and which side to buy where. Combined with the unverified-same-bet caveat, an agent has everything needed to call and interpret it.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the schema: feePctPerLeg's ability to flip isArbitrage to false, and the semantic intent of manualProbabilitiesPct (bypassing a live fetch). quotes/stakeUsd are largely restated from the schema, keeping this 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 ('checks 2-5 quotes ... for a guaranteed arbitrage') and pins the domain precisely: same real-world binary bet across prediction-market venues. It is unmistakably distinct from neighbors like run_prediction_market_edge or run_funding_arbitrage.

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

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

Explicitly routes on user intent ('Use when user asks "can I arbitrage this bet across venues?"'), and clarifies the two mutually exclusive input modes (live quotes vs manual probabilities). It lacks an explicit when-not, but the scope is clear enough that an agent can pick it confidently.

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, openWorldHint=false, destructiveHint=false, so the safety profile is covered. The description adds the return shape, which is useful, but says nothing about auth needs, compute cost, or failure modes for an inverse-contract edge case it hints at. Adequate but not rich.

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

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

Three sentences, front-loaded with the capability, then differentiation, then trigger phrases and returns. The middle sentence is slightly wordy ('output for the case where... is also wanted') but every sentence carries information.

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

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

Read-only, no output schema, yet the description enumerates the return fields (averageEntry, breakeven, per-level summary), which compensates for the missing schema. The main residual gap is the undocumented required 'side' parameter and edge-case behavior.

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

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

Schema coverage is 60% and the description adds no parameter meaning at all. It never mentions the required 'side' (long/short) parameter, nor contractType or the fee rates, and 'multiple fill prices and sizes' merely restates 'entries'. One point of clear guidance was available here (e.g. when side flips breakeven) and is absent.

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 ('DCA entry planner') and enumerates the exact outputs (weighted average entry price, breakeven, per-level contribution). It explicitly contrasts itself with the sibling primitive.average_entry, 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?

Gives an explicit selection rule ('use when breakeven or the per-level breakdown is also wanted, not just the bare average') and names the alternative tool plus the condition that selects it. Also supplies concrete trigger utterances for when to invoke.

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

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

Annotations already cover the safe-read profile (readOnlyHint, destructiveHint=false, openWorldHint=false), so the bar is lower. The description adds substantive method context: how correlated trials are handled (Kish's design effect) and the priority rule between trial_sharpes and n_trials. It doesn't state the trial_sharpes-priority caveat is enforced by the tool, but the intent is clear.

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

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

Front-loads method and the core question, then usage, then inputs, then return values. Efficient for a statistically dense tool, though the run-on sentence in the usage trigger is slightly heavy.

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

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

No output schema exists, and the description supplies the return fields (expected_max_sharpe, dsr, n_trials_effective) with plain-language meaning and the 0-1 range for dsr. For a four-parameter statistical tool with no output schema, this is complete enough to call correctly.

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

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

Schema coverage is 100%, so the schema already carries parameter semantics; baseline is 3. The description earns above baseline by explaining the conditional relationship (avg_correlation only meaningful with n_trials, lowers effective count) and asserting trial_sharpes takes priority over n_trials — semantics beyond the field descriptions alone.

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 statistical operation (deflating a Sharpe ratio for multiple trials) with the exact question it answers, and cites the method authors. Clearly distinguishable from sibling workflow.run_sharpe_stats, which computes plain Sharpe stats.

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

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

Explicit trigger questions ('is my backtested Sharpe ratio real, or did I get lucky') and an explicit selection rule between the two input modes (trial_sharpes most rigorous, else n_trials + avg_correlation). Nothing 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 cover the safety profile (readOnly, non-destructive), so the burden is lower, yet the description still discloses real behavioral traits: the confidence-vs-threshold feasibility constraint that triggers an exception, and edge-case semantics for xi, xi_asymptotically_normal, and es becoming null when xi>=1. It omits runtime/cost characteristics, but the error and domain conditions are unusually well documented.

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 operation and use case, which is good, but the trailing 'Returns:' block is a long, dense enumeration of six fields with heavy parenthetical citations. It is information-dense but borders on over-specification and would be better absorbed by an 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, no-output-schema tool, this covers method, use case, sibling differentiation, parameter meaning, error conditions, and return fields — an agent has what it needs to call it correctly. Not perfect only because return semantics are embedded in prose rather than a schema, and expected input format conventions (e.g., ordered series, sampling frequency) are left implicit.

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

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

Schema coverage is 100% and the schema already documents all three parameters, so the baseline is 3. The description goes beyond by explaining the domain meaning of threshold_percentile (percentile of the loss distribution, losses = -returns) and the cross-parameter constraint on confidence, adding interpretation rather than restating format.

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

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

States a precise verb and resource (fits a GPD to tail losses and extrapolates VaR/ES) and distinguishes itself from the sibling workflow.run_var_cvar by contrasting the distributional assumptions. An agent can route between the two 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 explicit triggering user phrasings ('what's my tail VaR without assuming normality?') and names the alternative tool (workflow.run_var_cvar) together with the condition that selects it — the fat-tailed case that normal parametric VaR understates. When-to-use and when-to-prefer-the-sibling are both present.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=false, so the safety profile is covered. The description adds only the return field, and does not disclose fee-handling behavior (feeOpenPct/feeClosePct defaults) that meaningfully affects results. Adequate but not rich 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?

Three tight sentences: purpose first, usage examples second, return value last. Zero waste; every sentence earns its place, and the return declaration compensates for the missing 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 9-param calculation tool with no output schema, the description covers purpose, triggering conditions, and the returned field, while annotations carry safety and the schema carries parameters. Only nuanced behavior (fee effects on the result) is unaddressed.

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 89%, so the schema already documents nearly all parameters, including the targetMode and contractType enums and fee defaults. The description adds no syntax or semantic detail beyond what the schema provides; baseline 3 applies.

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

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

States a precise verb+resource: 'Calculate the exact exit price needed to hit a target PnL or ROE percentage.' This is clearly distinct in intent from breakeven/scale-out siblings, but no sibling is named explicitly to route the agent.

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

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

Provides concrete user-question triggers ('at what price do I take profit to make $500?', 'where should I set TP for 20% ROE?'), which clearly signal when to use it. No when-not guidance or named alternatives (e.g. breakeven planning) are given.

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, non-destructive, and non-open-world behavior. The description adds meaningful context beyond that: it specifies the calculation method (plain arithmetic mean) and lists the exact return fields (totalUnits, totalCost, avgEntry). It does not address edge cases like empty fills, but for a simple averaging read operation the added computation and return detail is substantial.

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

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

The description is front-loaded with the core operation, follows with the rationale that differentiates it from the crypto sibling, then gives the trigger and return fields. Every clause earns its place and there is no 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?

For a simple two-parameter read-only averaging tool with full schema coverage and annotations, the description is complete: it explains the computation, provides a usage trigger, and enumerates the return values. No output schema exists, so specifying the return fields fills the remaining gap.

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

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

Schema description coverage is 100%, and the schema already documents both 'pair' (BASE/QUOTE format) and 'fills' (price and units). The description does not add further parameter syntax, constraints, or formatting details, so the baseline of 3 applies.

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

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

States a specific verb and resource: 'Size-weighted average entry price across multiple forex fills.' It explicitly distinguishes itself from the sibling crypto average_entry tool by contrasting arithmetic and harmonic means for inverse contracts, so an agent can tell them apart 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 an explicit trigger phrase: 'Use when user asks what's my average entry after these fills?'. It also implicitly sets boundaries by noting forex has no coin-margined analog, pointing to the crypto average_entry tool for that case. However, it does not explicitly state when not to use this tool or name the alternative as a direct replacement.

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 a read-only, non-destructive, closed-world calculation, and the description adds real behavioral context beyond that: commission is per standard lot in the quote currency and the commission-in-pips result is independent of position size by construction. It also previews the return shape. Does not discuss error cases or assumptions on spread handling, keeping it below 5.

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

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

Front-loads the definition, then the domain nuance, then a 'Returns:' list. The commission-scaling sentence is dense but earns its place by explaining why the pip figure is size-independent. Slightly overpacked but 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?

No output schema exists, so the description compensates by naming the returned fields (pipSize, commissionPips, totalCostPips, breakevenPrice). Inputs are adequately framed. Complete enough to call correctly, though edge cases (e.g. missing commission default behavior) are only implied.

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 60% schema coverage, the description usefully explains the semantics of commissionPerLotRoundTrip (per standard lot, pair's quote currency, default of 0 implied) and how it interacts with lot size. It adds meaning over the bare schema. Schema already documents pair, spreadPips, and the side enum, so it does not need to repeat those.

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

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

States a specific verb+resource: computes forex breakeven price accounting for spread and round-trip commission, quantified in pips and price. This clearly separates it from generic computation siblings, though it never names a specific sibling (e.g. run_forex_pip_value or run_breakeven_planning) to disambiguate.

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

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

Provides an explicit trigger: 'Use when user asks where's my true breakeven after spread and commission?'. This is clear usage context, but there are no exclusions or stated alternatives among the many run_forex_* / breakeven siblings.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=false, so safety is covered. The description adds genuinely non-obvious behavior: computation is on daily % returns rather than raw levels, the hedgeRatio uses Hull's cov/var formula, and no live fetch occurs. It stops short of 5 only because it doesn't discuss edge cases (e.g., zero variance, minimum series length enforcement) that an agent invoking with borderline inputs would want.

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 operation and the key no-fetch constraint, and the return values are summarized last. The parenthetical justification of % returns and the quoted formula explanation are slightly verbose, but each sentence 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?

For a pure-computation tool with no output schema, the description supplies the algorithmic method, the input shape requirement, the alternative sibling, and an explicit 'Returns: n, correlation, hedgeRatio' summary. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema by clarifying that the series are transformed to daily % returns before computing and that both must be of 'matching length' — a constraint the schema states but the description explains the reason for. It does not document the 5-item minimum beyond what the schema declares.

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

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

States a precise verb+resource (correlation coefficient and minimum-variance hedge ratio between two price series) and immediately distinguishes itself from workflow.run_forex_correlation_live by naming the sibling and the condition that selects it ('No live data fetch: supply the two price series directly'). 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?

Explicitly states the use condition ('Use when user already has two price series and wants their statistical relationship') and names the alternative (run_forex_correlation_live) with its contrasting capability ('both series fetched automatically for two named pairs'). This is the when/when-not/alternatives pattern at full strength.

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

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

Annotations only cover safety (readOnly/openWorld/not destructive); the description carries substantial extra behavior: ECB reference source, business-days-only data, date-aligned series, computation on daily % returns, the specific Hull formula behind hedgeRatio, and explicit failure semantics ('available: false + error if either pair has no data, or too few dates overlap').

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

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

Well front-loaded: purpose, then data/compute method, then when-to-use, then returns. Dense but nearly every sentence earns its place; the inlined Hull formula quotation is the only slightly verbose element.

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

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

With no output schema, the description fully documents the return contract (n, correlation, hedgeRatio, available + error conditions), the data window semantics, and failure modes. Nothing material for a correct call 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 baseline is 3, but the description adds real meaning beyond the schema: pairs are aligned by matching date, days is calendar days that yield fewer business-day points, and the required BASE/QUOTE format is reinforced. Adds value on top of an already-documented schema.

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

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

States a specific verb+resource (correlation coefficient and minimum-variance hedge ratio between two forex pairs) and the data provenance (live, frankfurter.app ECB daily series). It is clearly separable from its non-live sibling run_forex_correlation and from primitive.hedge_ratio.

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 questions ('how correlated are EUR/USD and GBP/USD?', 'what hedge ratio should I use?') and explains the live-fetch context. It does not explicitly name the alternative to use for historical/static data, which is the one clear gap.

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, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds the key behavioral trait that this is a pure, deterministic computation with no network fetch and a caller-supplied rate. It loses a point because 'Returns: converted' is an empty restatement rather than any useful detail about the result.

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

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

Three short sentences, front-loaded with the core behavior and the sibling routing. Every sentence carries weight except the trailing 'Returns: converted', which is filler and slightly dilutes an otherwise tight definition.

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

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

For a two-parameter, non-destructive, deterministic conversion with no output schema, the description covers the mode of operation and when to pick it. The only gap is that the return shape is not meaningfully described, though for a simple converter that is a minor omission.

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

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

Schema description coverage is 100% and both parameters (rate, amount) are documented in the schema with directional semantics for the rate. The description adds only the 'manually supplied' framing, which does not extend the parameter meaning beyond what the schema already supplies, so the baseline 3 applies.

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

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

States a specific verb (Converts) and resource (amount between currencies) plus the defining constraint: a manually supplied rate, no live fetch. It explicitly names the sibling it is not (workflow.run_forex_currency_converter_live), so an agent can separate the two without opening either schema.

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

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

Gives an explicit selection condition ('Use when user already knows the exact rate they want applied') and names the alternative tool that should be chosen otherwise. This is exactly the routing guidance a sibling-heavy namespace needs, since many forex siblings exist.

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

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

Goes well beyond the readOnly/openWorld annotations by disclosing the two-tier data pipeline (TrueFX live ticks for 10 majors, frankfurter.app ECB daily fallback for all other pairs, 30 total), and the failure behavior (available=false + error when no rate exists). This is exactly the operational context an agent needs for a live-data tool.

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

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

Front-loaded with the core purpose, then source tiering and usage guidance, then return fields. Dense but every sentence carries information; the parenthetical 'genuinely live tick data' is slightly chatty but justified as differentiation.

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

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

No output schema exists, and the description compensates by enumerating the returned fields (converted, rate, source, asOf, available + error). Combined with source-tier and failure disclosure, nothing needed to invoke or interpret the call 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 baseline is 3, but the description adds value the schema does not: it scopes which currency pairs are served and how each tier is sourced, which matters for choosing from/to codes. It does not add format syntax beyond the schema, so it stops short of 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 (convert an amount between currencies) and immediately distinguishes itself from its non-live sibling workflow.run_forex_currency_converter by naming the live-rate mechanism. An agent can tell which of the two converter tools applies 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 a concrete trigger ('what's $X worth in EUR?') and a useful exclusion ('where the rate itself isn't already known'). It does not explicitly route against the non-live sibling, but the live-rate framing provides clear context for selection.

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

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

Annotations already declare this a safe, read-only, non-open-world calculation, so the bar is low. The description still adds real value by disclosing the usedMargin=0 edge case and the deliberate null-instead-of-Infinity return, which an agent cannot infer from annotations or schema alone.

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 formula, then usage triggers, then return values, then the edge case – a sensible ordering. It is slightly dense with three separate concerns, but every clause carries information and 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?

With no output schema, the description compensates by listing the returned fields (freeMargin, marginLevelPct). Combined with the formula, edge-case note, and usage triggers, an agent has everything needed to call and interpret this tool.

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

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

Schema coverage is 100%, so both parameters are already documented, giving a baseline of 3. The description adds the relationship between them (equity divided by usedMargin times 100) and clarifies that usedMargin being 0 means no open position, which enriches semantics beyond the schema.

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

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

States the exact computation (equity/usedMargin*100) and names the resulting metrics (freeMargin, marginLevelPct), so the agent knows precisely what is produced. It also implicitly separates itself from the sibling run_forex_margin_required by framing itself as the stop-out proximity metric rather than a margin requirement calculation.

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

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

Gives concrete trigger phrasings ("how close am I to a margin call?", "what's my free margin?") that map directly to invocation. It does not explicitly name alternatives such as run_forex_margin_required for exclusion, but the usage context is unambiguous.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=false, destructiveHint=false, so the safety profile is covered. The description adds real behavioral context beyond that: it is a self-contained pure computation needing no live FX rate, and it enumerates the return fields (notionalQuote, marginQuote, base, quote). It stops short of stating units/precision conventions, hence a 4 rather than 5.

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

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

The opening sentence and the alternative-tool sentence are well front-loaded and actionable. However, the sentence 'Never built for Phase 1 of this domain since a margin figure has no natural currency-neutral form the way pip value does' is internal design rationale that does not help an agent decide or invoke, weakening the signal-to-noise ratio.

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

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

With no output schema, the description helpfully lists the returned fields and chains to the sibling variant. For a four-parameter read-only calculation this is nearly complete; only unit/tolerance conventions and the lots-vs-units question are left unaddressed.

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

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

Schema description coverage is 100%, so all four parameters are already documented, which sets the baseline at 3. The example ('X lots ... at 50:1') loosely maps units and leverage, but it also introduces 'lots' while the schema says 'units in base-currency units' — an unreconciled mismatch rather than added clarity.

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: computes notional and margin required for a forex position, and pins down the currency form ('pair's own quote currency: no live FX rate needed'). It clearly distinguishes itself from the sibling workflow.run_forex_margin_required_live, so an agent can pick 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?

Explicitly names the alternative (the _live variant) and the selecting condition ('when the account currency differs from the pair's quote currency'), and even supplies a concrete trigger query ('how much margin do I need for X lots of EUR/USD at 50:1?'). Both when-to-use and when-to-use-the-other are covered.

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

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

Annotations already cover the safety profile (readOnlyHint, destructiveHint=false, openWorldHint). The description adds real value beyond them: it names the external FX source (TrueFX/frankfurter.app) and discloses the failure mode (available=false + error when no rate is found), which an agent needs to handle the open-world dependency.

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

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

Front-loads purpose, then usage, then return fields in three dense sentences; the output-field enumeration is long but earns its place given there is no 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?

With no output schema, the description compensates by enumerating the added return fields (accountCurrency, notionalAccount, marginAccount, fxRate, fxSource, available) and the error condition, so an agent knows both input and output contract.

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

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

Schema description coverage is 100%, so all five parameters are already documented; the description only restates accountCurrency's role and lists output fields. 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+resource (notional and margin required for a forex position) and the exact scope qualifier (converted to account currency via a live FX rate). It also explicitly distinguishes itself from workflow.run_forex_margin_required, which it extends.

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

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

Gives a concrete trigger ("how much margin do I need in my account currency?") plus the selecting condition (account currency differs from the pair's quote currency), and names the non-live alternative for the other case.

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 it as a safe read-only operation. The description adds useful context beyond annotations: no live FX rate needed, pip size conventions (0.0001 vs 0.01), and the conditions when the live variant is required. However, it does not document error cases or limitations (e.g., unsupported pairs).

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?

Information is front-loaded and reasonably efficient, but slightly verbose with parenthetical explanations and a meta-comment about verification. Every sentence contributes, though some could be tightened.

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

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

Complete for a simple 2-parameter read-only calculator: covers purpose, the key alternative, and output fields. With no output schema, it lists the returned fields, which is helpful. Minor gap: no explicit handling of invalid pair formats or edge cases.

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 both parameters. The description provides example output naming and the pip size convention, but doesn't add format details for the parameters beyond what the schema says. Baseline 3 is appropriate.

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

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

States a specific verb+resource: the value of 1 pip for a forex pair and position size, clearly denominated. Distinguishes itself from the live sibling and scopes the calculation to the pair's own quote currency.

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

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

Explicitly names the alternative (workflow.run_forex_pip_value_live) and the condition that selects it (account currency differs from quote currency). Also gives a natural-language usage trigger.

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 and openWorldHint, so the safety profile is covered. The description adds real behavioral value beyond that: the two data sources (TrueFX live ticks for 10 majors, frankfurter.app ECB daily fallback for the other ~30 currencies) and the availability/failure contract (available=false plus error when no rate exists).

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

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

Front-loads the core purpose and the key routing rule before the data-source and return-value details. Dense but each clause carries information; the sourcing/return enumeration is slightly long but earns its place given there is no 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?

There is no output schema, so the description compensates by enumerating the return fields (accountCurrency, pipValueAccount, fxRate, fxSource, available/error). Combined with the routing rule and data-source disclosure, an agent has everything needed 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 description coverage is 100%, so all three parameters are already documented in the schema, giving a baseline of 3. The description reinforces how accountCurrency drives the FX conversion and that units is a base-currency position size, but adds no syntax or format detail beyond the schema.

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

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

States a specific verb and resource: computes the value of 1 pip for a forex pair and position size, converted to an account currency via a live FX rate. It explicitly distinguishes itself from the sibling workflow.run_forex_pip_value and names the exact use case.

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 ('Use when user asks what's 1 pip worth in my account currency?') and an explicit exclusion with the alternative: when the account currency matches the pair's quote currency, use workflow.run_forex_pip_value alone. Nothing is left to inference.

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

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

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false), so the bar is low. The description usefully adds return semantics (pips signed, positive favors the position taken) and output fields (pnlQuote), but says nothing about quote-currency conversion behavior or handling of open vs closed trades.

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

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

Two tight sentences: the first defines the output and scope, the second gives usage triggers, then a terse returns clause. Front-loaded, zero waste, no repetition of schema.

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

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

With no output schema, the description appropriately names the return fields (pips, pnlQuote) and their sign convention, and covers required inputs conceptually. It is complete enough to call correctly, but the missing price-field format details and open-vs-closed trade handling leave a modest gap for a 5-param, fully-required tool.

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

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

Schema description coverage is only 40% – pair and units are documented in the schema, while side, entryPrice, and exitPrice are bare. The description partially compensates by referencing 'X pips', 'Y lots', and 'pair's own quote currency', but adds no format or unit guidance for the price fields, so it neither fully covers the gap nor is irrelevant.

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 computed resource (forex PnL in pips and quote currency) with an explicit scope (closed or hypothetical trade, long or short). Distinguishes itself from sibling run_forex_pip_value by combining pips and money PnL, but never names a sibling to differentiate, so it falls short of a 5.

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

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

Gives concrete when-to-use cues via example user phrasings ('what did I make/lose on this trade?', 'what would X pips be worth on Y lots?'). It does not, however, say when NOT to use it or route to alternatives like run_forex_pip_value or run_forex_risk_reward, which matters given the dense forex sibling cluster.

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

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

With annotations already covering read-only and open-world safety, the description adds meaningful behavioral context: it uses a live external FX source, converts pip value into the account currency, and returns available=false plus an error when entry equals stop or no rate is found.

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

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

Front-loads the core computation before justifying the account-currency requirement, and the return fields are grouped at the end. The middle rationale sentence is slightly dense but earns its place by preventing misuse of the tool without a currency context.

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 five-parameter live workflow with no output schema, the description supplies the essential missing context: the FX-rate dependency, required account currency, return field names, and failure conditions. Enough for an agent to invoke it correctly without further documentation.

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

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

Schema coverage is 60%, so documentation must compensate. The description clarifies that riskAmount is expressed in accountCurrency, that stop distance is derived from entryPrice/stopPrice, and that a live rate converts pip value into that currency. It still does not define entry/stop directionality or pair-specific edge cases.

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

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

States a specific computation—position size in units and lots from risk amount and stop distance—and ties it to a live FX conversion. It distinguishes itself from generic position-sizing and other forex tools by naming the live-rate dependency and the account-currency requirement.

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

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

Gives a concrete user-facing trigger: 'how many lots should I trade to risk $X on this setup?', and explains why accountCurrency is non-optional. It does not explicitly compare against the non-live forex position-size siblings or state when to prefer this live variant over them.

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

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

Annotations already establish this is a safe, closed-world read, and the description goes further by disclosing output semantics: ratio is a raw number, not a verdict, and is null in two distinct conditions (stop at entry, validSetup false). It does not state units beyond pips or formatting of the ratio.

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

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

Front-loads the core computation, then the null-ratio caveats, then the return list. Dense but every clause carries information; only the trailing "Returns:" enumeration is somewhat redundant.

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

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

With no output schema, the description does the work of naming the return fields (riskPips, rewardPips, validSetup, ratio) and explaining the null cases. Adequate for a 5-param calculator; a few numeric-format details are the only missing piece.

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 only 20% (only pair is documented), so the description must carry the load. It usefully explains how stopPrice/targetPrice relate to entryPrice for a given side via the validSetup discussion, but gives no detail on price format, quote convention, or precision for the numeric fields.

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 precise verb+resource: computes risk/reward distance in pips from entry, stop and target, plus the ratio. The forex/pips framing implicitly separates it from the generic workflow.run_risk_reward sibling, but that differentiation is never made explicit.

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

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

Gives a concrete routing cue ("what's my risk/reward on this setup?") and a strong precondition: check validSetup before trusting the ratio, since ratio is null when the stop sits at entry or the stop/target are on the wrong side. It stops short of naming alternative siblings for related questions (e.g. pip value, position sizing).

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

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

Annotations already establish read-only, non-destructive, closed-world behavior, so the safety profile needs no repetition. The description adds genuinely useful semantics the annotations cannot carry: the pip deltas are signed by actual price direction and are not pre-adjusted for side, plus the returned field shape. It stops short of describing edge cases or constraints on delta ranges.

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

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

Three tight sentences: the core computation first, the trigger phrase second, the return shape last. Zero filler, and the sign-convention caveat is embedded where the agent will read it rather than buried.

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

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

With no output schema present, the description usefully names scenarios[] and its fields, and it pins down the sign convention that would otherwise cause wrong calls. It omits any mention of pip definition per pair or limits on the delta list, which are minor given the pip-value siblings exist.

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 only 60%, so the description must compensate, and it does for the two riskiest parameters: it clarifies that deltasPips are raw signed moves and that a single side (long or short) applies per call. It does not address entryPrice or units beyond what the schema already states, leaving some coverage gap.

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

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

States a specific computation (PnL across a range of hypothetical pip moves) for a specific resource (a single forex position, long or short), which an agent can distinguish from the many sibling workflow tools. It does not, however, explicitly contrast itself with the closest siblings such as run_forex_pnl or run_scenario_planning, so differentiation is left to inference.

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

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

Provides a concrete trigger phrase ("what if price moves X pips in either direction?") that tells the agent when to reach for this tool. There is no explicit when-not guidance or named alternative (e.g., use run_forex_pnl for a single realized PnL), so routing among the dense set of forex siblings is only partially supported.

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

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

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false), so the bar is lower; the description nonetheless adds real behavioral context: swap rates are broker-set with no free live feed, so swapPerLotPerNight is always a manual input quoted per standard lot, and the sign convention (negative=cost, positive=credit). It does not need to explain return format beyond the field list it already gives, but it stops short of noting anything about precision/rounding.

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 the manual-input caveat, sign convention, sibling disambiguation, trigger phrase, and return fields – well ordered and each sentence carries information. Slight redundancy with the schema on the negative/positive convention keeps it from a 5.

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

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

For a 4-required-parameter computation tool with no output schema, the description supplies the missing pieces: currency context for the result, the manual-input rationale for the only non-obvious parameter, the sign convention, the sibling routing rule, and the returned field list (lots, totalSwapQuote, base, quote). An agent has everything needed to call and interpret it.

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

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

Schema coverage is 100%, so baseline is 3; the description earns above that by explaining why swapPerLotPerNight is manual (no live source), that it is quoted per standard lot and mirrors how commission is quoted in workflow.run_forex_breakeven, and by reinforcing the negative/positive sign semantics. This adds genuine meaning beyond 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+resource ('total swap/rollover cost for holding a forex position overnight') with the unit of account (pair's own quote currency) and explicitly names the sibling it is not (workflow.run_forex_swap_cost_live). An agent can distinguish it from the many other forex workflow 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?

Gives an explicit trigger ('Use when user asks "how much will holding this position overnight cost me?"') and a routing rule to the alternative ('The live variant ... applies when the account currency differs from the pair's quote currency'). Both when-to-use and when-to-use-the-other are covered.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety and network profile is covered. The description adds real value beyond that: it names the live FX source (same as other forex _live tools), discloses the failure mode (available=false + error if no rate found), and explains why swapPerLotPerNight must be supplied manually (broker-set, no free live feed).

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

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

Front-loads the definition of the returned metric and the usage trigger, and the return-value sentence is compact. Slightly dense in the middle (FX source asides), but nearly every clause carries information an agent needs.

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

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

No output schema exists, yet the description enumerates the extra return fields (accountCurrency, totalSwapAccount, fxRate, fxSource, available) and the error case, and explains what the non-live sibling already returns. Nothing an agent needs to call or interpret this tool is missing.

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

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

Schema description coverage is 100%, so all five parameters are already documented, including the sign convention for swapPerLotPerNight. The description only reinforces that swapPerLotPerNight is a manual, broker-set input—useful but not additive over the schema's own detail. Baseline 3 applies.

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

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

States a specific output (total swap/rollover cost converted to account currency) and names the exact condition that separates it from its sibling workflow.run_forex_swap_cost (live FX conversion to a non-quote account currency). An agent can pick this tool apart from the non-live variant 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 with a quoted user question ('how much will holding this position overnight cost me in my account currency?') plus the qualifier that it applies when the account currency differs from the pair's quote currency. It also implicitly routes to workflow.run_forex_swap_cost when no conversion is needed.

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, openWorldHint=false, destructiveHint=false, so the safety profile is covered. The description adds genuinely new behavioral context: this tool returns bare numbers with no interpretation, and it lists the three values produced. It does not discuss defaults for the optional intervalHours/transferFeePct or edge cases like negative rates, 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-loads the computation and its outputs, then routes to the sibling, then gives trigger phrasings — good ordering. The trailing 'Returns: netProfitUsdt, annualizedYieldPct, breakevenDays' partially repeats the opening sentence's output list, 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?

With no output schema, the description correctly compensates by naming the returned fields, and the input schema fully covers all six parameters. What is missing is guidance on optional-parameter defaults and behavior on unusual inputs, but for this calculation tool an agent has enough 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 description coverage is 100%, including the enum for intervalHours and the positive/negative sign convention for both funding rates, so the schema carries the parameter burden. The description adds no syntax, units, or defaults beyond what is already documented, making the baseline 3 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 ('Calculate funding rate arbitrage profit: annualized yield, net profit, and breakeven days for a long/short basis trade across two exchanges') and explicitly names the sibling it is not (run_carry_trade). An agent can separate it from run_funding_breakeven, run_compound_funding, and run_cross_venue_arbitrage 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?

Names the alternative tool and the exact condition that selects it ('For the same math plus a profitable/marginal/loss verdict, use workflow.run_carry_trade instead'), and gives concrete user phrasings that should route here. When-to-use, when-not-to-use, and the alternative are all 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 readOnlyHint, non-destructive, and closed-world, so the safety profile is covered. The description adds the return field names, which is useful given no output schema, but says nothing about unit conventions, sign of requiredMovePct, or how holding period interacts with discrete funding periods.

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

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

Three short sentences, purpose front-loaded, examples then return keys. Efficient, though the quoted example questions are slightly verbose relative to the rest.

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 8-parameter compute tool with no output schema, the description supplies return field names and triggering intent, and the schema documents the rest. It is nearly complete, with only units/sign conventions for the returned values left implicit.

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 88% and contractType explicitly documents denomination behavior, so the schema carries the load. The description adds no parameter-level detail beyond 'holding period', so the baseline 3 is appropriate.

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

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

The first sentence names a specific computation (price move needed to cover funding + fees over a holding period), which an agent can distinguish from generic 'breakeven' siblings. It does not explicitly differentiate from run_breakeven_planning, run_funding_cost, or run_compound_funding, which are the closest neighbors.

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?

Two concrete example user phrasings are given, which map cleanly to invocation triggers. There are no explicit exclusions or named alternatives (e.g. use run_funding_cost instead when only the cost figure is wanted), so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, so the safe-computation profile is covered. The description adds real value beyond that by documenting the sign convention of the result (negative = pay, positive = receive), which is not derivable from annotations.

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

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

Three tight sentences with the purpose front-loaded, followed by usage triggers and return semantics. No filler; every clause carries information.

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

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

With no output schema, the description correctly compensates by naming the returned fields and their sign convention. Params are largely self-documented, so the main gap is minimal – an agent has enough 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 description coverage is 83%, with required params (side, sizeBase, entryPrice, fundingRate, days) and the contractType semantics already documented in the schema. The description adds no per-parameter detail beyond what is in the structured fields, 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+resource: calculating total funding cost/income for holding a perpetual futures position. The title and description align and the scope is unambiguous. It does not explicitly distinguish itself from close siblings like run_funding_breakeven or run_compound_funding, but the holding-period framing is distinctive enough.

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

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

Gives concrete trigger phrasing ("how much funding will I pay holding X days?", "is funding eating my profit?"), which tells an agent when to reach for this tool. It stops short of naming alternatives or conditions where another funding-related tool should be used instead.

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, non-destructive, closed-world), and the description adds a meaningful expectation caveat that the output is a backward-looking fit rather than a forecast guarantee. It also enumerates the returned fields, which no structured field provides.

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 compact sentences ordered purpose, routing cues, caveat, returns; nothing is repeated from the title or schema, and the return list compensates for the absent 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?

With no output schema, the description compensates by enumerating returned fields, and the single parameter is fully documented in-schema. It is nearly complete for a single-input statistical tool; only an explicit pointer to sibling volatility tools 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 sole parameter's minItems constraint plus rationale (at least 50 values needed to identify persistence) is already documented in the schema. The description adds no syntax or preprocessing detail beyond what the schema states, so the baseline 3 applies.

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

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

States a specific model (GARCH(1,1) fit by maximum likelihood), names the estimated quantities (omega/alpha/beta) and the output (next-period volatility forecast). This clearly separates it from siblings like run_implied_volatility or run_evt_tail_risk.

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 user phrasings that should route here and sets a boundary that it is a statistical fit, not a prediction guarantee. It does not name alternative volatility tools (e.g. implied volatility, EVT tail risk) as an explicit when-not branch, so it falls short of a 5.

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

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

Annotations already declare a safe read-only, closed-world, non-destructive operation, so the bar is lower. The description adds real behavioral value beyond that: the interpretation bands (H>0.5, H<0.5, H~0.5) and the critical input constraint that it takes a return series, not raw price levels, which directly affects correct invocation.

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 computation, then usage triggers, then the input caveat and return shape. Dense but almost every clause earns its place; the interpretation parentheticals are slightly verbose but useful for interpreting output since no output schema exists.

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

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

With no output schema, the description compensates by enumerating the return fields (hurst, interpretation, window_sizes, rs_values) and the meaning of the interpretation values. Combined with the input constraint and usage triggers, an agent has everything needed to call and interpret this tool.

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

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

Schema description coverage is 100% and the input constraint 'Return series (not raw price levels)' is already present in the schema for values. The description restates this same constraint rather than adding syntax or guidance on min_window beyond what the schema default already provides, 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 – computing the Hurst exponent via rescaled-range (R/S) analysis – and immediately distinguishes itself from siblings like run_garch and run_cointegration by naming the exact diagnostic it performs. The parenthetical interpretation thresholds give the agent a concrete sense of the output's meaning.

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

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

Provides explicit trigger phrasing ('is this asset trending or mean-reverting?', 'does this series show long-range dependence?') that maps a user question directly onto the tool. It doesn't name alternative tools or when NOT to use it, but the triggering questions are specific enough to route correctly among the 60+ workflow siblings.

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

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

Annotations already declare this is a safe, non-destructive, closed-world read, and the description adds substantial behavior beyond that: sign invariant (impermanentLossPct is always <= 0), normalization frame (relative to the quote token, dimensionless), the concentration caveat (IL worse than full_range when tight, position becomes fully single-asset and fee-less once price exits the range), and the stable-quote assumption behind the optional USD figures.

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

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

Front-loads the core definition and mode split before the trigger phrasing and return list, and nearly every clause carries information. It is a single dense block with the textbook closed form noted parenthetically, which is arguably more formula detail than an agent needs to select the tool.

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

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

With no output schema but a 7-parameter, mode-dependent computation, the description compensates by listing the returned fields (impermanentLossPct, lpValueMultiplier, hodlValueMultiplier, inRange, lossUsd/netResultUsd) and noting when they are null. Mode requirements and range constraints are covered between description and schema, leaving no material gap for 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 genuine meaning the schema lacks: what 'mode' actually selects between, why the concentrated bounds change the economics, and what the dollar outputs assume. It does not restate the schema's own constraints verbatim, which is the right call.

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 ('Impermanent loss for a liquidity-pool position: compares providing liquidity against simply holding the same tokens') and enumerates the two computation modes with their distinct formulas. The phrase 'manually-supplied entry and current price' implicitly separates it from the sibling workflow.run_impermanent_loss_live, so an agent can route between them without opening either schema.

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

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

Gives concrete user-facing triggers ('how much am I losing to impermanent loss?', 'is this LP position still worth it after fees?'), which tells the agent when to select it. It does not state exclusions or name the live variant as the alternative for auto-fetched prices, so it stops 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 readOnlyHint, destructiveHint=false, and openWorldHint=true, covering the safety profile, so the description's added value is the failure surface: 'routable (false + error if either token's price can't be resolved)' and the invariant that entryPrice is never overwritten by a live quote. It stops short of describing latency, caching, or chain-specific resolution behavior, which matters for an open-world price fetch.

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 distinction (live price derivation vs. manual), followed by the usage condition and the return deltas. The parenthetical rationale about not overwriting entryPrice is slightly discursive but earns its place by preventing a plausible caller error; overall still efficient.

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

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

With no output schema, the description compensates by naming the returned deltas (currentPrice, baseSymbol, quoteSymbol, routable) and the error condition. Combined with 100% schema coverage and read-only/open-world annotations, an agent has everything needed 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 description coverage is 100%, so the schema already documents all 10 parameters including entryPrice as 'manual - a historical fact'. The description reinforces why entryPrice stays manual and clarifies that currentPrice is derived rather than an input, but adds no new syntax, units, or default guidance beyond what the schema/enums already provide. 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 concrete verb+resource (fetches each token's current live USD price and derives currentPrice as their ratio) and explicitly frames itself as the live variant of workflow.run_impermanent_loss, which is itself in the sibling list. An agent can distinguish it from both the non-live variant and unrelated workflow 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?

Gives an explicit selection condition: 'Use when the caller has the pool's two token addresses but doesn't already know the current price ratio.' It also contrasts behavior with workflow.run_impermanent_loss (manual price supplied there, derived here), effectively naming the when-not case.

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

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

Annotations only cover the read-only/non-destructive safety profile, and the description adds substantial behavioral context: the numerical method (Newton-Raphson with bisection fallback), the failure modes it handles (flat vega, deep ITM/OTM, short-dated), and the explicit refusal behavior with converged:false + error rather than a garbage result.

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

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

Front-loads the core purpose, then layers failure handling and usage routing in two compact follow-ups. Every clause carries information: algorithm choice, edge-case handling, and return shape.

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

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

With no output schema, the description enumerates the return fields (impliedVolatilityPct, iterations, method, converged, priceAtSolution), and it covers failure semantics, so an agent has everything needed to call and interpret the tool.

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

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

Schema description coverage is already 83%, so the schema documents the inputs well. The description only references spot/strike/rate in passing for the no-arbitrage bounds and adds no syntax, units, or format detail beyond the schema, so baseline 3 applies.

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

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

States a precise verb+resource: solving for the volatility that makes Black-Scholes reproduce an observed price. It clearly differentiates from the sibling run_black_scholes by inverting the direction of the computation ('not the reverse').

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 ('what IV does this option price imply?' or a market price with volatility wanted) and an exclusion via 'not the reverse', which routes away from the forward-pricing sibling. It stops short of naming the alternative tool explicitly.

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

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

Annotations already declare readOnly/non-destructive, so the safety profile is covered. The description adds genuine behavioral context the annotations don't: the closed-form formula, the boundary behavior that lambda > 2 yields probability 1 rather than the raw formula value, and what is returned. It stops short of discussing numerical edge cases like alpha approaching 0/1.

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 reference and formula, then modes, then examples, then return values. Dense but every sentence carries information; the two illustrative examples are the only mildly redundant element against the mode description.

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

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

No output schema exists, and the description compensates by explicitly listing the returns (probability, lambda_fraction echoed or solved) and disclosing boundary behavior. For a 3-parameter read-only calculator, an agent has everything needed to invoke it correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description still adds value by framing the mutual exclusivity of lambda_fraction and max_probability as a mode switch, and by restating the (0, 2] validity bound that constrains the input beyond the schema's raw type descriptions.

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 computation (Kelly growth-security frontier probability) with an academic citation, and precisely states the two operating modes: compute probability from lambda_fraction, or solve lambda from max_probability. No sibling tool overlaps, so the agent can distinguish it purely from the description.

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 selection logic ('Provide either lambda_fraction ... or max_probability ...') plus two natural-language user-phrasing examples that anchor real invocation intents. It also states the valid lambda range (0, 2], which is a usage constraint rather than just a domain fact.

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, non-destructive, closed-world), and the description adds useful return context (liquidationPrice, distancePct) in the absence of an output schema. It does not disclose assumptions such as margin-mode limits or default mmr behavior, so it adds value without being rich.

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

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

Three tight sentences: purpose first, then usage triggers, then return fields. Every sentence carries distinct information with no padding.

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

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

With no output schema, the description usefully enumerates the returned fields, and the input schema covers almost all parameters. A brief note on the isolated-margin assumption or default mmr handling would close the remaining gap.

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

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

Schema description coverage is 80%, so the schema already documents mmr, leverage, entryPrice, and contractType including the linear/inverse distinction. The description adds no parameter-level meaning beyond that, which is the expected baseline when the schema does the heavy lifting.

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

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

States a specific verb and resource ('Calculate the liquidation price') plus the scope constraint 'isolated-margin futures position', which implicitly separates it from siblings like run_max_leverage or run_pre_trade_check. It never names an alternative sibling explicitly, so it stops short of a 5.

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

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

Gives concrete user-intent triggers ('where will I get liquidated?', 'how close is my liq price?'), which tells the agent when to reach for it. No when-not-to-use condition or named alternative is offered, so it is clear context rather than full routing guidance.

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

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

Annotations already establish read-only, non-destructive, open-world behavior. The description goes further by disclosing the fixed-supply assumption and the failure mode (comparable=false plus error when either market cap can't be resolved), which is genuinely useful operational context. It does not cover rate limits or latency, keeping 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 core action, then scope, then caveats, then return shape. Sentences are dense but each carries information; the parentheticals and quoted example slightly lengthen it without 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?

Despite no output schema, the description enumerates the return fields (multiplier, projectedValueUsd, projectedPriceUsd, profitUsd, comparable) and the error condition. Combined with full parameter coverage, an agent has everything needed to call and interpret this tool.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond it: chains may be Solana or one of 5 EVM chains and the two tokens can reside on different chains, which explains why tokenChain and compareToChain exist as separate parameters. That cross-chain nuance is not obvious from the schema alone.

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 ('compares two tokens' live market caps ... projects what an investment would be worth'), plus the cross-chain scope. No sibling in the list performs market-cap comparison, and the description makes the capability unmistakable even without reading 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?

Provides an explicit trigger phrase ('Use when user asks "what if this token reaches [other token]'s market cap?"') and bounds the tool's applicability by declaring it narrative-agnostic and pair-agnostic. It also clarifies the model's assumption ('snapshot ratio, not a forecast'), which tells the agent when the output is and isn't appropriate.

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

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

Annotations only cover the safety profile (readOnly, openWorld, non-destructive); the description goes well beyond them by disclosing the deliberate methodological choices (no expected value, no intra-bucket interpolation, open-ended tail buckets) and that every returned figure traces to a live sourced price. This is exactly the kind of behavioral context annotations cannot convey.

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

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

Front-loaded with purpose and method rationale, and the trailing 'Returns:' list earns its place given there is no output schema. The prose sentence before it is long and slightly dense, but no sentence is pure filler.

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

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

With no output schema, the description carries the full return-value burden and does so explicitly (buckets[], medianBucketLabel, modeBucketLabel, vigPct, conditional probabilityAtOrAbovePct + snappedThresholdUsd). Combined with the when-to-use examples, an agent has everything needed to call and interpret it.

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

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

Schema description coverage is 100%, so both parameters are already documented, including the default-BTC behavior and the threshold snapping rule. The description largely restates the schema's threshold semantics and only marginally extends it by naming snappedThresholdUsd as an output, so the baseline 3 applies.

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

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

States a specific verb and resource (reads Kalshi's live BTC/ETH year-end price ladder) and immediately characterizes the data as a set of mutually-exclusive prediction markets, which differentiates it from the sibling prediction-market tooling (run_prediction_market_edge, run_odds_converter). An agent can identify the tool's function 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?

Provides concrete triggering user utterances ('what does the market think BTC will be worth by year end?', 'what are the odds ETH ends the year above $X?'), which gives strong when-to-use signal. It does not explicitly name or exclude alternative tools, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds the return shape (maxLeverage, marginAtRisk), which is useful since no output schema exists, but discloses nothing about assumptions, units, or edge-case behavior.

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

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

Three compact sentences: purpose, usage triggers, and return values, with the core purpose front-loaded. No filler, though the return-value sentence could arguably be trimmed for a read-only calculator.

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 deterministic four-parameter calculator with a fully described schema and no output schema, the description covers purpose, inputs, triggers, and result fields. Missing only minor detail like the role of the optional mmr parameter and unit conventions.

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

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

Schema description coverage is 100%, so all four parameters including the optional mmr default are documented in the schema. The description restates the three required inputs but adds no format, unit, or default guidance beyond what the schema already supplies, so the baseline 3 applies.

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

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

States a specific verb and resource: 'Calculate the maximum safe leverage,' and names the three driving inputs (account size, max drawdown, daily volatility). It is clearly distinguishable from siblings like run_liquidation_safety or run_position_sizing, though it never explicitly names an alternative.

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

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

Gives concrete trigger phrasings ('what's the max leverage I should use on BTC?') that map user intent directly to the tool, which is strong positive guidance. It lacks any when-not condition or pointer to the sibling it should be preferred over, so it stops short of a 5.

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

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

Annotations already cover the safety profile (readOnly, non-destructive, openWorld), so the description's remaining job is disclosing quirks. It does this well: vig is computed from the market's own YES+NO prices rather than estimated, ADI returns available:false with an explanation instead of a fake price, and all venues are public keyless data. Minor gap is no note on rate limits or latency for the live fetches.

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 and the return values, which is good, but the venue enumeration and the extended ADI caveat make it long and dense. The parenthetical definitions of the five venues could be trimmed without loss.

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

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

For a 6-parameter, zero-required, no-output-schema tool, it covers the essentials: which inputs are mutually exclusive, what each source returns, what vigPct null means, and which sibling to use when ADI has no volume. An agent could invoke it correctly from the description alone.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds value the schema does not: the exclusivity rule ('provide exactly one of probability/kalshiTicker/...') and the meaning of the null vigPct when no live two-sided source was used.

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 (converts) and a precise multi-part resource: a probability into decimal odds, American odds, and breakeven win rate, from either a manual input or five named live venues. It also names the sibling workflow.run_window_fair_value as the right tool for ADI contracts, giving an agent an unambiguous selection signal.

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 phrases ('what odds does a 35% probability work out to?') and routes ADI queries to workflow.run_window_fair_value, but does not define when NOT to use this tool versus workflow.run_market_implied_odds or workflow.run_prediction_market_edge, which look adjacent in the sibling list.

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

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

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=true), so the bar is lower. The description adds genuinely useful context by enumerating the analytical outputs (open_location, open_type classification set, tails, scenario_framing, invalidation level), which the agent could not infer from schema or annotations. It does not mention cost/reproducibility of supplying candles, which the schema already 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?

Front-loaded with the purpose, then usage triggers, then a compact semicolon-delimited return inventory. The return list is dense but every field named is meaningful and there is no filler 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?

With no output schema, the description carries the burden of explaining return values and does so thoroughly (open classification, key levels, tails, scenario framing, invalidation). For a read-only analytical workflow with full schema coverage, the definition supplies everything an agent needs to call and interpret it.

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

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

Schema description coverage is 100% and all seven parameters are documented in the schema (venue enum, timeframe enum, value_area_rule range, candles reproducibility note). The description adds almost no parameter-level meaning beyond that; baseline 3 is appropriate when the schema does the heavy lifting.

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

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

States a specific verb and resource: 'Market Profile open analysis: where and how price opened vs the prior session value area.' The example queries ('how did BTC open today?') make the analysis target unambiguous. It does not, however, explicitly distinguish itself from adjacent siblings like workflow.run_session_structure, so a 4 rather than a 5.

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

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

The quoted user questions ('how did BTC open today?', 'what does the open imply for the session?') give concrete triggers for selecting this tool. There is no statement of when NOT to use it or which sibling to prefer for related session-structure questions, so it stops short of a 5.

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

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

Annotations already cover safety (readOnly, non-destructive, closed-world), so the description is free to add domain behavior — coin settlement, coin-denominated outputs, the USD convenience field, and the counterintuitive capped-call / unbounded-put payoff shape explicitly labeled 'not a bug'. That is exactly the context an agent needs to avoid mis-reading results.

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

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

Front-loads the core purpose and then layers the important settlement caveat; most sentences earn their place. It is dense and errs long, with the long-call/long-put asymmetry explained in one admittedly run-on sentence.

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

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

With no output schema, the description compensates by enumerating the returned fields (intrinsicPerUnitCoin, scenarioPnlCoin, scenarioPnlUsd, breakevenPrice, maxLoss/maxProfitCoin, isProfitable) and the null=unbounded convention, which is everything an agent needs to interpret the response.

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 71%, so the schema documents most inputs itself; the description reinforces that premium/P&L are base-coin denominated and echoes the max-profit formula, but it does not clarify parameters the schema leaves thin (e.g. multi-unit scaling of quantity or the currency default beyond a passing mention). Adds marginal value over the schema, hence baseline 3.

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

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

Specific verb and resource: computes payoff, P&L, and breakeven for a single-leg Deribit BTC/ETH option at a scenario expiry price. The 'single-leg' scope cleanly separates it from run_spread_payoff and run_straddle_strangle, so an agent can route 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 trigger phrases ('what does my BTC call/put pay off at price X?', 'where's my breakeven on this option?') which is strong when-to-use signal. It never names an alternative tool directly, relying on 'single-leg' to imply the exclusion, so it stops short of full routing guidance.

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

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

Far exceeds what the annotations provide. Documents side semantics (buy walks asks, sell walks bids), that impact is always a positive cost number from the book's own mid, the edge cases where vwap/impact are null (book insufficient vs ~0 notional), and the capacity_is_lower_bound caveat when the whole supplied book is consumed.

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

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

Front-loads the core purpose in the first clause and then qualifies behavior. Some sentences are dense and the return-value enumeration is long, but every statement earns its place and no filler is present.

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

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

With no output schema, the description carries the return-value contract fully, including the null conditions, book_sufficient flag, and capacity_is_lower_bound semantics. An agent has everything needed to call and interpret this tool.

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

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

Schema coverage is 100% so the baseline is 3, but the description meaningfully enriches it: it explains side semantics, the either/or relationship between notional_usd and impact_budget_bps, and the return fields correlated with each parameter mode. It stops short of describing the [price, size_base] level format, which the schema handles.

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

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

States a specific verb and resource ('walk the book' impact/capacity) and precisely describes the two computational modes. The description would let an agent distinguish it from siblings like run_swap_price_impact 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 trigger phrases ('what's my price impact if I trade $X', 'how much can I trade before impact exceeds Y bps') that map cleanly to the two modes. No explicit when-not or named alternative, but the usage context is very clear.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so safety is covered. The description goes further by enumerating the returned fields and giving a genuine edge-case disclosure (maxLossBound is non-null only for inverse/coin-margined shorts, includes the opening fee, null otherwise). That is real behavioral context beyond structured data, though it is buried in a dense sentence.

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

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

The purpose sentence and return-field list are front-loaded and efficient, but the maxLossBound clause is a single ~70-word parenthetical with nested asides that is hard to parse and could be split or trimmed. Roughly half the description's weight sits in an over-stuffed sentence.

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?

There is no output schema, so the description correctly carries the return-value burden by naming grossPnl, fees, netPnl, netPnlUsdt, roe and maxLossBound. With annotations covering the safety profile and the schema covering all params, this is nearly complete; only the unwieldy maxLossBound phrasing weakens it.

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

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

Schema description coverage is 100%, so every parameter (side, size, entryPrice, exitPrice, feeOpenPct, feeClosePct, contractType) is already documented with units and semantics. The description adds only one parameter-related fact (inverse PnL/fees are in base coin) which the schema also states, so the baseline 3 applies.

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

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

States a specific verb (calculate) and resource list (net PnL, ROE, fees, gross P/L) scoped to 'a futures trade', which distinguishes it from the sibling run_forex_pnl. An agent can identify the tool's function without opening the schema.

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

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

Gives an explicit trigger phrase ('what's my profit/loss on this trade?') that maps user intent to this tool. It does not name when-not-to-use or point at alternatives such as run_forex_pnl or run_breakeven_planning, so it stops short of full routing guidance.

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

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

Annotations already establish readOnly/no-destructive/no-open-world, so the bar is lower, and the description adds real behavioral context: linear positions sum into one USD total while inverse positions are grouped by settlement coin because cross-coin P&L cannot be summed, plus the healthy/watch/reduce/critical verdict logic. It omits error/limit behavior (the 50-position cap lives only in the schema) and any latency or computation caveats.

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 aggregation outputs before explaining the linear/inverse math distinction, and every sentence carries information. It is long, but the length is justified by the tool's complexity and the need to explain the settlement-coin grouping rationale. No filler or repetition 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 no output schema, the description does the right thing by naming the returned fields and the verdict categories. It covers the core call path adequately for a 2-parameter tool; the remaining gaps are the inverse-position coin requirement and default behaviors, which are documented in the schema rather than the description.

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

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

Schema coverage is 50%, so the description must carry weight; it restates the product-wide size convention (already in the size field description) and the account_balance→margin_usage_pct relationship (also already in the schema), adding only marginal clarification. It does not explain the required vs optional mix of the item objects, so the schema largely does the heavy lifting here.

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 ('Aggregates risk across multiple open positions in one call') and enumerates exactly what is produced: total notional, total P&L, total margin, margin usage %, and closest-to-liquidation position. It also differentiates from the single-position tools by explaining the roll-up relationship, so an agent can place it among 70+ 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?

Provides explicit trigger phrasings ('how exposed am I across all my positions?', 'which of my positions is closest to liquidation?') that map directly to user intent. It does not state when NOT to use it or name a concrete alternative (e.g. run_liquidation_safety for a single position), so it falls just short of a 5.

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