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

Annotations already declare readOnly/idempotent/non-destructive/closed-world, so the safety profile is covered. The description adds substantive context beyond that: the two-stage cap-then-phase-out mechanic, the $100-per-$1,000 MAGI reduction, the $0 outcome for MFS, and data provenance ('copied from irs.gov in Oct 2026'). It does not describe the response shape, but there is no output schema to lean on.

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 dense paragraph that front-loads the cap and phase-out before the eligibility nuances. Every clause carries information, though the statutory citation and IRS sourcing note add legal flavor an agent doesn't strictly need to invoke 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?

For an 8-parameter calculator with 3 required fields, no output schema and annotations already covering the safety profile, the description supplies the full decision logic: caps, phase-out rate, eligibility restriction, MFS exclusion, and input-path alternatives. Nothing material is missing for a correct invocation.

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

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

Schema coverage is 100%, so the baseline would be 3, but the description adds real meaning: it clarifies that the three input paths (hourly rate + hours + multiplier, total_overtime_pay, qualified_overtime_premium) are alternatives, and warns that raising the multiplier to 2 does not double the qualified amount. That is interpretive guidance the schema does not supply.

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

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

States a specific verb and resource ('Calculates the 2025-2028 federal deduction for qualified overtime pay'), names the governing statute and the IRS form line it mirrors, and pins the exact cap amounts. An agent can distinguish it from the tips and senior deduction siblings at a glance.

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 scopes what qualifies (FLSA half-time premium only, double time does not double it) and states the married-filing-separately exclusion, which is a real when-not condition. It does not explicitly route to or away from the sibling deduction tools, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, but the description adds substantial value: the full arithmetic ($6,000 per qualifying person, 6% reduction over $75,000/$150,000), the per-spouse application on joint returns, and provenance with a date for the figures. It stops short of describing the return shape (single amount vs. per-spouse breakdown), which matters since there is no 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?

Four sentences, front-loaded with the verb and statutory basis, then mechanics, edge cases, and provenance. Density is high but nearly every clause carries a distinct fact; the provenance sentence is justified because it dates the constants.

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 7-parameter, no-output-schema calculation tool, the description supplies the formula and the notable edge cases (MFS = $0, per-spouse reduction). The remaining gap is the output shape and how invalid combinations are handled, which the agent must discover by calling.

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

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

With 100% schema coverage the baseline is 3, and the description earns an extra point by explaining the phase-out math tied to magi and filing_status, including that the reduction is applied per spouse rather than to the combined $12,000. It does not address the birth_date vs. *_age_65_or_older precedence, though the schema already documents that fallback.

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 (calculates) and a precisely bounded resource: the 2025-2028 enhanced senior deduction under P.L. 119-21 mirroring Schedule 1-A Part V. The scope markers (65+, $6,000 per person, phase-out) clearly separate it from siblings like calculate_tips_deduction and calculate_overtime_deduction.

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

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

