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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, but the description adds behavioral context beyond them: it specifies error semantics (unknown method, missing input, or extra field returns an INVALID_ARGUMENT error envelope instead of raising), the no-defaults rule, and the IFRS/HKFRS scope restriction. This is meaningful disclosure not present in the annotations.

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

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

Front-loads purpose, then usage/exclusion, then method input lists, and closes with error behavior. Every sentence carries required information (frameworks, alternative tool, per-method inputs, error contract) with no filler, which is appropriate density for a 5-method, 14-parameter 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?

An output schema exists, so return values need not be explained. The description covers scope, method selection, required inputs per method, and error behavior, leaving nothing an agent needs in order to invoke this tool correctly.

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

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

Schema coverage is 100%, so baseline would be 3; however, the description adds the critical method-to-input mapping that the schema's method.enum explicitly defers to (e.g., ifrs17_gmm needs cash_flows, discount_rate, risk_adjustment; ias19_puc needs projected_benefits, discount_rate, attribution_years). Without this mapping the 14 flat parameters would be unusable, so the description materially compensates.

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 ('Actuarial present value engine', 'Discount expected cash flows with mortality, survival, and risk adjustment') and names the regulatory frameworks (IFRS 17, IAS 19, IFRS 2, IAS 37). It explicitly distinguishes itself from the sibling calculate_expected_value by excluding generic probability weighting, so an agent can tell the two apart 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 when to use ('for regulated IFRS/HKFRS obligations only'), when not to use ('does NOT do generic project or scenario probability weighting'), and names the alternative tool (calculate_expected_value). It also defines the invocation rule ('Supply exactly one method with its declared inputs (no defaults)') that governs correct use.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so safety is covered; the description goes further by disclosing the error contract (unknown method, missing input, or extra field yields an INVALID_ARGUMENT envelope rather than raising), the no-defaults rule, and that quantlib needs an optional engine while lsmc is Monte Carlo. It stops short of describing convergence/accuracy trade-offs or runtime cost, which would matter for method choice.

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 engine and technique before the routing guidance and method list, and every sentence carries information. It is somewhat repetitive, enumerating the five method names in two separate sentences plus the schema enum, which costs a little density.

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 12-parameter tool with a 100% covered schema and an output schema, the description supplies everything else an agent needs: the valuation domain, the sibling routing, the method/input contract, and the error behavior. Return values need not be explained given the output schema.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real invocation semantics beyond the schema: exactly one method's declared inputs must be supplied with no defaults, extra fields are rejected, and the method list is enumerated with its input set. This clarifies a schema that otherwise marks every parameter nullable with default null.

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 (value callable/puttable convertible or exchangeable bonds) and the exact numerical technique (Tsiveriotis-Fernandes lattice with credit spread), which immediately distinguishes it from the fixed-income and option siblings. An agent can identify the tool without opening the schema.

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

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

It explicitly routes the agent: use this for convertible/exchangeable bonds, use calculate_fixed_income for plain bonds or rate curves, and calculate_option for standalone options/warrants. It also explains that the five methods are interchangeable schemes for the same valuation and that the agent must choose one, which is genuine selection guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds real value beyond that: it discloses the error contract (unknown method, missing input, or extra field returns an INVALID_ARGUMENT envelope rather than raising) and the no-defaults, exactly-one-method constraint. It stops short of describing result shape or precision, but the output schema covers return values.

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 domain are front-loaded, followed by routing, then the compact method-to-input contract, then the error contract. The method list is dense but every clause is load-bearing for a tool with 8 mutually exclusive methods; 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 high-complexity multi-method calculator, the description covers purpose, sibling routing, the full method/input matrix, and failure semantics, while the output schema handles return values. An agent has everything needed to select a method and assemble a valid call.

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 method enum's schema description explicitly defers to the tool description for required inputs. The description supplies exactly that per-method mapping (ecl_12m: ead/pd/lgd; provision_matrix: receivables_ageing/loss_rates; cva_dva: exposure_profile/pd/lgd/discount_rate, etc.), which the schema alone cannot convey given 17 optional parameters and one discriminator.

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 (compute expected credit loss) and anchors it in a named domain (IFRS 9 / HKFRS 9), listing the concrete outputs (12-month/lifetime/staged ECL, PD/LGD/EAD, provision matrices, hazard rates, CVA/DVA). It explicitly distinguishes itself from calculate_convertible_bond and calculate_fair_value_adjustment, so an agent can route correctly without opening any schema.

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

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

