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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, fully covering the safety profile, and 'Compare' is consistent with a read-only analysis. The description adds scope context (which benefits are compared) but not assumptions like federal-only treatment, AGI phaseout handling, or that married_filing_separately filers are ineligible for AOTC/LLC. With strong annotations the burden on the description is lower, so 3 is appropriate. 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?

A single 16-word sentence that leads with the verb 'Compare' and front-loads the resource before enumerating the benefit categories. Every word earns its place, with no filler and no repetition of schema or annotation content.

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 an 8-parameter tool analyzing four distinct tax provisions with eligibility nuances (AOTC 4-year cap, MFS exclusion, income phaseouts), the description is adequate but thin: it names what is compared but not the assumptions or limitations (federal-only scope, whether the taxpayer is assumed to be the student, how phaseouts are applied). The presence of an output schema and strong annotations relieves it of return-value and safety explanation, which prevents a lower score.

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 88%, so the schema already documents 7 of 8 parameters (filingStatus is self-documenting via its enum), which sets the baseline at 3. The description adds modest value by mapping benefit categories to parameter groups the agent must supply, but it does not explain how values like yearsAOTCClaimed (the 4-year cap) or contribution529 influence the comparison.

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 ('Compare') with a specific resource ('education tax benefits') and enumerates the four items covered: AOTC, Lifetime Learning Credit, student loan interest deduction, and 529 plan advantages. This enumerated scope clearly distinguishes it from overlapping siblings like list_tax_credits, check_credit_eligibility, and list_deductions without requiring the agent 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 use case is implied — an agent can infer this tool is for comparing education tax benefits — but the description never states when to prefer it over overlapping siblings such as check_credit_eligibility (for 'am I eligible for AOTC?') or list_tax_credits (for 'what credits exist?'). No routing conditions, exclusions, or alternatives are named, leaving selection to inference.

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

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

Annotations already establish the tool is read-only and idempotent. The description adds the key behavioral trait that it performs a comparison (itemized-with-mortgage vs standard deduction), which is beyond what the annotations or schema names convey. It does not mention tax-law limitations, but those are not essential for safe invocation.

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 short sentences, with the primary action first and the comparison logic second. Every word adds signal and none of the schema's parameter details are redundantly repeated.

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 read-only/idempotent annotations, the description need not explain return values or safety. It gives enough context for an agent to know this is a mortgage-focused itemization comparison; only the missing guidance against the sibling standard_vs_itemized keeps this from a 5.

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 89%, so the schema carries most parameter meaning. The description highlights mortgage interest and property taxes as the core inputs but adds no detail beyond what the schema already provides, so it stays at the baseline.

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

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

The description uses a specific verb ('Analyze') and a concrete resource ('tax benefit of mortgage interest deduction and property taxes'), then states the comparison logic (itemizing with mortgage vs standard deduction). This clearly differentiates it from the general sibling standard_vs_itemized and the education-specific analyze_education_tax_benefits.

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 scenario is implied: use this when the user asks about mortgage-interest/property-tax itemization benefits. However, it never names the closest sibling standard_vs_itemized or states when to choose one over the other, so the agent must infer the boundary.

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

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

Annotations already declare the operation read-only, idempotent, and non-destructive, so the description correctly avoids repeating those. It adds a behavioral trait beyond the annotations: the tool performs a comparison/evaluation against expected withholding, producing a correctness assessment rather than just returning configuration data or raw tax figures. This meaningfully enriches the agent's understanding.

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 exactly two sentences with no filler. The purpose is front-loaded ('Analyze a paycheck to verify withholding accuracy'), followed by a direct instruction on usage and expected outcome. Every word 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 tool with 11 parameters, required fields, and an output schema, the description gives enough context for correct selection and basic invocation: it tells the user to provide pay stub numbers and describes the verification outcome. It does not explicitly state that stateCode is needed for state withholding analysis or that optional inputs control analysis scope, but the input schema and output schema cover those details. Complete enough for a moderately complex tool.

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

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

The description only says 'Input your pay stub numbers' — a general instruction that maps to all parameters but adds little specific meaning. Schema descriptions already cover most fields (73% coverage) with clear text like 'Gross pay this period' and 'Federal tax withheld this period', though stateCode lacks a description. The tool description does not compensate for that gap, leaving parameter semantics at 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 states a clear, specific verb and resource: 'Analyze a paycheck to verify withholding accuracy.' It further specifies the input ('your pay stub numbers') and the outcome ('see if your employer is withholding the right amount'), which distinguishes it from sibling tools like calculate_federal_tax or estimate_state_tax by focusing on verification of actual withholding rather than tax liability calculation.

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 used when you have a pay stub and want to check whether withholding is correct. However, it does not explicitly name alternatives or when-not conditions, such as using calculate_w4_withholding for planning future withholding instead of verifying current paycheck numbers. The context is clear but lacks explicit exclusions.

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 the exact-year state profile requirement and the need for explicit annual federal/state data for projections, but it does not disclose other behavioral details such as whether the analysis covers federal tax, state tax, or both.

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, both essential, with the core value stated first and the key limitation second. 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 tool with 10 parameters, 5 required inputs, and an output schema, the description is too sparse. It does not explain what the analysis returns, how optional inputs like capital gains or self-employment income factor in, or what 'explicit annual federal and state data' means when supplying projection years. An agent would need additional inference to 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 60%, and the description adds no per-parameter detail beyond what the schema already provides. Several parameters (dependents, capitalGains, selfEmploymentIncome) remain undocumented in both schema and description, and the phrase 'exact-year state profiles' only loosely relates to taxYear and yearsToProject without explaining input expectations.

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 task ('relocation tax analysis') with useful qualifiers ('in-depth', 'exact-year state profiles'). It clearly identifies the resource and domain, though it does not explicitly differentiate itself from siblings like compare_state_taxes or plan_multi_year_taxes.

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 relocation tax analysis, which gives some usage context. However, it never states when to prefer this tool over alternatives such as calculate_total_tax or compare_state_taxes, and it only mentions the projection-year input requirement as a constraint.

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 mark the tool as read-only, idempotent, and non-destructive. The description adds that it analyzes the tax return profile and produces risk indicators and advice, but it does not disclose additional behavioral traits such as methodology, scoring scale, or data handling. 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?

