irs-taxpayer-mcp

Overview Schema Related Servers Score Discussions

assess_audit_risk

Evaluate IRS audit risk by analyzing tax return factors like income, deductions, and red flags. Get a risk score and actionable tips to reduce audit exposure.

Instructions

Evaluate your IRS audit risk based on your tax return profile. Identifies red flags, scores your risk level, and provides tips to reduce audit exposure.

Input Schema

TableJSON Schema

Name	Required	Description
`filingStatus`	Yes
`grossIncome`	Yes	Total gross income
`selfEmploymentIncome`	No	Self-employment income
`cashBusiness`	No	Is your business cash-intensive (restaurant, salon, etc.)?
`homeOfficeDeduction`	No	Claiming home office deduction?
`charitableDonations`	No	Total charitable donations
`charitableNonCash`	No	Non-cash charitable donations (clothing, property)
`businessMeals`	No	Business meal deductions
`vehicleDeduction`	No	Vehicle/mileage deduction
`rentalLosses`	No	Rental property losses claimed
`cryptoTransactions`	No	Had cryptocurrency transactions?
`foreignAccounts`	No	Have foreign bank accounts or assets?
`largeRefund`	No	Expecting a very large refund?
`eitcClaimed`	No	Claiming EITC?
`roundNumbers`	No	Are most deductions round numbers ($5,000, $10,000)?

Implementation Reference

src/tools/comprehensive-tools.ts:721-864 (handler)

The main handler function for assess_audit_risk that evaluates IRS audit risk based on tax return profile. It analyzes various risk factors (income level, self-employment, cash business, home office, charitable donations, vehicle deductions, rental losses, crypto transactions, foreign accounts, EITC claims, etc.), calculates a risk score (0-100), determines risk level (LOW/MODERATE/HIGH), and generates a detailed report with red flags and tips to reduce audit exposure.

