Folionomiq

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds meaningful behavioral context: the shared window constraint, the specific measures computed, and the explicit limitation that it does not recommend which portfolio to hold. No contradiction with annotations.

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

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

Two compact sentences with no wasted words. The core action and scope are front-loaded, metrics follow, and the key limitation is stated at the end. 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 a rich output schema, detailed parameter schemas, and safety annotations, the description covers the essential behavioral context: scope, metrics, shared window, and non-recommendation boundary. It is complete enough for an agent to select and invoke correctly, though it could optionally mention how the shared window is determined.

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 reinforces the 'up to eight portfolios' constraint already present in the schema and adds the 'shared window' context, but it does not add new meaning about the `base` parameter or the portfolio label/ticker structure beyond what the schema already explains.

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 ('Measure'), names the resource ('portfolios'), and precisely scopes the action: 'up to eight portfolios over one shared window of price history.' It lists the computed metrics (growth, volatility, worst fall, correlation-like behavior) and distinguishes itself from a recommendation tool with 'does not say which 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?

The description gives clear context: this is for comparing multiple portfolios side by side over a shared price window. It implicitly differentiates from the single-portfolio sibling `measure_portfolio` by emphasizing 'up to eight' and 'against the others.' It does not explicitly name alternatives or state when not to use it, but the intended use case is clear.

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

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

Annotations already establish readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context: the result is comparative ('compared with the same holdings currency-hedged') and depends on the base currency setting, helping the agent interpret the output correctly. No contradiction with annotations.

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

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

The description is two sentences and front-loads the core question, then adds the comparative detail and the base-currency precondition. Each sentence earns its place, though the wording is dense and the title adds little structure.

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 full input schema and an output schema present, the description correctly focuses on semantics rather than syntax. It covers the essential purpose and the one non-obvious precondition, so an agent has enough to call the tool correctly, even if more detail on rate assumptions or edge cases could help.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema by explaining that `base` must be the reader's currency for the result to be meaningful. The `holdings` parameter is well documented in the schema, so the description does not need to repeat that detail.

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 outcome: how much of the portfolio is priced outside the base currency and what exchange-rate moves added to growth, volatility, and worst fall versus a currency-hedged version. This goes well beyond a vague label, though it does not explicitly differentiate itself from sibling tools like portfolio_structure or 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 a clear precondition: 'Needs `base` set to the reader's currency to mean anything,' which tells the agent when the output is actually meaningful. It does not explicitly state when to prefer this tool over alternatives or when not to use it, so some usage guidance is left implicit.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the description does not need to repeat safety. It adds meaningful behavioral detail: the tool runs a regression, reports which sensitivities are statistically distinguishable from zero, and shows explanatory power (R²). This goes beyond a generic 'calculate factor exposure' and gives the agent a clear mental model of the operation.

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 a single, focused sentence that front-loads the core purpose and includes essential output characteristics (significance, explained variance). It is concise without being terse, though it could arguably be split into two sentences for readability. No waste or redundant phrasing.

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 description adequately conveys what the tool does and what the agent will learn (sensitivities, significance, fit). An output schema exists, so return values are covered elsewhere. The description does not mention edge cases like handling of missing data or specific constraints, but these are not critical for tool selection and invocation, especially with schema covering inputs.

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%: both 'holdings' and 'base' are fully described in the input schema. The description itself adds no parameter-specific detail, so the baseline 3 applies. It does not introduce ambiguities or require additional explanation.

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 a specific analytical resource: a four-factor regression (market, size, value, momentum) on portfolio daily moves, and explicitly mentions the outputs (sensitivities, significance, explained variance). This distinguishes it from sibling tools like measure_portfolio or portfolio_structure, which address different analytical 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?