Three tightly written sentences with the main action front-loaded and no filler. Each sentence earns its place: purpose, output, and actionable benefit.

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

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

For a read-only analysis tool with a rich input schema and an output schema, this description gives an agent enough to decide when to call it and what to expect. Minor gaps remain around optional-field usage and clarifying that the risk score is an estimate, but these do not undermine effective 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 93%, so the schema already documents nearly every parameter. The description adds only the high-level framing that the inputs form a 'tax return profile' used for risk assessment, without providing detail 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 uses a specific action ('Evaluate') on a specific resource ('IRS audit risk') and clearly states what the tool produces: red flags, a risk score, and reduction tips. This audit-risk focus distinguishes it from sibling tax calculation, deadline, and deduction 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 intended use is implied: call this tool when a user wants to assess IRS audit exposure based on their tax profile. However, it does not explicitly state when not to use it or how to choose it over potentially overlapping tools like run_tax_health_check.

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 disclose that the operation is read-only and idempotent, so the description does not need to restate that. It adds useful context that EITC is a refundable credit for low-to-moderate income workers, but it does not disclose operational behaviors such as phase-out limitations, tax-year-specific rules, or how special cases like married_filing_separately are handled.

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 fluff. The first sentence leads with the action, and the second adds brief helpful context about the credit. It is front-loaded, appropriately sized, and 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?

Given an output schema, read-only annotations, and a schema covering most parameters, the description is nearly complete for selecting and invoking the tool. It could go further by noting a key eligibility rule such as the married_filing_separately exclusion or the investment income cap, but these are likely handled inside the calculation and are not necessary for basic 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 high at 83%, so the schema already documents most parameters. The description adds no parameter-level details beyond general EITC background; specifically, it does not clarify filingStatus semantics or investmentIncome restrictions, though the schema already names these fields.

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

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

The description uses a specific verb and resource: 'Calculate the exact Earned Income Tax Credit (EITC) amount.' This clearly states what the tool computes and distinguishes it from sibling tools like list_tax_credits or check_credit_eligibility, which have different purposes.

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

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

The description implies when to use the tool—whenever an exact EITC amount needs to be calculated—but it does not explicitly discuss alternatives or when not to use it. The tool's focused verb and resource make the main use case obvious, but no exclusions or sibling comparisons are provided.

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

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

Annotations already establish that the tool is read-only, idempotent, and non-destructive. The description adds a meaningful behavioral guarantee beyond those annotations: calculations run locally with no data sent to a server. It also communicates the scope of calculations included, which helps set expectations for what the tool can handle.

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 four short, purposeful sentences: primary purpose first, then year support, covered calculations, and a privacy guarantee. There is no filler or redundancy, and the feature list earns its place by clarifying the tool's scope for a complex calculator.

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 38 parameters, the description provides sufficient scope, supported years, covered tax areas, and privacy context, while the rich schema and output schema carry the remaining burden. Missing explicit alternative routing is a minor gap, but nothing essential is absent.

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

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

Schema description coverage is 97%, so the schema already documents the 38 parameters in detail. The description's feature list maps high-level tax topics like NIIT, QBI, capital gains, and child tax credit to related inputs, but it does not add parameter-specific information beyond what the schema already 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 verb ('Calculate') and resource ('federal income tax for an individual taxpayer'), and it lists the major tax components covered. However, it does not explicitly differentiate itself from overlapping siblings such as calculate_total_tax or simulate_tax_scenario, so sibling distinction is only implicit.

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 useful selection context: federal individual income tax, supported tax years 2024–2026, and the breadth of calculations included. It does not explicitly state when to prefer this tool over alternatives like calculate_total_tax, get_tax_brackets, or calculate_eitc, nor does it provide any exclusions.

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

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

The annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds behavioral value beyond the annotations by stating that it determines qualification and reports total tax savings, which clarifies the computed output without contradicting the read-only nature.

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 exactly two sentences, front-loading the action and resource, and then listing the deductions and the output. Every sentence earns its place with no redundancy or filler.

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

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

Given the 9-parameter schema, output schema, and read-only annotations, the description is sufficiently complete: it names all deductions, scopes the tax years, and states the output. It could add a bit more about eligibility conditions or calculation assumptions, but the structured data covers much of that 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 89%, so the schema already documents most parameters such as age, AGI, tipIncome, and autoLoanInterest. The description names the four deduction categories, which helps map them to parameters, but it does not add new semantic details 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 uses a specific verb ('Calculate') and a precise resource ('all OBBB new deductions for TY2025+'), enumerating the four deduction types and the expected output. This clearly differentiates the tool from general tax calculators and list_deductions by naming its exact 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 clearly frames the tool for the OBBB new deductions in TY2025+, and the output statement ('Shows which deductions you qualify for') makes the use case apparent. It does not explicitly name alternative sibling tools or state when not to use them, but the context is strong enough for an agent 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?

Annotations already cover read-only, idempotent, and non-destructive behavior, so the description's burden is lower. The description adds useful behavioral context by disclosing the result composition (federal breakdown, state tax, combined totals) and the one-call efficiency, which is not visible 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?

The description is a single front-loaded sentence followed by a clear return-value sentence. Every word earns its place, and there is zero redundancy or filler.

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

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

Given the tool's complexity (35 parameters, many optional credits and deduction inputs), the description is minimally adequate but doesn't help the agent know which optional inputs matter for a given scenario. The output schema and property descriptions compensate partially, but the high parameter count creates a completeness gap.

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 provides no parameter-level guidance despite a large 35-parameter schema with 63% description coverage. It doesn't clarify how optional fields like capitalGains, itemizedDeductions, or earnedIncomeCredit feed into the combined calculation, leaving the agent to infer meaning from the schema alone.

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 ('calculate') and resource ('combined federal + state tax'), and explicitly lists what the call returns: federal breakdown, state tax, and combined totals. This clearly differentiates it from siblings like calculate_federal_tax and estimate_state_tax, which cover only one jurisdiction.

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 'complete picture of total tax liability' and 'in one call' implies this is the right tool when both federal and state results are needed together. It doesn't explicitly name alternatives like calculate_federal_tax or estimate_state_tax, but the context makes the intended use clear without excluding them.

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, covering safety. The description adds useful behavioral context—'estimates' signals approximate output and 'recommended'/step-by-step indicates advisory results—but does not go beyond that. No contradiction with annotations.

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

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