Gives explicit when-to-use cases (impairment, fair-value credit adjustment, loan-loss provisioning) and two named when-not cases with the correct alternative for each (convertible bond credit component, liquidity/control/marketability discounts). This is exactly the routing information the sibling set requires.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds behavior beyond that: exactly one method per call, no defaults, and the failure mode (an INVALID_ARGUMENT error envelope rather than a raised exception). It does not need to discuss auth or rate limits for a pure in-process computation, so this is close to complete.

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

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

Purpose is front-loaded and the routing rule follows before the method list. The enumeration of methods and their inputs is long, but each entry is load-bearing because the schema does not encode per-method requirements. Slightly dense, yet nothing is redundant with the structured fields.

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

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

An output schema exists, so return values need not be described. With the safety profile in annotations, per-method input requirements, sibling routing, and error semantics all stated, an agent has everything required to select a method and call it correctly.

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

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

Schema coverage is 100%, which normally caps the baseline at 3, but here the schema marks 12 of 13 parameters as optional-with-null, so it cannot convey which inputs a given method actually requires. The description supplies that mapping explicitly per method (e.g. "terminal_multiple: final_cash_flow, exit_multiple; viu_pre_tax: cash_flows, pre_tax_discount_rate"), which is information no single-parameter schema description can express.

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 ("Discounted cash flow valuation engine") and enumerates the exact technique families covered (FCFF/FCFE DCF, NPV/IRR, terminal values, multi-stage growth). It also names the sibling tools it is not (calculate_residual, calculate_market_multiple, calculate_loss_making_company), so an agent can discriminate 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 routing rule: "Use this for going-concern cash-flow businesses; for asset-anchored or financial firms use calculate_residual, for peer-based pricing use calculate_market_multiple, and for pre-profit companies use calculate_loss_making_company." This is a when-to-use plus three named alternatives with the condition selecting each.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description still adds real behavioral context beyond them: exactly one method with its declared inputs, no defaults applied, and an error-envelope contract (INVALID_ARGUMENT) instead of raising on unknown method, missing input, or extra field. It omits any note on auth, limits, or output shape, but has an output schema covering returns.

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 routing before the dense method table; every sentence carries information. The per-method enumeration is long but necessary given nine modes, though it reads as a run-on and could be structured for faster scanning.

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 26-parameter, nine-method calculation tool, the description covers purpose, routing, method-to-input mapping, and failure semantics. A return-value explanation is unnecessary because an output schema exists. 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 baseline would be 3, but the description goes well beyond it by mapping each of the nine method values to the exact inputs it requires (e.g. wacc: equity_weight, debt_weight, cost_equity, cost_debt, tax_rate; ibr: risk_free, credit_spread, tenor_years). This conditional dependency between method and parameters is not expressible in the flat schema and is the key guidance for correctly invoking the tool.

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

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

Opens with a specific verb+resource ('Cost-of-capital engine. Compute WACC, cost of equity (CAPM), cost of debt, unlevered/relevered beta, and country or size premiums'), which is precisely scoped and clearly distinguished from the valuation siblings. The explicit statement that it 'returns a rate, not a valuation' separates it from calculate_dcf/calculate_residual without opening either schema.

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

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

States the use case ('derive the discount rate an income-approach valuation needs'), the boundary ('returns a rate, not a valuation'), and names the concrete downstream routing targets (calculate_dcf, calculate_residual for IFRS-basis measurement). An agent knows both when to call it and where its output goes.

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, idempotent, non-destructive, closed-world behavior, and the description goes further by disclosing the validation contract: exactly one method, no defaults, and an INVALID_ARGUMENT error envelope rather than an exception. That failure-mode disclosure is real value beyond the annotations. One caveat: 'no defaults' is in mild tension with the schema, which lists default null for every optional field, so a 4 rather than a 5.

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

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

Front-loads purpose, then exclusions, then the per-method input contract, then the error contract — a sensible priority order with no filler sentences. The middle method-inventory sentence is dense and list-heavy, but every element is load-bearing rather than decorative.

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 15-parameter tool with an enum discriminator and an output schema, the description supplies the method-to-input contract, the mutual-exclusion rule, the sibling routing, and the error behavior. Return values are covered by the output schema, so nothing an agent needs to invoke this correctly is missing.

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

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

