BetterOff

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

The description goes beyond the readOnlyHint/idempotentHint annotations by spelling out that it does not change page or account state, does not access customer data, and does not provide personalized financial advice. This gives an agent clear side-effect and privacy expectations.

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 tight sentences front-load the core function and then state behavioral boundaries; every clause adds information. There is no filler or repetition.

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, an output schema, and rich annotations, the description covers the relevant behavioral boundaries and use context. Nothing necessary for correct invocation—safety, data privacy, or input scope—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 parameters are already fully documented with ranges, defaults, and enums. The description only topically lists inputs like 'principal, monthly contributions, annual return, years' without adding syntax or behavioral 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 identifies a concrete function ('Calculates compound interest') and enumerates the exact inputs and compounding frequencies, making its scope unmistakable among siblings like calc_investment_return or calc_savings_goal. The 'Read-only educational calculator' label adds context that this is a projection tool, not a transactional one.

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

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

The description implies use whenever a compound-interest projection is needed and explicitly excludes personalized advice, but it does not name an alternative tool or state when not to use it. Agents must infer selection from the domain rather than receive explicit routing guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, but the description adds meaningful behavioral context: no page or account state changes, no BetterOff customer data access, and no personalized financial advice. It also clarifies the tool is educational and returns results from caller-supplied public inputs. This goes well 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 three short, front-loaded sentences with no filler. It leads with read-only status and the core comparison, then adds privacy and non-advice caveats. It does not repeat parameter details already present in the schema.

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

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

For a 9-parameter calculator with full schema coverage, an output schema, and strong annotations, this description provides the necessary context: educational, read-only, non-personalized, and based on public inputs. Nothing essential for correctly invoking the tool is missing.

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

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

Schema coverage is 100%, and every parameter already has a clear description, so the schema does the heavy lifting. The description only highlights cadence and horizon, which adds no new semantic meaning beyond what the schema provides. A 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 uses a specific verb ('Compares') and names the exact subject: dollar-cost averaging versus lump-sum investing. It also scopes the tool to market scenarios, cadence, and horizon, which cleanly distinguishes it from the many other calc_* siblings. The read-only educational framing reinforces what the tool is for.

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 use case is strongly implied: an agent can infer this tool is for comparing DCA vs. lump-sum investing. However, the description never states when not to use it or names any alternative such as run_public_calculator or compare_public_scenarios. Guidance is left to inference rather than made 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?

The description goes beyond annotations by explicitly stating it is read-only, returns results without changing state or accessing customer data, and does not provide personalized financial advice. This adds valuable context for safe usage, complementing the readOnlyHint and idempotentHint annotations without contradiction.

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 concise, front-loads the primary purpose, and adds important behavioral constraints in a structured manner. Every sentence contributes essential information without redundancy.

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 that an output schema exists, the description need not explain return values. It covers the calculator's purpose, supported strategies, input sources, and behavioral boundaries (no state change, no data access, no advice), making it complete for an agent to decide when and how to invoke it.

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

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

Schema coverage is 100% with each parameter having a description, so the schema already documents the parameters. The description mentions 'avalanche or snowball' and 'extra monthly payment', but these are already captured in the strategy enum and extraPayment field. No additional semantic meaning is added 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 clearly states the tool runs debt payoff projections using avalanche or snowball strategy and extra monthly payment, with a specific verb and resource. It distinguishes itself from sibling calculators by focusing on debt payoff strategies, making its purpose 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 provides clear context that this is a debt payoff calculator, implying it is the right tool for projecting debt payoff scenarios. It does not explicitly mention when not to use it or name alternatives, but the context is sufficient for basic selection.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, so the safety profile is covered. The description adds value by stating it does not change page or account state, does not access BetterOff customer data, and does not provide personalized financial advice—context beyond the annotations that tells the agent what side effects and data access are absent. This is a meaningful addition for a public calculator.

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

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

Two sentences with no filler. The first sentence states the core purpose and calculations, and the second clearly delimits what it does not do. The key behavioral constraints are front-loaded and easy to scan, making it efficient for an agent to parse.

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

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