The description implies when to use this tool—when analyzing portfolio exposure to common return factors—but does not explicitly mention alternatives, exclusions, or conditions. It lacks guidance on when not to use it or how it compares to siblings like test_a_change or currency_effect, leaving some inference to the agent.

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, covering safety. The description adds valuable behavioral context by clarifying the output is 'readings, not a grade' and that no overall score is returned, which is not implied by the annotations. It also suggests the tool returns figures, adding transparency without contradicting structured data.

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 two concise sentences that front-load the core purpose, provide examples of axes, and explicitly state the absence of an overall score. Every sentence contributes meaning, with no filler or repetition. The structure is tight and easy to scan.

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 object, optional base, output schema present), the description is sufficiently complete. It clarifies the analytical nature and the output format (figures, no score). While it does not enumerate all possible axes, it says 'and others,' and the output schema covers return details. The description is adequate for an agent to understand the tool's purpose and expected behavior.

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

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

Schema description coverage is 100%, so both base and holdings are already well-documented in the schema. The description does not add additional meaning beyond the schema, such as examples of how holdings are interpreted or how base affects output. Since coverage is high, the baseline of 3 is appropriate; no extra credit is earned.

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 the tool reads the portfolio along separate axes (risk composition, crisis performance, and others) and returns figures. It explicitly notes that no overall score is returned, distinguishing it from a grading tool. However, it does not name a specific sibling tool or explicitly contrast with them, so it lacks the full differentiation that would merit a 5.

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

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

There is no explicit guidance on when to use this tool versus alternatives like measure_portfolio, portfolio_report, or past_crises. The description only describes what the tool does without stating when it is the preferred choice or when to avoid it. This leaves the agent without clear routing information.

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 the operation read-only, idempotent, and non-destructive. The description adds a meaningful behavioral caveat: figures are minimums because funds publish only their largest holdings. It also discloses that overlap across funds and coverage share are part of the result, adding value beyond the structured annotations.

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

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

The description is a single well-structured sentence that front-loads the core action, lists the output facets, and closes with a useful caveat. Every clause earns its place and there is no redundancy with the schema or annotations.

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 and full schema coverage, the description provides the essential conceptual model and the key limitation about minimums. It is complete enough for an agent to invoke the tool correctly; the only missing piece is explicit sibling routing, which is covered under usage guidelines.

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 holdings as ticker-to-weight/amount maps and base as the reporting currency. The description only frames these as fund holdings aggregated into companies, which is helpful context but not additional parameter-level semantics.

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

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

The description names the exact aggregation operation ('added up across funds') and enumerates the outputs (largest names, share of portfolio, overlap names, sectors, coverage). This clearly distinguishes it from sibling tools like compare_portfolios or portfolio_structure, even though it does not use an explicit verb like 'computes'.

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

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

The phrasing 'companies owned through the funds' implies this tool is for aggregated look-through analysis, but there is no explicit statement of when to use it versus alternatives such as portfolio_structure or measure_portfolio. Usage context is inferable rather than directly stated.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds useful behavioral context beyond annotations: it states the tool is 'Descriptive: no forecast, no advice' and describes the output as a 'full report with every figure numbered F1, F2… beside the method that produced it'. This gives agents insight into the output format and intent, which is not present in the annotations. No contradiction with annotations.

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

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

The description is a single, dense sentence that packs many details but is somewhat run-on and could be more scannable. It front-loads the main verb and resource, but the long list of outputs in the middle is not broken into digestible parts. It is not overly verbose, but the structure could be improved with bullet points or shorter sentences for better agent readability.

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 and the presence of an output schema (which presumably documents return values), the description covers the key outputs (effective bets, risk concentration, fund holdings, crisis impact, numbered report) and clarifies its descriptive nature. It provides enough context for an agent to understand what the tool does and what it returns. Minor gaps like data prerequisites or limitations are not mentioned, but the description is fairly complete for its purpose.

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% – both 'holdings' and 'base' are fully described in the input schema, including details like ticker formats, weight/amount acceptance, and default currency. The description adds no additional parameter-level meaning beyond what the schema already provides. Since coverage is high, the baseline is 3, and the description does not exceed that baseline.

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

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