Schema coverage is 100% so the baseline would be 3, but the description adds the crucial conditional mapping the flat schema cannot express: which inputs each method value requires (discrete: outcomes+probabilities; continuous: distribution/mean/std/lower/upper; monte_carlo: iterations/distributions/base_params/seed, etc.). This resolves the cross-parameter dependency the enum alone leaves ambiguous.

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?

It names a specific verb and resource ('expected-value engine', 'Compute expected values') and immediately scopes the breadth of methods it covers. It distinguishes itself from sibling tools by name, explicitly ruling out calculate_actuarial_pv and calculate_structured_product, so an agent can route between them 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?

Explicit when-to-use ('generic probability weighting of scenarios, Monte-Carlo and decision trees') and two explicit when-not cases with the correct alternative tool named for each. Nothing about selection is left to inference.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so safety is covered. The description adds real behavioral context beyond that: exactly one method must be supplied with its declared inputs, there are no defaults, and invalid input returns an error envelope (code INVALID_ARGUMENT) rather than raising. It doesn't need to describe output because an output schema exists.

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

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

The purpose, alternatives and error contract are front-loaded, and every sentence carries information. The method/input listing is dense but necessary since the schema defers it here; it is slightly run-on but not padded.

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

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

For a 6-method, 10-parameter calculation tool this is complete: method-to-input mapping, alternatives, and error behavior are all covered, and return values are handled by the output schema. 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 field meanings are already documented, but the description adds cross-parameter semantics the schema cannot express: the exact input set required per method value, the exactly-one-method constraint, and that no defaults apply. That mapping meaningfully exceeds the per-field 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?

States a specific verb+resource ('fair-value-adjustment engine', 'compute exit-price adjustments') and enumerates the adjustment types (credit, liquidity, control, marketability, blockage, hierarchy). It explicitly distinguishes itself from siblings calculate_market_multiple and calculate_credit_loss, so an agent can route correctly without opening another schema.

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

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

Gives explicit when-to-use ('move from an indicated value to the fair value recognised in the accounts') and names the alternatives with the condition that selects them (liquidity/marketability inputs of a listed instrument -> calculate_market_multiple; expected credit loss -> calculate_credit_loss). Nothing is left to inference.

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

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

Annotations already declare readOnly, idempotent, non-destructive, so the safety profile is covered. The description adds genuinely useful behavioral contract beyond that: the exactly-one-method dispatch rule, 'no defaults' enforcement, and the error-envelope behavior (INVALID_ARGUMENT returned rather than raised) for unknown methods, missing inputs, or extra fields. It doesn't discuss numerical edge cases (e.g., non-convergence in yield solving) or output shape, 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?

Dense but front-loaded: purpose first, then sibling routing, then the per-method input contract, then the error contract. The method-input enumeration is long but every element earns its place given the 9-way method enum. Slightly cramped as one unbroken paragraph, which costs it 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?

Output schema exists, so return values need not be described, and the description covers the remaining agent-critical surface: which method to pick, what inputs each method requires, same-call constraints, and error semantics. For an 18-parameter, single-method-dispatch tool, nothing needed to invoke it correctly is missing.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real value the schema cannot: an explicit method-to-input mapping (bond_yield takes price instead of ytm; matrix_pricing takes target/benchmark tenors; pv_curve takes cash_flows plus times plus zero_rates). This tells the agent which of the 18 optional parameters to populate for a given method, which the flat schema does not convey.

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

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

States a specific domain engine with enumerated capabilities (bond pricing, YTM solving, duration/convexity, zero-curve bootstrap, forwards, curve discounting) and names the exact sibling alternatives for convertible and structured payoffs. An agent can distinguish it from calculate_convertible_bond and calculate_structured_product 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?

Explicit routing guidance: 'Use this for vanilla bonds, rate risk and discount curves; for convertibles use calculate_convertible_bond and for structured payoffs use calculate_structured_product.' Both the when-to-use and the when-not-to-use (with named alternatives) are stated.

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

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

Annotations already establish readOnly/idempotent/non-destructive, so the safety profile is covered; the description still adds real value by disclosing that every method returns a central value plus dispersion (sigma, percentiles, long-tail), that no defaults are applied, and that bad input yields an INVALID_ARGUMENT error envelope rather than raising. It does not contradict the annotations.

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

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