Given the tool's moderate complexity (6 params, no required fields), an output schema, and comprehensive annotations, the description is sufficiently complete. It covers purpose, read-only nature, and data-access limitations. The output format is handled by the output schema, so no further return-value details are needed. Minor omissions like edge-case behavior are not critical for a calculator of this type.

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 each parameter already has a clear description. The description's phrase 'from monthly expenses and coverage months' only highlights two of the six parameters, but the schema handles the rest. Since the schema does the heavy lifting, a baseline 3 is appropriate; the description adds no parameter-level nuances 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?

Description clearly states a specific verb and resource: 'Read-only educational calculator' for calculating emergency fund target, tracking progress, and estimating time-to-goal. It distinguishes itself from siblings by its educational, read-only nature and its focus on emergency funds, setting it apart from calculators like calc_savings_goal or calc_fire. The phrase 'without... providing personalized financial advice' further clarifies its scope.

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 provides clear context: it is a read-only educational tool that works from caller-supplied public inputs and does not access customer data or give personalized advice. This implicitly tells the agent when to use it (when a simple, non-personalized estimate is needed) and when not to (when personalized advice is required). It does not name specific alternatives, but the context is strong enough for tool selection.). It lacks explicit 'use X instead' guidance, but the boundaries are well-defined.

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, but the description adds valuable context beyond those: it explicitly states it does not access BetterOff customer data, does not change page or account state, and does not provide personalized financial advice. These are important behavioral traits for an educational tool and are not fully captured by 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?

The description is two sentences, with the core characterization 'Read-only educational calculator' front-loaded. It efficiently covers purpose, key inputs, and behavioral boundaries with no redundancy or wasted words.

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 available (as indicated) and full parameter documentation, the description is sufficiently complete. It clearly explains what the tool does, its scope, and its limitations. The only minor omission is guidance on how to interpret the result, but the output schema likely covers that. Overall, it is well-rounded for a tool of this 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?

All 10 parameters have schema descriptions (100% coverage), so the schema already explains each input. The description mentions several key inputs (annual expenses, withdrawal rate, current savings, monthly investment, return assumptions) but adds no new semantic detail beyond what the schema provides. Baseline of 3 is appropriate given full schema coverage.

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 is a read-only educational calculator that estimates a financial independence target from listed inputs. It specifies the verb (estimates), the resource (financial independence target), and distinguishes it from sibling calculators by focusing on FIRE, making its purpose 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 gives context that it is educational and read-only, and explicitly states it does not provide personalized financial advice or access customer data, which serves as an exclusion. However, it does not compare this tool to sibling calculators (e.g., calc_retirement) or state when to prefer this over alternatives, so usage guidance is mostly 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, idempotentHint, and destructiveHint, and the description adds meaningful behavioral context: it explicitly states no page or account state changes, no access to BetterOff customer data, no personalized financial advice, and public-input-only execution. This goes well beyond the annotations and clarifies side effects, privacy, and scope.

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 waste. It front-loads the read-only educational nature, then states exactly what the tool computes and what it does not do. Every sentence earns its place and the length is proportionate to the tool's simplicity.

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 educational calculator with rich annotations, a complete input schema, and an output schema, the description covers what the tool does, its side-effect guarantees, its data-access boundaries, and its advisory limits. Nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters with defaults, ranges, and examples. The description mentions 'initial investment and token price multipliers', which conceptually maps to the parameters, but adds no semantic detail beyond the schema. 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 uses a specific verb ('Estimates') with a clear resource ('impermanent loss') and the exact calculation context ('initial investment and token price multipliers in a 50/50 constant-product AMM'). This uniquely distinguishes it from the many sibling calculator tools without ambiguity.

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 clearly implies when to use it: when the user wants an educational impermanent loss estimate from price multipliers and initial capital, using public inputs. It does not explicitly name alternatives or exclusions, but the phrase 'Read-only educational calculator' and 'caller-supplied public inputs' provides enough context to select it appropriately.

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 (readOnlyHint, idempotentHint, destructiveHint), the description explicitly states it does not change page or account state, access customer data, or give personalized advice. These added behavioral guarantees provide value beyond the structured annotations and fully disclose operational boundaries.

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 zero wasted words. It front-loads the read-only educational nature, then the core function, and ends with safety clarifications. Every sentence 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?

