Cinderfi — Retirement Planning

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

No annotations are provided, so the description carries the full burden. It mentions the tool returns annual amounts, lifetime totals, and breakeven ages, which adds some behavioral context, but lacks details on permissions, rate limits, error handling, or computational complexity, which are important for a calculation tool.

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

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

The description is front-loaded and concise with two sentences that efficiently convey the tool's purpose, scope, and outputs without any wasted words, making it easy for an AI agent 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?

Given the tool's complexity (5 parameters, no output schema, no annotations), the description is adequate but incomplete. It covers what the tool does and its geographic scope, but lacks details on output format, error cases, or assumptions in calculations, which would help the agent use it correctly.

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

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

Schema description coverage is 100%, so the schema already documents all parameters thoroughly. The description adds no additional parameter semantics beyond what the schema provides, such as explaining interactions between parameters like cppStartAges and lifeExpectancy, so it meets 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 clearly states the tool's purpose with specific verbs ('compare', 'returns') and resources ('CPP and OAS benefits'), and distinguishes it from siblings by focusing on claiming age comparisons for Canadian retirement benefits, unlike tools like calculate_tax or run_monte_carlo.

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 for when to use this tool (comparing CPP and OAS benefits across claiming ages, Canada only), but does not explicitly state when not to use it or name specific alternatives among siblings, such as calculate_ss_timing which might handle similar timing analyses.

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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. While it mentions 'clawback mechanics and net benefit', it doesn't specify whether this is a read-only calculation or if it has side effects, what permissions are needed, rate limits, or error conditions. For a calculation tool with 6 parameters and no annotations, this leaves significant behavioral gaps.

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, efficient sentence that front-loads the core purpose. Every phrase ('Calculate...', 'plus...', 'Shows...') adds value without redundancy. It could be slightly more structured but remains appropriately concise for the tool's complexity.

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 6 parameters with full schema coverage but no output schema and no annotations, the description provides adequate context for the tool's purpose but lacks details on return values, error handling, or behavioral constraints. It's complete enough for basic understanding but insufficient for fully informed usage without additional documentation.

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 6 parameters thoroughly. The description adds no additional parameter semantics beyond what's in the schema, such as explaining interactions between parameters or calculation formulas. Baseline 3 is appropriate when schema does the heavy lifting.

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

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

The description clearly states the tool's purpose with specific verbs ('calculate', 'shows') and resources ('Guaranteed Income Supplement eligibility and amount', 'provincial seniors income supplement', 'clawback mechanics and net benefit'). It distinguishes from siblings like 'calculate_tax' or 'estimate_benefit' by focusing specifically on GIS and provincial supplements for Canadian seniors.

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 Canadian seniors' GIS calculations but doesn't explicitly state when to use this tool versus alternatives like 'estimate_benefit' or 'calculate_tax'. No guidance on prerequisites, exclusions, or specific scenarios where this tool is preferred over siblings 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It reveals the tool calculates withdrawal amounts, shows bracket headroom and tax costs, and is Canada-specific. However, it doesn't disclose important behavioral traits like whether this is a simulation vs actual transaction, what permissions might be needed, rate limits, or error conditions. The description adds some context but leaves significant behavioral aspects unspecified.

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 perfectly front-loaded with the core purpose in the first clause, followed by additional context about what the tool shows and geographic scope. Every sentence earns its place by adding distinct value: the calculation purpose, the output details, and the geographic limitation. No wasted words or redundant information.

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

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

For a complex financial calculation tool with 7 parameters, no annotations, and no output schema, the description provides adequate but incomplete context. It clearly states what the tool does and its geographic scope, but doesn't explain the return format, error conditions, or behavioral constraints. Given the absence of both annotations and output schema, the description should do more to compensate for these gaps in structured documentation.

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 description coverage, the baseline is 3. The description doesn't add any parameter-specific information beyond what's already documented in the schema. While it mentions the core parameters implicitly (RRSP balance, current income, target bracket), it doesn't provide additional semantic context, examples, or usage patterns for the 7 parameters that aren't already in their schema descriptions.

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

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