async (params) => {
  const flags: Array<{ item: string; severity: "🔴 High" | "🟡 Medium" | "🟢 Low"; detail: string }> = [];
  let riskScore = 0;

  // High income
  if (params.grossIncome > 500000) {
    flags.push({ item: "High Income", severity: "🟡 Medium", detail: "IRS audits ~1.1% of returns with income $500K-$1M, vs 0.4% overall" });
    riskScore += 15;
  }
  if (params.grossIncome > 1000000) {
    flags.push({ item: "Very High Income ($1M+)", severity: "🔴 High", detail: "IRS audits ~2-4% of returns with income over $1M" });
    riskScore += 25;
  }

  // Self-employment
  if (params.selfEmploymentIncome && params.selfEmploymentIncome > 0) {
    riskScore += 10;
    flags.push({ item: "Self-Employment Income", severity: "🟡 Medium", detail: "Schedule C filers are audited at higher rates. Keep detailed records" });

    if (params.cashBusiness) {
      riskScore += 20;
      flags.push({ item: "Cash-Intensive Business", severity: "🔴 High", detail: "Cash businesses are top audit targets. IRS uses statistical models to detect underreporting" });
    }

    // SE losses
    if (params.selfEmploymentIncome < 0) {
      riskScore += 15;
      flags.push({ item: "Business Losses", severity: "🟡 Medium", detail: "Repeated business losses may trigger hobby loss rules (IRC §183)" });
    }
  }

  // Home office
  if (params.homeOfficeDeduction) {
    riskScore += 8;
    flags.push({ item: "Home Office Deduction", severity: "🟢 Low", detail: "Less risky than reputation suggests, but must meet exclusive-use test. Consider simplified method ($5/sq ft)" });
  }

  // Charitable donations
  const charityRatio = params.grossIncome > 0 ? (params.charitableDonations ?? 0) / params.grossIncome : 0;
  if (charityRatio > 0.10) {
    riskScore += 10;
    flags.push({ item: "High Charitable Donations", severity: "🟡 Medium", detail: `Donations are ${(charityRatio * 100).toFixed(1)}% of income (IRS average is ~3-5%). Keep receipts for all donations over $250` });
  }
  if ((params.charitableNonCash ?? 0) > 5000) {
    riskScore += 12;
    flags.push({ item: "Large Non-Cash Donations", severity: "🟡 Medium", detail: "Non-cash donations over $5,000 require qualified appraisal (Form 8283). Over $500 requires Form 8283 Section A" });
  }

  // Vehicle
  if ((params.vehicleDeduction ?? 0) > 10000) {
    riskScore += 8;
    flags.push({ item: "Large Vehicle Deduction", severity: "🟢 Low", detail: "Keep a mileage log. IRS may question 100% business use. Mixed-use vehicles should prorate" });
  }

  // Rental losses
  if ((params.rentalLosses ?? 0) > 25000) {
    riskScore += 10;
    flags.push({ item: "Large Rental Losses", severity: "🟡 Medium", detail: "Passive loss rules limit deduction to $25K if AGI < $100K. Real estate professional exception requires 750+ hours" });
  }

  // Crypto
  if (params.cryptoTransactions) {
    riskScore += 8;
    flags.push({ item: "Cryptocurrency", severity: "🟡 Medium", detail: "IRS requires reporting all crypto transactions. Form 1040 asks directly about virtual currency. Exchanges report via 1099-DA" });
  }

  // Foreign accounts
  if (params.foreignAccounts) {
    riskScore += 15;
    flags.push({ item: "Foreign Accounts/Assets", severity: "🔴 High", detail: "Must file FBAR (FinCEN 114) if aggregate balance exceeds $10K. FATCA Form 8938 if assets exceed $50K. Penalties for non-filing are severe" });
  }

  // EITC
  if (params.eitcClaimed) {
    riskScore += 10;
    flags.push({ item: "EITC Claimed", severity: "🟡 Medium", detail: "EITC returns are audited at higher rates (~1.1%). IRS focuses on qualifying child and income verification" });
  }

  // Round numbers
  if (params.roundNumbers) {
    riskScore += 5;
    flags.push({ item: "Round Number Deductions", severity: "🟢 Low", detail: "Exact round numbers ($5,000, $10,000) look estimated rather than actual. Use precise amounts from receipts" });
  }

  // Large refund
  if (params.largeRefund) {
    riskScore += 5;
    flags.push({ item: "Large Refund", severity: "🟢 Low", detail: "Very large refunds may trigger additional review. Consider adjusting W-4 withholding" });
  }

  // Risk level
  let riskLevel: string;
  let riskEmoji: string;
  if (riskScore >= 50) { riskLevel = "HIGH"; riskEmoji = "🔴"; }
  else if (riskScore >= 25) { riskLevel = "MODERATE"; riskEmoji = "🟡"; }
  else { riskLevel = "LOW"; riskEmoji = "🟢"; }

  const lines = [
    `## 🔍 Audit Risk Assessment`,
    "",
    `**Risk Level**: ${riskEmoji} **${riskLevel}** (score: ${riskScore}/100)`,
    `**Income**: $${fmt(params.grossIncome)} | **Filing**: ${params.filingStatus.replace(/_/g, " ")}`,
    "",
  ];

  if (flags.length > 0) {
    lines.push(
      `### Red Flags Identified`,
      "",
      `| Severity | Item | Detail |`,
      `|----------|------|--------|`,
      ...flags.map((f) => `| ${f.severity} | ${f.item} | ${f.detail} |`),
      "",
    );
  } else {
    lines.push("✅ No significant audit red flags identified.", "");
  }

  lines.push(
    `### Tips to Reduce Audit Risk`,
    "",
    "- Keep receipts and documentation for ALL deductions",
    "- Use precise amounts, not round numbers",
    "- File electronically (paper returns have higher error rates)",
    "- Report ALL income (IRS receives copies of your W-2s and 1099s)",
    "- If self-employed, keep separate business bank account",
    "- Respond promptly to any IRS correspondence",
    "",
    `### IRS Audit Rates (2024 data)`,
    `| Income Range | Audit Rate |`,
    `|---|---|`,
    `| Under $25K (no EITC) | ~0.2% |`,
    `| $25K-$100K | ~0.3% |`,
    `| $100K-$500K | ~0.4% |`,
    `| $500K-$1M | ~1.1% |`,
    `| $1M-$5M | ~2.0% |`,
    `| $5M+ | ~4.0% |`,
    "",
    `> 📝 Overall audit rate is ~0.4%. Most audits are correspondence audits (by mail), not in-person.`,
    `> ⚠️ This is an informal risk assessment, not a guarantee of audit or non-audit.`,
  );

  return { content: [{ type: "text", text: lines.join("\n") }] };
}