The description covers the core calculation and safety behavior, and the output schema exists, so return values need no description. However, it omits the optional categoryRates parameter, which is documented in the schema. This is a minor gap, but an agent relying solely on the tool description might miss this advanced feature. Overall, adequate for basic usage.

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

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

The input schema alone provides 100% coverage with detailed descriptions for all four parameters, including categoryRates which is described as an optional override. The tool description mentions only amount, years, and inflation rate, omitting categoryRates entirely. Thus it adds minimal semantic value beyond the schema, earning the baseline score for high schema coverage.

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 projects purchasing power erosion from amount, years, and inflation rate, which is a specific and distinct calculation. While it does not explicitly name alternatives, the domain (inflation) is evident from the name and the calculation description, making it distinguishable from sibling calculators without further elaboration.

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 provides clear context: it is a read-only educational calculator for projecting purchasing power erosion. It implicitly indicates when to use the tool (for inflation-related projections) but does not mention alternatives or exclusions. This meets the 'clear context, no exclusions' bar.

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, but the description adds meaningful context: it explicitly says the tool does not change page or account state, does not access BetterOff customer data, and does not provide personalized financial advice. This goes beyond the structured annotations and clarifies the tool's non-invasive behavior.

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

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

Two concise sentences front-load the core purpose ('Read-only educational calculator'), then state the outputs and inputs, and finish with behavioral guarantees. Every clause earns its place with no filler or repetition.

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 that an output schema exists and annotations cover the safety profile, the description is largely complete for correct invocation. The only minor gap is that feesPaid is not referenced in the description, though its schema entry provides the necessary information. Overall, an agent has enough context to select and call this tool correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description enumerates several inputs (initial investment, final value, years, dividends) but omits feesPaid, which is present in the schema. Overall, the description adds little semantic value beyond what the schema already documents.

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 'Read-only educational calculator' and explicitly names the outputs ('total return, annualized return (CAGR), and dollar gain') and inputs ('initial investment, final value, years, and dividends'). This clearly distinguishes it from sibling calculators by stating its specific calculation scope and educational nature.

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 provides clear usage context: it is an educational, read-only calculator that operates on caller-supplied public inputs and does not provide personalized financial advice. It implies when to use it (for simple investment return calculations) but does not explicitly name alternative tools or exclusion conditions, so it stops short of a 5.

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

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

Beyond the readOnly/idempotent/destructive annotations, the description explicitly guarantees no page or account state change, no access to BetterOff customer data, and use of only caller-supplied public inputs. This adds privacy and scope context that the annotations do not convey.

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

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

The description is two well-structured sentences: it front-loads the read-only/educational nature, enumerates outputs and input categories, then closes with explicit non-effects. Every clause adds useful information with no filler.

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

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

With all 11 optional parameters fully documented in the schema and an output schema present, the description only needs to orient the agent on selection and behavior, which it does. It covers outputs, input sources, no state change, no customer-data access, and no personalized-advice use.

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 has its own helpful description, so the schema carries the parameter documentation burden. The description only summarizes inputs as 'home price, down payment, rate, and term' and does not add per-parameter meaning beyond that.

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

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

The description states a specific verb and resource: it 'calculates monthly PITI mortgage payment, total interest, total cost, and builds amortization schedule.' This clearly defines what the tool does and distinguishes it from the other calc_* siblings focused on different financial scenarios.

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 provides clear context: it is a 'read-only educational calculator' and explicitly disclaims personalized financial advice, telling the agent when not to use it. It does not name alternative calculators or provide a direct selection rule, so it stops short of the strongest sibling-differentiation guidance.

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

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

The description goes beyond the provided annotations by explicitly stating that it is 'read-only', does not change page or account state, does not access BetterOff customer data, and does not provide personalized financial advice. This clearly discloses side effects and access limitations, matching the annotations (readOnlyHint, destructiveHint, openWorldHint). No contradictions.

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 long and highly focused. It states the purpose, then the key constraints, without extraneous information. Structure is logical 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 relatively simple calculator, the description provides enough context: it names the inputs (assets, debts), the calculation (net worth, liquid net worth, debt percentage), and the output nature ('Returns a result'). It does not specify the exact output schema, but that is likely covered by an output schema (as indicated by the context). The description is complete enough for an agent to decide whether to use it, though a few edge cases or formatting details are omitted.

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

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