The description clearly states the specific action ('calculate how much RRSP/RRIF to withdraw') with the precise purpose ('to fill a target tax bracket') and identifies the specific strategy ('RRSP meltdown strategy'). It distinguishes from siblings by specifying 'Canada only' and focusing on tax bracket optimization rather than other financial calculations like CPP timing or benefit estimation.

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 about when to use this tool ('to fill a target tax bracket' for 'RRSP meltdown strategy'), but doesn't explicitly state when NOT to use it or name specific alternatives among the sibling tools. It implies usage for Canadian retirement tax planning without contrasting with tools like calculate_tax or optimize_withdrawal_order.

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?

With no annotations provided, the description carries full burden for behavioral disclosure. It mentions 'runs a full projection internally' which hints at computational intensity, but doesn't address critical behavioral aspects like execution time, rate limits, authentication requirements, error conditions, or whether this is a read-only vs. state-changing operation. For a complex tool with 46 parameters, this is inadequate.

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 appropriately concise with three sentences that efficiently convey purpose, components, and internal behavior. It's front-loaded with the core functionality and avoids unnecessary elaboration. Every sentence contributes meaningful 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 the tool's high complexity (46 parameters, nested objects), no annotations, no output schema, and low schema description coverage, the description is insufficiently complete. It doesn't explain the return format beyond mentioning 'overall score with label and detailed breakdown,' nor does it address the tool's computational requirements, error handling, or relationship to sibling tools. The agent lacks critical context for effective 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 description coverage is only 43%, meaning many parameters lack documentation in the schema. The description adds minimal parameter semantics by mentioning the five evaluation components, but doesn't explain how specific parameters map to these components or provide guidance on parameter relationships. It partially compensates for the low schema coverage but leaves significant gaps.

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 calculates a Cinder Score (0-100) retirement readiness assessment, specifying it evaluates five specific components (survival risk, income coverage, tax efficiency, estate buffer, savings rate) and returns an overall score with labels and detailed breakdown. It distinguishes from siblings by focusing on a comprehensive retirement readiness score rather than specific calculations like CPP timing or tax optimization.

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 no guidance on when to use this tool versus alternatives. It doesn't mention sibling tools like 'run_full_analysis' or 'run_projection' that might overlap in functionality, nor does it specify prerequisites or appropriate contexts for use. The agent must infer usage 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions the tool returns specific outputs (annual amounts, taxable portions, etc.) and geographic limitation ('USA only'), but lacks details on error handling, computational assumptions, or performance characteristics. The description adds some context but does not fully compensate for the absence of 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 front-loaded and efficiently structured in two sentences: the first states the core function and scope, the second lists outputs and geographic constraint. Every sentence adds essential information with zero waste, 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?

Given the tool's moderate complexity (5 parameters, no output schema, no annotations), the description is adequate but has gaps. It covers purpose, outputs, and geographic scope, but lacks details on behavioral traits, error conditions, or how results should be interpreted. Without annotations or output schema, the description does not fully compensate for these missing elements.

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 has 100% description coverage, so the baseline is 3. The description adds value by clarifying the tool's focus on 'Social Security benefits' and 'claiming ages (62–70)', which helps interpret parameters like ssAtFRA and startAges in context. However, it does not provide additional syntax or format details 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 clearly states the tool's purpose with specific verbs ('compare Social Security benefits') and resources ('across claiming ages 62-70'), distinguishing it from siblings like calculate_cpp_timing or estimate_benefit by focusing on Social Security timing analysis. It specifies the geographic scope ('USA only') and output details, making the 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 implies usage for comparing Social Security claiming ages, but does not explicitly state when to use this tool versus alternatives like calculate_cpp_timing or run_projection. No guidance is provided on prerequisites, exclusions, or specific scenarios where this tool is preferred over others, leaving usage context inferred rather than clearly 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It states what the tool does and returns but does not disclose critical behavioral traits such as whether it performs calculations based on current tax laws, requires internet access for updates, has rate limits, or handles errors. For a tax calculation tool with complex inputs and no annotations, this is a significant gap.

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

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

