Folionomiq

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 still adds useful behavioral context beyond that: the exchange-suffix requirement for non-US symbols and a scope disclaimer about advice/prediction/tax. It does not say what happens on an invalid or ambiguous ticker, which is the one remaining 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-loads the resource and its returned fields, then examples, then the sibling alternative, then constraints — a sensible priority order. Slightly over-packed with example questions and a metric list, but no sentence is 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, the description need not enumerate return values, and the read-only annotations cover the safety profile. Combined with routing to search_symbols for suffix discovery, an agent has what it needs to call this correctly; only failure handling for unknown tickers is unaddressed.

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

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

Schema coverage is 100% and there is a single parameter, so the baseline is satisfied by the schema alone. The description nevertheless adds real operational meaning: single-ticker only, and the exchange-suffix convention illustrated with VWCE.DE and IWDA.AS, which is more actionable than 'as the exchange lists it'.

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

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

States a precise verb+resource: returns profile data for a single fund or share, enumerating the exact fields (name, type, exchange, cost, return, volatility, worst fall, top holdings and sectors). It explicitly separates itself from look_through (whole portfolio) and search_symbols (ticker discovery), so an agent can route between siblings without opening schemas.

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

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

Gives concrete triggering questions ('What is EQQQ.DE?', 'What's inside VXUS?'), names the alternative for the portfolio-level case (look_through), and states the prerequisite that non-US tickers need an exchange suffix with search_symbols as the resolver. It also sets explicit exclusions: no recommendations, predictions, or tax calculations.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds real behavioral context: the 'after' portfolio is hypothetical, the output is a three-column decision sheet, and the tool does not recommend, predict, or calculate tax. Missing only practical traits like cost/latency or data freshness, which is why it is not a 5.

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

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

Front-loads the purpose, then the typical questions, then the exclusion, then the limits — a sensible information hierarchy. Slightly dense with three quoted example questions, but each sentence carries routing or scoping value.

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?

The tool is complex (nested holdings, unit inference), yet the description plus the 100%-covered schema and an existing output schema cover everything needed to call it and interpret the answer. Limits (no advice, no tax, hypothetical after-portfolio) close the remaining ambiguity.

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

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

Schema description coverage is 100% and the schema already explains the units inference rule, ticker formats (including CASH.USD), and the amount's unit alignment. The description echoes the general 'holdings + add + amount' shape but adds no parameter detail beyond what the schema documents, so baseline 3 applies.

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

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

States a specific verb+resource+scope: adding one new holding to an existing portfolio, reporting overlap, independence, crisis behavior, and a now-vs-cash-vs-new-holding decision sheet. It explicitly separates itself from test_a_change, so an agent can route between the two without opening a schema.

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

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

Gives the triggering condition ('before adding one new holding'), concrete user phrasings as examples, and an explicit exclusion with the correct alternative ('for selling, reweighting or several changes at once, test_a_change'). It also bounds the tool's role: it never says whether to buy.

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 adds genuine context beyond that: the 2-8 portfolio limit, the input shape, the measures returned including cross-portfolio co-movement, and an explicit negative capability boundary. Minor gap: nothing about how a window or date range is chosen, though no such parameter 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 input and output contract, then alternatives, then exclusions – a sensible order with little waste. The inline 'In: {label: {ticker: weight}}' duplicates the schema slightly and reads awkwardly, but overall it is tight.

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, yet the description still names the four headline measures and the cross-portfolio comparison. Input format, cardinality limit, use cases and exclusions are all covered for a tool with nested object parameters.

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 (base currency default USD, portfolios map) are documented in the schema, including label shortening. The description restates the {label: {ticker: weight}} shape and the 2-8 limit but adds no syntax or weighting semantics beyond what the schema already says, so baseline 3 applies.

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

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

States a specific verb and resource with scope: two to eight portfolios measured on one shared window of prices. That scope, plus the output measures listed, makes it immediately distinguishable from single-portfolio siblings like 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 concrete example questions that select this tool, and explicitly routes the adjacent case (one portfolio before/after a change) to test_a_change or check_before_you_buy. Also states what the tool does not do: no recommendations, predictions or tax.

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

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

Beyond the readOnlyHint/idempotent annotations, it discloses that the tool does not recommend, predict or calculate tax, and that base must match the holder's currency. It does not describe return format or error behavior, but with an output schema and strong annotations, this adds useful context.

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

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

The description is front-loaded with the core purpose, then typical questions, then limits. It is appropriately sized, though the illustrative questions could be seen as slightly verbose; every part still adds clarity.

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 the tool's complexity (nested holdings, currency mismatch, hedged comparison) and the presence of a full output schema and annotations, the description is complete enough for an agent to decide when and how to call it correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds a meaningful constraint not in the schema: base must be set to the holder's currency. It otherwise relies on the schema for units and holdings format.

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

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

The description states a specific analytical purpose: decomposing currency effects on growth, volatility and worst fall for holdings partly outside the base currency, and comparing against a hedged version. It is clear what the tool does, but does not explicitly differentiate itself from sibling portfolio analysis tools.

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 provides concrete typical questions ('I'm in euros but hold US funds...') and a clear limit: only applies when some holdings are priced in another currency, and base must be the holder's currency. However, no alternative tools are named for cases where the limit is not met.

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 that this is a read-only, idempotent, non-destructive operation. The description adds useful behavioral context by describing the outputs (sensitivities, significance versus zero, explanatory power) and stating that it does not recommend, predict, or calculate tax.

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 measurement and then adds examples, an alternative tool, and limitations. It is somewhat longer than strictly necessary due to three sample questions, but each part remains relevant.

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

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

With an output schema present, the description does not need to explain return values in full, and it already summarizes the key outputs and limitations. It could say more about the estimation window or method, but overall it is complete enough for correct tool selection and invocation.

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

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

Schema description coverage is 100%, so the schema already documents base, units, and holdings in detail. The description does not add parameter-specific semantics beyond referring generally to portfolio daily moves, so the baseline score of 3 is appropriate.

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

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

The description states precisely what the tool measures: a portfolio's daily return sensitivity to four named common patterns (market, size, value, momentum). It also clearly distinguishes this from the sibling portfolio_structure tool, which handles independent-bet counts.

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 provides concrete typical questions that indicate when to use it, such as checking unintended growth or small-cap tilts. It also explicitly names an alternative, portfolio_structure, and the condition under which that alternative is more appropriate.

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

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

Annotations already declare this as a read-only, idempotent, non-destructive, non-open-world operation. The description adds important behavioral context beyond that: it produces three separate axis readings with no overall score, returns nothing for an axis lacking sufficient history, and explicitly does not recommend, predict, or calculate tax.

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 purpose and then adds routing examples, an alternative, and limitations. It is slightly longer than strictly necessary because of the three example questions, but each part is relevant and clearly structured.

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 the tool's complexity, rich schema, annotations, and output schema, the description covers what an agent needs: the three axes, the absence of an overall score, the sibling alternative for full measurement, behavior with insufficient history, and non-recommendation boundaries. Return formatting is handled 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 description coverage is 100%, and the input schema already documents `holdings`, `base`, and `units` in detail, including unit inference rules and examples. The tool description does not add parameter-specific meaning beyond what the schema provides, so the baseline score of 3 is appropriate.

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

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

The description states a specific verb and resource: it reads one portfolio along three separate axes — risk construction, crisis behavior, and return for risk taken. It explicitly distinguishes this from the sibling `measure_portfolio`, which provides the full measurement, so an agent can select it without opening the schema.

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

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

It gives concrete typical questions that should trigger the tool and names the alternative: use `measure_portfolio` for the full measurement. It also notes that an axis without enough history comes back without a reading, setting expectations for incomplete results.

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 and openWorldHint, so the safety profile is covered. The description adds scope traits beyond that: one price per ticker, no history, and explicit non-goals ('does not recommend, predict or calculate tax'). It does not discuss rate limits, symbol validity handling, or what happens with unknown tickers, which keeps it below a 5.

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

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

The core statement is front-loaded and the follow-on sentences each carry distinct information: examples, the sibling alternative, the one-price-no-history constraint, and the non-goals. There is minor formatting noise from an embedded line break in the text, but no redundant 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?

An output schema exists, so return values needn't be explained, and the description covers purpose, exclusions, and non-goals for a simple two-parameter tool. A minor gap is that it doesn't hint at behavior for invalid or unknown tickers, despite a validate_symbols sibling in the family.

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 the 'tickers' (up to 50) and 'base' (default USD) parameters are already documented. The description reinforces the dual-currency output and shows tickers in use (VWCE, VTI), but adds no syntax, formatting, or edge-case 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?

The description names a specific verb and resource: the latest daily close per ticker, expressed in both the ticker's own currency and the base currency, plus the date. It explicitly carves out the boundary against asset_info ('for history and figures of one asset'), so an agent can distinguish it from siblings without opening either schema.

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

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

It supplies concrete example questions ('What's the last price of VWCE?'; 'Turn 120 shares of VTI into dollars.'; 'Latest close for these tickers.') that map real intents to this tool. It also names the alternative and the condition that selects it: 'Instead: for history and figures of one asset, asset_info. One price per ticker, no history.'

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), and the description adds interpretation-critical context beyond them: results are counts of past starts and 'never a probability', and the replay is bounded by 'every start month the history allows'. It stops short of saying how far back the data reaches per ticker, which matters for a closed-world historical tool.

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

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

The output spec is front-loaded and the alternative tool plus caveats follow in a logical order with no filler sentences. It is a single dense block with telegraphic phrasing and three example questions where one would establish the pattern, so it is slightly longer than needed.

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 six-parameter, nested-object tool with an output schema and full annotation coverage, the description covers what it computes, how to read the output as historical counts, and the sibling alternative. The missing piece is the boundary of the available history, which the phrase 'the history allows' acknowledges without quantifying.

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 base, units, years, amount, holdings and withdrawal, and the description mostly restates the holdings/units inference rules. It does add the consequence of that inference ('which makes the falls come out in money') and re-states that the withdrawal is raised with the real price index, but it never mentions years or amount directly.

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 operation on a specific resource: a yearly withdrawal, inflation-adjusted, replayed from every start month, reporting survival counts, depletion dates, worst-start low, and the highest failing rate. It explicitly separates itself from monthly_plan, so an agent can route without opening either schema.

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

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

Gives concrete selection cues via three typical questions, names the alternative tool and the condition that selects it ('for money put in every month instead, monthly_plan'), and states exclusions ('does not recommend, predict or calculate tax'). Nothing about when to pick this 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 establish read-only, idempotent, non-destructive behavior, but the description adds important caveats: figures are minimums when funds disclose only top holdings, the answer reports named coverage, and the tool does not recommend, predict, or calculate tax. It does not discuss rate limits or authentication, but those are not central for this local analysis tool.

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

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

Front-loads the purpose and expected output, then gives examples and exclusions. It is somewhat long, but most sentences earn their place by clarifying output scope or avoiding misuse.

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 an output schema exists, the description need not restate return fields in detail, and it already names the main output categories plus key limitations. For a read-only analytical tool with fully described parameters, this is complete enough to invoke 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 parameter definitions already carry the baseline. The description adds useful semantics beyond the schema: ticker formatting conventions, cash notation, 1–100 holdings, and the units inference rule when omitted.

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-like operation and resource: aggregating the companies a portfolio owns through its funds. It also distinguishes the scope from sibling asset_info, so an agent can tell this is portfolio-wide look-through rather than single-fund detail.

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 typical questions and names the alternative: use asset_info for one fund on its own. That directly routes the agent between this tool and a close sibling.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered; the description adds value by disclosing the response contents and hard scope exclusions (no advice, no prediction, no tax). It stops short of stating latency, cost, or failure modes (e.g. unknown tickers), so not a 5.

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

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

Front-loads the core statement in one sentence, then In/Out, then usage routing and exclusions — well structured. The long list of example questions is slightly padded but each element maps to a distinct decision the agent must make.

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

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

With an output schema present, the description needn't document return shapes, yet it still summarizes them; combined with explicit sibling routing and scope exclusions, an agent has everything needed 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 the schema already documents base, units, and holdings including the weights-vs-money auto-detection rule; the description's 'In: holdings as weights or money amounts' merely restates it. Baseline 3 applies since structured fields carry the parameter burden.

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

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

States a specific verb and resource ('full measurement of one portfolio'), then enumerates concrete outputs (independent bets, risk vs money share, look-through companies, past crises, numbered report), which lets an agent distinguish it from narrower siblings. The scope is 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?

Explicitly routes the agent: 'for one narrow question use the narrower tool' and names three alternatives with their domains (portfolio_structure, look_through, past_crises), plus portfolio_report for quotable text and plain_findings for the shortest answer. Also states what it does not do (recommend, predict, calculate tax).

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds meaningful model assumptions the agent would otherwise guess: dividends reinvested, purchases on the first trading day, results before taxes and fees, and no recommendation/prediction/tax computation. It stops short of disclosing data frequency or how the 'deepest point below' is measured, so not a full 5.

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

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

The core action leads, followed by the reported quantities, example questions, and exclusion routing — a sensible front-load. Some phrasing is stylized ('what it became against what was put in') and the three sample questions are slightly redundant, but nothing is padded enough to waste an agent's attention.

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

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

For a 4-parameter tool with nested holdings and an output schema, the description covers what is computed, the reinvestment/timeframe assumptions, tax and fee scope, and the sibling to use instead. Return-value explanation is rightly omitted because an output schema exists.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds semantics the schema lacks: the monthly amount is bought on the first trading day, and the start year defines a January with the plan also replayed from every possible starting January (a rolling-window behavior not evident from 'the year whose January the plan starts in'). The dollar examples reinforce the monthly parameter's scale.

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

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

States a specific computation: a fixed monthly purchase on the first trading day of each month, replayed on the portfolio's own history with dividends reinvested, reporting final value vs. contributions, the deepest underwater point, and rolling January-start replays. This is a precise verb+resource definition that an agent can separate from siblings like return_history or compare_portfolios without opening a schema.

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

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

Gives concrete triggering questions ('If I put $500 a month into these...', 'Dollar-cost averaging into VTI since 2007?') so an agent can pattern-match a user's ask. It also names explicit negatives and alternatives: living_off_it for withdrawals, return_history for the raw record.

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 that this is a read-only, idempotent, non-destructive operation. The description adds meaningful behavioral context beyond that: it explains the output fields, notes that crises before a holding existed are labelled 'not tested', and states that the tool does not recommend, predict, or calculate tax.

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 purpose and input/output shape, then adds examples, sibling routing, and scope caveats. Despite being fairly detailed, every element is useful for selecting and invoking the tool correctly.

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 the tool's complexity, the presence of an output schema, and rich annotations, the description is complete enough: it covers the scenario, input expectations, output meaning, limitations, and alternatives. Nothing critical for correct invocation appears 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%, and the input schema already fully documents holdings, base, and units. The description reinforces that holdings drive the analysis and that money-based versus percentage-based holdings affect whether falls appear in money or percentages, but it adds little parameter syntax or meaning beyond the schema.

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

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

The description states a specific analytical operation: showing what named historical crises did to a current portfolio mix using its price history. It distinguishes the tool from siblings by explicitly naming reverse_stress and return_history as alternatives for different questions.

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 usage cues through typical questions and clearly routes related needs elsewhere: reverse_stress for a chosen loss level and return_history for the whole record. This leaves little ambiguity about when to call past_crises versus its siblings.

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

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

Annotations already declare readOnly/idempotent/non-destructive/closed-world, so the safety profile is covered. The description adds genuine behavior context the annotations don't: output length (three or four sentences), that every figure carries its measurement window, and that advice/prediction/tax calculation are out of scope. It stops short of saying how invalid or unknown tickers are handled, which matters for a tool that takes free-form 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-loaded with the output shape, then example questions, then sibling routing, then exclusions — a sensible order with no filler. It is slightly long-winded and the awkward line breaks make it read as one run-on block, 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, rich annotations, and fully described parameters, the description only needs to say what the tool is for and when to prefer it — which it does. Minor gap: nothing about failure behavior for unrecognized tickers or about how expensive/long the call is, which is the one thing left for an agent to guess.

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

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

Schema description coverage is 100% and the holdings property is documented in depth (scales, ticker conventions, CASH.USD, example object), so the schema carries parameter meaning. The description only implies the single-portfolio scope and adds nothing on base/units handling or the 1–100 holding limit. 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 exactly what the tool produces (three or four plain sentences about one portfolio's risk construction and worst historical fall, each with its window), which is a specific verb+resource+output shape. It explicitly names the two sibling tools that do something else (measure_portfolio, portfolio_report), so an agent can pick it without opening any schema.

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

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

Gives concrete triggering questions ('Explain my portfolio simply', 'I'm new to investing...') plus explicit routing to alternatives for the figures-in-full and numbered-report cases. It also adds a negative boundary: it does not recommend, predict or calculate tax.

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 carry readOnly/idempotent/non-destructive/closed-world, so the bar is lower; the description still adds the scope boundary (no recommendations, predictions, or tax calculations) and the output nature (a quotable text). It does not discuss length, rate limits, or what happens with unusual holdings, but nothing it says conflicts with 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-loaded with what the tool produces before the routing information; sentences are terse and telegraphic ('In: … Out: … Instead: … does not …'). The three sample questions are useful for matching but are the one slightly padded element.

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

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

Output schema exists and the description still characterizes the return as a quotable numbered text, plus it delimits scope against three siblings and states what it will not do. For a read-only report tool with a fully documented schema, an agent needs nothing more to call it correctly.

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

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

Schema coverage is 100% and each parameter (base, units, holdings) carries detailed enumeration and defaults, including the money-vs-weights inference rule and ticker/cash formatting. The description only signals 'In: holdings' and adds no syntax or default 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 (a written report on one portfolio) with the distinctive artifact spelled out: figures numbered F1, F2… beside method and window. Explicitly separates itself from measure_portfolio (full structured measurement) and plain_findings (a few plain sentences), 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?

Gives both sides: 'In: holdings. Out: a text to quote or keep', three concrete user phrasings that should select this tool, and named alternatives with the condition that selects them (measure_portfolio for structured measurement, plain_findings for plain sentences). Exclusions are also stated ('does not recommend, predict or calculate tax').

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, non-open-world, idempotent, and non-destructive behavior. The description adds useful methodological context: risk shares are Euler contributions summing to 100%, and results cover the full record and recent years. It also clarifies boundary limitations, though it does not go into permissions or output details.

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

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

The purpose is front-loaded, and the description is organized into purpose, example questions, and alternatives. It is appropriately sized for a nuanced analytical tool, though the opening sentence is dense and slightly long.

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 a complete input schema, output schema present, and annotations covering safety behavior, the description provides enough context about what the tool measures, how to interpret risk shares, and when to choose it over siblings. No critical invocation detail 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 input schema already documents base, units, and holdings in detail. The description adds only general framing about holdings and price co-movement, not parameter-specific 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?

The description states a specific analytical resource: measuring how many independent bets a portfolio's holdings make based on co-movement, and each holding's risk contribution. It clearly distinguishes this from counting tickers and from sibling tools like look_through 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?

It gives explicit example questions that indicate when to use the tool and names alternatives for adjacent tasks: look_through for companies inside funds, measure_portfolio for everything at once. It also states what the tool does not do, including recommendation, prediction, or tax calculation.

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

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

The annotations already establish read-only, idempotent, non-destructive, and closed-world behavior, while the description adds meaningful boundaries beyond that: it does not forecast, recommend, predict, or calculate tax. It also discloses that inflation-adjusted returns and rebalance weight drift are included, which helps the agent understand the scope of analysis.

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

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

The definition is front-loaded with the core purpose, then lists outputs, typical questions, alternatives, and limitations. Every clause is informative and there is no redundant restatement of the title or schema.

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

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

Given rich annotations, full schema description coverage, and an output schema, the description is complete enough for correct selection and invocation. It covers purpose, alternatives, output scope, and explicit non-goals.

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

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

Schema description coverage is 100%, and the input schema already explains base, units, and the holdings object in detail, including currency codes, money-vs-weight inference, ticker formatting, and examples. The description adds no parameter-specific guidance beyond that, so the baseline 3 is appropriate.

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

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

The description states a specific verb and resource ('what one portfolio returned over its record') and enumerates the concrete outputs: annual growth before/after inflation, best/worst months and years, rolling 12-month stretches, calendar returns, and rebalance drift. It also distinguishes itself from sibling tools by explicitly naming past_crises and monthly_plan as alternatives.

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 typical user questions that select this tool, and explicitly routes two adjacent use cases to alternatives: crises-only analysis to past_crises and recurring contributions to monthly_plan. It also clarifies the tool is for past performance, not forecasting.

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

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

The annotations already declare readOnly, idempotent, and non-destructive behavior, so the description does not need to restate those. It still adds useful scope limits beyond them: no probability is computed, and it does not recommend, predict, or calculate tax. That is valuable for a read-only analytics tool, though it does not say anything about output size or cost.

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 core behavior and the alternative appear first, and the example questions make the intent concrete. Some phrasing is dense ('beside the worst each move actually did in the record'), but no sentence is wasted and the negative scope statements earn their place.

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

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

An output schema exists, so return values do not need explaining. For a three-parameter analytic tool, the description covers the intent, the alternative, and the exclusions. What is missing is minor: no note on how large the output is or limits on portfolio complexity.

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 defines base, loss, and the holdings object in detail, including units and ticker format. The description adds only mild framing ('a loss the reader names' and per-company output) beyond that. The baseline of 3 is appropriate.

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

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

The description names a specific operation on a specific object: it starts from a named loss and finds the least extreme combination of market moves that would cause it on this portfolio, alongside the worst each move actually did and each single company on its own. It is clearly separable from siblings, and it explicitly contrasts itself with past_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?

It gives concrete user questions that select this tool ('What would it take to lose 30%?', employer-stock crash, market decline), and it names the alternative for a different intent ('for what past crises actually did, past_crises'). The routing decision is 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?

Beyond the readOnly/idempotent annotations, it discloses the result cap ('up to ten listings'), that unchecked listings are flagged as such, and a real gotcha: a bare US symbol can resolve to a different fund than the European listing of the same letters. It also sets a negative scope ('does not recommend, predict or calculate tax') so the agent won't over-trust the output.

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

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

Front-loaded with the verb and input/output contract, followed by usage examples and the sibling alternative. Slightly dense with three quoted example questions and a parenthetical ticker illustration, but every element carries information an agent needs.

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

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

For a two-parameter lookup tool with full schema coverage, annotations and an output schema, nothing material is missing: input forms, result limits, the unchecked flag, the sibling alternative, and the failure mode of ambiguous symbols are all covered.

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

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

Schema coverage is 100%, so baseline is 3; the description adds value by clarifying that 'query' is exactly one search phrase and may carry an exchange suffix (EQQQ.DE / EQQQ.L). It does not explain the 'base' currency parameter at all, leaving that 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 and resource ('Finds tickers') plus the accepted input types (name, partial ticker, ISIN) and what comes back per listing (the exchange). It is clearly separable from validate_symbols, which the description names as the different 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?

Explicit routing: 'Instead: when the tickers are already written down, validate_symbols.' Concrete example queries show the exact situations this tool is meant for, and the exchange-suffix paragraph tells the agent how to disambiguate ambiguous symbols rather than guessing.

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 adds meaningful scope beyond that: it reports volatility, risk share, and independent bets at each weight, and explicitly refuses to recommend an optimal weight or calculate tax. It does not discuss edge cases or error behavior, but the output schema covers return structure.

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

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

The purpose is front-loaded and the alternatives and limitations are clearly organized. The three example questions and multiple clarifications are useful rather than redundant, though the description is longer than strictly necessary.

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

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

For a complex analytical tool with a full output schema, complete parameter descriptions, and safety annotations, the definition is complete enough to call correctly. It explains the sweep behavior, the metrics, the intended questions, the alternatives, and the non-goals.

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 ticker, holdings, base, weight scale, and ticker format are already fully documented in the schema. The description reinforces that the holding must already be in the portfolio and that the sweep covers every weight, but does not add syntax or constraints beyond the schema.

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

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

The description states a specific analysis verb/resource: sweeping one existing holding across every weight from 0% to 100%, with the rest shared proportionally. It also names the metrics produced (volatility, risk share, independent bets) and distinguishes itself from test_a_change and check_before_you_buy.

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 use cases through example questions like 'Show me my portfolio with 0% to 100% QQQ' and clear alternatives: test_a_change for one specific change, check_before_you_buy for a holding not yet owned. It also states what the tool does not do, including recommending a weight, predicting, or calculating tax.

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 non-destructive behavior, so the safety profile is covered. The description adds useful behavioral context — the comparison is on the same prices, figures are in the structured result, and the tool does not recommend, predict, or calculate tax. It does not need to repeat safety hints.

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 core purpose and comparison are front-loaded, followed by useful alternatives and examples. It is somewhat lengthy but each section serves a distinct purpose; minor tightening could improve it.

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 safety, a full input schema, and an output schema, the description provides everything needed: what goes in, what comes out, when to use it versus siblings, and what it deliberately does not do.

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

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

Schema description coverage is 100%, including clear descriptions for current and proposed holdings and optional date/currency parameters. The description adds conceptual meaning ('two sets of holdings') but does not elaborate on the {ticker: weight} format or date/currency semantics beyond the schema.

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

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

States a specific verb and resource — measuring a portfolio change before it is made — and sharply distinguishes it from sibling tools. The 'In/Out' framing and concrete examples make the operation 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?

Explicitly names alternatives and the conditions that select them: check_before_you_buy for one new holding, sweep_holding for one holding at every weight, compare_portfolios for unrelated portfolios. Typical questions further anchor when to use it.

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

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

Annotations already declare readOnly, idempotent, non-open-world, non-destructive, so safety is covered; the description adds useful scope limits ('up to 150 tickers') and explicit non-capabilities ('does not recommend, predict or calculate tax') plus how failures are surfaced ('closest listings'). It does not discuss rate limits or latency, so it stops short of full disclosure.

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

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

The core check and its output are front-loaded, and the boundary-plus-alternative sentence is efficient. The three quoted example questions take up noticeable space for modest routing value, costing a bit of tightness.

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 don't need exhaustive description, yet the description summarizes them helpfully (validity, trading currency, closest listings). For a 2-parameter read-only tool with full schema coverage and annotations, this is nearly complete; only the 'base' currency behavior is left implicit.

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

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

Schema description coverage is 100%, so both parameters are already documented (tickers with maxItems 150, base currency with default USD). The description repeats the 150 cap but does not mention the 'base' currency parameter or explain how it affects returned trading-currency figures. Baseline 3 applies when the schema carries the parameter burden.

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

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

The description uses a specific verb and resource ('checks tickers') and defines both input scope (up to 150 tickers) and output (usable price history, trading currency, closest listings for misses). It explicitly separates itself from search_symbols, so an agent can route between the two without opening either schema.

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

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

It gives the sequencing rule ('before a measurement'), sample user questions that map to the tool, and a named alternative with the exact condition that selects it ('when only a name is known, search_symbols'). It also states the negative boundary ('measures nothing'), which prevents misuse as a measurement tool.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive, and closed-world behavior. The description adds meaningful behavioral context beyond that: it returns no allocation to hold and does not recommend, predict, or calculate tax, which helps set expectations for a read-only analytical tool.

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

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

The description is front-loaded with the core procedure and then lists typical questions and limits. It is somewhat dense and the typical-questions list is long, but every sentence contributes useful selection or scope 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 six-parameter analytical tool with an output schema and full annotation coverage, the description supplies enough context about purpose, usage, and limits. It does not need to explain return values because an output schema exists, though it could say more about what the out-of-sample comparison reports.

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 parameter meanings are already well documented. The description still adds conceptual value by explaining the walk-forward mechanic: fitting on years before each date maps to train_years, holding on unseen prices maps to step_months, and comparison with the held portfolio maps to holdings.

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 analytical procedure: fit on prior years, hold out-of-sample, repeat, and compare optimized refits against the held portfolio and equal weights. It also explicitly distinguishes the tool from allocation-selection by saying it is not for choosing weights and returns no allocation to hold.

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 clear typical questions that indicate when to use the tool, such as testing whether an optimizer would have beaten a portfolio or whether rebalancing to an optimized mix helps. It also states a useful exclusion: only for that question, not for choosing weights or tax advice. It does not name specific sibling alternatives, 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.