The schema descriptions cover all parameters (100% coverage), so the baseline is 3. The tool description mentions 'asset and debt entries' but does not add significant semantic detail beyond what the schema already provides (e.g., 'Debt categories', 'Asset categories', 'Snapshot date'). The parameter meanings are adequately captured, but no extra insight is offered.

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 explicitly states the tool's primary function: 'Calculates net worth from asset and debt entries, plus liquid net worth and debt percentage of assets.' It also clarifies its read-only and educational nature, which distinguishes it from other calculators in the sibling set.

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 does not explicitly state when to use this tool versus alternatives. While the name and description make its purpose clear, there is no direct guidance such as 'Use this when you need a net worth calculation' or comparison to other calculators. The 'educational' and 'read-only' qualifiers hint at appropriate scenarios but are not explicit usage guidelines.

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. The description adds beyond this by explicitly stating it does not change page/account state, does not access BetterOff customer data, and does not provide personalized financial advice. These are important behavioral boundaries not covered by annotations, and they complement the read-only nature without contradiction.

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 redundancy. The first sentence front-loads the purpose and core inputs; the second sentence clarifies behavioral limits and data access. Every phrase earns its place, and the structure is easy to scan 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?

Given the tool has 14 parameters all described in the schema, an output schema, and comprehensive annotations, the description adds the key contextual details: the 2026 tax year, educational nature, and the guarantee that it does not touch account data or give advice. This is sufficient for an agent to understand the tool's role and limitations, though it does not elaborate on edge cases or return format, which is acceptable given the output schema.

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

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

Schema coverage is 100%, so the schema already documents all 14 parameters. The description adds a high-level grouping of input types (salary/hourly, pay frequency, filing status, state, W-4, FICA, pre-tax deductions) that helps an agent understand which parameters belong together, but it does not add semantics beyond what the schema descriptions already provide. The baseline 3 for full schema coverage 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 a specific verb (estimates) and resource (take-home pay for 2026), lists the input categories, and distinguishes itself from sibling calculators by naming the exact computation. It is not a tautology and immediately conveys what the tool does.

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 the tool is for paycheck take-home estimation but does not explicitly state when to use it over alternative calculators (e.g., calc_compound_interest, calc_retirement). It mentions 'educational' and 'without providing personalized financial advice,' which hints at scope boundaries, but it does not name alternatives or exclusion conditions. The context is clear but not explicit enough for agents picking among many 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 readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds valuable context: it does not change page or account state, does not access BetterOff customer data, and provides no personalized financial advice. This goes beyond the annotations in a meaningful way.

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 three tight sentences with no filler. The first sentence front-loads the core purpose and read-only nature, the second states the calculation, and the third lists the key boundary conditions. Every sentence 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?

For a simple read-only calculator with fully documented parameters, rich annotations, and an output schema, the description covers everything an agent needs: what it computes, what it doesn't do, and its boundaries. No critical operational context 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%, and each parameter is already documented with its own description in the schema. The description adds a mild interpretive layer by tying 'years to retirement' and 'risk tolerance' to the inputs, but it does not need to add more given the schema's completeness.

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 ('Calculates') and a precise resource ('illustrative portfolio allocation across U.S. stocks, international stocks, bonds, and cash'). It names the two driving inputs (years to retirement and risk tolerance), making it clearly distinguishable from the many sibling calculator 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?

The description establishes clear context: this is an educational, illustrative calculator that uses only caller-supplied public inputs and deliberately avoids personalized advice or access to customer data. It implies when it should be used, though it does not explicitly name alternative tools or state when not to use it.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, and the description adds useful context beyond that: it will not change page or account state, will not access BetterOff customer data, and will not provide personalized financial advice. It also discloses the projection outputs, which strengthens transparency.

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

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