Two tightly written sentences with no filler. The primary purpose is front-loaded in the first sentence, and the second sentence efficiently describes what the user receives without introducing concepts not covered by the schema or output.

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 rich input schema (100% param coverage) and the presence of an output schema, the description is nearly complete for invocation. It explains the tool's purpose and result format; only a small gap is the absence of explicit caveats or assumptions (e.g., that the estimate assumes current federal withholding rules), but these are not necessary for selecting and calling the tool.

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

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

Schema description coverage is 100%, and the description does not explain any parameters. Each of the 9 parameters already has a meaningful schema description (e.g., taxYear with allowed years, filingStatus enum, payFrequency enum), so the description adds no additional semantic 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 opens with 'Calculate recommended W-4 withholding settings,' a specific verb and resource unique among the siblings (none mention W-4). It also specifies the output: per-paycheck federal tax estimate and step-by-step W-4 form recommendations, making the tool's role 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?

No guidance is given on when to choose this tool over related siblings like calculate_federal_tax or analyze_paycheck. The W-4 focus is implicit, but there is no explicit 'use this when' context or exclusion, leaving the selection decision to inference.

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

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

The annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so no safety contradiction exists. The description adds little behavioral detail beyond the word 'Check', but 'may be eligible' does convey that the result is conditional rather than a firm guarantee.

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 one concise, front-loaded sentence with no filler. It communicates the core purpose immediately and 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?

Given the rich input schema, the required AGI and filing status fields, safety annotations, and an output schema, a short description is sufficient for an agent to select and call the tool. The generic wording leaves some situational details implicit, but the schema compensates.

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 high at 86%, so the schema already explains most parameters and the description does not need to repeat them. The description adds no extra parameter-level meaning and does not clarify the one weakly documented field, numChildren, but the high schema coverage keeps this at 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 states a specific action ('Check'), a clear resource ('tax credits'), and a clear scope ('eligible based on your situation'). It distinguishes eligibility screening from sibling tools like list_tax_credits, though it does not explicitly name that alternative.

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

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

The phrase 'based on your situation' implies this tool should be used when a user has personal/financial details and wants credit eligibility results. However, it does not explicitly state when to prefer this over list_tax_credits, calculate_eitc, or similar siblings, leaving usage somewhat to inference.

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

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

Annotations already convey readOnlyHint, idempotentHint, and non-destructive behavior. The description adds important behavioral context beyond annotations: it does not access the user's IRS account, and instead provides official links and requirements. This meaningfully reduces the risk of misuse.

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 function, and the second corrects the most likely misconception about what the tool can and cannot do. 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 reference tool with one optional, fully described parameter, an output schema, and safety-related annotations, the description is largely sufficient. The only notable gap is that it does not explain how the optional 'filedElectronically' parameter changes the provided instructions, though this is a minor omission.

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 fully documents the single parameter 'filedElectronically' with a clear description, so the schema carries the parameter meaning. However, the tool description adds nothing about how this boolean affects the instructions, links, or requirements returned.

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

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

The description uses a specific verb and resource: 'Provide instructions on how to check IRS refund status.' It also explicitly disambiguates itself from an actual account-access tool by stating it does NOT access the IRS account, which is essential for correct agent selection.

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 usage context is implied through the task framing—when the user wants instructions on how to check a refund status—but there is no explicit when-to-use guidance or named alternatives among the many sibling tax tools. The non-access caveat helps, but it does not fully steer the agent away from or toward specific 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 cover read-only, idempotent, and non-destructive behavior. The description adds the key behavioral trait that the tool compares multiple filing statuses for a fixed income and outputs the most advantageous option, which is useful beyond the annotations. 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?

Two short sentences front-load the action and add the value proposition without redundancy. Every word contributes meaning.

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 comparison tool with an output schema and fully documented parameters, the description is complete. It conveys the input constraint (same income) and the intended decision support, so nothing critical is missing.

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

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

Schema description coverage is 100%, so the schema already documents all parameters (taxYear, grossIncome, dependents, itemizedDeductions). The description adds no parameter-specific detail beyond referring to 'same income,' so it stays at 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?

Description uses a specific verb ('compare') and resource ('tax liability across different filing statuses') and states the goal ('determine the most advantageous filing status'). However, it does not enumerate which statuses are included or differentiate itself from the sibling compare_mfj_vs_mfs, so it lacks explicit sibling distinction.

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 stated purpose implies when to use it: when comparing the same income under multiple filing statuses to find the best one. It provides clear context but no explicit exclusions or alternatives, so it does not reach the highest 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, so the safety profile is covered and the bar is lower. The description adds useful output behavior (shows the tax difference, enumerates MFS restrictions), which goes beyond the schema. It does not, however, disclose caveats such as whether it returns a recommendation or how it treats edge cases like hasEITC under MFS.

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 short sentences with zero filler. The primary action is front-loaded ('Compare Married Filing Jointly vs Married Filing Separately'), and the second sentence specifies the outputs. Every word 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 output schema covers return values and annotations cover the read-only/idempotent profile, so the description is only responsible for purpose and routing. It handles purpose and output behavior well, but it lacks any differentiation from or guidance around the closely related sibling compare_filing_statuses, which is a real completeness gap for a 9-parameter tool.

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

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

Schema description coverage is 100% — all 9 parameters carry type, constraints, and explanatory text (e.g., 'combined for MFJ, split for MFS'). The description adds no parameter-level meaning of its own, so it sits at the baseline 3; it neither enriches nor undermines the schema's 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 uses a specific verb ('Compare') with an exact resource (MFJ vs MFS) and states what the tool produces: a tax difference and a list of MFS restrictions. The scope is unambiguous and the name reinforces it. However, it never explicitly names or differentiates from the overlapping sibling compare_filing_statuses, so it stops short of a 5.

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

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