Front-loads purpose, then usage/exclusions, then the method-to-input catalog. The method listing is long but each term carries load for a 27-parameter tool; only the repeated 'range_method' tail across every method is slightly wasteful.

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 27 params, one required discriminator, full schema coverage, and an existing output schema, the description supplies everything an agent needs: purpose, routing versus siblings, the per-method input contract, no-defaults rule, and error behavior. Return-value detail is correctly left to the output schema.

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

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

Schema coverage is 100%, which alone would cap the baseline at 3, but the description goes well beyond the per-field schema text by mapping each of the seven method enum values to the exact inputs it requires (e.g. merton_equity: firm_value, firm_volatility, debt, risk_free, maturity) and stating that exactly one method's declared inputs must be supplied. That mapping is genuinely unavailable from the flat 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 (value currently unprofitable companies) and enumerates the exact method families the engine covers. It explicitly distinguishes itself from siblings by naming calculate_expected_value (probability weighting of arbitrary scenarios) and calculate_dcf (single going-concern DCF), so an agent can route correctly without opening any schema.

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

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

Gives an explicit trigger ('Use this when earnings-based multiples break down') plus two named alternatives with the precise condition that selects each. Coverage of when-to-use and when-to-use-something-else is essentially complete.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), but the description adds real behavioral detail the annotations cannot: exactly one method must be supplied with its declared inputs, no defaults are applied, and invalid input returns an error envelope (INVALID_ARGUMENT) rather than raising. It does not discuss output shape or numeric precision, which keeps it short of a 5.

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

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

Purpose and sibling routing are front-loaded, then the method-to-input table follows. The enumeration is long but each entry is load-bearing, since the schema alone does not encode the mapping; there is little fat to trim.

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

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

An output schema exists, so return values need no explanation. The description covers method selection, required inputs per method, the exactly-one-method constraint, and error behavior, which is everything an agent needs to invoke a 26-parameter, 11-branch tool correctly.

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

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

Schema coverage is 100% for the 26 individual fields, but the schema cannot express which subset each method requires. The description supplies that complete cross-parameter mapping for all 11 methods plus the one-method-at-a-time rule, which is genuine value 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?

The description opens with a specific verb and resource ('Market-multiple engine') and states the exact scope: apply peer multiples or derive implied multiples for comparable-basis pricing. It explicitly distinguishes itself from calculate_dcf and calculate_residual, so an agent can route correctly without opening the schema.

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

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

It gives an explicit when-to-use condition ('market-approach pricing where peers exist') and names two alternatives with the conditions that select them (intrinsic cash-flow value -> calculate_dcf; residual-income/IFRS -> calculate_residual). Nothing is left to inference.

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

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

Annotations already declare readOnlyHint/idempotentHint/non-destructive, so safety is covered. The description adds genuinely useful behavior beyond the schema: the 'exactly one method with its declared inputs (no defaults)' rule and the error envelope contract (INVALID_ARGUMENT instead of raising). It does not describe whether greeks are always returned, but the output schema covers the return 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?

The prohibition clause is front-loaded well, but the per-method input lists read as a compressor run-on and are somewhat redundant with the method enum plus parameter descriptions. The content is justified by the combinatorial method/input matrix, but the dense single block is heavy to parse.

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 9-way method enum over 22 parameters with only one required field, the method-to-input mapping is the key missing piece and it is provided. An output schema exists so return values need not be explained, and the error contract closes the remaining gap. Nothing an agent needs to form a valid call is absent.

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 documents each parameter's meaning and constraints (maturity > 0, volatility > 0, IFRS 2 labels). The description goes further by mapping which inputs each method value requires, which is semantic information the field-level schema does not express. It does not add unit/format details 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 (price) and a well-defined resource (European/American options and warrants) with the exact formula families named. It explicitly distinguishes itself from the sibling calculate_structured_product, which an agent could otherwise confuse given the overlapping 'contingent payoff' domain.

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 exclusion set (CBBCs, inline/derivative warrants, autocallables) and routes the agent to the correct sibling calculate_structured_product. The 'single contingent claim or warrant on one underlying' framing gives the positive selection criterion.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds real behavioral context beyond that: no defaults are applied, and an unknown method, missing input, or extra field returns an error envelope with code INVALID_ARGUMENT rather than raising. It does not discuss magnitude/precision of results, but with annotations plus an output schema that gap is minor.

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

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