Two sentences carry all essential information with no wasted words. The core purpose and output are front-loaded, and the safety/educational caveat is appended cleanly.

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

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

With an output schema present and full parameter descriptions in the schema, the description adequately covers purpose, output behavior, and boundary conditions. It could go slightly further in explaining how the gap is derived or how displayMode affects results, but the available structured data fills those 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 baseline is 3. The description mentions age, contributions, return assumptions, and income target, but it does not add parameter-level detail; the schema already documents every parameter, so the description is not required to compensate.

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 a specific verb and resource: it projects retirement savings, returns year-by-year balances, and estimates a gap with a 4% withdrawal assumption. It does not explicitly contrast itself with sibling tools like calc_fire or calc_savings_goal, so it is clear but not fully differentiated from 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?

The description gives clear context by framing the calculator as 'read-only educational' and based on 'caller-supplied public inputs,' implying it is for illustrative projections rather than personalized advice. It does not explicitly name when not to use it or point to sibling alternatives, but the context is strong enough for an agent to infer appropriate use.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds meaningful context beyond that: it explicitly says the tool returns a result from caller-supplied public inputs without changing page or account state, without accessing BetterOff customer data, and without giving personalized financial advice. These are behavioral guarantees not present in the annotations, so this is a strong transparency score.

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, starts with the most essential fact ('Read-only educational calculator'), and packs the calculation scope and safety guarantees into a tight, front-loaded format. No filler or redundant phrases.

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 that an output schema exists (so return format is documented), the description covers the core behavior, safety profile, and generic inputs. The only gap is that it doesn't explain the 'mode' parameter (time_to_goal vs required_monthly) or how the calculator handles combinations of inputs, but for a straightforward educational calculator this is acceptable. Overall it leaves little critical information 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 86%, so the input schema already documents all parameters well. The description maps inputs to high-level categories ('target, current balance, return, and deadline') but does not add much detail beyond the schema. It earns the baseline 3 for not contradicting or duplicating the schema, but it doesn't meaningfully expand parameter meaning.

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 ('Calculates') and identifies the exact outputs: savings-goal timeline, required monthly savings, and weekly equivalent. It clearly distinguishes this tool from sibling calculators by concentrating on savings-goal planning with a weekly-equivalent twist, so an agent can select it without guessing.

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?

Although the main use case is obvious ('calculates a savings-goal timeline'), the description provides no explicit guidance on when to use this tool versus any sibling (e.g., calc_compound_interest, calc_dca, calc_retirement). No when-not or alternative-routing information is included, leaving the agent to infer context from the name 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?

Beyond the readOnlyHint/idempotentHint/destructiveHint annotations, the description explicitly discloses that the tool does not change page or account state, does not access BetterOff customer data, and does not provide personalized financial advice. This gives an agent concrete behavioral boundaries that the structured annotations alone do not convey.

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

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

The description is three focused sentences: a one-sentence overview, a one-sentence functional summary, and a one-sentence safety/data boundary. It is front-loaded with the most important classification ('Read-only educational calculator') and contains no filler or repetition.

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 calculator with a nested subscriptions array and an output schema, the description covers the high-level behavior, what inputs are used ('caller-supplied public inputs'), and the key safety/privacy boundaries. It is slightly incomplete only because it does not clarify how the two opportunity-cost parameters influence the computation, but the output schema and annotations carry much of the remaining context.

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 only 33%, and the top-level numeric parameters opportunityReturnPct and opportunityHorizonYears have no descriptions. The prose adds some context by tying subscriptions and mixed intervals to the calculation outcomes, but it does not explain what the two opportunity parameters mean or how they affect the future-price scenarios, leaving the agent to rely on guessing from names.

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-resource combination: 'Normalizes mixed-interval subscriptions into monthly-equivalent costs... ranks by impact, and computes triage savings, category totals, and future-price scenarios.' This makes the tool clearly distinguishable from sibling calculators such as calc_compound_interest or calc_mortgage without needing to open 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?