When to use this tool is implied by its name and content — an agent comparing MFJ vs MFS would naturally select it. But there is no explicit when/when-not language, no mention of prerequisites, and no routing to the broader compare_filing_statuses sibling for cases involving other filing statuses. The guidance is implicit rather than stated.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, so the safety profile is fully covered. The description adds useful behavioral context about the single-year restriction and the state-profile precondition, but leaves open what happens if a state lacks a profile and gives no hint about error behavior or output shape beyond the output schema.

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

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

One sentence, front-loaded with the core action and then the two narrow constraints. No wasted words; every phrase 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?

Annotations and output schema carry much of the burden, but the key precondition 'explicit calculation profile' is not operationalized: an agent has no guidance on how to determine whether a state has one or which sibling to consult beforehand. For a tool with five parameters and a conditional availability constraint, this is a meaningful gap.

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 five parameters, including the deprecated taxableIncome alias and filingStatus default. The tool description adds no parameter-level detail and therefore sits at the baseline 3 for this dimension.

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

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

States a specific verb ('compare') with a clear resource ('state income tax') and two scoping constraints: one tax year only, and the requirement that every requested state has an explicit calculation profile. This distinguishes it from siblings like compare_tax_years and estimate_state_tax 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?

Explicitly states the condition under which the tool should be used ('only when every requested state has an explicit calculation profile') and constrains it to a single tax year. It does not name a specific alternative tool, but the context is clear enough for an agent to infer when to look elsewhere.

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 meaningful context by explaining what the comparison highlights—bracket changes and inflation adjustments—which goes beyond the annotations.

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

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

The description is two short sentences with no filler. It front-loads the primary action and follows with useful context about what the comparison reveals.

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

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

The tool has an output schema and annotations that cover return values and safety, so the description does not need to repeat those. The main missing piece is clearer differentiation from the closely named sibling what_changed_between_tax_years, but overall the description is adequate for selecting and invoking this tool.

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

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

Schema description coverage is only 25%, and the description does not compensate. It clarifies that income is held constant ('same income') and implies bracket relevance, but it does not explain dependents, filingStatus, or selfEmploymentIncome, leaving most parameter semantics undocumented.

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 ('compare') and a specific resource ('tax liability across different tax years'), while clarifying the scope with 'for the same income.' It also names the output focus ('bracket changes and inflation adjustments'), which distinguishes it from other tax tools like calculate_total_tax or compare_filing_statuses.

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 for when to use the tool: when comparing tax liability across years while holding income constant. It does not explicitly list alternatives or when-not-to-use conditions, but the intended scenario is reasonably evident.

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

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

Annotations already cover read-only, idempotent, non-destructive behavior, so the description only adds context about Form 1040-ES and the target taxpayer. It does not disclose assumptions, calculation approach, or limitations such as whether underpayment penalties or safe harbor rules are considered. This is acceptable but not rich.

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

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

The description is a single, focused sentence with the core action front-loaded. It avoids redundancy and wasted words, while still conveying the purpose and target users.

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 and annotations present, the description provides a minimum viable explanation. However, it lacks guidance on how this tool differs from close siblings like estimate_self_employment_tax or calculate_total_tax, and it does not mention whether the result is an estimated amount per quarter or an annual total. Slightly more context would improve confidence for an agent deciding among similar tools.

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 83%, so most parameters are already documented in the schema. The description loosely adds meaning by tying 'self-employed' to selfEmploymentIncome and 'expected' income to expectedAnnualIncome, but it does not explain relationships between parameters or any special requirements beyond the schema.

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

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

The description states a specific action ('Calculate estimated quarterly tax payments'), names a concrete resource (Form 1040-ES), and identifies the target audience. It does not explicitly contrast itself with siblings like estimate_self_employment_tax or calculate_total_tax, so it stops short of full differentiation.

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

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

The description implies when to use the tool ('for self-employed or other taxpayers who need to make estimated payments'), which gives clear context. However, it does not explicitly state when not to use it or name alternative tools for related calculations, such as calculate_total_tax or estimate_self_employment_tax.

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

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

Annotations already declare readOnly and idempotent, so the description's incremental value lies in the conditional behavior: above the QBI threshold it will include SSTB classification, W-2 wages, and qualified-property basis, defaulting to 0 when not applicable. This gives the agent useful expectation-setting about output variation. No contradiction with the safety 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 filler; the first fronts the core purpose and output list, the second adds conditional behavior. The wording is slightly dense, but every clause carries information. Efficient for an 11-parameter estimation 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?

The combination of a rich output schema and detailed conditional description covers what the tool returns and when it changes behavior. The 'annual QBI threshold' is not defined, and no alternative tools are mentioned, but the required inputs are in the schema and the main ambiguity (zero-filling unapplicable QBI values) is resolved. 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?

With schema description coverage at 55%, the schema already documents revenue, expenses, W-2 income, premiums, and retirement contributions. The description adds meaning for the otherwise under-documented QBI parameters by naming them and explaining that W-2 wages and property basis default to 0 when not applicable. It does not detail every remaining optional parameter, but the most ambiguous ones are addressed.

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 a specific verb phrase ('Detailed self-employment tax breakdown') and names distinct outputs: Schedule C profit, SE tax, QBI deduction, and quarterly payments. This makes the tool's scope evident and separates it from sibling calculators like calculate_total_tax or estimate_quarterly_tax. The conditional QBI sentence further specifies the resource's behavior.

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: it is the tool for a comprehensive self-employment tax estimate, not a general tax calculation. It stops short of explicitly naming alternatives or stating when not to use it, but the 'detailed breakdown' framing differentiates it from sibling quarterly-payment and total-tax tools. No misleading exclusions are present.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds value beyond annotations by disclosing the fail-closed behavior ('Unsupported state-year paths fail closed') and the versioned-profile semantics, which tell the agent how errors and unsupported inputs are handled. No contradiction with annotations.

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

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

Two sentences totaling roughly 20 words, with the core purpose first and the critical fail-closed behavior second. Every word earns its place; no filler.

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

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

With an output schema present, full parameter documentation in the schema, and robust annotations, the description does not need to cover return values or safety. The fail-closed disclosure fills the main behavioral gap; the only omission is explicit routing guidance versus closely related siblings, which is already penalized under usage guidelines.

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

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