src/tools/comprehensive-tools.ts:704-720 (schema)

Zod schema definition for the assess_audit_risk tool input parameters. Defines required fields (filingStatus, grossIncome) and optional boolean/number fields for various audit risk factors like selfEmploymentIncome, cashBusiness, homeOfficeDeduction, charitableDonations, businessMeals, vehicleDeduction, rentalLosses, cryptoTransactions, foreignAccounts, largeRefund, eitcClaimed, and roundNumbers.

{
  filingStatus: FilingStatusEnum,
  grossIncome: z.number().min(0).describe("Total gross income"),
  selfEmploymentIncome: z.number().min(0).optional().describe("Self-employment income"),
  cashBusiness: z.boolean().optional().describe("Is your business cash-intensive (restaurant, salon, etc.)?"),
  homeOfficeDeduction: z.boolean().optional().describe("Claiming home office deduction?"),
  charitableDonations: z.number().min(0).optional().describe("Total charitable donations"),
  charitableNonCash: z.number().min(0).optional().describe("Non-cash charitable donations (clothing, property)"),
  businessMeals: z.number().min(0).optional().describe("Business meal deductions"),
  vehicleDeduction: z.number().min(0).optional().describe("Vehicle/mileage deduction"),
  rentalLosses: z.number().min(0).optional().describe("Rental property losses claimed"),
  cryptoTransactions: z.boolean().optional().describe("Had cryptocurrency transactions?"),
  foreignAccounts: z.boolean().optional().describe("Have foreign bank accounts or assets?"),
  largeRefund: z.boolean().optional().describe("Expecting a very large refund?"),
  eitcClaimed: z.boolean().optional().describe("Claiming EITC?"),
  roundNumbers: z.boolean().optional().describe("Are most deductions round numbers ($5,000, $10,000)?"),
},

src/tools/comprehensive-tools.ts:700-865 (registration)

Complete MCP tool registration for assess_audit_risk using server.tool() method. Includes the tool name, description, input schema, and the async handler function. This is the 6th tool registered in the registerComprehensiveTools function.

