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 genuinely useful non-annotated behavior: the $10,000 cap, the exact phase-out mechanics ($200 per $1,000 of MAGI over $100,000/$200,000, reaching $0 at $149,001/$249,001), and the eligibility gates. It does not describe the return payload (e.g. whether it reports the deductible amount and estimated tax saved via marginal_tax_rate), which is the remaining gap.

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

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

Front-loaded with the core calculation and phase-out math, then the eligibility checklist, then provenance. The middle eligibility run-on is dense but every clause carries a distinct rule; nothing is filler, though the single-sentence block could be broken for scanability.

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 14-parameter, no-output-schema tool, the description covers the domain rules, the computation, and the eligibility gates thoroughly. The one omission is what the tool actually returns (deductible amount, phase-out-reduced figure, estimated tax savings), which an agent cannot infer since there is no output schema.

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

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

Schema coverage is 100%, so the baseline is 3. The description still adds meaning beyond the schema by explaining the phase-out formula that governs how magi and interest_paid interact, the $10,000 cap, and by enumerating the eligibility tests that map to the boolean flags (new_vehicle, us_final_assembly, secured_by_first_lien, is_lease, gvwr_under_14000_lbs). It does not explain marginal_tax_rate or interest_deducted_elsewhere, leaving a small residual gap.

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

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

States a specific verb and resource ('Calculates the 2025-2028 federal deduction for car loan interest'), cites the exact statutory authority (P.L. 119-21, IRC 163(h)(4)) and the IRS form it mirrors (Schedule 1-A Part IV). This is unmistakably distinct from the SALT, bracket, and child tax credit siblings without needing to open any 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 tax-year window (2025-2028, 'deduction ends after 2028'), the eligibility checklist, and 'available whether or not you itemize' give clear conditions for when this applies. It never names an alternative tool or states when not to use it, but the sibling deductions are conceptually disjoint so the routing risk is low.

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 no credit is due for restating safety. The description adds genuine behavioral substance the annotations cannot: the 5% phase-out with excess rounded up to the next $1,000, the tax-liability limitation, and the separate refundable component at 15% of earned income over $2,500 — all of which affect how an agent should interpret results. It stops short of describing what the response actually returns.

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 lead clause is front-loaded with verb, resource, and authority, and every subsequent number (per-child amount, phase-out rate, thresholds, refundable cap) is load-bearing for a credit calculation. It is dense to the point of being a single run-on sentence, which costs a little readability, but no sentence is wasted.

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 credit engine with no output schema, the description supplies the full calculation logic so the agent can predict what the numbers mean and sanity-check results. The remaining gap is that it never states the shape of the returned value (e.g., split between nonrefundable and refundable amounts), which a no-output-schema tool would ideally disclose.

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

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

With 100% schema description coverage, the schema already documents every parameter including the MAGI default for earned income and the MAGI-based estimate for tax liability, so the baseline is 3. The description does add some semantic mapping — $400,000 joint vs $200,000 other thresholds tie directly to filing_status, and $2,200 per qualifying child vs $500 per other dependent tie to those counts — but it does not add format or edge-case guidance beyond that.

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

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

Opens with a specific verb+resource ("Calculates the child tax credit as Schedule 8812 does") and pins the governing law and applicable years, so an agent can distinguish it from the three deduction/bracket siblings without opening any schema. The statutory anchor makes the tool's scope unmistakable.

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?

Scope is clearly bounded to 2025 and 2026 tax years with the OBBBA rules, which effectively tells the agent when this tool applies, and the description implies a completed calculation rather than a rate lookup. However, it never names the sibling tools or states exclusions (e.g., what to do for other years or for non-child credits), so the alternative-selection guidance is implicit rather than explicit.

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

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

Annotations already declare this a pure read-only, idempotent, closed-world computation, so the bar is lower; the description earns credit by disclosing the exact computation method (IRS worksheet), the phase-out formula, and source provenance for the amounts. It stops short of describing the response shape or units of the returned comparison.

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?

Purpose is front-loaded in the first clause and every sentence carries substantive information, but the middle sentence is a dense run-on of statutory dollar amounts that is harder to scan than a short list. No filler, though.

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 should say what comes back; it implies a deduction amount plus an optional itemize-vs-standard comparison but never names the returned fields. Parameters and computation logic are otherwise fully covered for a calculator of this complexity.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds formula-level meaning for how magi and tax_year drive the cap and phase-out, but it does not add per-parameter guidance beyond what the schema descriptions already state (e.g., filing_status enum handling, behavior when state_and_local_taxes is below the cap).

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 resource (SALT deduction on Schedule A), plus the governing statute and year range. It is unambiguous against siblings like calculate_car_loan_interest_deduction or get_tax_brackets_and_standard_deduction, since the tax item is 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?

The description implies usage ('Optionally compares itemizing with the standard deduction') and explains that other_itemized_deductions is only needed for that comparison, but it never says when to call this versus the sibling standard-deduction tool or what to do for years before 2025/tax years outside the modeled window. Usage is inferable, 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 (readOnly, idempotent, non-destructive, closed-world), and the description goes well beyond them: it names the legal provenance (One Big Beautiful Bill Act, Rev. Proc. 2025-32), documents a freshness check date against the Internal Revenue Bulletin and irs-drop, and states how unpublished years fail. That is exactly the trust and staleness context an agent needs for a tax-data lookup.

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?

Purpose is front-loaded in the first clause, which is good, but the body is a dense run-on that inlines eight dollar figures per year plus provenance and a check date. The dollar amounts are return values that the response itself would carry, so much of this length is not load-bearing for tool selection.

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 carries the return-value burden and does so: it enumerates brackets, standard deductions per filing status, the age-65/blind add-on, and the optional tax and marginal-rate result. Nothing an agent needs to call it correctly or interpret the result 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 tax_year bounds, the filing_status enum, and that filing_status is required for the income computation. The description reinforces the optional computation behavior but adds no new syntax or constraint detail beyond that baseline.

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

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

States a specific verb and resource: 'Returns the official 2025 and 2026 federal income tax brackets and standard deductions,' plus an optional computation mode. This is clearly distinguishable from the calculate_* siblings, which are single-deduction calculators rather than a bracket/deduction reference with tax computation.

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 implied by two described modes - fetch the bracket tables, or 'optionally computes the tax and marginal rate on a taxable income' when income is supplied. However, it never tells the agent when to prefer this tool over the calculate_* siblings, nor any exclusions beyond the 2027 'not yet published' case.

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