Schema description coverage is 100%, so the baseline is 3; the schema already documents taxYear, stateCode, filingStatus, the deprecated taxableIncome alias, and incomeBeforeStateDeductions. The description adds only the state-year path coupling, which is useful but does not substantially deepen parameter understanding beyond the schema.

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

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

The description states a specific verb ('Estimate'), resource ('state income tax'), and a defining mechanism ('explicit tax-year calculation profile'). It clearly carves out state-level estimation, distinguishing it from siblings like calculate_federal_tax and get_state_tax_info by scope, though it does not name any sibling explicitly.

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 'using an explicit tax-year calculation profile' and the fail-closed note imply the tool is for supported state-year combinations where the caller provides a concrete tax year. However, there is no explicit when-to-use/when-not-to-use guidance or naming of alternatives (e.g., calculate_total_tax, get_state_tax_info), leaving selection largely to inference.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safe compute-only profile is established without description help. The description adds modest context: the term 'supported state tax' hints that state coverage is conditional, and listing 'refund inputs' clarifies the report computes refund/amount-owed impact. No contradiction with annotations — 'generate an estimate' is consistent with a read-only computation. It stops short of explaining output format or behavior on unsupported states, but the output schema partially covers that.

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

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

A single 22-word sentence that front-loads the verb and resource, then efficiently enumerates the report's coverage in one clause. There is zero filler, and the description earns its place by communicating scope without redundantly listing parameter names already visible 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 tool with 39 parameters and two required fields, the one-sentence description is thin. It does not tell an agent which of the many optional parameters matter for common scenarios, does not clarify whether unspecified fields default to zero, and provides no contrast with the heavily overlapping sibling calculators. While the output schema and annotations reduce the burden on the description, an agent still lacks the context needed to reliably select this tool over calculate_total_tax or simulate_tax_scenario and to scope the parameter set for a real user situation.

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 72%, which is in the mid-range, so the schema carries most parameter documentation (with gaps like qualifiedDividends, taxExemptInterest, and qualifiedBusinessPropertyBasis having no descriptions). The tool description adds a light semantic overlay by grouping the 39 parameters into categories (federal inputs, state inputs, FICA, credits, deductions, take-home pay, refund inputs), which helps an agent mentally organize the parameter space. It does not add per-parameter detail 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 uses a specific verb ('Generate'), a clear resource ('detailed tax estimate'), and enumerates the components ('federal tax, supported state tax, FICA, modeled credits, deductions, take-home pay, and refund inputs'). This establishes it as a comprehensive aggregation tool. However, it does not explicitly differentiate from close siblings like calculate_total_tax or calculate_federal_tax; the 'combining' wording and 'full' in the name imply scope but the distinction is left to inference.

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?

No usage guidance is provided. With 43 siblings including calculate_federal_tax, estimate_state_tax, calculate_total_tax, and simulate_tax_scenario, an agent has no explicit direction about when to invoke this comprehensive report instead of a single-component calculator. The description offers no 'use X instead when...' routing, leaving the agent to guess based on the word 'full'.

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 adds meaningful behavioral context beyond the readOnly and idempotent annotations: the computation is deterministic, executed locally/privacy-first, and the output includes assumptions, source provenance, calculation trace, and explicit unsupported boundaries. This materially helps an agent trust and interpret the result.

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

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

One dense sentence with no filler; every element—deterministic, privacy-first, structured results, assumptions, provenance, trace, unsupported boundaries—earns its place and conveys a distinct attribute of the 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?

The tool is complex: 9 parameters, nested income objects, four filing-status enums, and tax-year constraints. The description focuses on output characteristics rather than invocation context, required fields, or input categories. The output schema covers return shape, but the description leaves too much for an agent to infer about how to 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 only 22%, yet the description names no parameters and gives no hints about taxYear, filingStatus, income, family, business, payments, education, stateCode, or deductions. It does nothing to compensate for the low schema coverage, so parameter semantics are effectively absent.

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 ('Generate') and a specific resource ('tax plan'), then distinguishes the tool through traits like 'deterministic', 'privacy-first local', 'source provenance', and 'calculation trace'. These traits separate it from sibling tools such as generate_full_tax_report or simulate_tax_scenario 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?

There is no guidance on when to use this tool versus alternatives like simulate_tax_scenario, generate_full_tax_report, or plan_multi_year_taxes. No exclusions, prerequisites, or decision conditions are given; usage context is only implied by the tool's name and the word 'plan'.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, covering the safety profile. The description adds useful behavioral context about the returned content: section-by-section guidance, required data, and mistake warnings, without contradicting 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 a single, information-dense sentence with no filler. It front-loads the core purpose and then quickly adds useful details about the guide's content.

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 lookup with one parameter and an output schema, the description is largely complete. It explains what the output covers, though it does not mention any limitations on form coverage or whether some forms/schedules are unsupported.

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 already documents formNumber at 100% coverage with concrete examples. The description adds only the generic concept of 'form or schedule' and provides no additional parameter-level meaning, so the baseline of 3 is appropriate.

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

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

The description clearly states the tool provides a step-by-step guide for a specific IRS form or schedule, and specifies what the guide contains (sections, required data, common mistakes). It distinguishes itself from general tax calculators, though it does not explicitly contrast with the similar sibling get_irs_form_info.

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

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

The intended context is implied: use when someone needs help filling out an IRS form. However, the description provides no explicit guidance on when not to use it or which sibling tool (e.g., get_irs_form_info for form overviews) should be preferred instead.

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

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

Annotations already establish that this is a safe, read-only, idempotent operation. The description adds useful context about the scope ('common' forms) and the nature of the returned content (explanations, audience, and sources), which goes beyond the bare annotations without contradicting them.

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 sentence with no filler. The main action and resource are front-loaded, and the em-dash efficiently enumerates the three kinds of information provided.

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 low-complexity tool with one parameter and an output schema, the description covers the essential purpose and content areas. It is slightly incomplete in that it does not clarify which forms are considered 'common' or how this relates to filing-format guidance from siblings, but this is a minor gap.

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 already documents the single parameter formNumber with helpful examples, so the description carries little parameter burden. It does not add any additional semantic detail about the parameter, justifying 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 identifies the verb ('Get information') and resource ('IRS tax forms'), and adds the scope qualifier 'common' to narrow the topic. It does not explicitly distinguish itself from the closely related sibling get_form_filing_guide, so it stops short of a 5.

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

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