server.tool(
  "assess_audit_risk",
  "Evaluate your IRS audit risk based on your tax return profile. " +
  "Identifies red flags, scores your risk level, and provides tips to reduce audit exposure.",
  {
    filingStatus: FilingStatusEnum,
    grossIncome: z.number().min(0).describe("Total gross income"),
    selfEmploymentIncome: z.number().min(0).optional().describe("Self-employment income"),
    cashBusiness: z.boolean().optional().describe("Is your business cash-intensive (restaurant, salon, etc.)?"),
    homeOfficeDeduction: z.boolean().optional().describe("Claiming home office deduction?"),
    charitableDonations: z.number().min(0).optional().describe("Total charitable donations"),
    charitableNonCash: z.number().min(0).optional().describe("Non-cash charitable donations (clothing, property)"),
    businessMeals: z.number().min(0).optional().describe("Business meal deductions"),
    vehicleDeduction: z.number().min(0).optional().describe("Vehicle/mileage deduction"),
    rentalLosses: z.number().min(0).optional().describe("Rental property losses claimed"),
    cryptoTransactions: z.boolean().optional().describe("Had cryptocurrency transactions?"),
    foreignAccounts: z.boolean().optional().describe("Have foreign bank accounts or assets?"),
    largeRefund: z.boolean().optional().describe("Expecting a very large refund?"),
    eitcClaimed: z.boolean().optional().describe("Claiming EITC?"),
    roundNumbers: z.boolean().optional().describe("Are most deductions round numbers ($5,000, $10,000)?"),
  },
  async (params) => {
    const flags: Array<{ item: string; severity: "🔴 High" | "🟡 Medium" | "🟢 Low"; detail: string }> = [];
    let riskScore = 0;

    // High income
    if (params.grossIncome > 500000) {
      flags.push({ item: "High Income", severity: "🟡 Medium", detail: "IRS audits ~1.1% of returns with income $500K-$1M, vs 0.4% overall" });
      riskScore += 15;
    }
    if (params.grossIncome > 1000000) {
      flags.push({ item: "Very High Income ($1M+)", severity: "🔴 High", detail: "IRS audits ~2-4% of returns with income over $1M" });
      riskScore += 25;
    }

    // Self-employment
    if (params.selfEmploymentIncome && params.selfEmploymentIncome > 0) {
      riskScore += 10;
      flags.push({ item: "Self-Employment Income", severity: "🟡 Medium", detail: "Schedule C filers are audited at higher rates. Keep detailed records" });

      if (params.cashBusiness) {
        riskScore += 20;
        flags.push({ item: "Cash-Intensive Business", severity: "🔴 High", detail: "Cash businesses are top audit targets. IRS uses statistical models to detect underreporting" });
      }

      // SE losses
      if (params.selfEmploymentIncome < 0) {
        riskScore += 15;
        flags.push({ item: "Business Losses", severity: "🟡 Medium", detail: "Repeated business losses may trigger hobby loss rules (IRC §183)" });
      }
    }

    // Home office
    if (params.homeOfficeDeduction) {
      riskScore += 8;
      flags.push({ item: "Home Office Deduction", severity: "🟢 Low", detail: "Less risky than reputation suggests, but must meet exclusive-use test. Consider simplified method ($5/sq ft)" });
    }

    // Charitable donations
    const charityRatio = params.grossIncome > 0 ? (params.charitableDonations ?? 0) / params.grossIncome : 0;
    if (charityRatio > 0.10) {
      riskScore += 10;
      flags.push({ item: "High Charitable Donations", severity: "🟡 Medium", detail: `Donations are ${(charityRatio * 100).toFixed(1)}% of income (IRS average is ~3-5%). Keep receipts for all donations over $250` });
    }
    if ((params.charitableNonCash ?? 0) > 5000) {
      riskScore += 12;
      flags.push({ item: "Large Non-Cash Donations", severity: "🟡 Medium", detail: "Non-cash donations over $5,000 require qualified appraisal (Form 8283). Over $500 requires Form 8283 Section A" });
    }

    // Vehicle
    if ((params.vehicleDeduction ?? 0) > 10000) {
      riskScore += 8;
      flags.push({ item: "Large Vehicle Deduction", severity: "🟢 Low", detail: "Keep a mileage log. IRS may question 100% business use. Mixed-use vehicles should prorate" });
    }

    // Rental losses
    if ((params.rentalLosses ?? 0) > 25000) {
      riskScore += 10;
      flags.push({ item: "Large Rental Losses", severity: "🟡 Medium", detail: "Passive loss rules limit deduction to $25K if AGI < $100K. Real estate professional exception requires 750+ hours" });
    }

    // Crypto
    if (params.cryptoTransactions) {
      riskScore += 8;
      flags.push({ item: "Cryptocurrency", severity: "🟡 Medium", detail: "IRS requires reporting all crypto transactions. Form 1040 asks directly about virtual currency. Exchanges report via 1099-DA" });
    }

    // Foreign accounts
    if (params.foreignAccounts) {
      riskScore += 15;
      flags.push({ item: "Foreign Accounts/Assets", severity: "🔴 High", detail: "Must file FBAR (FinCEN 114) if aggregate balance exceeds $10K. FATCA Form 8938 if assets exceed $50K. Penalties for non-filing are severe" });
    }

    // EITC
    if (params.eitcClaimed) {
      riskScore += 10;
      flags.push({ item: "EITC Claimed", severity: "🟡 Medium", detail: "EITC returns are audited at higher rates (~1.1%). IRS focuses on qualifying child and income verification" });
    }

    // Round numbers
    if (params.roundNumbers) {
      riskScore += 5;
      flags.push({ item: "Round Number Deductions", severity: "🟢 Low", detail: "Exact round numbers ($5,000, $10,000) look estimated rather than actual. Use precise amounts from receipts" });
    }

    // Large refund
    if (params.largeRefund) {
      riskScore += 5;
      flags.push({ item: "Large Refund", severity: "🟢 Low", detail: "Very large refunds may trigger additional review. Consider adjusting W-4 withholding" });
    }

    // Risk level
    let riskLevel: string;
    let riskEmoji: string;
    if (riskScore >= 50) { riskLevel = "HIGH"; riskEmoji = "🔴"; }
    else if (riskScore >= 25) { riskLevel = "MODERATE"; riskEmoji = "🟡"; }
    else { riskLevel = "LOW"; riskEmoji = "🟢"; }

    const lines = [
      `## 🔍 Audit Risk Assessment`,
      "",
      `**Risk Level**: ${riskEmoji} **${riskLevel}** (score: ${riskScore}/100)`,
      `**Income**: $${fmt(params.grossIncome)} | **Filing**: ${params.filingStatus.replace(/_/g, " ")}`,
      "",
    ];

    if (flags.length > 0) {
      lines.push(
        `### Red Flags Identified`,
        "",
        `| Severity | Item | Detail |`,
        `|----------|------|--------|`,
        ...flags.map((f) => `| ${f.severity} | ${f.item} | ${f.detail} |`),
        "",
      );
    } else {
      lines.push("✅ No significant audit red flags identified.", "");
    }

    lines.push(
      `### Tips to Reduce Audit Risk`,
      "",
      "- Keep receipts and documentation for ALL deductions",
      "- Use precise amounts, not round numbers",
      "- File electronically (paper returns have higher error rates)",
      "- Report ALL income (IRS receives copies of your W-2s and 1099s)",
      "- If self-employed, keep separate business bank account",
      "- Respond promptly to any IRS correspondence",
      "",
      `### IRS Audit Rates (2024 data)`,
      `| Income Range | Audit Rate |`,
      `|---|---|`,
      `| Under $25K (no EITC) | ~0.2% |`,
      `| $25K-$100K | ~0.3% |`,
      `| $100K-$500K | ~0.4% |`,
      `| $500K-$1M | ~1.1% |`,
      `| $1M-$5M | ~2.0% |`,
      `| $5M+ | ~4.0% |`,
      "",
      `> 📝 Overall audit rate is ~0.4%. Most audits are correspondence audits (by mail), not in-person.`,
      `> ⚠️ This is an informal risk assessment, not a guarantee of audit or non-audit.`,
    );

    return { content: [{ type: "text", text: lines.join("\n") }] };
  }
);