The description states a specific verb 'Measure' and a specific resource 'a portfolio from its price history', and lists distinct outputs (effective bets, risk outliers, fund holdings, crisis impact, numbered report). It clearly distinguishes itself from sibling tools like compare_portfolios (which compares) and test_a_change (which tests changes) by focusing on a single portfolio's measurement. 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?

The description implies this tool is for descriptive measurement (explicitly stating 'no forecast, no advice'), which is a form of usage guidance. However, it does not name alternative tools or explicitly state when to use this versus compare_portfolios, search_symbols, test_a_change, or validate_symbols. The routing context is implied by the tool's purpose, but no direct 'use this when' or 'for that, use X' guidance is provided.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context: it distinguishes measured from forecast, and notes that crises before a holding's existence are named as 'not tested.' This goes beyond annotations and helps the agent understand edge cases and output semantics.

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 compact and front-loaded: it states the main action, the crises covered, the output metrics, and the handling of missing history in just a few sentences. Every sentence adds information, with no redundancy or 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?

The description covers the essential behavioral contract (what is replayed, what metrics are shown, how missing history is handled) and relies on the existing output schema for return structure. Combined with the fully described schema, an agent has all necessary information to call the tool correctly.

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

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

Schema description coverage is 100% for both parameters ('base' and 'holdings'), so the schema already documents their meaning and defaults. The description reinforces the money-vs-weight distinction already in the schema, but does not add new parameter-level details. With full coverage, 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 clearly states the tool's purpose: it replays holdings through past crises and reports the fall, worst day, and recovery time. It names specific crises (2008, 2020, 2022) and clarifies that it is measured, not forecast. This is a specific verb+resource with no ambiguity, and it is distinct from sibling tools that focus on comparisons, structure, or validation.

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

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

The description implies when to use the tool (when you want historical crisis behavior for holdings) but does not explicitly compare it to alternatives or state when not to use it. It provides context on input formats (weights vs amounts) but lacks explicit routing among the listed sibling tools. The usage is clear enough from the title and description, but no exclusions or alternatives are mentioned.

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 the tool read-only, idempotent, and non-destructive. The description adds behavioral context beyond those annotations by explaining the output format: each figure is numbered F1, F2..., linked to its method and window, and accompanied by a receipt. This helps the agent know what to expect from the response.

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 two terse sentences with no filler. It front-loads the core purpose, then gives one essential operational instruction about quoting numbered figures, making it easy to parse quickly.

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 rich schema, an output schema, and clear safety annotations, the description covers the key non-schema information: the report is written, figures are numbered, and figures should be quoted by number. It could add explicit selection guidance relative to sibling tools, but that gap is already captured in the usage dimension.

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 gives detailed semantics for both holdings and base currency. The description adds no parameter-level detail beyond what the schema provides, so the baseline score 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?

The description identifies the tool as the engine's written report on the portfolio, with numbered figures tied to the method and window that produced them. This makes the core purpose clear and broadly distinguishes it from numeric or structural sibling tools, though it does not explicitly name any alternative.

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

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

There is no explicit guidance about when to use this tool versus the many sibling tools, nor any exclusions or alternatives. The final instruction to quote figures by number is useful after invocation but does not help an agent select this tool in context.

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, covering safety. The description adds methodological context (co-movement analysis, recent-years window) without contradicting annotations, enhancing transparency beyond the structured fields.

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 a single dense sentence with no filler, front-loading the primary output. It is efficient but slightly packed; a minor split into two sentences could improve readability without adding length.

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 output schema and annotations, the description sufficiently conveys what the tool returns and its input needs. It does not specify edge cases like how 'recent years' is defined, but that is acceptable given the structured fields cover the essentials.

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

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

Schema coverage is 100% for both parameters (holdings and base). The description does not add extra meaning to parameters beyond what the schema already documents, so it sits at the baseline 3.

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

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

The description states precisely what the tool computes: the number of independent bets derived from co-movement, each holding's share of risk versus money, and the same metrics over recent years. It explicitly differentiates from ticker count and names the core outputs, making it distinct from sibling tools like measure_portfolio or portfolio_report.

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

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