The description implies the tool is for general lookup of IRS form information—what forms are, who needs them, and where to find them—but it gives no explicit guidance on when to prefer this tool over siblings like get_form_filing_guide or lookup_tax_rule. No alternatives or exclusions are mentioned.

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

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

Annotations already declare readOnlyHint: true, idempotentHint: true, and destructiveHint: false, fully covering the safety profile. The description adds contextual value by stating the output covers 'deadlines for filing, estimated payments, extensions, and key actions,' but it does not disclose any behavioral quirks beyond what annotations and the output schema already convey. No contradiction exists.

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

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

The description is two tight sentences with no wasted words. The action and resource are front-loaded in the first sentence, and the second sentence efficiently enumerates what the calendar includes.

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

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

With a rich output schema and annotations covering read-only and idempotent behavior, the description plus schema are largely sufficient for an agent to invoke the tool correctly. The only notable gap is the lack of guidance for choosing between this tool and get_tax_deadlines, but the optional parameters and required taxYear are documented in the schema.

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

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

Schema description coverage is 100%, so the parameters are fully documented in the input schema. The description's phrase 'based on your situation' reinforces the purpose of the boolean flags but adds no specific meaning beyond what the schema already provides for each parameter.

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 ('Generate') and a clear resource ('personalized tax calendar based on your situation'), and it enumerates the calendar's contents: 'deadlines for filing, estimated payments, extensions, and key actions.' However, it does not explicitly differentiate itself from the sibling tool get_tax_deadlines, which likely serves a similar purpose for non-personalized deadlines.

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?

Usage context is implied through the phrase 'based on your situation' and the word 'personalized,' which suggests this tool should be used when tailoring a calendar to individual circumstances. There is no explicit when-to-use or when-not-to-use guidance, and no alternatives are named, so the agent must infer selection criteria from the tool name and description alone.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered. The description adds contextual value by specifying the content areas returned (limits, tax treatment, income limits, tips) without contradicting 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 a single concise sentence that front-loads the action and resource, then lists specific content areas. Every word earns its place; there is no filler, repetition, or unnecessary detail.

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 lookup with one optional parameter and an output schema present, the description gives sufficient context to select and call the tool correctly. It would be slightly stronger with a pointer to sibling tools for strategic planning, but that gap is already reflected in the usage guidelines score.

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 the sole parameter accountType fully described including example values and empty behavior. The description adds no parameter-specific information, but none is needed given the schema's completeness; the baseline of 3 is appropriate.

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

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

The description uses a specific verb ('Get details') and identifies the resource ('retirement account types'), then enumerates key attributes (contribution limits, tax treatment, income limits, tips). This differentiates it from sibling tools like get_retirement_strategy or plan_retirement_withdrawals, though it does not explicitly disambiguate 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 implies its usage context (retrieving reference details about retirement account types) but provides no explicit when-to-use guidance or alternatives. With several retirement-related sibling tools, an agent must infer the boundary between this and tools like get_retirement_strategy.

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's 'Get' wording is consistent with a safe read operation. It adds no significant behavioral context beyond the annotations, such as response scope or limitations, but it also contradicts nothing.

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

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

The description is a single focused sentence that front-loads the action and resource, then lists illustrative examples. There is no redundant or filler content.

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 one optional parameter fully documented in the schema, strong annotations, and an output schema present, the description gives enough information to select and invoke the tool. It could be strengthened by distinguishing it from planning-focused siblings, but that is a usage-guidance nuance rather than a blocking gap.

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

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

Schema coverage is 100%, and the schema itself documents strategyId with concrete example values and the 'Leave empty for all' behavior. The description adds only conceptual framing by listing strategy names, which is helpful but not necessary because the schema already carries the parameter semantics. Baseline 3 applies.

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

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

The description opens with the verb 'Get' and identifies a specific resource ('detailed info on tax-advantaged retirement strategies') with concrete named examples. It is clearly understood as an informational lookup, but it does not explicitly differentiate itself from overlapping siblings such as plan_retirement_withdrawals or optimize_capital_gains.

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 statement implies when to use it (when detailed informational content on these retirement strategies is needed), and the named examples give useful context. However, it offers no explicit when-not-to-use guidance or alternatives, leaving an agent to infer the boundary with siblings like get_retirement_accounts and plan_retirement_withdrawals.

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

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

The annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds moderate context by listing rates, brackets, and key details, but it does not disclose edge cases such as whether territories are included or how federal versus state tax data is scoped.

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

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

The description is a single well-structured sentence that front-loads the primary purpose and adds useful specifics. There is no filler, repetition, or unnecessary detail.

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?

This is a simple read-only lookup tool with one fully documented parameter, rich annotations, and an output schema available. The description covers the core scope and content well. It is not quite complete because it does not point to sibling tools for related use cases, but that is a secondary gap given the tool's low 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?

The schema provides 100% coverage for stateCode with type, length constraints, and an example. The description adds no new parameter-specific meaning beyond the broad scope of 'any US state,' so the schema carries the weight and the baseline of 3 is appropriate.

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

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

The description uses a specific verb ('get') and resource ('state income tax information'), and clarifies what is included: rates, brackets, and key details. It clearly identifies this as a state-level tax information tool, but it does not explicitly differentiate it from closely related siblings like get_tax_brackets or estimate_state_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 gives no explicit guidance about when to choose this tool over alternatives such as compare_state_taxes, estimate_state_tax, or get_tax_brackets. It only states that it covers state income tax information, leaving the agent to infer selection boundaries.

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, so the safety profile is covered. The description adds that the tool returns both tax brackets and the standard deduction, which is useful scope information, but it does not discuss response size, pagination, or any other runtime behavior. No 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?

A single 15-word sentence front-loads the verb and resource, then adds the two qualifiers. There is zero redundancy or filler.

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

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

Despite no explicit usage guidance, the definition is complete for a simple read-only lookup: annotations cover safety, schema covers all parameter constraints with 100% coverage, and an output schema exists to document the return shape. The description states the core resource and scope, so an agent can safely call it.

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

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