Tool Definition Quality

B3.3/5.0

Behavior2/5

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

With no annotations provided, the description carries full burden but provides only basic behavioral information. It mentions the tool evaluates, identifies red flags, scores risk, and provides tips, but doesn't disclose important behavioral traits like whether this is a read-only analysis (likely), whether it requires specific permissions, how the scoring works, what format the output takes, or any rate limits. The description doesn't contradict annotations (none exist), but it's insufficient for a mutation/analysis tool.

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?

The description is appropriately concise (two sentences) and front-loaded with the core purpose. Every sentence adds value: the first states what the tool does, the second elaborates on specific outputs. No wasted words, though it could potentially be structured to better highlight key behavioral aspects.

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

Completeness2/5

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

Given the complexity (15 parameters, no output schema, no annotations), the description is incomplete. It doesn't explain what the output looks like (risk score format, red flag details, tip structure), how comprehensive the analysis is, or any limitations. For a tool with this many inputs and no structured output documentation, the description should provide more context about what users can expect.

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

Parameters3/5

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

Schema description coverage is high (93%), so the baseline is 3. The description doesn't add any parameter-specific information beyond what's already in the schema descriptions. It mentions 'tax return profile' which aligns with the parameters, but provides no additional context about how specific parameters affect audit risk or which are most important.

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?

The description clearly states the tool's purpose with specific verbs ('evaluate', 'identifies', 'scores', 'provides') and resources ('IRS audit risk', 'tax return profile', 'red flags', 'risk level', 'tips'). It distinguishes from sibling tools by focusing specifically on audit risk assessment rather than general tax calculation, analysis, or planning functions.

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

Usage Guidelines3/5

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

The description implies usage context ('based on your tax return profile') but doesn't explicitly state when to use this tool versus alternatives. Among sibling tools, there's no direct audit risk alternative mentioned, but tools like 'run_tax_health_check' or 'simulate_tax_scenario' might overlap. No explicit exclusions or prerequisites are provided.

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

Install Server

Other Tools

Latest Blog Posts

Tool Definition Quality Score (TDQS)
By punkpeye on April 3, 2026.
mcp
The Hackers Who Tracked My Sleep Cycle
By punkpeye on March 26, 2026.
security
Open Source Has a Bot Problem
By punkpeye on March 19, 2026.
open source

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/dma9527/irs-taxpayer-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server