The description implies usage for portfolio risk analysis but does not explicitly mention when to prefer this tool over alternatives or when not to use it. There is no comparison to siblings, leaving the agent to infer context from the purpose alone.

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 the operation read-only, idempotent, and non-destructive, so the description is not burdened with safety disclosure. It adds useful behavioral context by saying results include the exchange and that unverified listings are explicitly marked unchecked, which is a meaningful caveat for an agent choosing whether to trust a result.

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

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

The description is two sentences with no wasted words: the first leads with the verb and resource and packs in search scope and output, the second adds the one important caveat. It is front-loaded and easy to scan.

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

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

For a simple search tool, the description covers query types, returns (ticker and exchange), and the unchecked-listing caveat; the output schema and read-only annotations fill the rest. No critical detail such as pagination or special permissions seems needed to call this 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?

With 100% schema coverage, the baseline is 3, but the description adds a real semantic nuance: it says query can be a ticker fragment, not just an exact ticker as the schema might suggest. It does not add anything about the base parameter, but the schema already documents it fully.

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 identifies the resource (the ticker for a fund or company) and the three query types (name, ticker fragment, ISIN), and states the exchange is included in results. It is specific enough to be distinguished from the portfolio-focused siblings, though it does not explicitly contrast itself with validate_symbols.

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

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

The intended call context is implied: use this tool when you need to resolve a fund/company name, ticker fragment, or ISIN into a ticker and its exchange. There is no explicit statement about when to prefer an alternative such as validate_symbols, nor any exclusions or prerequisites.

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 annotations (readOnly, idempotent, non-destructive), the description discloses two critical behavioral traits: 'after' figures are counterfactual (the proposed portfolio was not held) and the tool never recommends a course of action. It also states that both portfolios are evaluated on the same price history, which prevents an agent from assuming a before/after comparison across different histories.

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

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

Three short sentences, each doing distinct work: the primary action, the substantive dimensions, and the decision-agnostic limitation. The key phrase 'before it is made' is front-loaded, and there is no filler or repetition of schema details.

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 output schema exists and annotations already declare the safety profile, the description covers what an agent needs to select and call the tool: purpose, what is measured, counterfactual semantics, and the limitation that it gives no recommendation. The optional window/base parameters are sufficiently documented by the 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%: current and proposed are documented as {ticker: weight} objects, start/end are dates, and base is a currency. The description adds conceptual context (same price history, what is measured) but does not add format or syntax details beyond the schema, so 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 opens with the action 'Measure a change before it is made', names the resource (current portfolio vs proposed portfolio), and specifies the dimensions compared (structure, risk, worst falls, additions/removals). It distinguishes itself from generic compare tools by stressing the counterfactual nature of the 'after' figures, which is exactly what separates it from siblings like compare_portfolios or 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 explicitly frames the use case: testing a change before applying it, and explicitly states what the tool will not do ('Never says whether to make the change'). It does not name sibling tools or give when-not conditions relative to them, but the counterfactual and pre-change language gives the agent a clear, non-implied usage context.

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, so the safety profile is covered. The description adds useful behavioral detail about the output (which tickers are usable, which are not, and closest-listing resolution) beyond what the annotations provide.

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?

One dense, front-loaded sentence conveys the purpose and output shape without waste. Every clause carries information: usable vs non-usable tickers and ambiguity resolution.

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 has an output schema, two simple parameters, and annotations defining read-only, idempotent behavior. The description plus schema gives an agent everything needed to invoke it correctly; no critical gaps.

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 adds no parameter-specific meaning beyond what the input schema states, matching 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?

The description uses a specific verb ("say which") and names the resource (tickers) and output categories (usable price history, unusable, closest listing for ambiguous symbols). It clearly distinguishes this validation tool from the search and measurement siblings.

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

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

The title "Check symbols before measuring" and the phrase "for a measurement" make the intended use context clear. However, it does not explicitly contrast with search_symbols or state when not to use it, so it falls short of a full 5.

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