The description is appropriately sized and front-loaded, with two sentences that efficiently convey purpose, scope, and output without redundancy. Every sentence adds value: the first defines the core function and geographic scope, and the second details the return values and support coverage, with zero 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?

Given the tool's complexity (6 parameters, no annotations, no output schema), the description is incomplete. It adequately covers purpose and output but lacks behavioral context (e.g., calculation basis, error handling) and does not compensate for the absence of an output schema by detailing return formats. It is minimally viable but has clear gaps for a tool with significant parameters and no structured safety or output information.

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 6 parameters thoroughly. The description adds no specific parameter semantics beyond implying that 'region' corresponds to provinces/states and 'income' is annual taxable. It does not explain interactions between parameters (e.g., how 'filingStatus' is ignored for Canada) or provide additional context beyond the schema, meeting the baseline for high 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 specific action ('calculate income tax'), the resource ('income'), and scope ('Canada or the US'), distinguishing it from sibling tools like 'calculate_cpp_timing' or 'estimate_benefit' that perform different financial calculations. It explicitly mentions what it returns (federal, provincial/state, total tax with rates) and geographic coverage (all Canadian provinces and US states).

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 income tax calculations in North America but does not explicitly state when to use this tool versus alternatives like 'compare_scenarios' or 'run_full_analysis'. It mentions geographic scope but lacks guidance on prerequisites, exclusions, or specific scenarios where this tool is preferred over others in the server.

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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It explains the inheritance model ('Each scenario inherits all base inputs and overrides only the fields you specify') and output format ('Returns a comparison table with Cinder Score, financial freedom age, estate value, lifetime tax, and depletion risk for every scenario vs the base'), which are valuable behavioral details. However, it doesn't mention computational intensity, error conditions, or data persistence aspects that would be helpful for a complex tool with 47 parameters.

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 perfectly structured and concise. The first sentence states the core purpose, the second explains the inheritance model and output, and the third provides usage examples. Every sentence earns its place with no wasted words, and key information is front-loaded for quick comprehension.

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

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