Schema description coverage is 100%: taxYear is documented as 'Tax year (2024, 2025, or 2026)' and filingStatus has an explicit enum. The description only restates the two dimensions ('given tax year and filing status') without adding format constraints, allowed values, or edge-case handling, so it adds no 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 uses the specific verb 'Get' with a precise resource: 'federal income tax brackets and standard deduction,' qualified by 'tax year and filing status.' This clearly distinguishes it from state-tax siblings like get_state_tax_info and calculation tools like calculate_federal_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?

No explicit when-to-use or when-not-to-use statements; it does not name alternative tools or exclusion criteria. The description implies use when a specific federal tax year and filing status are known, but the agent must infer this from the purpose, and many siblings overlap thematically.

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 agent knows this is a safe, non-mutating lookup. The description adds modest scope context ('IRS', 'given tax year', 'important') but does not disclose any additional behavioral traits such as whether the returned list is comprehensive or filtered, or whether state deadlines are excluded.

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, front-loaded sentence with no redundant phrasing. Every word contributes to the agent's understanding of the tool's purpose.

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 lookup with one optional parameter, an output schema, and full annotation coverage, the description is largely sufficient. The term 'important' is somewhat vague, and the description does not clarify whether it covers all deadlines or only key ones, but this is a minor gap given the output schema and sibling 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?

The schema already documents the only parameter 'taxYear' with its default value, and schema description coverage is 100%. The description rephrases the parameter as 'given tax year' but adds no new semantic detail 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 action ('Get') and the resource ('important IRS tax deadlines and due dates for a given tax year'). It is specific and understandable, but it does not explicitly differentiate from the sibling 'get_personalized_tax_calendar', which may serve a similar need.

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?

No guidance is provided about when to use this tool over alternatives. Siblings like 'get_personalized_tax_calendar' or 'lookup_tax_rule' exist, but the description gives no selection criteria or exclusions, leaving the agent to infer usage from the tool 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?

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds useful behavioral context by indicating that the checklist is personalized and driven by the user's income sources, deductions, and life events. This goes beyond the annotations without contradicting them.

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 filler. The primary action and output are front-loaded, and the input basis is stated immediately after. 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?

Given the rich input schema with 20 well-documented boolean parameters, an output schema, and annotations covering idempotence and safety, the description is complete enough for an agent to select and invoke the tool correctly. It explains what the tool produces and what factors influence the result; return-value details are covered by the output schema.

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

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

Schema description coverage is 100%, and each boolean parameter already has a clear description. The tool description's reference to 'income sources, deductions, and life events' provides a light conceptual grouping, but it does not add meaningful parameter semantics beyond what the schema already supplies. 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 ('Generate') and resource ('personalized checklist of tax documents'), and clearly states the purpose: helping gather documents for filing. This is distinct from sibling tools like get_tax_deadlines or calculate_total_tax, so an agent can immediately tell what this 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 phrase 'for filing' plus 'based on your income sources, deductions, and life events' gives clear context for when to use this tool: when a user needs a document-gathering checklist customized to their situation. It does not explicitly name alternatives or exclusions, but the purpose is sufficiently distinct 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?

Annotations (readOnlyHint=true, destructiveHint=false) already cover the safety profile, and the description aligns with those by using 'Get' and 'Suggests'. It adds some output context by saying the tool 'suggests actions,' but does not disclose whether the response is a ranked list, a single strategy, or if there are limitations like 'not financial advice.' With annotations covering the safety profile, a 3 is appropriate.

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 with no redundancy. The primary purpose is front-loaded ('Get personalized year-end tax optimization strategies') and the second sentence adds clarifying output context without wasting 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?

This tool has 15 parameters, 3 required, and an output schema, yet the description gives only a high-level overview. It does not mention required inputs (taxYear, filingStatus, estimatedIncome), how optional parameters factor in, or any scope limitations (e.g., US federal only). For a tool of this complexity, the description is too sparse to fully orient an agent.

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 53%, leaving several parameters (hasMortgage, isSelfEmployed, hasCapitalGains, hasCapitalLosses, estimatedCapitalGains, estimatedItemizedDeductions) undocumented. The description only broadly references 'income, deductions, and situation' and does not compensate for the missing parameter explanations. It also omits the required taxYear parameter entirely, leaving the agent to infer that it is needed.

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 and resource: 'Get personalized year-end tax optimization strategies' and further clarifies it 'Suggests actions to reduce tax liability before year-end.' This distinguishes it from calculation and factual tools like calculate_total_tax or get_tax_brackets. However, it does not explicitly differentiate from the similarly broad sibling generate_tax_plan, so it falls short of a 5.

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

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

The phrase 'year-end tax optimization strategies' implies when to use the tool (before year-end, for personalized tax-saving advice), but gives no explicit when-not-to-use guidance or alternative routing. An agent must infer usage from the year-end context, and there is no mention of when to choose generate_tax_plan or plan_multi_year_taxes instead.

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

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

Annotations already cover the safety profile via readOnlyHint, idempotentHint, and destructiveHint. The description adds useful content context but does not disclose additional behavioral traits such as defaults, ordering, or filtering behavior beyond what the schema and annotations already 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?

Two short sentences, front-loaded with the core action and resource, and no filler. The scope statement earns its place by clarifying coverage.

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 list tool with one optional, fully documented parameter and an output schema, the description covers purpose, scope, and content expectations. Nothing critical is missing.

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

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

Schema description coverage is 100%, so the category parameter is fully documented. The description's mention of above-the-line and itemized deductions aligns with enum values but adds no 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?

States a specific verb ('List') and resource ('tax deductions'), plus content scope ('eligibility rules and limits') and coverage ('above-the-line and itemized'). This distinguishes it from siblings like list_tax_credits and standard_vs_itemized.

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

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

The description implies when to use the tool, but does not explicitly name alternatives or state when not to use it. An agent can infer usage from the purpose, but the selection context versus overlapping tax tools is left implicit.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered without description effort. The description adds only the completeness scope ('all US states'), which aligns with openWorldHint=false, but contributes no further behavioral context such as data recency or sensitivity to changing tax law.

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, 9-word sentence with every word earning its place and no filler or redundancy. The core scoping ('all US states with no state income tax') 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?

