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, 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, destructiveHint=false and a closed world, so the safety profile is covered. The description goes well beyond that by explaining the exact semantics of key outputs: margin_added is cash/margin at this leverage rather than full notional, risk_penalty_pct is measured against the fresh-entry alternative, and liquidation_before_stop means the exchange force-closes before the stop fires. That is exactly the extra behavioral context the annotations cannot supply.

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 correctly, opening with the purpose and closing with usage triggers, and every clause carries information. But the output-explanation passage is a single sprawling multi-clause sentence dense with em-dashes that is harder to parse than necessary; it would read better as a short bulleted field list.

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 rightly carries the full burden of explaining return values, and it names every notable returned field (blended average, liquidation, breakeven before/after, margin_added, the three risk figures, risk_penalty_pct, liquidation_before_stop) with meaning attached. For a computation tool with 11 documented parameters this is sufficient for correct invocation.

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

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

Schema description coverage is 100%, so the parameter contract is fully documented in the structured data and the baseline is 3. The narrative adds interpretive meaning (e.g. add_price doubles as today's price, margin_added is not notional, inverse denomination in base coin), but most of this concerns outputs rather than the 11 input parameters themselves.

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

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

The description states a specific verb and resource: it is a 'should-I-average-down check' that compares adding at a worse price against buying the same total size fresh. That is a concrete, agent-readable purpose. It does not, however, differentiate itself from the close siblings workflow.run_average_entry, primitive.average_entry, or run_dca_entry, which an agent could easily confuse with this one.

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

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

It gives explicit user-facing triggers ('should I add to this losing position?' / 'what does averaging down actually cost me here?') and frames the internal alternative it weighs (fresh entry at add_price). No when-NOT-to-use guidance or tool-level alternative (e.g. use run_average_entry for the plain blended price) is offered, 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, 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 readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds useful behavioral context by stating this is a pure fee-only computation and naming the returned fields (breakevenPrice, totalFees) in the absence of an output schema; it could say more about fee assumptions, but that is largely in 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?

Three front-loaded sentences with zero waste: purpose, then when-to-use, then when-not-to-use with alternatives, plus a return note. Every sentence earns its place, including the emphatic scoping phrase that prevents over-application.

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 bounded 6-parameter read-only computation, the description supplies the selection boundary and the return fields despite there being no output schema, while the schema fully documents parameters and defaults. 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%, including enum explanations and inverse/linear semantics, so the schema does the heavy lifting. The description adds no parameter-level detail beyond what the schema already provides, 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?

The description names a specific verb+resource ('Calculate the break-even exit price') and scopes it tightly ('this alone, nothing else'). It explicitly distinguishes itself from workflow.run_risk_reward and workflow.run_pre_trade_check, so an agent can select it without opening any schema.

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

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

It gives an explicit positive trigger (user asks only 'what price do I need to just break even?') and explicit exclusions with named alternatives for the stop/target or full-safety-check cases. Nothing about when-not-to-use is left to inference.

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

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

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 flag readOnlyHint=true and destructiveHint=false, and the description goes well beyond them: it states the annualized-yield metric is price-independent, explains exactly how upside is capped and how the floor is computed, and flags the non-textbook coin-denominated premium behavior. This is rich behavioral context an agent cannot get from the schema or annotations.

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

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

Purpose and both strategy branches are front-loaded, and the return fields are enumerated at the end. It is dense and the parenthetical formula asides are verbose, but for a multi-metric strategy workflow most of the detail earns 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?

With no output schema, the description carries the return-value burden and does so thoroughly, enumerating staticYieldPct, annualizedYieldPct, valueAtScenarioUsd, breakevenPrice, floorValueUsd, and vsHoldingUsd. An agent has enough to call it and interpret results; only the exact field types/units per output are unstated.

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

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

Schema description coverage is 100%, so the schema already documents all 7 parameters including the strategy enum and premium direction. The description adds formula-level meaning (premium scaling, floor/breakeven semantics) but little per-parameter syntax or format beyond what the schema provides, so baseline 3 is appropriate.

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

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

Starts with a specific verb+resource pair, naming both supported strategies (covered call, protective put) and the underlying (Deribit BTC/ETH position). The two strategies are clearly distinguished from siblings like run_straddle_strangle, run_spread_payoff, and run_options_payoff by their long-coin-plus-short-call / long-put structure.

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 phrases ('what annualized yield do I get selling covered calls on my BTC?' and 'how much does insuring my BTC with a put cost me?'), which directly maps user intent to the two strategy enum values. It does not, however, name when to prefer a sibling (e.g., options_payoff) or state exclusions, so it stops short of full alternative 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 this a safe read-only, open-world computation, and the description adds substantial context beyond them: the complementary-binary convention (No = 1 - Yes), that feePctPerLeg can erase an apparent spread and is reported honestly via isArbitrage, and the important caveat that the caller asserts the same bet and the tool does not verify it.

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 operation and scoping, but is a single very dense paragraph with some redundancy (the fee/spread point is stated twice) and could be broken into clearer units.

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 returned fields (isArbitrage, locked-in cost, guaranteed profit, ROI, which side to buy where), covers assumptions and both input modes, and states the verification boundary—nothing needed to call it correctly is missing.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning beyond the schema by explaining that feePctPerLeg is optional and materially affects the result, and that quotes and manualProbabilitiesPct are alternatives rather than complements.

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 quotes across venues for arbitrage) and frames the exact scope: 2-5 quotes for the SAME binary bet, with direction-independent logic. It is clearly distinguishable from siblings like run_funding_arbitrage or run_prediction_market_edge.

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 ("can I arbitrage this bet across venues?", "is there a risk-free profit here?") and clarifies the two input modes (live quotes vs manualProbabilitiesPct) as mutually exclusive, matching the schema's either/or design.

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

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