Given the tool's high complexity (47 parameters, nested objects, no output schema) and low schema description coverage (45%), the description does a good job explaining the core comparison functionality but leaves significant gaps. It doesn't address the many base plan parameters, error handling, or what happens when scenarios exceed the 4-item limit. For such a complex tool, more comprehensive guidance would be beneficial.

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 only 45% schema description coverage, the description compensates well by explaining the core parameter concept: 'Each scenario inherits all base inputs and overrides only the fields you specify.' It clarifies that scenarios are variants that modify specific fields from a base plan, which adds crucial semantic context beyond the schema's technical definitions. However, it doesn't explain the purpose of the many other parameters (country, region, person1 details, etc.) that make up the base plan.

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: 'Compare 1–4 retirement scenario variants side-by-side against a base plan.' It specifies the verb ('compare'), resource ('retirement scenario variants'), and scope ('side-by-side against a base plan'), distinguishing it from siblings like 'run_projection' or 'run_monte_carlo' which perform different types of analysis.

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 this tool: 'Useful for answering "what if" questions — retire 5 years earlier, spend more, run bear-market assumptions, delay CPP, or enable RRSP meltdown.' It provides concrete examples ('Compare retiring at 60 vs 65 vs 70' or 'What's the difference between 4% and 6% returns?') that help differentiate it from alternatives like 'run_full_analysis' or 'compare_spending_strategies'.

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?

With no annotations provided, the description carries full burden but offers minimal behavioral insight. It mentions simulation and trajectory display but doesn't describe computational methods, assumptions, output format, or whether this is a read-only analysis versus a mutation. For a complex simulation tool with 6 parameters, this leaves significant behavioral questions unanswered.

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 appropriately concise with two sentences that efficiently convey core functionality. It's front-loaded with the main purpose and follows with output details. However, the second sentence could be more tightly integrated with the first for better flow.

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

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

For a complex simulation tool with 6 parameters, no annotations, and no output schema, the description is inadequate. It doesn't explain what 'compare' means operationally, how results are presented, what assumptions underlie the simulation, or how this differs from similar sibling tools. The agent would need to guess about critical behavioral aspects.

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 parameters thoroughly. The description mentions 'simulated retirement period' which aligns with the 'years' parameter and references the four strategies by name, but adds no meaningful semantic context beyond what's already in the well-documented schema. Baseline 3 is appropriate when schema does the heavy lifting.

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

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

The description clearly states the specific action ('compare'), the resources involved ('four retirement spending strategies'), and the output ('shows spending and portfolio trajectories'). It distinguishes from siblings by focusing specifically on strategy comparison rather than calculation, optimization, or simulation of other 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 no guidance on when to use this tool versus alternatives like 'compare_scenarios', 'run_backtest', or 'run_projection'. It doesn't mention prerequisites, constraints, or appropriate contexts for strategy comparison versus other financial analysis tools available.

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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions the tool 'calculates the adjusted annual benefit' and includes 'early/late adjustment factors,' but doesn't disclose important behavioral traits like whether this is a read-only calculation, what assumptions are made, how accuracy is affected, or what the output format looks like. For a financial calculation tool with zero annotation coverage, this is a significant gap.

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

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

The description is efficiently structured in two sentences that directly address the tool's purpose and calculation method. Every sentence earns its place by specifying what benefits are estimated and how the calculation works, with zero wasted words or redundant information.

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

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

Given the complexity of financial benefit calculations with 5 parameters and no output schema, the description is moderately complete. It covers the purpose and basic calculation approach but lacks crucial context about behavioral traits, output format, assumptions, and accuracy limitations that would be needed for proper tool selection and invocation.

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

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

Schema description coverage is 100%, so the schema already documents all 5 parameters thoroughly. The description adds minimal value beyond the schema by mentioning 'claiming age' (which maps to startAge) and 'early/late adjustment factors' (implied by startAge ranges), but doesn't provide additional syntax, format details, or clarification about parameter interactions beyond what the schema provides.

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 specific action ('Estimate government retirement benefits') and identifies the exact resources (CPP, OAS, US Social Security). It distinguishes this tool from siblings by focusing on benefit estimation rather than timing calculations (e.g., calculate_cpp_timing), tax calculations, or scenario comparisons.

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 estimating adjusted annual benefits based on claiming age, but provides no explicit guidance on when to use this tool versus alternatives like calculate_cpp_timing or calculate_ss_timing. It mentions the benefit types covered but doesn't specify 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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions that the tool 'runs a full projection internally' and surfaces 'optimization opportunities', but lacks details on computational intensity, rate limits, authentication needs, or error handling. For a complex tool with 46 parameters and no annotations, this is a significant gap in 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?

The description is appropriately sized and front-loaded, starting with the core purpose and followed by examples. Every sentence adds value, though the list of analysis areas is somewhat dense. It efficiently communicates the tool's function without unnecessary elaboration.

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 high complexity (46 parameters, nested objects, no output schema, and no annotations), the description is incomplete. It lacks information on output format (beyond mentioning insight titles and severity), error conditions, performance characteristics, and how results relate to the extensive input parameters. This is inadequate for guiding effective 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 description coverage is 43%, so the description must compensate. It lists specific analysis areas (e.g., 'RRSP/IRA ceiling analysis', 'FHSA transfer deadlines') which help clarify the tool's scope and indirectly inform parameter relevance, but does not explicitly explain individual parameters or their relationships. The description adds some value over the schema but does not fully address the coverage gap.

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 with specific verbs ('generate personalized, actionable financial insights') and resources ('based on a retirement plan'). It distinguishes from siblings by focusing on optimization opportunities rather than calculations, comparisons, or simulations, and provides concrete examples of insights like 'RRSP/IRA ceiling analysis' and 'portfolio distribution'.

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 context through examples ('Are there any red flags in my retirement plan?' or 'What should I optimize first?'), suggesting this tool is for identifying optimization opportunities in retirement planning. However, it does not explicitly state when to use this tool versus alternatives like 'run_full_analysis' or 'run_projection', nor does it provide 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It describes key behaviors: auto-detection of account types from names, return of a 'mapping report' with classification details, and handling of different data sources. However, it lacks details on error handling, performance characteristics, or rate limits, which are important for a tool with 19 parameters and complex data processing.

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 well-structured and front-loaded with the core purpose. Each sentence adds value: explaining the translation process, auto-detection feature, return values, and user-specific guidance. While slightly dense due to the tool's complexity, there is minimal waste, and information is presented logically.

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 high complexity (19 parameters, no annotations, no output schema), the description is moderately complete. It covers the purpose, usage guidelines, and key behaviors but lacks details on output structure beyond 'populated inputs object' and 'mapping report', and doesn't address potential errors or constraints for a data transformation tool of this scale.

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 description coverage is 63%, so the description must compensate. It adds significant value by explaining the overall purpose of parameter groups (e.g., 'Pass account names and balances directly from YNAB, bank feeds, or spreadsheets'), clarifying how certain parameters relate to user contexts (YNAB vs. bank users), and providing practical examples. This goes beyond what the schema descriptions provide, though some parameters remain only schema-documented.

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: 'Translate real-world financial data into Cinderfi projection inputs.' It specifies the verb ('translate'), resource ('real-world financial data'), and output ('Cinderfi projection inputs'), distinguishing it from sibling tools like run_projection or run_full_analysis which use these inputs rather than create them.

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

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

The description provides explicit guidance on when to use this tool versus alternatives: 'Returns a populated inputs object ready to pass directly to run_projection or run_full_analysis.' It also offers specific usage instructions for different user types (YNAB users, bank users), clarifying the context and prerequisites for effective 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It reveals the computational approach ('Sweeps 0–50% in 1% increments'), geographic limitation ('Canada only'), and access requirement ('Requires Pro'), which are valuable behavioral traits. However, it doesn't disclose performance characteristics, error conditions, or what constitutes 'optimal' beyond tax minimization.

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 extremely efficient - three sentences that each earn their place. The first states the core purpose, the second adds operational details, and the third provides constraints. No wasted words, perfectly front-loaded with the main purpose first.

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

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

For a complex optimization tool with 8 parameters and no output schema, the description provides good context about what the tool does and its constraints. However, without annotations or output schema, it doesn't describe what the optimization result looks like or how to interpret it. The 'Requires Pro' hint about access requirements partially compensates for the lack of annotations.

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 description coverage, the schema already documents all 8 parameters thoroughly. The description adds minimal parameter semantics beyond what's in the schema - it implies the tool uses these parameters to calculate tax-minimizing splits but doesn't explain how specific parameters affect the optimization. This meets the baseline 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 specific action ('find the optimal pension income split percentage'), the resource ('between spouses'), and the goal ('to minimize combined federal + provincial tax'). It distinguishes from siblings by focusing specifically on pension splitting optimization rather than general tax calculation or other financial simulations.

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 about when to use this tool ('Canada only', 'Requires Pro'), and the sweep range ('0–50% in 1% increments') gives operational boundaries. However, it doesn't explicitly state when NOT to use it or name specific alternatives among the sibling tools for different scenarios.

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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes key behavioral traits: it's a read-only optimization tool (implied by 'find' and 'returns'), discloses performance constraints ('CPU-intensive — runs may take 15-60 seconds'), and specifies output details ('Returns the top-5 strategies for each objective'). It does not cover authentication needs or rate limits, but given the complexity, it provides substantial context beyond basic purpose.

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 appropriately sized and front-loaded, with three concise sentences that each add value: the first states the purpose, the second specifies the output, and the third covers usage constraints and performance. There is no wasted text, and it efficiently communicates essential information.

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

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

Given the high complexity (47 parameters, nested objects) and lack of output schema, the description does a good job of contextual completeness. It explains the tool's purpose, output format, and performance characteristics. However, it could improve by briefly mentioning the input scope (e.g., country-specific parameters) or linking to sibling tools for simpler analyses, but it is largely complete for guiding 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?

Schema description coverage is 45%, which is low, but the description does not add meaningful parameter semantics beyond what the schema provides. It mentions testing 'combinations of CPP/SS claiming age, RRSP meltdown / Roth conversion, and withdrawal ordering,' which hints at some parameters but does not explain their usage, constraints, or relationships. The description compensates minimally for the coverage gap, meeting the baseline for moderate 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's purpose: 'Find the optimal retirement strategy by testing combinations of CPP/SS claiming age, RRSP meltdown / Roth conversion, and withdrawal ordering.' It specifies the verb ('find'), resource ('retirement strategy'), and scope ('testing combinations'), distinguishing it from siblings like 'run_projection' or 'run_monte_carlo' by focusing on optimization of specific variables.

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 for when to use this tool ('Pro tier only') and mentions performance characteristics ('CPU-intensive — runs may take 15-60 seconds'), which helps set expectations. However, it does not explicitly state when not to use it or name specific alternatives among the sibling tools, such as 'run_projection' for simpler scenarios.

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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It does well by explaining what the tool returns (success rate, median/worst/best outcomes, spending strategy performance) and mentions the dataset source (Robert Shiller's). However, it doesn't disclose important behavioral aspects like computational intensity, potential rate limits, error conditions, or what constitutes a 'success' in the success rate metric. For a complex tool with 50 parameters, more behavioral context would be helpful.

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 perfectly structured and concise. The first sentence establishes the core purpose, the second explains outputs, the third provides concrete use cases with examples, and the fourth clarifies the three modes. Every sentence earns its place with zero wasted words, and the information is front-loaded with the most important details first.

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 high complexity (50 parameters, nested objects, no output schema, no annotations), the description is adequate but incomplete. It covers the purpose, outputs, and modes well, but doesn't address the extensive parameter landscape, error handling, performance characteristics, or detailed behavioral expectations. For such a sophisticated financial modeling tool, more comprehensive guidance would help agents use 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?

With only 48% schema description coverage, the description compensates significantly by explaining the core parameters through context. It clarifies the three 'mode' options with their meanings (decumulation, fullLifecycle, accumulation), mentions key concepts like 'spending strategies,' and implies parameters like country selection through the dataset reference. While it doesn't detail all 50 parameters, it provides essential semantic context that helps understand what inputs drive the backtesting.

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 with specific verbs ('Test a retirement plan') and resources ('against every historical market window since 1871 using Robert Shiller's dataset'). It explicitly distinguishes what it does (historical backtesting) from what siblings like 'run_monte_carlo' or 'run_projection' likely do (forward-looking simulations). The description answers concrete questions like 'would my plan have survived the Great Depression?' which further clarifies its unique purpose.

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 about when to use this tool: for historical backtesting of retirement plans across different market periods. It mentions three specific modes (decumulation, fullLifecycle, accumulation) that help determine applicability. However, it doesn't explicitly state when NOT to use it or name alternative tools for different types of analysis (like forward-looking projections or tax calculations), which prevents a perfect score.

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?

With no annotations provided, the description carries full burden. It describes what the tool returns (comprehensive analysis outputs) but doesn't disclose behavioral traits like computational cost, time requirements, error conditions, or rate limits. The description is informative about outputs but lacks operational context.

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

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

Well-structured with bullet points for outputs and a clear usage guideline paragraph. Every sentence adds value, though the bullet list could be slightly more concise. The description is appropriately sized for a complex tool with 46 parameters.

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

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

For a complex tool with 46 parameters, no annotations, and no output schema, the description does well explaining purpose and usage but lacks details about computational behavior, error handling, and the relationship between the many parameters. The output description is comprehensive, but 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 only 43%, but the description compensates by explaining the tool's comprehensive nature and relationship to financial data mapping. While it doesn't detail specific parameters, it provides crucial context about what kind of analysis is performed, which helps agents understand the parameter requirements beyond the schema documentation.

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: 'Run a complete retirement analysis in one call' with specific outputs listed (retirement readiness score, key metrics, insights, year-by-year summary). It distinguishes from siblings by being the comprehensive 'full picture' tool versus more focused calculators like calculate_score or run_projection.

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

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

Explicitly states when to use this tool: 'Ideal for agents that have already mapped user financial data via map_financial_data and want the full picture in a single tool call.' This provides clear prerequisites and distinguishes it from data-mapping tools and more specialized calculators.

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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes key behavioral traits: the tool is computationally intensive ('CPU-intensive — runs may take 10-30 seconds'), has access restrictions ('Pro tier only'), and produces probabilistic outputs. It doesn't mention error handling, rate limits, or authentication needs, but covers the most critical operational aspects for a complex simulation tool.

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

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

The description is perfectly front-loaded with the core purpose in the first clause, followed by outputs, access restrictions, and performance characteristics. Every sentence earns its place: the first explains what the tool does, the second lists key outputs, the third states access requirements, and the fourth warns about computational intensity. No 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?

For a complex tool with 47 parameters, nested objects, no annotations, and no output schema, the description is somewhat incomplete. While it covers purpose, outputs, access, and performance well, it doesn't address the complexity of inputs, error conditions, or what the actual return format looks like. Given the tool's sophistication, more guidance on input requirements or output interpretation would be helpful.

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 description doesn't add any parameter-specific information beyond what's in the schema. With 47 parameters and only 45% schema description coverage, the description doesn't compensate for the coverage gap. However, the schema itself is highly detailed with descriptions for most critical parameters, so the baseline of 3 is appropriate given the schema does substantial documentation work.

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 specific action ('Run a Monte Carlo retirement simulation'), the resource ('with randomized market returns'), and the outputs ('probabilistic outcomes including success rate, percentile ranges for net worth/income/tax across all years, and estate value distribution'). It distinguishes this tool from siblings like 'run_backtest' or 'run_projection' by emphasizing the Monte Carlo simulation aspect and probabilistic outcomes.

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 for when to use this tool: for retirement simulations with probabilistic outcomes. It mentions 'Pro tier only' as a prerequisite and 'CPU-intensive — runs may take 10-30 seconds' as a performance consideration. However, it doesn't explicitly state when not to use it or name specific alternatives among the sibling tools (e.g., 'run_projection' for deterministic projections).

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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions the tool's scope and outputs but fails to describe critical behavioral traits such as computational requirements, execution time, error handling, or data persistence. For a complex projection tool with 46 parameters, this omission is significant, though it does hint at token usage limits via maxRows.

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 appropriately sized and front-loaded, starting with the core purpose and outputs, then listing supported features. Every sentence adds value, with no redundant information. However, it could be slightly more structured by separating purpose from features for even clearer readability, but it remains efficient and well-organized.

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 high complexity (46 parameters, nested objects, no output schema) and lack of annotations, the description is moderately complete. It covers the tool's purpose, outputs, and supported features adequately, but for such a sophisticated tool, it should ideally mention more about behavioral aspects like performance, assumptions, or limitations to fully guide an agent. The absence of an output schema increases the need for more context on return values.

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 description coverage is low (43%), but the description adds substantial value by summarizing key parameters implicitly through feature mentions ('singles and couples', 'multiple withdrawal strategies', 'RRSP meltdown / Roth conversion', etc.). It contextualizes many parameters without detailing each one, effectively compensating for the schema's gaps and providing a high-level understanding of input 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 clearly states the tool's purpose with specific verbs ('Run a full retirement projection') and resources ('for Canada or US'), detailing what it projects ('year-by-year income, taxes, account balances, government benefits, and spending') and what it returns ('summary metrics... and optional year-by-year rows'). It distinguishes from siblings by specifying its comprehensive scope, unlike more focused tools like calculate_cpp_timing or calculate_tax.

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 context by listing supported features ('Supports singles and couples, multiple withdrawal strategies...'), but does not explicitly state when to use this tool versus alternatives like run_monte_carlo or run_full_analysis. It provides some guidance through feature enumeration but lacks clear when/when-not directives or named alternatives, leaving room for ambiguity.

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?

With no annotations provided, the description carries full burden and does well by explaining key behavioral aspects: how one-time vs recurring purchases affect savings/spending differently, the withdrawal order logic (non-reg → TFSA → RRSP), and what metrics are returned (score delta, estate impact, etc.). It doesn't cover rate limits, error conditions, or authentication needs, but provides substantial operational context.

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

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

The description is efficiently structured: purpose statement first, then behavioral details, then return values, ending with concrete examples. Every sentence adds value with zero waste. The two example questions at the end effectively illustrate usage without being verbose.

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 high complexity (48 parameters, nested objects) and no output schema, the description provides good behavioral context but leaves significant gaps. It explains what the tool does and returns, but doesn't address the extensive parameter requirements, error handling, or computational characteristics. For such a complex tool, more guidance on required vs optional parameters would be helpful.

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 46% (low), but the description adds minimal parameter semantics beyond the schema. It mentions 'purchaseAmount' and implies 'frequency' through one-time vs recurring distinction, but doesn't explain the complex person1/person2 objects, country/region requirements, or other parameters. The description compensates somewhat but not fully for the coverage gap.

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: 'Show the retirement impact of a spending decision' with specific examples (car, vacation, etc.). It distinguishes from siblings by focusing on purchase simulation rather than CPP timing, tax calculation, or other financial analyses listed in the sibling 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 provides clear context for when to use this tool: to evaluate the retirement impact of spending decisions. It includes examples like 'What does a $60,000 car do to my retirement?' However, it doesn't explicitly state when NOT to use it or mention specific alternatives among the sibling 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?

With no annotations provided, the description carries full burden and does well. It discloses key behavioral traits: the tool optimally allocates across accounts in specific order, tests multiple strategies for couples, and returns specific outputs (allocation breakdown, tax refund estimate, etc.). It mentions the 'Cinder Score' metric and differentiates between one-time vs recurring scenarios. However, it doesn't mention computational complexity, rate limits, or error conditions.

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 perfectly structured and concise. The first sentence establishes the core purpose. The next two sentences explain the allocation logic and couple-specific behavior. The 'Returns:' section clearly lists outputs. The examples provide concrete usage scenarios. Every sentence earns its place with no wasted words, and key information is front-loaded.

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 high complexity (48 parameters, no output schema, no annotations), the description does remarkably well. It explains what the tool does, how it behaves, what it returns, and provides usage examples. The main gap is that with such a complex parameter schema and no output schema, the description could better prepare users for the detailed inputs required. However, it provides enough context to understand the tool's scope and value.

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 46%, but the description adds significant value by explaining the core parameters conceptually. It clarifies that 'windfallAmount' can be lump sum or recurring savings, mentions country-specific account types (TFSA/Roth, RRSP/IRA), and implies the need for personal financial details. While it doesn't detail all 48 parameters, it provides enough semantic context to understand the tool's inputs beyond the schema's technical definitions.

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: to show retirement impact of receiving money or increasing savings. It specifies the verb ('show'), resource ('retirement impact'), and scope (windfalls like inheritance, bonus, etc.). It distinguishes from siblings by focusing specifically on windfall allocation optimization rather than general projections or other calculations.

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 for when to use this tool: for evaluating one-time windfalls or increased savings. It gives specific examples ('I'm getting a $50,000 inheritance' and 'What if I save an extra $500/month?'). However, it doesn't explicitly state when NOT to use it or name specific alternative tools for different scenarios.

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