The phrase 'Read-only educational calculator' and the explicit exclusion of personalized financial advice imply it should be used for educational subscription-cost estimates. However, the description never explicitly states when to prefer this tool over sibling calculators or provides any when-not/alternative routing guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds useful behavioral context: it returns both results without ranking or personalized advice, and implies no cost or public access. This goes beyond what annotations provide, though it could mention rate limits or error behavior.

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

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

A single, front-loaded sentence with zero filler. It leads with the usage condition and immediately clarifies key behavioral constraints (no ranking, no personalization).

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

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

For a 3-parameter tool with no schema descriptions, the description is insufficient. An agent needs to know how to specify the calculator (likely via an ID from a list tool) and what constitutes valid input JSON. The output schema exists, so return format isn't required, but the input contract is underspecified.

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 0% schema description coverage, the description must compensate by explaining the parameters. It only vaguely implies 'two inputs' but does not clarify what 'calculator' should be (e.g., an identifier from list_public_calculators) or the expected format of the input JSONs. The names firstInputJson and secondInputJson hint at JSON, but no format details are given.

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 it runs two inputs through the same free public calculator and returns both results without ranking, which distinguishes it from run_public_calculator and other siblings. It specifies the verb, resource, and scope in one sentence.

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

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

Provides an explicit 'Use this when...' condition, indicating it should be used when two inputs need to be run through the same calculator. However, it does not explicitly mention when not to use it or point to an alternative like run_public_calculator for single runs, 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=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful context that the data is public and restricted to an allow-listed corpus, but does not go much beyond that scope qualifier. 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 short sentences, front-loaded with the use case and ending with an explicit exclusion. Every word earns its place; there is no repetition 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?

For a simple one-parameter read-only tool with a robust annotation set and an output schema present, the description covers when to use it, what it returns, and what it is not for. A small gap is that it doesn't explain how an agent should identify or format a valid feature name, but this is not a serious omission given the tool's simplicity.

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 0% and the schema only describes 'feature' as a string with length constraints. The description adds meaning by clarifying that the parameter must identify a BetterOff feature from the allow-listed corpus, but it provides no examples, formats, or way to discover valid feature identifiers.

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 action and resource: retrieving 'public details about one BetterOff feature from the allow-listed corpus.' It also sets a clear boundary by saying not to use it for authenticated product state, which helps distinguish it from the sibling calculator and documentation 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 opens with an explicit 'Use this when...' condition and adds a clear exclusion: 'Do not use it for authenticated product state.' However, it does not name a specific alternative tool to use for that state, so guidance is strong but not fully complete.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, covering the safety profile. The description adds context that the data is 'canonical and public,' but this is more about data nature than behavior. It does not contradict annotations and adds minimal behavioral insight beyond them, which is acceptable given the high annotation coverage.

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

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

The description is two sentences with no redundancy. The main usage is front-loaded in the first sentence, and the exclusion is stated in the second. Every word contributes value with no waste.

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

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

For a tool with no parameters, rich annotations, and an output schema, the description is adequately complete. It states the purpose and the boundary of use. The only minor gap is not specifying what the output contains, but the output schema covers that. Overall, it provides enough for an agent 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?

The tool has zero parameters, so the schema fully defines the input. The baseline for a zero-parameter tool is 4, and the description does not need to add any parameter explanation. It is sufficient.

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 the tool provides BetterOff's canonical public pricing facts and assumptions, which gives a specific resource and intent. It implicitly means the tool returns those facts, though it doesn't use a direct verb like 'retrieve' or 'return'. It clearly distinguishes from customer billing/account data, which helps separate it from other tools, though no sibling has a directly similar name.

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 provides both when to use ('when an agent needs... public pricing facts') and when not to use ('Do not use for customer billing or account data'). This gives clear context and an exclusion. While no specific alternative tools are named, the boundary is set, satisfying the criterion for explicit when/when-not guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds meaningful behavioral context beyond annotations: the result is 'exact' and 'bounded', and the tool is meant as a pre-execution step, implying it does not execute the calculator.

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?

