Folionomiq

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

Annotations declare readOnly, idempotent, non-destructive, closed-world, so safety is covered. The description adds valuable behavioral context beyond that: 'yearly cost when the issuer publishes it' signals nullable data, the exchange-suffix convention for non-US tickers, and the not-found fallback to search_symbols. It does not mention rate limits or caching, but the additions go beyond the annotations.

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

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

Front-loads what the tool returns, then usage routing, then the ticker format and fallback. Dense but every clause carries information. Slightly heavy for a one-parameter tool, but no wasted sentences.

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

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

For a read-only single-ticker info tool with an output schema already covering return values, the description supplies the remaining context an agent needs: field scope, sibling disambiguation, ticker format, and failure recovery. Nothing material is missing.

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

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

Schema coverage is 100% and the single param is fully described in-schema, so baseline is 3. The description adds real value by explaining the exchange-suffix format with concrete examples (VWCE.DE, IWDA.AS) and by prescribing search_symbols as the recovery path for invalid tickers.

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 detailed reference data for a single fund or share. Lists the concrete fields returned (name, type, exchange, cost, return, volatility, worst fall, holdings, sectors), which distinguishes it from siblings like last_price (price only) and look_through (portfolio-level ownership).

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 says 'Use it before deciding whether a ticker belongs in a measurement,' then names two alternatives with when to prefer each: last_price for today's price only, look_through for whole-portfolio ownership. Also routes to search_symbols when a ticker is not found.

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

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