Annotations already declare readOnlyHint=true and a closed, non-destructive calculation, so the safety profile is covered. The description adds real behavioral context beyond that: how fees are applied (buy fee on top of cost, sell fee out of proceeds), the mutually exclusive investment/quantity input rule, and the non-obvious annualization rule (only when holdingDays >= 30, otherwise null). It does not discuss rounding or currency assumptions, but the remaining gaps are minor.

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

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

Purpose and scope are front-loaded, and the routing/trigger sentences come before the mechanical details. The final sentence packing the full return list is dense and runs long, but every clause carries distinct information (units, conditional null), so little is wasted.

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

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

There is no output schema, so the description carries the return-value burden and does so completely — it enumerates every returned field, notes unit conventions (fractions vs percentages), and explains the conditional annualizedReturnPct null case. Combined with the fee and input-exclusivity rules, 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 coverage is 100%, so the baseline is 3, but the description goes further by explaining the fee semantics in words that clarify what buyFeePct/sellFeePct actually act on (a fraction of that fill's trade value, asymmetric treatment of buy vs sell), and by restating the investment-vs-quantity exclusivity. That adds interpretative value the schema fields alone do not.

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 verb and resource — profit or loss on a spot crypto trade — and immediately scopes it ('no leverage, no funding'), which is exactly the boundary that separates it from the many other P&L siblings. It also explicitly routes the leveraged case to workflow.run_pnl_planning, so the agent can distinguish it without opening either schema.

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

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

It gives explicit when-to-use triggers in the form of verbatim user questions ('I bought BTC at $X, what is my profit if I sell at $Y?') and explicitly names the alternative tool for the leveraged case. Nothing about selection is left to inference.

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

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

Annotations already declare readOnlyHint/non-destructive/closed-world, and the description adds substantial context beyond them: the unit assumption baked into n_trials (per-period, mean 0, variance 1), concrete threshold values at N=10/100/1000, why that makes dsr effectively 0 for daily series, and that trial_sharpes centers on the observed mean rather than a zero-skill null. These are exactly the interpretive traps an agent would otherwise fall into.

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 concept, then usage triggers, then two labeled limits, then return values — a sensible order. It is a dense unbroken paragraph of roughly 250 words for a four-parameter tool; the content earns its place but bullets or line breaks would improve scanability.

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 being a numeric workflow with no output schema, the description names the three returned fields and how to read them (expected_max_sharpe as the threshold, dsr as a 0-1 probability), and covers the failure mode that would otherwise produce a silent wrong answer. An agent has everything needed to call it and interpret the result.

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

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

Schema coverage is 100%, so baseline is 3; the description goes beyond the schema by explaining the priority relationship, the Kish design-effect role of avg_correlation, and the unit caveat that makes n_trials unsuitable for daily data. It does not restate scalar ranges or types, which the schema already covers, so it falls just 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?

Names a specific, well-defined statistic (Deflated Sharpe Ratio, Bailey & Lopez de Prado) and states in plain language exactly what it computes: the Sharpe ratio the best of N trials would clear by luck alone, and whether the actual strategy still clears it. This is clearly distinguishable from a plain Sharpe calculation in the sibling list (run_sharpe_stats) without opening either schema.

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

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

Gives explicit trigger phrasing ('is my backtested Sharpe ratio real, or did I get lucky...?', 'how many independent trials does this really represent?') and an explicit selection rule between the two input paths: prefer trial_sharpes[] as most rigorous, fall back to n_trials + optional avg_correlation. It even states when NOT to use n_trials ('use trial_sharpes there' for low-frequency series). 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 (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, and openWorldHint=false, so the safety profile of this pure-computation tool is fully covered. The description adds the return field (targetExitPrice) which is useful given there is no output schema, but it discloses nothing further about determinism, fee handling, or edge cases.

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 verb and resource, then two illustrative queries, then the return value. Every sentence earns its place and there is no filler.

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

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

For a deterministic read-only calculator whose safety is covered by annotations and whose parameters are fully documented in the schema, the description is nearly complete and even covers the return field in the absence of an output schema. Detailed inverse/linear output handling is left to the schema, which is acceptable.

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 9 parameters, including the three enums (side, targetMode, contractType) and fee defaults, are already documented in the schema. The description only restates the PnL/ROE distinction without adding 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 (Calculate) plus the exact resource (the exit price needed to hit a target PnL or ROE percentage), and disambiguates the two target modes. An agent can immediately distinguish this from sibling entry/sizing tools like run_average_down or run_position_sizing.

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 ('at what price do I take profit to make $500?', 'where should I set TP for 20% ROE?'), which clearly signals when to call it. However, it does not name alternatives (e.g., run_scale_out, run_pnl_planning, run_breakeven_planning) 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, destructiveHint=false, and openWorldHint=false, so safety is covered. With no output schema, the description compensates by naming the returned fields (totalUnits, totalCost, avgEntry) and disclosing the computational method, which is genuinely useful behavioral context.

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

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

Front-loads the core computation, then the method note, trigger, and return fields. The parenthetical comparing harmonic vs arithmetic means is somewhat long but earns its place by preempting a plausible sibling confusion.

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

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

With no output schema, the description usefully enumerates return fields, and the method note plus trigger cover the call context. For a simple 2-param, read-only computational tool the definition is essentially 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% with only 2 parameters, so the schema already documents pair format (BASE/QUOTE) and fill structure (price, units). The description's 'size-weighted' phrasing adds marginal semantic clarity about units but nothing beyond the schema; baseline 3 applies.

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

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

States a specific verb+resource ('size-weighted average entry price across multiple forex fills') and explicitly differentiates from the sibling primitive.average_entry by explaining why the arithmetic mean is used rather than the harmonic mean. An agent can distinguish it without opening schemas.

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

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

Provides a clear trigger ('Use when user asks "what's my average entry after these fills?"') and contrasts the method against the crypto average_entry tool. It does not state an explicit exclusion or when to prefer the sibling instead, but the routing context is clear.

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

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

Annotations already establish readOnlyHint=true, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds genuine domain behavior: commission is per standard lot in the quote currency, and commission-in-pips is position-size invariant by construction. It does not discuss edge cases such as zero commission or non-standard lot conventions.

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 core purpose, then the commission/scale invariant, then the return key list. Dense but each sentence carries meaning; the mid-sentence derivation of size-independence is slightly verbose but earns its place by preventing unit errors.

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

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

With no output schema and five parameters, the description compensates fully: it enumerates the returned keys (pipSize, commissionPips, totalCostPips, breakevenPrice) and explains the unit conventions of the inputs. 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 coverage is 100%, so the baseline is 3. The description goes beyond the schema by explaining the semantics of commissionPerLotRoundTrip (per standard lot, in quote currency, default 0 pure-spread model) and why its pip conversion is size-independent, which helps an agent reason about the units rather than just passing numbers.

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: computing a forex position's breakeven price inclusive of spread and round-trip commission, in both pips and price. This is well differentiated from generic breakeven siblings by the 'forex' + 'commission' scope, but it never names the closest siblings (run_breakeven_planning, run_funding_breakeven) it could be confused with.

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

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

Provides an explicit trigger phrase: 'Use when user asks "where's my true breakeven after spread and commission?"', which gives a clear context for invocation. It stops short of stating when NOT to use it or which alternative handles the simpler spread-only case, so routing among the many breakeven/pnl siblings is left to inference.

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

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

Annotations already declare readOnlyHint=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 declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds behavior the annotations cannot: that it works for both closed and hypothetical trades, and that the returned pips figure is signed with positive favoring the position taken. No output schema exists, so this return-value disclosure is the main carrier of 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 dense sentences: purpose and scope first, then trigger phrasings, then the return contract. Every clause carries information and nothing is repeated from the schema.

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

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

For a pure computation tool with full annotation coverage the description is nearly complete, and it compensates for the absent output schema by naming the two return fields and the sign convention. Only minor edge cases (JPY-style pairs, pip definition per pair) are left implicit, which is acceptable given the schema's price-convention notes.

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% across all five parameters, so entry/exit price conventions, side enum and units are already fully documented structurally. The description reinforces the quote-currency convention and the long/short choice, but adds no syntax or constraint 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 (compute profit or loss) and a specific resource (a closed or hypothetical forex trade), and scopes it as pips plus the pair's own quote currency for long or short positions. That is enough to separate it from siblings such as run_forex_pip_value, run_forex_risk_reward and run_pnl_planning without opening any schema.

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

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

Gives concrete user phrasings that select this tool ("what did I make/lose on this trade?", "what would X pips be worth on Y lots?"), which is strong situational guidance. It stops short of naming an alternative or an exclusion, so it is clear context rather than a full when/when-not routing rule.

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/openWorld/non-destructive, so the bar is lower. The description adds real value beyond them: the live data source (TrueFX/frankfurter.app), the returned fields, and the failure behavior (available=false with 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-loaded with the purpose, then rationale, trigger, and returns in a logical order. The middle justification sentence about the account-currency-agnostic form is slightly verbose but does explain the required parameter.

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 return fields and error cases, and it names the live data source. For a five-param, all-required read-only tool, 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 description coverage is 100%, so the schema already documents all five parameters and the baseline is 3. The description adds only light framing (risk amount denominated in account currency, stop distance driving pip value) without new syntax or format details.

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 (position size in units and standard lots) plus the exact inputs (risk amount, stop distance, account currency) and the live-FX mechanism. It is clearly distinguishable from siblings like run_forex_pip_value_live, which supplies the rate this tool consumes.

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 usage trigger ("how many lots should I trade to risk $X on this setup?") and explains why accountCurrency is mandatory. It does not, however, name a specific alternative or exclusion versus siblings such as run_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?

Beyond the readOnly/non-destructive annotations, it discloses non-obvious output behavior: ratio is null when stop equals entry and when validSetup is false, with a concrete example (a long with its stop above entry). That pre-empts a real misinterpretation an agent would otherwise make.

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 computed quantity, then the null-edge cases, then the trigger, then the return fields. Every sentence carries information; the "a raw number, not a verdict" clause usefully clarifies output semantics rather than padding.

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

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

With no output schema, the description supplies the return field list (riskPips, rewardPips, validSetup, ratio) and the conditions under which ratio is null. Combined with a fully documented input schema and safe-read annotations, 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%, so all five parameters are already documented (including the BASE/QUOTE convention and side enum). The description adds only conceptual reference to entry/stop/target and no new per-parameter syntax or constraint, 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 computation (risk/reward distance in pips from entry/stop/target plus the reward/risk ratio) on a specific resource (forex setup). It is clearly separable from generic siblings like workflow.run_risk_reward and from adjacent forex tools such as run_forex_pnl or run_forex_pip_value.

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 risk/reward on this setup?'") and a precondition (check validSetup before trusting the ratio). It does not name or exclude alternative siblings, so the when-not guidance is absent, but the context is clear.

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

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

Annotations already establish the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false) and are not contradicted. The description adds a genuinely valuable behavioral note: pips are signed by actual price direction and are not pre-adjusted for side, a convention trap an agent would otherwise get wrong.

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

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

Three tight sentences: what it computes, its sign caveat, when to use it, and the return shape. Front-loaded with the core purpose and no filler, though the return-shape sentence could be trimmed since it is mechanically enumerable.

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 return fields (deltaPips, exitPrice, pnlQuote). For a 5-required-param read-only workflow tool the description covers purpose, trigger, and result shape adequately; only sibling differentiation 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 100%, so the baseline is 3, but the description earns a bump by clarifying deltasPips semantics (signed, side-agnostic) — precisely the parameter most likely to be misused. It also ties the single-position-size constraint to units without re-listing 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+scope: PnL over a range of hypothetical price moves for a single forex position, long or short. An agent can tell this apart from most siblings, though nothing in the text distinguishes it from close relatives like run_forex_pnl or run_scenario_planning.

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 if price moves X pips in either direction?") which is exactly the user phrasing that should select this tool. It stops short of naming an alternative or a when-not condition, 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?

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 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?

Far exceeds the readOnlyHint annotation: discloses the solver (Newton-Raphson with bisection fallback), why bisection is used (flat vega in deep ITM/OTM or short-dated), the pre-check against no-arbitrage bounds, and the deliberate refusal path (converged=false + error) instead of returning a garbage number. That refusal and the identifiable=false ambiguity case are exactly the traits an agent needs before trusting output.

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 solve, then the numerical method, then the guardrail, then the return contract. It is dense but each sentence carries distinct information; the only mild bloat is re-explaining the identifiable/converged interaction in two places.

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 carries the return contract itself and does so fully: field-by-field enumeration of impliedVolatilityPct, iterations, method, converged, identifiable, warning, priceAtSolution, plus the semantics of the ambiguous and failed cases. Nothing needed to interpret a result correctly is missing.

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

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

Schema description coverage is 100%, so all six parameters (including the risk-free rate default) are already documented in the schema, making 3 the correct baseline. The description reinforces targetPriceUsd as the observed price and names the supporting inputs (spot/strike/rate) but adds no format or unit guidance 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: solves for the volatility that makes Black-Scholes reproduce an observed option price. It also explicitly distinguishes the direction of the calculation ('the volatility, not the reverse'), which separates it from the Black-Scholes pricing sibling 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 IV does this option price imply?' or a market price with a desire for volatility) and a negative condition (not the reverse). It stops short of naming the inverse tool to route to, leaving the agent to infer run_black_scholes for the reverse 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 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 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 mark this readOnly and non-destructive, and the description goes well beyond them: it discloses that vig is computed from the market's own YES+NO prices (not estimated), that NULL vig results when no live two-sided source is used, and that ADI Predictstreet returns available:false with an explanation rather than a fabricated price. That last point is exactly the kind of honesty an agent needs to interpret a null result correctly.

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

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

Front-loaded with the core action, then alternatives, then exceptions, then return shape – a sensible order. It is dense and long for a single call, but nearly every clause carries distinct information; only the venue-chain details for Myriad/Limitless edge toward redundancy with the schema descriptions.

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 enumerating every returned field (probability, decimalOdds, americanOdds, breakevenWinRatePct, vigPct, source, identifier, label) and their null conditions. For a six-input tool with a degenerate-mode caveat, nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds the mutually-exclusive selection rule across the six parameters and characterizes the five venues by data source (public keyless, on-chain chains). It stops short of describing format details per parameter, which the schema already carries.

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

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

States a specific verb (converts) and a specific, three-part output (decimal odds, American odds, breakeven win rate), with two input modes spelled out. It also explicitly scopes itself against workflow.run_spread_reader for cross-venue comparison, so an agent can distinguish it from that 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?

Gives concrete trigger phrasings ('what odds does a 35% probability work out to?', 'what's the vig on this Kalshi market?'), states the one-market-one-venue limit, and names the alternative for multi-venue comparison. The 'provide exactly one of ...' constraint is stated outright rather than 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, closed-world), and the description adds substantial domain behavior on top: coin settlement means P&L and caps come back in BTC/ETH not USD, the scenarioPnlUsd conversion exists, a long call's upside is capped while a long put's is unbounded, and null caps mean unbounded. It even pre-empts the natural 'this looks like a bug' reaction to the asymmetric payoff shape.

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 output list, then the coin-settlement explanation. It is dense and longer than most definitions, but nearly every sentence carries non-obvious information (settlement denomination, capped vs unbounded upside). Slightly over-explained in the payoff-shape passage, costing a point.

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 (intrinsicPerUnitCoin, scenarioPnlCoin, scenarioPnlUsd, breakevenPrice, maxLossCoin/maxProfitCoin, isProfitable) and explains the null-means-unbounded convention. Combined with the settlement context, 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 coverage is 100%, so the baseline is 3, but the description adds interpretive meaning the schema lacks: it explains that premiumCoin is coin-denominated per unit (matching Deribit quotes) and that coin settlement is why P&L is reported in the base coin. This clarifies the units and semantics of the numeric inputs rather than just restating them.

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

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

States a specific verb+resource+scope: 'Payoff, P&L, and breakeven price for a single-leg Deribit BTC/ETH option (long or short call/put) at a given scenario price at expiry.' The 'single-leg' qualifier implicitly separates it from multi-leg siblings like run_spread_payoff or 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 two concrete trigger phrases ('what does my BTC call/put pay off at price X?', 'where's my breakeven on this option?'), which is clear context for when to use it. It does not explicitly name the alternative to reach for a multi-leg payoff (e.g. run_spread_payoff), so the exclusion is only implied by 'single-leg'.

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?

With readOnlyHint, openWorldHint=false, and destructiveHint=false already declaring the safety profile, the description adds rich behavioral context: the computation pipeline, why linear sums into USD while inverse groups by settlement coin, the need for a live conversion rate, and the healthy/watch/reduce/critical verdict logic. No auth or rate-limit constraints are needed for this compute 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-loads aggregation and output list, then explains mechanics, verdict, use cases, and size convention. Dense but every sentence supports correct invocation or interpretation; minor redundancy with the schema on position-size wording.

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 explain return values; it does by listing total notional, total P&L, total margin, margin usage %, the position closest to liquidation, and verdict categories. It also covers input conventions and aggregation logic, making it complete for this complex 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 the baseline is 3. The description adds the product-wide position-size convention and explains account_balance's effect on margin usage, but this information is already present in the schema descriptions and adds no new syntax or constraints beyond the structured 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?

States a specific verb and resource: aggregates risk across multiple open positions. Lists the exact outputs and explicitly contrasts with single-position tools by noting roll-up and canonical math. An agent can distinguish it from siblings like run_open_analysis or run_liquidation_safety 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 explicit trigger questions: 'how exposed am I across all my positions?' and 'which of my positions is closest to liquidation?'. Clear context for use, but no when-not-to-use guidance or named alternatives, 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?

Beyond the readOnly/non-destructive annotations, the description discloses genuine behavioral traits: returns are decimals (0.02 is 2%), at least 3 periods are required, and the call errors when the series never draws down (Calmar undefined) or no period falls below mar (Sortino undefined). It does not describe the shape of the returned object, but the error conditions and unit convention are meaningful additions.

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 purpose, then usage, then return/error semantics. The first sentence is a long run-on metric list, but every item earns its place by telling the agent exactly what comes back from a tool with 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?

Given a complex analytics tool with no output schema, the description compensates by enumerating every returned metric, stating input units, minimum periods, and the two error conditions. Nothing essential for calling it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by clarifying the decimal convention for returns and tying the mar parameter to the Sortino error condition, though it does not elaborate on benchmark_sharpe or periods_per_year beyond what the schema 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 opens with a specific verb/resource: 'Core risk/return tearsheet from a single return series,' and enumerates the metrics produced. It distinguishes itself from the many single-metric siblings by stating 'not just one metric,' though it never names run_sharpe_stats or run_portfolio_risk explicitly.

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

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

It gives a clear use trigger: 'Use when user asks for a full risk summary/report on a strategy or portfolio's returns, not just one metric.' That implicitly routes single-metric requests elsewhere, but no explicit when-not conditions or named alternatives are provided.

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 value beyond them by enumerating the three return fields (positionSize, positionUsdt, marginRequired), which matters because no output schema exists. It omits that inverse contracts return margin in the base coin, a behavioral quirk left only 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?

Three compact sentences: what it computes, when to reach for it, what it returns. The core computation is front-loaded and no sentence is redundant.

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

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

For a stateless read-only calculator with no output schema, describing the return fields and the required inputs is sufficient. Minor gaps remain: no note on how leverage/fees/contractType shift the output, and no indication of failure modes (e.g., stopLoss equal to entryPrice).

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 eight parameters are already documented in the schema. The description only echoes stopLoss and riskUsdt and adds no syntax or interaction detail (e.g., how leverage or the fee fractions influence the result). Baseline 3 applies when the schema carries the semantic 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 (calculate), resource (position size), and the two governing inputs (max risk in USDT, stop-loss price). This clearly separates it from reporting/normalizing siblings like run_forex_pip_value or run_breakeven_planning, though it does not name a specific alternative tool.

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 trigger phrasings ("how many coins should I buy?", "size my position so I risk exactly $X") that map directly to the required params riskUsdt and stopLoss. No when-not conditions or explicit sibling routing 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 the safety profile (readOnlyHint=true, destructiveHint=false, openWorld=true), so the description's job is to add context — which it does: it discloses the no-edge/no-bet rule (zero stake returned), states the Kelly convention explicitly, and notes live-source fetching. It does not clarify that no bet is actually placed, only a recommendation returned, which keeps it from a 5.

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

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

Front-loaded with the core comparison-and-sizing action, then usage triggers, then returns. Sentence two is somewhat heavy ("default: quarter-Kelly, a standard conservative haircut on full Kelly, stated explicitly as a convention") and duplicates the schema's default, so it is efficient but not lean.

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 enumerating every returned field (edgePct, evPerDollarStaked, fullKellyFraction, cappedKellyFraction, recommendedStakeUsd, verdict) plus the verdict enum values. An agent has everything needed to call 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?

Schema coverage is 100%, so the baseline is 3, but the description adds real value beyond it: the exclusive-or rule across the four market-price sources and the quarter-Kelly default convention. Marginal value is genuine, though it repeats the schema's own default statement.

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 pair: compares the user's own probability estimate against a market price and sizes a stake via fractional Kelly. It is clearly separable from neighbours like run_kelly_frontier, run_position_sizing, and run_market_implied_odds because it is the only one framed around prediction-market edge and bet sizing.

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 ("does this bet have edge?", "how much should I stake…") and a hard input constraint ("Provide exactly one of marketProbabilityPct/kalshiTicker/limitlessSlug/myriadSlug"). It does not name an alternative sibling tool 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 declare readOnlyHint=true and destructiveHint=false, and the description adds substantial context beyond them: the reference exchange set, exact threshold bands (0.25%/1%), the meaning of the 'insufficient' status, and the exclusion of inverse, dated and unlisted contracts. This is exactly the kind of behavioral detail annotations cannot carry.

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

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

Long but dense and front-loaded: the core check is stated first, then the exchange set, then thresholds, then usage, then the return shape. Every sentence carries information, though the return-field enumeration is slightly list-heavy for a 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?

Despite no output schema, the description enumerates the returned fields (status, summary, median, peerMedian, spreadPct, deviationPct, sources, quotes, thresholds_pct, as_of) and defines the status vocabulary, so an agent knows both inputs and outputs well enough 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 by stressing that the symbol must be the exchange-native perp symbol (with per-exchange examples such as BTCUSDT on bybit and ETH-USDT-SWAP on okx) and by explaining that the chosen exchange is compared against the rest. That prevents a common cross-exchange symbol mismatch.

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 ('cross-exchange agreement check for one perpetual futures price') and immediately bounds the scope to 7 named exchanges with the chosen one compared against the rest. An agent can distinguish this from sibling workflows like run_cross_venue_arbitrage or run_pre_trade_check 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 an explicit trigger ('Use before acting on a live price') plus a worked example question ('is this Bybit BTC price in line with the market?'). It also clarifies when NOT to treat the result as a verdict (insufficient status, non-comparable contract types), which is strong 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 cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false), so the bar is lower. The description adds genuine behavioral context beyond that: it specifies long-only output, an iterative convergence criterion, and the exact return fields including risk_contributions matching risk_budgets.

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 constraint, followed by usage triggers and the return contract. Dense but each sentence contributes; the parenthetical return-list is compact rather than padded.

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

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

No output schema exists, so the description carries the return-value burden and does so by enumerating weights, risk_contributions, and portfolio_volatility. Combined with full parameter coverage and a clear safety profile, an agent has what it needs; only edge-case behavior (non-convergence, asset-count limits) is unstated.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters including the returns-or-covariance exclusivity and the internal normalization of risk_budgets. The description restates the covariance/return-series duality but adds no syntax or format detail beyond the schema, 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 ('finds long-only weights where each asset contributes its target share of total portfolio risk') and names the domain constraint (risk parity, equal or custom risk contribution). An agent can distinguish this from siblings like run_portfolio_risk or run_kelly_frontier 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 explicit trigger phrasing ('what weights give each asset equal risk contribution?') and a clear exclusion ('A portfolio-construction calculation, not a buy/sell recommendation'). It stops short of naming a specific alternative sibling to route to, so it is clear context without full alternative routing.

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