Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@soi-mcp What is the income distribution for ZIP 90210?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
IRS income & tax statistics by ZIP code, inside your agent. An MCP
server that lets an LLM pull the income distribution, tax, credits, and deductions of any U.S. ZIP
straight from the IRS Statistics of Income (SOI) — built on Anthropic's official
mcp Python SDK.
All tools are read-only and the data is public domain (a U.S. government work) — no API key required. The dataset is downloaded once into a local SQLite store and served offline.
Status: published —
uvx mcpwright-soi(PyPI) and listed in the official MCP Registry asio.github.mcpwright/soi-mcp. 10 tools, working today (see below). The IRS SOI ZIP release lags ~2–3 years; the latest available year (currently Tax Year 2022) loads by default, and older years are onerefresh <year>away. See the roadmap for what's next.
Tool | What it does |
| Confirm a ZIP has SOI data → state, number of returns, number of individuals, tax year. A good first call. |
| Adjusted gross income (AGI), average AGI per return, and income components: salaries/wages, taxable interest, ordinary dividends, business net income, net capital gain. |
| The distinctive one. The ZIP's returns and AGI split across the six IRS AGI brackets (<$25k, $25–50k, $50–75k, $75–100k, $100–200k, $200k+), with each bracket's share — the income shape of a ZIP, not just an average. |
| Income tax, income tax before credits, total tax liability (broader — includes self-employment tax, etc.), total tax payments, and average total tax per return. |
| EITC take-up (overall and split by number of qualifying children: none / one / two / three or more) and the additional (refundable) child tax credit. |
| Standard vs. itemized deductions (count and amount), the taxes-paid (SALT) deduction, and the percent of returns that itemized. |
| Single / married-filing-jointly / head-of-household return counts, elderly returns (age 65+), and the count and share of electronically filed returns. |
| Rank several ZIPs by one metric (e.g. |
| A whole state's totals and AGI-bracket mix (returns, individuals, AGI, average AGI per return, income tax, total tax liability), from the IRS state rollup. Accepts |
| Escape hatch: the raw value of one SOI field code (e.g. |
All dollar amounts are returned in whole USD (the source reports thousands). Counts are numbers of returns, rounded by the IRS to the nearest 10.
Related MCP server: ZipExplore MCP Server
Requires Python 3.12+. The zero-clone way to run it (the PyPI package is mcpwright-soi; the
command, server, and tools are all "soi"):
uvx mcpwright-soiThe first tool call downloads the latest SOI ZIP file (~200 MB) into a local SQLite store under your OS cache directory and serves everything offline thereafter. To pre-load (or to pick a specific tax year) without waiting for the first query:
uvx mcpwright-soi setup # download the latest available year
uvx mcpwright-soi refresh 2021 # re-pull a specific older year for comparisonclaude mcp add soi -- uvx mcpwright-soiAdd to claude_desktop_config.json:
{
"mcpServers": {
"soi": { "command": "uvx", "args": ["mcpwright-soi"] }
}
}It's a standard MCP server, so it works with any MCP-capable client — not just Claude. With the OpenAI Agents SDK:
from agents import Agent, Runner
from agents.mcp import MCPServerStdio
async def main():
async with MCPServerStdio(
name="soi",
params={"command": "uvx", "args": ["mcpwright-soi"]},
) as soi:
agent = Agent(
name="Analyst",
instructions="Use the SOI tools for IRS income and tax data by ZIP.",
mcp_servers=[soi],
)
result = await Runner.run(
agent, "What's the income distribution of ZIP 90210 vs 10001?"
)
print(result.final_output)They all launch a stdio MCP server the same way — point yours at:
{
"mcpServers": {
"soi": { "command": "uvx", "args": ["mcpwright-soi"] }
}
}Hosted chat connectors (e.g. ChatGPT connectors) expect a remote MCP server over Streamable HTTP;
mcpwright-soiruns locally over stdio.
Storage: the dataset lives in a SQLite file under your OS cache dir (override with the
SOI_MCP_STOREenv var). Delete it any time;setup/refreshrebuilds it.
A note on suppression: the IRS excludes ZIPs with fewer than 100 returns (folding them into a "99999" bucket) and suppresses line items with fewer than 20 returns. Summed ZIP totals can therefore slightly understate reality and won't exactly equal the state total. All figures are aggregates of filed returns, not a population census.
git clone https://github.com/mcpwright/soi-mcp && cd soi-mcp
uv sync
uv run pytest # tests (mocked download + seeded SQLite)
uv run ruff check src/ && uv run ruff format --check src/ # lint + format
uv run mypy # strict type checking
uv run mcp dev src/soi_mcp/server.py # poke the tools in the MCP Inspectorlookup_zip / get_income / get_agi_distribution — the income backbone
get_tax / get_credits / get_deductions / get_filing_status — the tax side
compare_zips — rank ZIPs by a metric
get_state_totals — state rollups from the IRS 00000 row
get_soi_field — raw-field escape hatch
setup / refresh [year] — download once, re-pull or pick an older tax year
Publish to PyPI (mcpwright-soi) + the official MCP Registry (io.github.mcpwright/soi-mcp)
Multi-year queries in one call (trend a ZIP across tax years)
soi-mcp runs entirely on your machine. It collects, stores, or transmits no personal data
— no accounts, no tracking, no telemetry. Its only outbound requests go to the U.S. IRS static
file host (www.irs.gov/pub/irs-soi) to download the public SOI ZIP-code CSV; no API key is
needed and nothing about your queries leaves your machine. The downloaded dataset is cached on
disk as a local SQLite file (under your OS cache dir, or SOI_MCP_STORE); delete it any time.
Full policy: https://mcpwright.com/privacy/
Questions, ideas, or "could it do X?" → Discussions
Bugs & concrete feature requests → Issues
Contributions welcome — and if you build something with it, I'd love to hear about it.
Part of mcpwright · built by Devender Gollapally
Rank several ZIPs by a single metric, highest value first.
`zips`: a list of 5-digit US ZIPs to compare. `metric`: one of
`total_returns`, `adjusted_gross_income`, `avg_agi_per_return`,
`pct_returns_200k_plus`, `total_income`, `salaries_and_wages`, `income_tax`,
`total_tax_liability`, `avg_total_tax_per_return`, `eitc_amount`. Returns each
ZIP's value, sorted descending; ZIPs with no SOI data are listed last. A 0
for a sparse metric (e.g. `eitc_amount`) may be IRS-suppressed, not a true
zero.
| Name | Required | Description | Default |
|---|---|---|---|
| zips | Yes | ||
| metric | Yes |
| Name | Required | Description |
|---|---|---|
| metric | Yes | The compared metric's name |
| results | Yes | One entry per requested ZIP, sorted by value descending; ZIPs with no data are listed last |
| tax_year | Yes | SOI tax year of the data |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint and openWorldHint, the description adds essential behavioral details: results sorted descending, ZIPs without SOI data listed last, and suppressed zeros potentially not representing true zeros. This significantly enhances transparency for the agent.
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 compact yet complete, front-loading the core action and then providing param semantics and behavior in a well-structured format. The metric list, while lengthy, is necessary 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 output schema exists, the description does not need to explain return values, but it still covers sorted order and missing-data handling. Both parameters are fully specified, making the tool's behavior complete for 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?
Despite zero schema description coverage, the description fully explains both parameters: `zips` as a list of 5-digit US ZIPs and `metric` with every possible enum value enumerated. This adds complete meaning beyond the bare 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 tool ranks several ZIPs by a single metric, specifically highest value first. It distinguishes itself from sibling tools by focusing on comparison across multiple ZIPs rather than single-lookup getters.
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 conveys when to use this tool (comparing several ZIPs on one metric) and implies the scope of input. It does not explicitly state alternatives or when-not-to-use, but the context of siblings and the unique compare functionality provides clear usage context without exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The income distribution of a ZIP across the six IRS AGI brackets.
`zip_code`: a 5-digit US ZIP. Returns, for each bracket (<$25k, $25-50k,
$50-75k, $75-100k, $100-200k, $200k+), the number of returns and total AGI
plus each bracket's share of the ZIP's returns and AGI. This is the income
*shape* of a ZIP — what a single median can't show.
Note: a bracket showing 0 may be IRS-suppressed (<20 returns in that cell)
rather than truly empty, so the other brackets' shares can be slightly
overstated.
| Name | Required | Description | Default |
|---|---|---|---|
| zip_code | Yes |
| Name | Required | Description |
|---|---|---|
| state | No | 2-letter USPS state code |
| zipcode | Yes | 5-digit ZIP code |
| brackets | Yes | One entry per AGI bracket, ordered 1 (lowest) to 6 (highest) |
| tax_year | Yes | SOI tax year of the data |
| total_agi | No | Total AGI across all brackets (USD) |
| total_returns | No | Total returns across all brackets |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (readOnlyHint=true, openWorldHint=true), the description discloses a critical behavioral nuance: 'a bracket showing 0 may be IRS-suppressed (<20 returns in that cell) rather than truly empty', and that this can cause other brackets' shares to be 'slightly overstated'. It also clearly enumerates what is returned (number of returns, total AGI, and share) which goes beyond the annotation hints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with a clear purpose statement, then compactly details return contents and the suppression caveat in a separate paragraph. Every sentence adds value, and the note is placed at the end to avoid obscuring the main behavior. No fluff or repetition.
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 exists, the description doesn't need to spell out every return field, but it does anyway by naming the six brackets and listing the metrics returned. It also covers edge behavior (IRS suppression) and the impact on other shares. This makes the tool fully understandable in context, with no major gaps.
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 0%, the description compensates by explaining `zip_code` as 'a 5-digit US ZIP'. This is minimally sufficient for a single-parameter tool. It doesn't clarify whether a numeric string with leading zeros is expected, but the 5-digit US ZIP description covers the core semantic need.
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 'Returns the income distribution of a ZIP across the six IRS AGI brackets', naming a specific resource (ZIP income distribution) and the six bracket breakdown. It distinguishes itself from sibling tools by emphasizing 'the income *shape* of a ZIP — what a single median can't show', which contrasts with likely aggregate income tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context on when to use the tool: when the full distribution shape is needed rather than a single median. It doesn't explicitly name alternative tools for other use cases, but the phrase 'what a single median can't show' implies a comparison and sets expectations. The IRS suppression note also helps the user interpret results correctly, which is part of guiding appropriate use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Refundable-credit take-up for a ZIP: the EITC and additional child tax credit.
`zip_code`: a 5-digit US ZIP. Returns the number of returns and total amount
for the Earned Income Tax Credit (overall and split by number of qualifying
children: none / one / two / three or more), plus the additional (refundable)
child tax credit. Amounts in USD.
Note: a 0 may be IRS-suppressed (<20 returns in each AGI-bracket cell)
rather than a true zero — it does not prove no one claims the credit.
| Name | Required | Description | Default |
|---|---|---|---|
| zip_code | Yes |
| Name | Required | Description |
|---|---|---|
| state | No | 2-letter USPS state code |
| zipcode | Yes | 5-digit ZIP code |
| tax_year | Yes | SOI tax year of the data |
| eitc_amount | No | Total EITC amount (USD) |
| eitc_returns | No | Number of returns claiming the EITC |
| eitc_by_children | Yes | EITC returns and amount split by number of qualifying children |
| additional_ctc_amount | No | Additional (refundable) child tax credit amount (USD) |
| additional_ctc_returns | No | Number of returns with the additional (refundable) child tax credit |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and openWorldHint, so the safety profile is covered. The description adds valuable behavioral context beyond annotations, notably the IRS-suppression caveat where a zero may not be a true zero, plus the output components and USD units. This significantly helps interpretation.
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 tightly structured: purpose sentence, parameter and return detail, then an essential caveat. Every sentence earns its place, and the most critical information is front-loaded. 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 an output schema present, detailed return structure is covered externally. The description provides the purpose, the one parameter's format, the breakdown logic, and a crucial data-quality caveat, making it complete for an agent to select and invoke the 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 coverage is 0%, but the description compensates by explicitly defining `zip_code` as a '5-digit US ZIP', adding format and meaning beyond the schema's bare string type. With only one required parameter, this fully covers the parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Refundable-credit take-up for a ZIP' and explicitly names the EITC and additional child tax credit, clearly distinguishing this from sibling tools focused on income, AGI, deductions, or filing status. It uses a specific verb and resource, making the tool's purpose immediately identifiable.
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 use when ZIP-level refundable credit data is needed, and enumerates the exact breakdowns returned (e.g., by number of qualifying children). It does not explicitly name alternative tools or state when not to use it, so it stops short of full exclusion guidance, but the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Deduction measures for a ZIP: standard vs. itemized, plus SALT.
`zip_code`: a 5-digit US ZIP. Returns the count and amount of standard
deductions and itemized deductions, the taxes-paid (SALT) deduction, and the
percent of returns that itemized. Amounts in USD.
Note: a 0 may be IRS-suppressed (<20 returns in each AGI-bracket cell)
rather than a true zero — it does not prove no one in the ZIP itemizes.
| Name | Required | Description | Default |
|---|---|---|---|
| zip_code | Yes |
| Name | Required | Description |
|---|---|---|
| state | No | 2-letter USPS state code |
| returns | No | Number of returns |
| zipcode | Yes | 5-digit ZIP code |
| tax_year | Yes | SOI tax year of the data |
| salt_amount | No | Taxes-paid (SALT) deduction amount |
| salt_returns | No | Number of returns with the taxes-paid (SALT) deduction |
| itemizing_pct | No | Percent of returns that itemized rather than took the standard deduction (0-100) |
| itemized_amount | No | Total itemized deductions amount |
| itemized_returns | No | Number of returns with itemized deductions |
| standard_deduction_amount | No | Standard deduction amount |
| standard_deduction_returns | No | Number of returns claiming the standard deduction |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds important behavioral context beyond the annotations: it explains that a 0 may be IRS-suppressed rather than a true zero, which is a critical interpretation caveat. It also states the return includes counts, amounts, and percentages. Since annotations already convey read-only and open-world semantics, this additional note about data suppression provides meaningful insight, though it does not cover all possible edge cases.
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 concise and front-loaded, starting with a clear purpose statement, then a focused parameter explanation, then return details, and finally a brief caveat. Every sentence earns its place with no unnecessary filler. It is well-structured and easy to scan.
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, the description does not need to enumerate every return field, but it still summarizes the key outputs (counts, amounts, SALT, percent itemized). It explains the zip_code parameter and provides the crucial IRS-suppression caveat. With the annotations indicating read-only and open-world behavior, this description is complete for making a correct tool 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?
The input schema only defines zip_code as a string with no description (0% schema coverage). The description compensates by specifying 'a 5-digit US ZIP' and explaining what the parameter is used for (returns deduction measures for that ZIP). This adds the necessary format and semantic meaning beyond the schema, but could go further with examples or valid values.
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 'Deduction measures for a ZIP: standard vs. itemized, plus SALT,' which clearly identifies the resource (deductions) and scope (ZIP). The tool name 'get_deductions' supplies the verb, and the distinction from sibling tools like get_income or get_tax is implicit. However, the description lacks an explicit verb phrase, so it falls just 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 provides no guidance on when to use this tool versus the sibling tools. It does not mention alternative tools like get_tax or compare_zips, nor does it state any exclusions or prerequisites. The only implied context is that it is for ZIP-level deduction measures, but the description does not explicitly help the agent decide between this and related tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Filing-status mix for a ZIP: single / married-joint / head-of-household.
`zip_code`: a 5-digit US ZIP. Returns the number of single, married-filing-
jointly, and head-of-household returns, the number of elderly returns (age
65+), and the count and share of electronically filed returns.
Note: a 0 count may be IRS-suppressed (<20 returns in each AGI-bracket
cell) rather than truly absent.
| Name | Required | Description | Default |
|---|---|---|---|
| zip_code | Yes |
| Name | Required | Description |
|---|---|---|
| state | No | 2-letter USPS state code |
| zipcode | Yes | 5-digit ZIP code |
| tax_year | Yes | SOI tax year of the data |
| total_returns | No | Total number of returns |
| single_returns | No | Single returns |
| elderly_returns | No | Returns with the taxpayer aged 65 or older |
| married_joint_returns | No | Married-filing-jointly returns |
| electronically_filed_pct | No | Percent of returns filed electronically (0-100) |
| head_of_household_returns | No | Head-of-household returns |
| electronically_filed_returns | No | Electronically filed returns |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond readOnlyHint, the description discloses IRS suppression behavior for 0 counts, a critical nuance not captured in annotations. It also defines 'elderly returns' as age 65+, adding valuable specificity.
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 efficient, covering purpose, parameters, and a caveat in three concise sentences with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a low-complexity tool with an existing output schema, the description completely covers the input format, return metrics, and an important data-quality note. No critical information 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 only provides type/name, but the description explains that zip_code must be a 5-digit US ZIP. This is essential for correct invocation and adds 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 clearly states the tool returns filing-status mix (single, married-joint, head-of-household) for a ZIP, using the specific verb 'get'. It distinguishes from siblings like get_income or get_agi_distribution by focusing on filing status.
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 ZIP-specific scope is obvious from the description, making the intended use clear. However, it does not explicitly mention when not to use this tool or reference alternatives, 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.
Income measures for a ZIP: AGI, average AGI per return, and components.
`zip_code`: a 5-digit US ZIP. Returns total adjusted gross income (AGI),
average AGI per return, and the main income components — salaries and wages,
taxable interest, ordinary dividends, business net income, and net capital
gain. All dollar amounts in USD.
Note: figures cover filed tax returns only. Average AGI is a *mean per
return*, not a median per household, and AGI omits most nontaxable income —
so it is not directly comparable to Census median household income.
| Name | Required | Description | Default |
|---|---|---|---|
| zip_code | Yes |
| Name | Required | Description |
|---|---|---|
| state | No | 2-letter USPS state code |
| returns | No | Number of returns |
| zipcode | Yes | 5-digit ZIP code |
| tax_year | Yes | SOI tax year of the data |
| total_income | No | Total income amount |
| net_capital_gain | No | Net capital gain (less loss) amount |
| taxable_interest | No | Taxable interest amount |
| avg_agi_per_return | No | AGI divided by the number of returns |
| ordinary_dividends | No | Ordinary dividends amount |
| salaries_and_wages | No | Salaries and wages amount |
| business_net_income | No | Business or professional net income (less loss) amount |
| adjusted_gross_income | No | Total adjusted gross income (AGI) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds significant behavioral context beyond the readOnly/openWorld annotations: it explains data covers filed tax returns only, average AGI is a mean not median, and AGI omits nontaxable income. These caveats help the agent avoid misinterpretation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a summary line, a detailed list of returned components, and a crucial note. Each sentence adds value, and the most important information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With annotations declaring read-only/open-world and an output schema available, the description covers all essential behavioral and interpretive context. It provides ample detail for a single-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?
The schema only provides a title 'Zip Code', but the description details that `zip_code` is a 5-digit US ZIP and explains how it is used. This high-value guidance compensates for the schema's lack of description.
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 returns income measures for a ZIP, listing specific components (AGI, average AGI, and income components). It distinguishes itself from siblings by focusing on ZIP-level income aggregates with a specific set of metrics.
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?
Clear context is provided for when to use the tool: when ZIP-level income figures are needed. The note about not being comparable to Census median household income acts as an implicit exclusion, though no explicit alternatives are named.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Raw value of a single SOI field for a ZIP — an escape hatch.
`zip_code`: a 5-digit US ZIP. `field`: a SOI field code (e.g. `A00100` for
AGI, `N1` for number of returns); case-insensitive. Returns that field summed
across the ZIP's AGI brackets, with its label and unit (USD for amount fields,
count for return counts). Limited to the fields held in the local store (the
same ones the other tools draw on); an unknown field errors with the list.
Note: a 0 may be IRS-suppressed (<20 returns in a cell) rather than a true
zero, and a sum over suppressed cells slightly understates the real total.
| Name | Required | Description | Default |
|---|---|---|---|
| field | Yes | ||
| zip_code | Yes |
| Name | Required | Description |
|---|---|---|
| unit | Yes | 'USD' for amount fields, 'count' for return counts |
| field | Yes | SOI field code, e.g. 'A00100' or 'N1' |
| label | Yes | Human-readable description of the field |
| state | No | 2-letter USPS state code |
| value | No | The field's value for this ZIP (summed over brackets) |
| zipcode | Yes | 5-digit ZIP code |
| tax_year | Yes | SOI tax year of the data |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint=true annotation, the description discloses return semantics (summed across AGI brackets, includes label and unit), case-insensitivity, error behavior for unknown fields, and the IRS-suppression caveat. This is rich context that heavily informs the agent about outputs and edge cases, far exceeding the annotation baseline.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: a one-sentence purpose lead, followed by parameter details and a caution note. Every sentence carries necessary information, though slightly verbose with the inclusion of examples and caveats. It remains appropriately sized for the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the tool's scope, parameters, return value semantics, error behavior, and data caveats. Since an output schema exists, it doesn't need to detail the response shape further. For a 2-parameter read-only tool, this is fully complete.
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 0%, so the description fully compensates by defining both parameters: zip_code as '5-digit US ZIP' and field as a 'SOI field code' with examples (A00100, N1) and case-insensitivity. This gives complete practical meaning to the schema's bare property names.
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 function: 'Raw value of a single SOI field for a ZIP — an escape hatch.' This specifies a distinct resource (single SOI field) and verb (get raw value), and differentiates it from siblings by emphasizing it's a raw/escape-hatch access to underlying data rather than a standardized aggregate tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context via 'escape hatch' and notes the tool is 'Limited to the fields held in the local store (the same ones the other tools draw on).' This gives clear sense of when to use it (raw field access, when other tools don't expose it) but does not explicitly name alternatives or state when not to use it, leaving some implicit guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
State-level SOI totals and AGI distribution from the IRS state rollup.
`state`: a 2-letter USPS code (e.g. 'CA') or full state name (e.g.
'California'). Returns the state's total returns, individuals, AGI, average
AGI per return, income tax, total tax liability, and the income distribution
across the six AGI brackets. Drawn from the IRS 00000 state-total row.
| Name | Required | Description | Default |
|---|---|---|---|
| state | Yes |
| Name | Required | Description |
|---|---|---|
| state | Yes | 2-letter USPS state code |
| returns | No | Total returns in the state |
| brackets | Yes | The state's income distribution across the six AGI brackets |
| tax_year | Yes | SOI tax year of the data |
| income_tax | No | Total income tax amount |
| individuals | No | Total individuals (filers plus dependents) |
| avg_agi_per_return | No | AGI divided by the number of returns |
| total_tax_liability | No | Total tax liability amount |
| adjusted_gross_income | No | Total adjusted gross income (AGI) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is established. The description adds transparency by specifying the data source ('IRS 00000 state-total row') and listing the exact fields returned, which enriches the behavioral context 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 efficiently structured: the first sentence states the purpose, the second details the parameter, and the third lists the returned fields. Every sentence contributes useful information without unnecessary verbosity.
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 single well-documented parameter and an output schema present, the description is nearly complete for a simple retrieval tool. It covers source, returned fields, and parameter format, leaving only minor gaps like error handling, but these are not critical given the output schema and annotation 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 input schema only defines the 'state' parameter with no description (0% schema coverage). The description fully compensates by explaining accepted formats (2-letter USPS code or full state name) with examples, providing essential 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 clearly states the tool's purpose: to retrieve state-level SOI totals and AGI distribution from the IRS state rollup. It names the specific resource and differentiates from siblings by focusing on state-level aggregates rather than zip-level or single-metric 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 implies the tool is for state-level aggregate data but does not explicitly state when to use it over alternatives. No exclusions or alternative tool names are mentioned, so usage guidance is implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tax measures for a ZIP: income tax, total liability, and average per return.
`zip_code`: a 5-digit US ZIP. Returns income tax, income tax before credits,
total tax liability (broader — includes self-employment tax and other taxes),
total tax payments, and the average total tax per return. Amounts in USD.
| Name | Required | Description | Default |
|---|---|---|---|
| zip_code | Yes |
| Name | Required | Description |
|---|---|---|
| state | No | 2-letter USPS state code |
| returns | No | Number of returns |
| zipcode | Yes | 5-digit ZIP code |
| tax_year | Yes | SOI tax year of the data |
| income_tax | No | Income tax amount (after credits, before other taxes) |
| total_tax_payments | No | Total tax payments amount |
| total_tax_liability | No | Total tax liability (broader than income tax: includes self-employment tax, recapture, etc.) |
| avg_total_tax_per_return | No | Total tax liability divided by the number of returns |
| income_tax_before_credits | No | Income tax before credits amount |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and openWorldHint, covering safety. The description adds valuable behavioral context: it explains what the broader total liability includes (self-employment tax, other taxes), specifies that amounts are in USD, and clarifies the ZIP format. This goes beyond the schema, though it could mention edge cases (e.g., invalid ZIPs), hence a 4.
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: first a high-level summary, then parameter detail and return list. Every sentence contributes information without fluff. It is front-loaded with the main purpose and structured logically.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has an output schema, but the description still explains the returned fields, which is helpful. All relevant context—purpose, parameter, return metrics, currency—is provided. The description is complete for a simple query tool, with no missing operational details expected for 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?
The schema only provides the parameter name 'Zip Code' with 0% description coverage. The tool description fully compensates by specifying the exact format ('5-digit US ZIP') and its purpose in the query. This adds meaning beyond the raw schema, making the parameter semantics clear.
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 retrieves tax measures for a given ZIP code, enumerating specific metrics (income tax, total liability, average per return). It distinguishes from sibling tools like get_income or get_credits by focusing on aggregate tax measures and explicitly noting the broader total tax liability including self-employment 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 context is clear: use this tool when you need tax data for a 5-digit US ZIP code, with a list of returned metrics. It implies when to use this over more specific tools like get_income (which likely focuses on income tax only), but does not explicitly name alternatives or exclusions, so it stops 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.
Confirm a ZIP has SOI data and return its return and individual counts.
`zip_code`: a 5-digit US ZIP. A good first call to validate a ZIP before
asking for more detail. Returns the state, number of returns, number of
individuals, and the SOI tax year. ZIPs with <100 returns are excluded.
| Name | Required | Description | Default |
|---|---|---|---|
| zip_code | Yes |
| Name | Required | Description |
|---|---|---|
| state | No | 2-letter USPS state code |
| returns | No | Total number of tax returns filed from this ZIP |
| zipcode | Yes | 5-digit ZIP code |
| tax_year | Yes | SOI tax year of the data |
| individuals | No | Total number of individuals (filers plus dependents) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only and open-world hints. The description adds valuable behavioral details: the exclusion of ZIPs with fewer than 100 returns and the specific data returned (state, counts, tax year). It does not contradict annotations and enhances understanding beyond 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 concise and front-loaded with the core purpose. Every sentence adds value: the ZIP format, the use case, and the exclusion rule. No redundancy or irrelevant 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 simple single-parameter lookup with an output schema, the description covers the essential context: what it does, when to use it, and key constraints. It does not describe the not-found behavior, but the output schema likely handles that, and the annotations cover safety.
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 0% schema description coverage, the description compensates by defining 'zip_code' as a 5-digit US ZIP and noting the exclusion threshold. It adds practical meaning beyond the schema's basic property definition, though it could specify validation rules more explicitly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: to confirm a ZIP has SOI data and return counts. It uses specific verbs and identifies the resource (ZIP), and distinguishes itself from siblings by positioning as a validation first call.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly recommends this as a 'good first call' before requesting more detail, giving clear usage context. It does not name alternative tools or provide when-not-to-use scenarios, but the context is sufficient for a simple lookup tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v0.1.1compare_zipsget_agi_distributionget_creditsget_deductionsget_filing_statusget_incomeget_soi_fieldget_state_totalsget_taxlookup_zipEach tool targets a distinct facet of SOI data: validation, income, distribution, tax, credits, deductions, filing status, comparison, state aggregates, and raw field access. No two tools overlap in purpose, making selection unambiguous.
All tool names follow a clear verb_noun pattern with lowercase and underscores: lookup_zip, get_income, get_agi_distribution, compare_zips, etc. The variation in verbs (lookup, get, compare) is natural and consistent with each tool's action.
With 10 tools, the set is well-scoped for a domain-specific SOI server. Each tool covers a major data category, and the count fits comfortably within the ideal 3-15 range without redundancy or bloat.
The surface covers the full range of SOI data categories: counts, income, tax, credits, deductions, filing status, comparison, state-level totals, and a raw field escape hatch. There are no obvious dead ends or missing lifecycle operations for the stated purpose.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
US ZIP code intelligence: demographics, weather, tax, crime, housing, voting, and more.
Verifiable US tax oracle for AI agents: cited, machine-checkable federal and state tax computation
Current source-cited 2026 US tax constants and calculators for AI agents; every answer cites IRS.
SEC filings and financial data for AI agents: 55 tools for financials, valuation and supply chains.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/mcpwright/soi-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