Front-loaded correctly: purpose, then routing guidance, then the method-to-inputs table. The length is justified by 22 methods and 46 parameters, and every clause carries information, but the single run-on sentence with semicolon-delimited clauses is hard to scan and could be structured as a 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?

For a high-complexity dispatcher with an output schema already present, the description supplies the two things an agent actually needs: the method enum's input contract and the strict-failure behavior. Nothing required 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 per-field meanings are already documented and the baseline would be 3. The description exceeds that by mapping each of the 22 enum methods to its exact required input set (e.g. 'impairment_viu: carrying_value, value_in_use'), which is cross-parameter semantics the schema cannot express — essential given 46 optional-looking 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?

Opens with a specific verb+resource ('IFRS/HKFRS measurement engine') and enumerates the exact measurement domains covered (goodwill/PPA, IAS 36 impairment, IAS 40 investment property, IAS 16 revaluation, IAS 41 biological assets, residual income, etc.). It explicitly names sibling tools it is not (calculate_dcf for going-concern cash flow, calculate_market_multiple for peer multiples), so an agent can route without opening schemas.

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

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

'Use this for accounting-basis measurement of assets and equity; for going-concern cash flow use calculate_dcf and for peer multiples use calculate_market_multiple' gives an explicit when-to-use plus named alternatives and the condition that selects each. It also states the invocation contract ('supply exactly one method with its declared inputs'), removing ambiguity about how to call 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 cover read-only/idempotent/non-destructive safety, and the description adds substantial extra behavior: it warns that exactly one method must be supplied with its declared inputs (no defaults) and that unknown methods, missing inputs, or extra fields yield an INVALID_ARGUMENT error envelope rather than raising. This is genuinely useful call-time behavior not derivable from annotations.

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

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

Front-loads purpose, then method-to-input mapping, then error semantics. The method list is dense and long but each entry carries required information; some parenthetical metric glosses could be trimmed without loss.

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

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

For a 34-param, one-required-field dispatcher with an output schema, the description covers everything the agent needs: method enumeration, per-method required inputs, single-method constraint, and error behavior. Return-value detail is correctly left to the output schema.

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

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

Although schema coverage is 100%, the description supplies the critical cross-parameter mapping the schema cannot express: which inputs each method value requires (e.g. ltv needs arpu/gross_margin/churn_rate; nvt needs market_cap/transaction_volume). The schema itself defers to the description for this ('the tool description lists the exact inputs each value requires').

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 ('compute the metrics that anchor valuation') and enumerates the concrete industry domains and metrics covered (ARR, NRR, take rate, NVT, etc.). It explicitly differentiates from siblings by declaring it returns operating metrics, not a valuation.

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?

Clearly routes the agent: the outputs are 'inputs to calculate_market_multiple or calculate_dcf,' which distinguishes this tool from the valuation siblings. It does not give explicit exclusion criteria for individual methods, but the when-to-use context is clear.

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

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

Annotations already declare readOnly/idempotent/non-destructive; the description goes further by disclosing the dispatch contract (one method, no defaults) and the failure mode ('unknown method, missing input, or extra field returns an error envelope code INVALID_ARGUMENT instead of raising'). That error-shape disclosure materially changes how an agent handles failures and is not available anywhere else.

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 routing, then the method/input table — a sensible order. The method listing is dense but earns its place given 13 enum values and 24 optional fields; a small amount of repetition ('notional, spot, maturity, risk_free' recurs) keeps the per-method rows self-contained.

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

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

An output schema exists, so return values need no explanation. With purpose, sibling routing, method-to-input mapping, strictness rules, and error behavior all covered, an agent has everything needed to call this 24-parameter dispatcher 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 per-parameter units are already documented and the baseline is 3. The description exceeds that by mapping each of the 13 method values to its exact required input set, information the flat schema cannot express (the enum description even defers to it). It stops short of a 5 because per-parameter units/edge semantics are left entirely to the schema.

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

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

States a specific verb ('Value') and enumerates the exact instrument classes it covers (CBBCs, derivative/inline warrants, ELNs/ELIs, autocallables, accumulators, CLNs, TRS, CFDs). It explicitly contrasts itself with named siblings (calculate_option, calculate_convertible_bond, calculate_fixed_income), so an agent can route 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?

Explicit when-to-use ('equity-linked and credit-linked payoff structures') plus three named alternatives with the condition that selects each, and a dispatch rule ('supply exactly one method with its declared inputs'). Nothing about tool selection is left to inference.

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