Loading ToolBench
MCP server for IRS Statistics of Income (SOI) data by ZIP code — income, AGI distribution, tax, credits, and deductions from filed returns.
Strong domain-specific tool set with clear naming (verb_noun pattern: lookup_zip, get_income, etc.) and comprehensive descriptions (avg 180 chars, well above 10-char minimum). All 13 tools have descriptions and input schemas with type definitions. However, output schemas are not explicitly documented in the visible code, only inferred from model classes. Parameter descriptions are present but minimal (avg 30 chars). No tool annotations (readOnlyHint/destructiveHint) despite clear risk classifications. Error handling guidance is absent from descriptions. One tool (refresh) is WRITE-capable but lacks confirmation/dry-run pattern.
List the SOI field codes available for direct lookup via ``get_soi_field``. Returns the SOI field codes (e.g. "A00100", "N1", "A06500") that are stored and can be queried. This is the curated subset of the ~150 source columns — the store holds income, tax, credits, deductions, and filing-status fields.
List the metric names accepted by ``compare_zips``. Returns the names of all metrics that can be used to rank ZIPs — e.g. ``total_returns``, ``adjusted_gross_income``, ``avg_agi_per_return``, ``pct_returns_200k_plus``, ``income_tax``, ``eitc_amount``, etc.
Rank several ZIPs by one metric (e.g. avg_agi_per_return, pct_returns_200k_plus, total_tax_liability). `zips`: a comma-separated list of 5-digit US ZIPs (e.g. "90210, 10001, 60601"). `metric`: the metric to rank by — one of the available metrics (see ``available_metrics`` for the full list). Returns the ZIPs sorted by that metric, highest value first; ZIPs with no SOI data are listed last.
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.
Output schemas not explicitly documented in tool definitions. Model classes (ZipInfo, Income, etc.) exist but are not referenced in tool descriptions or visible in the schema registration. LLMs cannot infer return structure without explicit documentation.
No tool annotations (readOnlyHint/destructiveHint/idempotentHint) despite clear risk classifications in metadata. The 'refresh' tool is marked WRITE but lacks destructiveHint annotation and confirmation pattern.
Parameter descriptions are minimal (avg 30 chars). 'zip_code' is described as 'a 5-digit US ZIP' but lacks format constraints (regex pattern, length validation). 'metric' in compare_zips lacks enum values or reference to available_metrics.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-23 | C | 64 | 2026-07-28+ | v2 |
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.
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 claims the deduction.
Filing status and e-filing counts for a ZIP. `zip_code`: a 5-digit US ZIP. Returns the count of single, married-filing- jointly, and head-of-household returns, plus elderly and electronically-filed counts and the e-filing percentage.
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.
The raw value of one SOI field code for a ZIP. `zip_code`: a 5-digit US ZIP. `field`: a SOI field code (e.g. "A00100" for AGI, "N1" for number of returns). Returns the aggregated value across all six AGI brackets for that ZIP and field. Amounts are in whole USD; counts are numbers of returns. This is an escape hatch for fields not directly exposed by the other tools — the store holds only the curated subset of the ~150 source columns.
State-level totals from the SOI 00000 rollup row. `state`: a 2-letter USPS state code (e.g. "CA") or a 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 AGI distribution across the six brackets. Amounts in USD.
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.
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.
Download and reload the SOI data for a given tax year (or the latest if not specified). `year` (optional): a tax year (e.g. 2022). If not given, the latest published SOI ZIP-code year is probed and loaded. The SOI release lags ~2–3 years, so the latest available year is typically 2–3 years in the past. Older years stay available for comparison — you can refresh to any year the IRS has published.
Error handling guidance absent from tool descriptions. No recovery hints (e.g., 'If ZIP not found, try lookup_zip first'). No categorization of errors as retryable vs. user-fixable.
The 'refresh' tool (WRITE operation) lacks dry-run or confirmation pattern. Agents could accidentally reload data without safeguards.