A single, front-loaded sentence that immediately states when to use the tool and what it returns. Every phrase contributes meaningful information, with no filler or redundant restatement of the tool name.

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 read-only contract-fetching tool with rich annotations and an output schema, the description covers the essential purpose, contents, and timing. The only material gap is the lack of clarity around the input value format, which leaves the overall completeness just short of full.

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 0%, so the description must compensate for explaining the 'calculator' parameter. It only says 'a calculator' and does not specify whether the value is a slug, ID, name, or how it maps to the sibling calc_* tools. The property name is suggestive but not sufficient to form a valid value.

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 ('retrieve') and a precise resource ('exact bounded input schema, output schema, methodology, assumptions, and canonical source') for a calculator. It clearly distinguishes itself from running a calculator or listing calculators, so an agent can infer the tool's unique role.

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 opening phrase 'Use this before running a calculator' gives explicit timing guidance and establishes a clear workflow relationship with run_public_calculator and the calc_* siblings. It does not name alternatives or exclusions explicitly, but the intended context is clear.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. Description adds that results contain canonical URLs and never access customer data, which is useful context beyond 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 sentences with no fluff, front-loading the discovery purpose and adding a key behavioral fact (no customer data). Highly efficient.

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

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

For a read-only listing tool with output schema present, annotations already cover safety, and description states the primary use case. No critical missing info for an agent 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 has 0% description coverage, but descriptions of parameters are not provided. However, parameter names and constraints (limit, query, category) are self-explanatory, and the description's mention of 'discover' implies filtering capability. Baseline 3 is appropriate since the description does not add meaning beyond schema constraints.

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 specific verb (list) and resource (public calculators), with a clear purpose for discovery before choosing one. Distinguishes from siblings like run_public_calculator and get_public_calculator_contract.

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 frames when to use: discover free public calculators before selecting one. Does not explicitly state when not to use, but context and sibling names imply alternatives for specific calculators (e.g., calc_* tools).

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 context about bounded input and the educational nature of results, but does not explain contract requirements, error behavior, or how results should be interpreted.

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

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

Two sentences, front-loaded with the use case, and no filler. The educational disclaimer is concise and valuable. It is an example of appropriately sized documentation.

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 generic runner, an agent needs to know where to get calculator IDs and the inputJson contract, likely from list_public_calculators or get_public_calculator_contract. The description omits this and leaves both parameters underspecified, making the tool not self-sufficient for correct invocation.

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

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

Schema description coverage is 0%, so the description carries the burden of explaining parameters. It mentions 'bounded JSON input' but never explains how to choose the calculator identifier or what inputJson must contain or how it maps to a specific calculator contract. This is minimal semantic help.

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 action—run one free public BetterOff calculator with bounded JSON input—so an agent understands the core operation. It does not explicitly differentiate from the many calc_* siblings or compare_public_scenarios, but the scope is reasonably clear.

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 opens with 'Use this when an agent needs to run one free public BetterOff calculator,' giving clear invocation context. However, it does not mention exclusions or alternatives, such as using a specific calc_* tool or compare_public_scenarios for multi-scenario comparisons.

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 safety is covered. The description adds a meaningful behavioral boundary beyond annotations: it is restricted to public documents and must not be used for personal/private data. This is useful scoping information an agent would not get from the annotations alone.

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

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

Two sentences with no fluff. The primary usage instruction comes first, and the exclusion is stated immediately after. Every word earns its place, and the description is appropriately sized for a single-parameter search tool.

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

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

For a simple read-only search tool with one obvious parameter and an output schema present, the description covers the core decision: when to use it and what domain it searches. Annotations cover mutation/safety profile, and the output schema handles return-value expectations. Nothing necessary for correct invocation 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 0%, so the description must compensate for the undocumented 'query' parameter. It does not mention the parameter at all, its format, or any usage hints. The param is simple and self-descriptive by name, but the description provides no added semantic value beyond the schema type and length constraints.

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 ('search') and a clear resource ('BetterOff public product, pricing, trust, or calculator documents'), and it explicitly carves out what it is not for (customer, household, account, personalized data). This distinguishes it from the sibling calculator and pricing tools without needing to inspect their 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?

The description explicitly states when to use the tool ('when an agent needs to search BetterOff public...') and when not to use it ('Do not use it for customer, household, account, or personalized financial data'). It stops short of naming a specific alternative sibling tool, but the context is clear.

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