Gives clear eligibility conditions that determine use: age 65+ by Dec 31, tax years 2025-2028, and an explicit exclusion that married_filing_separately gets $0. It does not, however, name sibling tools or tell the agent where to route a taxpayer who fails the age test (e.g., explain_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 this as a safe, idempotent, non-destructive read, so the description correctly focuses on behavior: the $25,000 per-return cap applied identically across filing statuses, the $100-per-$1,000 MAGI phase-out above $150,000 ($300,000 joint), the self-employed net-income ceiling, and the zeroed-out MFS case. It also discloses provenance and vintage of the figures (irs.gov, Oct 2026), which matters for a statutory-formula calculator tied to a specific 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?

Front-loaded with the formula and cap before the phase-out and edge cases, and no sentence is filler. It is dense to the point of requiring a re-read on the nested parentheticals ($150,000 / $300,000 joint) and the final provenance sentence, though that sentence does add value.

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

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

For a 6-parameter, output-schema-less calculation tool, the description supplies the full computation logic and the key edge cases. The remaining gap is the result surface — whether it returns just a deduction amount, a phase-out ratio, or also an eligibility note — plus behavior on disallowed filings.

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

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

Schema coverage is 100%, so baseline would be 3; the description earns above baseline by explaining how parameters interact rather than restating them — MAGI drives the phase-out at two different thresholds depending on filing status, and self_employed_tips are constrained by that business's net income. It does not, however, clarify what happens on an MFS input (return zero vs. error) or the ordering of cap-before-phase-out.

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 (calculates) and a precisely scoped resource (the 2025-2028 federal tips deduction under IRC 224 / Schedule 1-A Part II). The subject matter is clearly distinct from the sibling tools (overtime, senior, tax savings, eligibility), so an agent can route without opening the schema.

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

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

Gives clear applicability context: valid tax years 2025-2028, an explicit exclusion (married filing separately gets $0), and the self-employed net-income limitation. What it lacks is any routing language toward siblings such as explain_eligibility or estimate_tax_savings when the agent needs eligibility reasoning rather than a number.

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

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

Annotations already establish read-only, idempotent, non-destructive, closed-world behavior, so the description's job is to add computation semantics — and it does: it applies each deduction's cap and phase-out, computes taxable income before and after, and names the controlling revenue procedures. It also transparently discloses the 2027-2028 bracket substitution rather than silently assuming. It stops short of saying what happens when both overtime_hours+hourly_rate and qualified_overtime_premium are supplied.

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 sentences, front-loaded with the verb and result, then methodology, then the year caveat and scope limit. No sentence is redundant and each adds a distinct fact.

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 11-parameter, no-output-schema estimation tool the description covers methodology, year coverage, and scope boundaries well. The main gap is return shape — "before and after" and "says so" hint at a breakdown or note field, but with no output schema the agent must call it to learn what a result looks like.

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 every parameter already carries authoritative documentation (including MAGI's Schedule 1-A Part I definition and the MFJ-only constraint on spouse_age_65_or_older). The description adds no parameter-level guidance beyond what the schema supplies, so baseline 3 applies.

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

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

States a specific verb ("Estimates"), a specific resource ("federal income tax saved"), the year range, the three deductions combined, and the computational method (caps/phase-outs then IRS bracket tables). This is clearly distinguishable from the sibling tools, which calculate single deduction amounts rather than the combined tax effect.

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?

"Federal income tax only" establishes an explicit scope exclusion, and the note about 2027-2028 brackets tells the agent how the tool degrades. However, it never states when to prefer this combined tool over calculate_overtime_deduction / calculate_tips_deduction / calculate_senior_deduction, nor any prerequisite (e.g. filing status restrictions beyond what the schema says). Usage is implied by the name, not 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 cover the safety profile (read-only, idempotent, closed-world, non-destructive), so the description's added value is the provenance and currency note ('Taken from IRS FAQs and forms fetched Oct 2026') plus the disclosure that behavior changes across years (2026 code TT restriction). That is genuinely useful context an agent cannot get from the annotations, though return format is unstated.

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 dense sentence front-loads the core purpose and then packs the specific coverage list, ending with the source note. It is slightly run-on with a long parenthetical, but every clause carries substantive information and nothing is redundant.

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 no output schema, the description must convey what comes back, and it does so concretely: eligibility rules, year coverage, excluded filing status, SSN rule, FLSA eligibility, and the specific reporting locations (W-2 box 12 TT/TP, 1099 boxes, Schedule 1-A lines), plus the 2026 nuance. Only the response shape/format is left unstated, which 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?

Schema description coverage is 100% and both parameters (topic enum, tax_year 2025-2028) are fully documented in the schema, so the baseline of 3 applies. The description corroborates the year range and topic set and notes that rules differ by year, but adds no syntax or default behavior beyond what the schema states.

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 and resource ('Explains who can claim the ... deductions for overtime, tips and seniors') and enumerates the exact subject matter (filing status exclusions, SSN rule, FLSA, reporting boxes). This clearly distinguishes it as an explanatory/reference tool rather than a calculator, though the sibling tools (calculate_*_deduction) are never named 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?

Usage is only implied: an agent can infer this is the tool to consult before or instead of the calculate_* siblings, and the tax_year parameter range hints at year-specific rules. There is no explicit statement of when to use this versus the four calculation siblings, nor any ordering guidance such as 'call this first to determine eligibility.'

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