Tax Numbers

Estimate US federal income tax

estimate_federal_tax

Read-onlyIdempotent

Use this when the user wants a rough US federal income tax figure, for example "how much federal tax on $90,000 of wages", "estimate my tax with $40,000 of freelance income", "what is my marginal rate". Pass the tax year, filing_status (single, mfj, mfs, hoh) and wages in dollars, and optionally self_employment_income, other_ordinary_income, long_term_capital_gains and adjustments. It uses the standard deduction and adds self-employment tax (with the Social Security wage base and the half-deduction), the Additional Medicare Tax and long-term capital gains rates. Returns taxable income, ordinary tax, capital gains tax, self-employment tax, total, marginal and effective rate, the assumptions made and a not_included list (credits, state tax, alternative minimum tax, itemized deductions and more). It is an estimate, not tax advice, and it is not a return.

Input Schema

TableJSON Schema

Name	Required	Description
`year`	Yes	The tax year (the year the income was earned). Available: 2025, 2026.
`wages`	Yes	Taxable wages for the year in US dollars (W-2 box 1), for everyone on the return. 0 if none.
`adjustments`	No	Deductions taken from income before the standard deduction, such as IRA or HSA contributions, in US dollars. Optional.
`filing_status`	Yes	single, mfj (married filing jointly), mfs (married filing separately) or hoh (head of household).
`other_ordinary_income`	No	Other income taxed at ordinary rates in US dollars, such as interest or short-term gains. Optional.
`self_employment_income`	No	Net profit from self-employment in US dollars (after business expenses). Optional.
`long_term_capital_gains`	No	Long-term capital gains and qualified dividends in US dollars. Optional.

Output Schema

TableJSON Schema

Name	Required	Description
`year`	No
`total`	No
`se_tax`	No
`status`	Yes
`message`	No
`sources`	No
`disclaimer`	No
`assumptions`	No
`gross_income`	No
`not_included`	No
`ordinary_tax`	No
`filing_status`	No
`last_verified`	No
`marginal_rate`	No	Rate on the next dollar of ordinary income, as a fraction (0.22 is 22%).
`effective_rate`	No	total divided by gross_income, as a fraction.
`taxable_income`	No
`capital_gains_tax`	No
`standard_deduction`	No
`additional_medicare_tax`	No

Schema Changelog

Changes observed during successful MCP inspections.

First observedOct 3, 2026

TDQS

A4.6/5.0

Behavior5/5

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

Annotations already declare read-only, idempotent and non-destructive, but the description adds substantial model behavior: standard deduction use, self-employment tax with Social Security wage base and half-deduction, Additional Medicare Tax, LTCG rates, and an explicit not-included list and disclaimer. This is well beyond what structured fields convey.

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

Conciseness4/5

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

Front-loaded with the when-to-use trigger before parameter enumeration and return description, so the most decision-relevant content comes first. Dense and largely waste-free, though the single long paragraph is heavier than strictly needed.

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

Completeness5/5

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

For a 7-parameter estimation tool with annotations and an output schema, the description still supplies scope (federal only), what is and isn't modeled, and the estimate disclaimer. Nothing an agent needs to invoke or interpret it is missing.

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

Parameters4/5

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

Schema coverage is 100% so the baseline is 3, but the description adds interpretation: it explains that filing_status maps to four codes, that inputs are combined for everyone on the return, and how self-employment/capital-gains/adjustment inputs feed the calculation. That goes beyond the raw schema wording.

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

Purpose5/5

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

States a specific verb (estimate) and resource (US federal income tax) with concrete example queries, making it clearly distinct from siblings like get_tax_parameters or tax_deadlines. An agent can select it without inspecting the schema.

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

Usage Guidelines4/5

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

Gives explicit trigger conditions via user-phrasing examples ("how much federal tax on $90,000 of wages", "what is my marginal rate") and clarifies it is an estimate, not advice or a return. It does not name alternative tools or state when-not to use it, which keeps it 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.

All Tax Numbers tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?