For a 0-parameter lookup whose output schema exists and whose annotations cover safety, the definition is nearly complete: an agent knows exactly what to invoke and what it will get. The only minor gap is the absence of a temporal caveat that state income-tax status can change over time.

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 and its input schema is trivially 100% covered, so there is nothing for the description to explain. Per the zero-parameter baseline of 4, the description needs no parameter documentation and adds appropriate value by narrowing the query scope.

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 ('List') with an unambiguous resource ('all US states with no state income tax'), making the tool's scope instantly clear. It is inherently distinct from siblings like get_state_tax_info (per-state detail), compare_state_taxes (comparison), and analyze_relocation_taxes (relocation scenarios), none of which provide this exact filtered list.

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?

No explicit when-to-use or when-not-to-use guidance is given, and no alternatives are named. An agent must infer from the tool's name and clear scope that it is the right choice for a flat enumeration task, rather than being told to prefer compare_state_taxes for comparative analysis or get_state_tax_info for state-specific detail.

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 no further safety disclosure is required. The description adds some context about the returned content (eligibility, amounts, phase-out rules) but does not disclose additional behavioral traits such as data sources, rate limits, or side effects. With annotations already covering the behavioral profile, this is acceptable but not exemplary.

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, front-loading the core action and resource before listing covered categories. Every phrase earns its place; there is no redundant or filler language. It is appropriately sized for a straightforward listing 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 listing tool with optional parameters, an output schema, and clear annotations, the description provides enough context for an agent to call it correctly. It covers the scope, the categories, and the kind of information the user will receive. No critical operational detail is missing.

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

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

Both parameters are fully described in the input schema, with category providing an enum of options and refundableOnly described as 'Only show refundable credits'. The description repeats the category coverage but does not add meaning beyond the schema. Since schema description coverage is 100%, the baseline of 3 applies.

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

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

The description clearly states the tool's action ('List') and resource ('available federal tax credits') and identifies the kind of information returned (eligibility, amounts, phase-out rules). It also distinguishes itself from sibling tools like list_deductions and calculate_eitc by focusing specifically on credits rather than deductions or a single credit calculation.

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 for when this tool is appropriate: when an agent needs an overview of federal tax credits across categories such as family, education, energy, retirement, healthcare, and income. It does not explicitly name alternatives or state when not to use it, but the listing-oriented wording is enough to separate it from more targeted sibling tools like check_credit_eligibility.

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

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

Annotations already establish readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description does not need to restate the safety profile. The description adds minimal behavioral context beyond the base 'look up' framing, such as that the output will be definitions or answers to common questions, but no detail on result structure or limitations is provided.

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 short sentences, with the core action front-loaded and scope examples following. No repetitive filler or 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 single-parameter, read-only lookup with a complete schema and an output schema present, the description provides adequate context: what the tool accesses (IRS rules), what topics it covers, and examples of valid topic values. Nothing critical for a correct call 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?

The schema's topic parameter is described at 100% coverage with concrete examples, so the schema carries the parameter documentation burden. The description only echoes those examples ('wash sales', 'credit eligibility') without adding format, constraints, or usage syntax 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 opening phrase 'Look up IRS tax rules, definitions, and common questions' names a specific verb and a substantive resource, so an agent can tell this is a reference lookup rather than a calculator or filing tool. However, it does not explicitly differentiate from specialized siblings such as list_deductions or check_credit_eligibility, and the trailing 'and more' is broad.

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 examples in the second sentence ('filing rules, income types, deduction rules, credit eligibility, stock options, wash sales') imply when the tool is appropriate. There is no explicit guidance about when to prefer a specialized sibling or when not to use this tool, leaving some routing to inference.

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

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

Annotations already establish readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds meaningful behavioral detail about what the analysis considers, such as long-term vs short-term treatment, 0% bracket space, loss harvesting, and wash sale rules. It does not contradict 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 a single, dense sentence that front-loads the core action and then lists relevant decision factors. It contains no filler, repetition, or unnecessary detail.

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 presence of an output schema and safety annotations, the description covers the core decision logic and input context well. It could more explicitly distinguish itself from overlapping planning siblings like plan_retirement_withdrawals or generate_tax_plan, but it is largely complete for a read-only optimization tool.

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

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

Schema description coverage is 80%, so the schema already documents most parameters. The description reinforces the high-level purpose around lots and tax minimization but does not add detail beyond what the schema provides, nor does it explain the optional targetGainOrLoss parameter.

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 ('Analyze'), a clear resource ('investment lots'), and an explicit outcome ('suggest which to sell to minimize tax'). It also names distinct decision factors (long-term vs short-term, 0% bracket space, loss harvesting, wash sale rules), making it easily distinguishable from sibling tax calculation 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 clearly implies when to use it: when analyzing investment lots to minimize capital gains tax. It does not explicitly name alternatives or state when not to use it, but the context is strong enough for an agent to infer the intended scenario.

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 meaningful behavioral context by specifying what the tool models: income changes, Roth conversions, retirement contributions, and bracket management. No contradiction between the 'Create' wording and the read-only annotation is present.

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

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

The description is a single, well-structured sentence that front-loads the core purpose ('Create a 3-5 year tax projection and strategy') before listing the modeled factors. Every phrase earns its place with no redundancy or filler.

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

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

Given the rich input schema with required fields and an output schema, the description covers the strategic purpose sufficiently for an agent to select and invoke the tool. It could add more nuance about required per-year input structure, but the schema already documents those constraints, and the annotations cover the behavioral safety profile.

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%, but the description partially compensates by naming planning levers that map to parameters: Roth conversions (plannedRothConversion), retirement contributions (plannedIRA/planned401k), and income changes (expectedIncome). It does not explain top-level parameters like currentAge or per-year fields like stateCode and dependents, leaving some meaning to be inferred from 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 verb 'Create' and the specific resource: a 3-5 year tax projection and strategy. It names the key modeled dimensions (income changes, Roth conversions, retirement contributions, bracket management), which helps identify the tool's purpose. It does not explicitly contrast with siblings like generate_tax_plan or simulate_tax_scenario, but 'multi-year' provides meaningful differentiation.

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 for multi-year tax projection and strategy, which naturally distinguishes it from single-year calculators among the siblings. However, it does not explicitly state when not to use it or name alternatives, so it stops short of full routing guidance.

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