Annotations already declare read-only, idempotent, non-destructive, closed-world, so the safety profile is covered. The description adds genuinely useful context beyond that: it discloses the data source (the fund's SEC filing when one exists) and frames the output as a counterfactual that 'never says whether to buy,' which sets correct expectations for the agent. It stops short of describing cost, latency, or failure behavior for unknown tickers.

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 capability, then usage guidance, then parameters — efficient and dense with no filler. The opening sentence is a long colon-separated run-on that is slightly harder to parse than it needs to be, but nothing is wasted.

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

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

With annotations covering the safety profile, a full output schema covering return values, and every parameter documented, the description supplies exactly the missing layer: what the tool computes, when to use it versus the sibling, and that it is advisory-only. Nothing an agent needs in order to call it correctly 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 already documents all four parameters in detail (including the holdings map format and cash ticker convention). The description's parameter gloss ('add is the ticker considered, amount how much of it in the same units as holdings, base the currency') largely restates the schema rather than adding new semantics. Baseline 3 is appropriate.

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

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

Names the specific operation (evaluate one proposed addition against an existing portfolio) and enumerates the three concrete outputs: overlap with current funds, whether it adds an independent bet, and crisis counterfactuals. It explicitly distinguishes itself from the sibling tool, so an agent can route without opening either schema.

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

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

Gives an explicit when-to-use ('for one addition') and an explicit when-not with the alternative named ('for removing, reweighting or several changes at once, test_a_change'). The selection condition between the two tools 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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description adds real value beyond that: the 2-8 cardinality, the single shared window, and a scope boundary ("Says what each was; does not say which to hold") that tells the agent the tool won't give advice. It stops short of stating return shape, but an output schema exists.

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

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

Front-loaded with the metrics and scope, then disambiguation, then parameter tips. Every sentence earns its place, though the clipped fragments ("Says what each was; does not say which to hold") trade readability for 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?

With annotations carrying safety, an output schema covering returns, and 100% schema coverage for params, the description need only cover scope and routing — which it does. The only thin spot is the co-movement metric ("how each moved against the others"), which is left slightly vague but is likely resolved by the output schema.

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

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

Schema coverage is 100% and both parameters are already well documented there, including the label-shortening rule and the base-currency default. The description largely restates that ("base sets the one currency... default USD"), adding only the hint that labels are referenced in the answer. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

States a specific verb+resource (compare separate portfolios) plus the scope (two to eight, one shared price window) and the metrics returned (growth, volatility, worst fall, co-movement). It explicitly distinguishes itself from the sibling test_a_change, so an agent can route without opening either schema.

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

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

"Use it for separate portfolios; for a before-and-after of one portfolio, test_a_change" names the alternative and the exact condition that selects it. 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 cover safety (readOnly, non-destructive, idempotent, closed-world), so the bar is lower. The description adds useful behavioral context: it only produces output when foreign-currency holdings exist, and that base must be correct. It does not describe the output shape or comparison methodology beyond the hedged baseline, but that is partly covered by the output schema.

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

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

The description is front-loaded with the core purpose, then usage conditions, then a prerequisite. It is compact and every sentence adds value. Minor redundancy in 'what exchange-rate moves added to its growth, volatility and worst fall' could be tightened, but overall 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?

Given two parameters with full schema coverage, a nested holdings object, an output schema, and extensive annotations, the description covers purpose, when to use, and a critical prerequisite. The only gap is that it doesn't explicitly state that the tool returns a comparison (e.g., metrics with and without hedging), but the purpose sentence implies 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%, and both parameters have detailed schema descriptions (base currency, holdings format, weights/amounts, ticker conventions). The description adds a note that base must be the holder's currency to be meaningful, which is valuable context but not syntax beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description clearly states what the tool does: decomposes a portfolio's exposure to foreign currency and quantifies what exchange-rate moves contributed to growth, volatility, and worst fall compared with a hedged version. This is a specific verb+resource. Sibling differentiation is partially implied by the currency focus, but no sibling is explicitly named.

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 (only when some holdings are priced in another currency) and when-not (entirely in one currency, nothing to show), plus a prerequisite (base set to holder's currency). No alternative sibling is mentioned, but the condition is fully stated and leaves nothing to inference.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds genuine interpretive behavior beyond that: a sensitivity that cannot be distinguished from zero is reported as such rather than as an actionable number. It stops short of describing output shape or data-window behavior, but with an output schema present that is not a real gap.

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

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

Front-loaded with what the tool produces, then usage routing, then parameter notes, then the significance caveat. The nested parenthetical listing the four factors is dense but earns its space; nothing is 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?

Covers purpose, sibling routing, both parameters, and the interpretation caveat, and the return values are carried by the output schema. For a read-only two-parameter analytical tool, an agent has everything it needs to select 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 description coverage is 100% and both parameters are fully documented there (weights vs amounts, ticker formats, base currency default). The description restates the same facts ('holdings as weights or amounts; base sets the currency... default USD') without adding syntax or constraint detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb+resource (decomposing one portfolio's daily moves into four named factor sensitivities) and enumerates exactly what the four patterns are: market, size, value, momentum. It also reports the three outputs (sensitivity, significance vs zero, joint explanatory power), which distinguishes it cleanly from portfolio_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?

Gives an explicit trigger ('what style am I really exposed to?') and routes the adjacent question ('how many independent bets there are') to the named sibling portfolio_structure. This is the when/when-not/alternative 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 already cover the safety profile (readOnly, non-destructive, idempotent, closed-world), so the bar is lower. The description adds genuine output behavior beyond that: no overall score is returned and an axis lacking sufficient history (e.g. no crisis in window) yields no reading rather than a guess.

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

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

Purpose and the three axes are front-loaded, followed by usage routing and behavioral caveats. The phrasing is somewhat ornate ('what its risk is built from', 'for the risk taken'), 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 an output schema present the return values needn't be spelled out, yet the description still flags the two surprising output behaviors (no overall score, missing readings on short-history axes). Combined with the named alternative and full schema coverage, 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 both parameters (holdings, base) are fully documented in the schema, including the weights-vs-amounts distinction and the USD default. The description lightly restates these, adding no meaning beyond the structured fields; baseline 3 applies.

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

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

Names a specific verb+resource (a portfolio read) and enumerates the three axes it returns: concentration, resilience, efficiency. It also distinguishes itself from measure_portfolio, so an agent can route correctly without opening either schema.

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

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

Gives an explicit trigger ('when the reader asks whether something is off in how the portfolio is built') and names the alternative for the broader case ('for the full measurement use measure_portfolio'). Both the when-to-use and the when-not-to-use 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 declare readOnlyHint, idempotentHint and destructiveHint=false, so safety is covered. The description adds behavior beyond that: cardinality and return scope ('One figure per ticker; no price history is returned') plus the dual-currency framing. It does not mention rate limits or failure modes, but for a read-only lookup with full annotation coverage this is solid.

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

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

Front-loaded with the core definition, then usage, then the alternative, then the base parameter. Every sentence carries weight, though the parenthetical aside about 'base' interrupts the flow of the usage guidance and could be merged more cleanly.

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

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

An output schema exists, so return-value explanation is not strictly required, and the description still volunteers the key cardinality fact. The phrase 'in the base currency and in its own' combined with 'One figure per ticker' is mildly ambiguous about whether two amounts or one are returned, but the output schema resolves 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 base default and the 50-ticker cap. The description's 'base sets the currency of the converted price (default USD)' largely restates the schema rather than adding syntax or format detail, so the baseline of 3 applies.

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

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

States a specific verb+resource+scope: 'The latest daily close for each ticker, in the base currency and in its own, with the date.' It also explicitly distinguishes itself from the closest sibling ('for the history and figures of one asset use asset_info'), so an agent can route without opening either schema.

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

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

Gives a concrete when-to-use case ('turn a number of shares into an amount before a measurement') and names the alternative tool for the contrasting case ('asset_info'). Nothing is left to inference about which of the two to pick.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds genuinely useful behavioral context beyond that: the result is 'a count of starts, never a probability' and 'a span the record is too short for is said, not invented' — both important framing for interpreting output, though it does not discuss performance or pagination.

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 every sentence carries information, but the opening sentence is a long, comma-heavy enumeration and the parameter notes are packed into the same paragraph rather than separated. Dense and useful, slightly 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?

With an output schema present, return values needn't be explained, and the description still covers scope, defaults, units, the sibling alternative, and the counts-not-probabilities caveat. Complete enough for a 5-parameter analytic tool, though nothing is said about the base-currency interaction or runtime cost.

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 baseline is 3, but the description adds meaning the schema lacks: amount 'defaults to the sum of the holdings', withdrawal is 'the yearly amount in today's money', and years' 5–50 range with default 30 is restated inline. That clarifies the weights-vs-money distinction the schema only hints at.

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 — replaying a yearly, inflation-raised withdrawal from every start month the history allows — and enumerates the four outputs (starts that lasted, starts that ran out and when, lowest point from worst start, highest failing rate). An agent can distinguish it from monthly_plan and past_crises 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 use case ('can I live off this?') and routes to the right alternative by condition: 'for money put in every month instead, monthly_plan.' That is the sibling-routing pattern that makes selection 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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the description's real contribution is the disclosure that figures are minimums, count only nameable companies, and that the answer reports coverage. That is meaningful behavioral context beyond the annotations, though it says nothing about rate limits or performance.

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?

Content is front-loaded (what it returns, then usage, then input semantics) and every clause carries information. The sentences are dense and clause-heavy, which costs a little readability, but there is no filler.

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

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

With an output schema present, return-format explanation is unnecessary, and the description still covers the aggregation scope, input forms, currency, and the important 'minimums / nameable-only' caveat. Complete enough for a nested-object, single-required-param 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 schema already documents both parameters. The description restates the holdings-as-money behavior and the base currency default (USD), adding little beyond what the schema already conveys. Baseline 3 is appropriate.

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

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

The description states a specific verb+resource: aggregating the underlying companies a portfolio owns through its funds, with shares, overlapping names, and sectors. It explicitly distinguishes itself from measure_portfolio (full measurement) and asset_info (one fund), 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 names the user question it answers ('what do I really own?') and routes to explicit alternatives: measure_portfolio for the full measurement, asset_info for a single fund. Both when-to-use and when-not-to-use are present.

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive, closed-world), so the bar is lower; the description adds real behavioral context by declaring the tool descriptive ('no forecast, no advice') and explaining that supplying amounts switches the crisis output into money terms. It does not cover latency, aggregation limits, or failure behavior, but for a read-only aggregate nothing critical is missing.

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 routing rule; every sentence carries information. The output enumeration slightly duplicates the output schema, and the sentence is long, but there is no filler.

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

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

For a 2-parameter tool with one required nested object, an output schema, and full annotation coverage, the description supplies everything else needed: scope, routing, descriptive framing, and the amount-vs-weight consequence. Nothing required to call it correctly 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 coverage is 100%, so the baseline is 3, but the description frames the weight-vs-amount parameter decision as an output-selection choice ('Give amounts to get losses in money') rather than raw syntax — a meaning an agent can act on without reading the schema. The base currency note largely restates the schema, which caps the score below 5.

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

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

States a specific verb and resource ('complete measurement of one portfolio in a single call') and then enumerates the exact outputs (independent bets, risk-out-of-line holding, look-through companies, crisis drawdown/recovery, numbered report). This lets an agent distinguish it from siblings like portfolio_structure or past_crises 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 rule: 'Use it when the reader asks broadly about a portfolio; for one question the narrower tools answer faster' followed by the four named alternatives. Both the when and the when-not (with named substitutes) 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 declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds genuinely non-obvious behavior: dividends are reinvested, results are in each year's money, figures are pre-tax and pre-fee, the plan is re-run from every January, and nothing before the record is extrapolated. It does not discuss cost or return shape, but the output schema covers the latter.

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 leads and the routing sentence follows, so it is front-loaded. The middle clause stacking three outputs ('what it became..., the day it stood furthest below..., the longest stretch below it') is dense and slightly clause-heavy, but each clause carries real information.

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

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

For a read-only historical simulation with full annotations and an output schema, the description supplies everything needed to call it correctly: what is simulated, in what currency basis, what caveats apply, and which siblings to prefer instead. No material gap remains.

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 four parameters including the weights-vs-amounts acceptance rule and ticker format. The description's 'Holdings are weights here; monthly is the amount, start the first year' restates that mapping rather than adding new meaning, so the baseline 3 applies.

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

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

States a specific verb (replays) on a specific resource (a fixed monthly purchase on one portfolio's history), and enumerates exactly what it computes: final value vs. contributions, deepest shortfall, longest underwater stretch, plus re-runs from every January. An agent can distinguish it from return_history or living_off_it without opening either schema.

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

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

Gives an explicit trigger phrase ('if I put X a month into these, what would it have become?') and names two alternatives with their selecting conditions: living_off_it for withdrawals and return_history for the raw record. When-to-use and when-to-use-something-else 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 establish this as a safe, read-only, idempotent, deterministic operation, so the safety burden is covered. The description adds genuinely useful behavioral disclosures not in annotations: unknown-before-holding crises are named 'not tested' rather than estimated, and amounts trigger a money-denominated view in the base currency.

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

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

Front-loaded with the resource and the exact crisis scope, then usage guidance, then the parameter-dependent output behavior. The prose is compact and every clause carries information, though the distinctive 'not tested' policy sits at the end when it might belong earlier for routing decisions.

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

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

For a read-only analysis tool with a fully described schema and output schema, the description covers purpose, sibling routing, the holdings/amounts duality, base-currency handling, and the handling of pre-existence crises. Nothing material an agent needs in order to call it correctly or interpret its output 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 both base and holdings are fully documented structurally, and the schema describes the holdings syntax (ticker: weight/amount, 1–100, cash handling). The description adds a layering detail the schema omits: numbers are interpreted as amounts in the base currency specifically to show each fall in money rather than as weights.

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: it returns what named crises (2008, 2020, 2022) did to one portfolio, including the fall, worst day, and recovery days. It explicitly distinguishes itself from the sibling return_history and explains the 'not tested' labeling, so an agent can select it without inspecting 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?

Directly gives the trigger phrase ('what did crashes do to this?') and names the alternative sibling (return_history) for the whole record. It also notes that amounts produce per-crisis money figures, so the agent knows which parameter shape changes the output.

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 and non-destructive, so safety is covered. The description adds meaningful output behavior beyond that: prose sentences, no tables, no numbered report, and that supplying amounts makes the fall render in money at the base currency (default USD). This is genuine context the annotations do not carry.

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

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

It is front-loaded with the output shape before the usage and currency details. The parentheticals make it slightly dense and it runs long for a two-parameter tool, but every sentence carries information.

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

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

With an output schema, rich annotations, and 100% parameter coverage, the remaining burden is output style and routing, both addressed. A reader understands what they get and when to prefer it, so nothing critical 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 both parameters are already documented. The description restates that amounts produce the fall in money and that base defaults to USD, which largely mirrors the schema rather than adding new syntax or constraints. Baseline 3 is appropriate.

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

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

The description states concretely what is produced: three or four plain-language sentences covering what a portfolio's risk is built from and its worst historical fall. It differentiates from siblings by pointing to measure_portfolio for figures and contrasting with 'no tables and no numbered report' (portfolio_report). It lacks a crisp action verb but the resource and output are unambiguous.

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 selection context: 'Use it for the shortest answer, or for a reader new to investing', and routes the agent to measure_portfolio when figures are wanted. There is no explicit 'when not to use' beyond the report contrast, 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 cover read-only/idempotent/non-destructive, and the description adds genuinely new behavioral context: the report window 'starts when the youngest holding starts' and amounts are converted into base currency. It stops short of describing report length or pagination, but that is minor given the annotation coverage.

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 whole thing is four tight sentences. The prose is a little flowery ('make the report speak in money'), which costs a point, but nothing is redundant.

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

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

Output schema exists so return values need not be spelled out, and both parameters plus the window-start behavior and currency handling are covered. The only soft spot is that the actual contents of the numbered report are described only abstractly.

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 already documents base-currency defaults and the weights-vs-amounts semantics of holdings. The description largely restates these ('amounts in the base currency (default USD)'), adding little beyond the schema, so the baseline 3 is appropriate.

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

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

States a specific artifact (a written, numbered F1/F2 report) on a single resource (one portfolio) and explicitly distinguishes itself from measure_portfolio, which returns 'this same report together with structure, look-through and crises'. An agent can tell exactly what this produces versus its closest 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 the selection condition ('For a reader who wants something to quote or keep') and names the alternative (measure_portfolio) that returns a superset. The when-to-use and the competing option are both explicit.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered. The description adds genuinely useful behavior beyond that: 'the window is set by the youngest holding' and that weights vs amounts yield the same answer here. It does not, however, discuss output granularity or cost/latency for what is clearly a heavy computation.

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

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

Front-loaded with the core purpose, then usage, then caveats, with no filler sentences. The opening clause ('from how their prices moved together rather than how many tickers there are') is a touch convoluted but earns its place as the key differentiator.

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

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

An output schema exists, so return values need no explanation, and parameters are fully documented in the schema. The description covers purpose, usage, sibling routing and the window rule; only deep output-shape or performance expectations are absent, which is acceptable 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 description coverage is 100%, so both parameters are already documented (base currency, holdings map with ticker conventions). The description only restates base's role and default, adding the mildly useful note that weights and amounts give the same answer. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

States a specific, non-obvious verb+resource: the effective number of independent bets derived from co-movement rather than ticker count, plus per-holding risk share vs money share. It explicitly distinguishes itself from measure_portfolio, which is named as the superset that also includes look-through and crises.

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 questions it answers ('am I diversified?', 'which holding carries the risk?') and names the alternative with the condition that selects it (measure_portfolio includes this plus look-through and crises). An agent can route between the two without inspecting schemas.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description still adds real context beyond them: the result is a past record and explicitly not a forecast, and the base currency choice changes results for holdings priced in other currencies. It does not discuss pagination or performance limits, 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 returned content before routing advice, and every sentence carries information. The output enumeration is dense but coherent; it is slightly long, which keeps it out of the top score rather than harming comprehension.

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 restated, and the description covers purpose, routing, the currency caveat, and the past-only scope. For a two-parameter read tool, an agent has everything needed to select and 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 the baseline is 3, but the description earns extra by explaining the consequence of 'base' (it sets the currency growth is measured in and changes the result for non-USD-priced holdings) in a way the schema's terse field description does 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?

States a concrete verb+resource and precisely enumerates what is returned: growth per year before/after inflation, best/worst months and years, rolling 12-month ranges, calendar returns, and weight drift between rebalances. It also explicitly distinguishes itself from siblings past_crises and monthly_plan, so an agent can route 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 an explicit trigger ('how did this do?') plus two named alternatives with their selecting conditions ('for crises only use past_crises, for money put in every month monthly_plan'). Nothing about when to choose this versus its 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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world), but the description adds a substantive behavioral limit: 'No probability is computed: the answer says how large the moves would be, not how likely.' That prevents a plausible misuse of the result. It stops short of describing cost, rate limits, or how the 'least extreme' combination is selected.

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

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

Front-loaded with the core behavior, then usage routing, then parameter notes, then the probability caveat. Every sentence carries information; the parenthetical glosses are slightly redundant with the schema but not 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?

For a read-only analytical tool with an output schema, a fully documented input schema, and sibling routing, the description supplies everything an agent needs: what it computes, when to pick it, and the key interpretive limitation.

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 nested holdings object is thoroughly documented in the schema itself. The description's 'loss is a fraction (0.25 is a quarter); base sets the currency (default USD)' largely restates what the schema already says, so it adds little beyond the baseline.

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

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

States a specific verb and resource ('starts from a loss... finds the least extreme combination of market moves that would produce it on this portfolio') and explicitly contrasts with the sibling past_crises. An agent can distinguish it from the 21 other 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 the triggering question verbatim ('what would it take to lose that much?') and names the alternative for the opposite question ('for what past crises actually did use past_crises'). When-to-use and when-not-to-use are both explicit.

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

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

Annotations already cover the safety profile (readOnlyHint=true, idempotentHint=true, destructiveHint=false, openWorldHint=false). The description adds useful behavior beyond them: results include the exchange each listing trades on, the base parameter reorders listings by currency, and unchecked listings are flagged. That last point is a meaningful disclosure about result trustworthiness; only the return shape/pagination is left unstated (and an output schema exists).

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

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

Front-loaded with the core purpose and example, and every clause carries information. The prose is a bit run-on and parenthetical, but there is no filler sentence to cut.

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 lookup with full schema coverage, annotations and an output schema, the description supplies the intent, the routing decision, and the notable result traits (exchange, unchecked status). Only pagination/result-count behavior is unspecified, a minor gap 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 would be 3, but the description adds real meaning beyond the schema: it clarifies that query accepts partial names and ISINs, and that base is an ordering preference ('puts the listings in that currency first') rather than just a display currency, which the schema's own text 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 verb+resource (finds a ticker) and enumerates the accepted input forms (name, partial ticker, ISIN) with a concrete example ('Vanguard total world' gives VT). It also names the sibling it is not (validate_symbols), 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?

Explicit when-to-use ('Use it first when a ticker is uncertain') and an explicit exclusion with the alternative named ('for a list of tickers already written down, validate_symbols'). 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, destructiveHint=false and a closed world, so the safety profile is covered. The description adds a genuinely useful behavioral caveat beyond the structured fields: it never recommends a weight, only reports the sweep. It stops short of describing return shape, but the output schema carries that.

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

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

The purpose is front-loaded, followed by routing guidance and parameter notes in a compact block with no filler sentences. Slightly dense run-on phrasing around the output metrics, but every clause earns its place.

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

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

With annotations, a 100%-covered schema, and an output schema, the description only needs to carry intent and routing, which it does fully. The only omission is any hint about result volume or interpretation of the sweep output, which is minor given the output schema exists.

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

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

Schema description coverage is 100%, so the schema already documents all three params. The description's notes on ticker ('must be one of the holdings') and base ('default USD') largely restate the schema, adding little syntax or behavioral meaning beyond it. Baseline 3 is appropriate.

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

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

The description states a specific operation (measure one already-held holding at every weight from none to all, rest shared pro rata) and names the exact outputs (volatility, risk share, number of independent bets). It explicitly distinguishes itself from test_a_change and check_before_you_buy, 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?

It gives an explicit use case ('how much of this is enough to change anything?') plus two contrasting alternatives with their selecting conditions: test_a_change for one specific change, check_before_you_buy for a holding not yet owned. Nothing about when-to-use vs when-not 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, closed-world behavior, so the bar is lower. The description adds real beyond-annotation context: the 'after' figures are counterfactual and the window defaults to the longest shared one unless start/end are supplied. It stops short of describing output format, though the output schema covers that.

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

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

Front-loads the core purpose, then alternatives, then parameter notes, then the scope caveat — a logical order with little wasted text. Slightly dense and clause-heavy in the opening sentence, which keeps it from a 5.

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

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

For a nested-object comparison tool, the description covers purpose, alternatives, window behavior, and the counterfactual caveat; annotations carry the safety profile and an output schema exists so return values need no explanation. 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 description coverage is 100%, so the baseline is 3. The description goes further by explaining that start/end override the default 'longest shared' window and by restating that current/proposed are the two holding sets, giving the parameter meaning beyond the bare 'Optional window start' 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 and resource ('any change to one portfolio, measured before it is made') with the exact output dimensions (structure, risk, worst falls, additions/removals). It also distinguishes itself from siblings by naming check_before_you_buy and sweep_holding with the conditions that select them.

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

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

Explicitly routes the agent: for a single new holding use check_before_you_buy, for one holding at every weight use sweep_holding. It also closes a scope question by stating the tool 'never says whether to make the change', so the agent knows the output is diagnostic only.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so safety is covered. The description adds real behavioral context beyond that: it is a pre-flight check that 'measures nothing', and it discloses the shape of its findings (usable vs. unusable history, closest listing). It does not mention limits such as the 150-ticker cap or rate/latency behavior, but the added scope clarification is meaningful.

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 what the tool does and its three outputs, then the when-to-use rule and alternative, then the base nuance, closing with the scope boundary ('It measures nothing'). Every clause carries information and none 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?

An output schema exists, so return values need not be spelled out; the description still summarizes them helpfully. Purpose, routing to the sibling tool, and the one non-obvious parameter behavior are all covered for a two-parameter read-only validator.

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

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

Schema coverage is 100%, so the baseline is 3. The description goes further than the schema's 'Currency every figure is expressed in' by explaining that base prioritizes the listing in that currency when a symbol trades in several markets — a tie-breaking semantic the schema does not state.

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

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

States a specific verb and resource (checks a list of tickers) and enumerates the three concrete outcomes it returns: which have usable price history, which do not, and the closest listing for ambiguous symbols. It is clearly distinguishable from siblings like search_symbols and measure_portfolio.

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

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

Gives an explicit when-to-use condition ('when the tickers are already written down') and names the alternative plus its triggering condition ('when only a name is known, search_symbols'). 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, closed-world, so the safety profile is covered. The description adds real behavioral context beyond that: refit windows (train_years, step_months), the comparison baseline (equal weights), and the crucial caveat that it 'returns the record, never an allocation to hold' — clarifying that no actionable weights come back.

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

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

The purpose is front-loaded in the first sentence, followed by usage guidance and then parameter roles, so ordering is logical. The prose is dense and long-winded in places (the refit loop is described twice, once narratively and once via train_years/step_months), but every clause carries information.

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

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

With an output schema present, return values need not be enumerated, and annotations carry the safety profile, so the description only needs usage, method and param context — all of which are supplied. The one gap is that 'base' is only explained in the schema, but that is covered there, leaving the definition effectively 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%, so the structured schema already documents every parameter including base and the enum-like objective values. The description restates roles for tickers, holdings, objective, train_years and step_months but adds no syntax or format detail beyond the schema, and omits base entirely. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

The description names a concrete procedure (fit on prior years, hold on unseen prices, repeat, compare against the held portfolio and equal weights) rather than restating the title, so an agent knows this is an out-of-sample walk-forward evaluation. It also carves out what it is not ('not for choosing weights'), which separates it from weight-selection siblings, though it does not name a specific sibling 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?

It gives an explicit trigger ('use it only when the reader asks whether an optimiser would have beaten what they hold') and an explicit exclusion ('it is not for choosing weights'). The when-to-use condition is unambiguous and tied to the reader's intent.

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