Skip to main content
Glama
README.md
# itr-agent

[![npm](https://img.shields.io/npm/v/itr-agent?label=npm)](https://www.npmjs.com/package/itr-agent)
[![CI](https://github.com/Sagargupta16/itr-agent/actions/workflows/ci.yml/badge.svg)](https://github.com/Sagargupta16/itr-agent/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![MCP](https://img.shields.io/badge/MCP-stdio-blueviolet)](https://modelcontextprotocol.io)

Local-first ITR filing agent for Indian income tax. Claude interviews you one question at a time, picks your ITR form, computes your tax deterministically on your machine, reconciles your documents, and walks you to the portal's submit button -- no accounts, no uploads, no cloud.

Works with Claude Desktop, Claude Code, and any MCP client. Formerly published as [`itr-mcp`](https://www.npmjs.com/package/itr-mcp).

```
You:    Help me file my ITR.
Claude: [file_my_itr] One question at a time. First: were you a resident of India
        for all of FY 2025-26?
You:    Yes, salaried, and I have vested US RSUs from my employer.
Claude: [recommend_itr_form] Foreign assets (Schedule FA) rule out ITR-1: you file
        ITR-2, due 2026-07-31. Next: how many employers this year?
```

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="docs/demo-dark.svg">
  <source media="(prefers-color-scheme: light)" srcset="docs/demo-light.svg">
  <img width="600" src="docs/demo-dark.svg" alt="Terminal animation of five tool calls against the built server. recommend_itr_form with foreign assets: ITR-2, due 2026-07-31, ITR-1 ruled out because foreign assets need Schedule FA. compare_regimes on 18L salary with 3.75L deductions: new Rs 1,50,800 vs old Rs 2,34,000, new saves Rs 83,200. compute_tax on 12.75L salary: Rs 0 after a Rs 60,000 rebate. The same salary plus 1.25L LTCG: Rs 62,400, because total income of Rs 13,25,000 loses the 87A rebate. schedule_advance_tax on 2.4L tax with 1.8L TDS: Jun Rs 9,000, Sep Rs 18,000, Dec Rs 18,000, Mar Rs 15,000.">
</picture>

Those are the calls Claude makes during the interview, sent to the built server by [`scripts/demo.mjs`](scripts/demo.mjs). Every figure in the animation is one that run printed.

## Why

Every Indian tax tool wants your data on their servers. itr-agent flips it: your documents stay local, the LLM never does arithmetic, and every number comes from a versioned rule pack you can audit. The agent layer drives the interview; the deterministic engine does the math.

**What it will never do:** submit the return for you. India has no public filing API -- returns are filed by you on [incometax.gov.in](https://www.incometax.gov.in) (or by an authorized ERI/CA). The agent takes you to that button with every number verified; you press it.

## The agent

`file_my_itr` (MCP prompt) runs the guided interview:

1. Residency, age band -- one question at a time
2. Income heads: salary, house property, capital gains, business/F&O, other sources
3. Disqualifier sweep: foreign RSUs/ESPP, director role, unlisted shares, ESOP deferral
4. Losses, current and brought-forward (they change the form)
5. `recommend_itr_form` -> the form, with rule-by-rule reasoning
6. `compare_regimes` -> the regime, with real numbers
7. `parse_ais` / `parse_form26as` / `reconcile_documents` -> fix mismatches BEFORE filing
8. `schedule_advance_tax` / `compute_interest_234` if applicable
9. `filing_checklist` -> schedule-by-schedule portal walkthrough, ending at e-verification

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="docs/diagrams/filing-flow-dark.svg">
  <source media="(prefers-color-scheme: light)" srcset="docs/diagrams/filing-flow-light.svg">
  <img width="880" src="docs/diagrams/filing-flow-light.svg" alt="The guided filing interview as a numbered flow. Step 1: you answer Claude one question at a time on residency, income and losses. Claude then calls the itr-agent tools in order: step 2 recommend_itr_form returns the form and deadline, step 3 compare_regimes returns the regime and savings, step 4 parse_form26as and parse_ais return your TDS rows, step 5 reconcile_documents returns the mismatches, step 6 schedule_advance_tax and compute_interest_234 return the installments, step 7 filing_checklist returns the portal walkthrough. Step 8, drawn dashed because it happens outside the tool: you e-verify and press submit on incometax.gov.in.">
</picture>

## Tools (v0.5)

| Tool | What it does |
| --- | --- |
| `recommend_itr_form` | ITR-1/2/3/4 selection with rule-by-rule reasoning and loss-continuity awareness: brought-forward business losses force ITR-3 even with zero current-year business income (Schedule CFL). Knows the AY 2026-27 two-house-property allowance, the s.194N bar, and the 44AD/44ADA turnover ceilings (when you pass the turnover). Returns each deadline with its statutory citation |
| `filing_checklist` | Ordered, form-specific walkthrough: documents, reconciliation, computation, portal steps schedule by schedule, e-verification |
| `compute_tax` | Full FY 2025-26 (AY 2026-27) computation: new/old regime slabs (incl. the senior and super-senior slab sets), standard deduction, employer NPS under 80CCD(2) in both regimes, house-property loss set-off (s.71(3A) cap; none under 115BAC), 87A rebate (new regime: Rs 60,000 where TOTAL income is up to Rs 12L with marginal relief, never offsetting 111A/112A tax; old regime: Rs 12,500 on total income up to Rs 5L, no marginal relief, offsets 111A), 111A (20%) / 112A (12.5% above 1.25L) capital gains with the unexhausted-basic-exemption set-off, surcharge with the 15% gains cap and its own marginal relief, 4% cess, s.288A/288B rounding |
| `compare_regimes` | Old vs new side by side, recommended regime, savings amount |
| `schedule_advance_tax` | Jun/Sep/Dec/Mar installment plan (15/45/75/100%) with shortfall tracking |
| `compute_interest_234` | Sections 234A/234B/234C interest with the statutory 12%/36% safe harbors, the s.234B(2) self-assessment payment ladder, and Rule 119A rounding (principal floored to Rs 100, part month = full month). Reports which sections it skipped and why |
| `compute_hra` | HRA exemption per Rule 2A, period-wise (least of three limbs; FY 2025-26 metros: Delhi/Mumbai/Kolkata/Chennai) + the 80GG alternative, with its Rs 5,000-per-month cap and the bars under the new regime and alongside HRA |
| `list_deductions` | Old-regime deduction checklist with statutory caps (80C, 80CCD(1B), 80D tiers, HRA metros) |
| `parse_form26as` | Parse the caret-delimited Form 26AS Text export from TRACES into structured TDS entries with booking status (only F is creditable; the tool reports `creditableTdsDeposited` beside the raw total), and TCS rows separated into `tcsEntries` |
| `parse_ais` | Decrypt + parse the AIS JSON export on-device (AES-256-CBC/PBKDF2 with the password derived from PAN + DOB); normalized rows with label-matched amounts/dates/codes |
| `reconcile_documents` | Form 16 vs AIS vs 26AS mismatch report -- the checks that pre-empt 143(1)(a) intimations and 139(9) defect notices (TDS over-claim against the creditable 26AS total, non-final booking status, missing employer, undeclared AIS interest/dividend) |
| `list_tax_years` | Supported fiscal years + AY 2026-27 filing deadlines with their statutory citations |

All tools are read-only (`readOnlyHint: true`), take zod-validated inputs, and return `structuredContent` alongside the human-readable text.

## Install

**What `npx` installs today.** The npm badge at the top is live. While it reads 0.3.0, `npx -y itr-agent` installs the July 2026 engine without the 0.4.0 and 0.5.0 fixes (senior slab sets, surcharge marginal relief, s.87A on total income, 26AS booking status). No publish has reached npm since then: every `npm publish` from `publish.yml` has been refused by npmjs.com, most recently for v0.5.3 on 2026-10-20. Until the badge reads 0.5.x, use the `.mcpb` from the [v0.5.3 release](https://github.com/Sagargupta16/itr-agent/releases/tag/v0.5.3) (one click, below) or install from source.

### Claude Code

```bash
claude mcp add itr-agent -- npx -y itr-agent
```

### Claude Desktop

Add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "itr-agent": {
      "command": "npx",
      "args": ["-y", "itr-agent"]
    }
  }
}
```

### Claude Desktop, one click

From the v0.5.3 release on, every [GitHub release](https://github.com/Sagargupta16/itr-agent/releases) carries `itr-agent-<version>.mcpb` and its `.sha256`. The bundle inlines the server and its dependencies into one file, so there is no npm or `npx` step: double-click it, or use Settings > Extensions > Install Extension in Claude Desktop. It needs Node 22 or later, like the npm package. `pnpm bundle` builds the same file locally into `build/`.

### From source

```bash
git clone https://github.com/Sagargupta16/itr-agent
cd itr-agent
pnpm install
pnpm build
node dist/index.js   # stdio server
```

### Migrating from itr-mcp

Same server, new name. Replace `itr-mcp` with `itr-agent` in your MCP config; the `itr-mcp` npm package is deprecated and frozen at v0.2.0.

## Example prompts

- "Help me file my ITR." (starts the guided interview)
- "I'm salaried with US RSUs and 2L of equity LTCG -- which ITR form am I supposed to file?"
- "My CTC is 18L with 50K NPS through my employer -- which regime should I pick for FY 2025-26?"
- "My estimated tax is 2.4L and TDS covers 1.8L. Plan my advance tax installments."
- "Parse `C:/tax/26AS.txt` and total the TDS my employer deposited."

## Filing after the due date

The s.139(1) due date for FY 2025-26 is in `deadlines` (`list_tax_years` prints them, with the statutory basis for each in `deadlineCitations`). Once it has passed, the return is **belated under s.139(4)** and four things change. `file_my_itr` asks about timing before anything else, because two of them are cheaper to know up front.

The pack's `deadlines.itr1_2` is 2026-07-31 (s.139(1) Explanation 2(c)). `deadlines.itr3_4_nonAudit` is 2026-08-31: Finance Act 2026 moved non-audit assessees with business or professional income to 31 August from AY 2026-27, and CBDT granted no further extension (checked 2026-09-10). Audit cases are later again (`deadlines.audit`, 31 October), and no tool ever selects it because nothing here takes a 44AB input, so `recommend_itr_form` and `filing_checklist` both report the non-audit date and both say so in `notes`.

- **You can still file**, up to `deadlines.belated` (2026-12-31 for AY 2026-27) or before the assessment is completed, whichever is earlier.
- **s.234F fee**: Rs 5,000, or Rs 1,000 where total income does not exceed Rs 5 lakh. Both figures come from the rule pack (`lateFee234F`) and are returned by `recommend_itr_form` and `filing_checklist`.
- **s.234A interest**: 1% per month, or part of a month, on the tax still outstanding after TDS/TCS, advance tax and reliefs, running from the day after the due date to the date of filing. Call `compute_interest_234` with `monthsLateFiling` (part month = full month, Rule 119A).
- **s.80 forfeits this year's loss carry-forward.** Business, speculative and capital losses of the current year cannot be carried forward in a belated return. Set-off of losses already determined in an earlier year survives, and so does the house-property loss carry-forward (s.71B). `recommend_itr_form` says this in `notes` whenever a business, speculative or capital loss flag is set, so its ITR-3 recommendation is not read as an unconditional carry-forward. A house-property-only loss does not trigger it, because s.71B carries that one forward either way.

**Revising a filed return.** Finance Act 2026 substituted s.139(5): a revised return may now be filed any time before the end of the AY (`deadlines.revised`, 2027-03-31), no longer three months before it. A revision filed after `deadlines.revisedWithoutFee234I` (2026-12-31) attracts the new s.234I fee; its tiers are not in the pack because no primary source for them was found, so read the amount off the portal.

Not modeled, deliberately: whether a belated business filer keeps the old-regime election (s.115BAC(6) / Form 10-IEA is due on or before the s.139(1) date). Ask a CA before relying on either answer.

## Validation

[`docs/validation.md`](docs/validation.md) runs 20 cases (58 figures) through the built server and puts each next to its source. Nine come from the Finance Minister's own table in the [Budget Speech 2025-26](https://www.indiabudget.gov.in/doc/bspeech/bs2025_26.pdf) (Annexure to Part-B, printed page 47): slab tax, rebate and tax after rebate from 8 to 50 lakh. The other eleven are worked by hand from the statute, with the arithmetic in the table: the 87A marginal relief and its crossover, gains that cost the rebate, the old-regime age bands, and the 10% surcharge with its own marginal relief. All 58 match. CI runs `pnpm validate` on every leg and fails if a figure stops matching or the committed table goes stale.

It is not a comparison with the e-Filing portal's own calculator, which refuses automated browsers. A case from a CA-prepared computation is the most useful pull request this repo can get.

## Scope and limitations

Honest boundaries, so you know before you rely on it. [`docs/v0.2-spec.md`](docs/v0.2-spec.md) carries the statutory citations behind each rule, the per-section implementation status, and the register of claims that were researched and refuted.

- **Resident individuals, FY 2025-26 (AY 2026-27).** NRI/RNOR computation differs (the form recommendation accounts for residency, the tax engine assumes resident).
- **No filing.** There is no public API to submit an ITR; only you or an authorized ERI can file. The agent prepares and verifies everything, then hands over.
- **You supply the income figures.** `compute_tax` computes tax on the heads you give it: salary, other income, 111A STCG, 112A LTCG, a house-property loss (as a positive number; it applies the s.71(3A) cap and the s.115BAC bar), employer NPS under 80CCD(2), and old-regime deductions as a single total. It does not itself compute house-property income (30% standard deduction, 24(b) interest), other capital-gains heads (112 debt/property, 115BBH crypto, slab-rate debt MF under 50AA), or business P&L -- work those out separately, or with `list_deductions` for the Chapter VI-A caps, and pass the totals in.
- **s.87A under the new regime tests total income.** The statute's first proviso says "total income" and this engine follows it, so 12 lakh of salary plus any equity gains loses the Rs 60,000 rebate. Some practitioners read the threshold as slab-rate income only; `compute_tax` says which reading it applied whenever gains are present, and the rule pack can encode the other one (`thresholdBasis: "normalIncome"`).
- **Not yet modeled:** house-property and business P&L computation (`presumptive` picks the single-installment 234C schedule and, with `presumptiveTurnover`, the 44AD/44ADA ceilings -- the income itself is not computed), crypto/VDA (115BBH), non-equity capital gains, loss set-off arithmetic beyond the house-property cap ([#4](https://github.com/Sagargupta16/itr-agent/issues/4)), Schedule FA valuation ([#5](https://github.com/Sagargupta16/itr-agent/issues/5)), Form 16 PDF parsing (`reconcile_documents` takes Form 16 figures as input, it does not read the PDF), broker capital-gains statements ([#7](https://github.com/Sagargupta16/itr-agent/issues/7)).
- **Dividend is ordinary income for surcharge purposes.** There is no dividend input: it goes in `otherIncome`. The First Schedule keeps dividend out of the 25%/37% surcharge bands and caps its surcharge at 15%, and `compute_tax` does neither for dividend (it does both for 111A/112A gains). Only bites above Rs 2 crore of total income; below that every band rate is already at or under 15%.
- **Transaction-date rules not yet split.** The engine applies FY 2025-26 rates uniformly; the 23-Jul-2024 capital-gains rate flip and the 1-Oct-2024 buyback change matter for FY 2024-25 returns, which this pack does not cover.
- **The encrypted AIS file is not a safe place to store your data.** Its password is your PAN plus your date of birth, stretched with only 1,000 PBKDF2-SHA256 iterations. Once someone knows your PAN, every plausible DOB can be tried in about 4 seconds single-threaded (measured on a laptop: 0.11 ms per key derivation over a ~36,600-date space). That is the portal's scheme, not this tool's choice, and nothing here can strengthen it -- treat a downloaded AIS export as effectively unencrypted and delete it when you are done.
- **`parse_ais` decryption is unproven on a live export.** The AIS password scheme is reverse-engineered from open-source utilities and verified against this repo's synthetic round-trip, never against a file the portal actually produced. If it fails, the error tells you to pass `password` explicitly or use the portal's CSV export, and [an issue report](https://github.com/Sagargupta16/itr-agent/issues) with your download date helps fix it. Every other tool is unaffected.
- **Not tax advice.** Complex cases belong with a CA. Every output says so.

## Architecture

One stdio process, three layers, no network. The prompt sequences the interview, the MCP layer validates every input, and pure functions over a versioned JSON rule pack produce every number.

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="docs/diagrams/architecture-dark.svg">
  <source media="(prefers-color-scheme: light)" srcset="docs/diagrams/architecture-light.svg">
  <img width="880" src="docs/diagrams/architecture-light.svg" alt="Architecture of itr-agent. Inside the boundary labelled Your machine: you chat with an MCP client (Claude Desktop or Claude Code), which speaks JSON-RPC over stdio to the itr-agent Node process. Inside that process the stdio transport (src/index.ts) hands requests to the MCP tool surface (12 tools and one prompt, zod-validated inputs), which calls three pure engine functions in src/engine (the tax engine for slabs, 87A, surcharge and cess; the form picker for ITR-1 to ITR-4 and the checklist; interest, advance tax, HRA and reconcile) and two read-only parsers in src/parsers (Form 26AS from the TRACES text export, and AIS with on-device AES decryption). The engine reads every constant from the rule pack data/fy2025-26.json, validated at load. The parsers read your 26AS and AIS exports from files on your disk through an extension allow-list. A dashed arrow from you to incometax.gov.in, drawn outside the tool, marks the one step itr-agent never does: you press submit, because no filing API exists.">
</picture>

The spec behind the picture is [`docs/diagrams/architecture.yaml`](docs/diagrams/architecture.yaml), rendered with [orrery](https://github.com/Sagargupta16/orrery); every node names the source file it stands for.

| Decision | Why |
| --- | --- |
| stdio only, no HTTP transport | The documents carry PAN, salary and TDS data. No port means nothing to expose; CONTRIBUTING declines network transports outright |
| Rule pack in JSON, not code | Tax law changes every Finance Act. A new FY is a new `data/fyYYYY-YY.json` plus golden tests; `validatePack()` refuses a pack missing any section the engine reads, so a missing rate fails loudly instead of falling back to a hardcoded one |
| The LLM never computes | A figure a model produced cannot be audited or reproduced. The model asks questions and calls tools; every rupee figure is a deterministic function output, returned with `disclaimers` and the fiscal year it applied |
| `structuredContent` beside text | Downstream tools (`reconcile_documents`) consume the parsed 26AS/AIS directly, while the text mirror masks PAN for the chat transcript |
| CI asserts computed figures | On Ubuntu and Windows across Node 22/24/26, the smoke test boots `dist/index.js`, sends JSON-RPC, and checks 12.75L salary = Rs 0 and 15L other income = Rs 1,09,200. A separate job installs the packed npm tarball and repeats the 1,09,200 check as a user would run it. `pnpm validate` replays all 58 validation figures on every leg, and a third job unpacks the `.mcpb` bundle where no `node_modules` can reach it and repeats the check again |

## Design principles

- **Local-only.** stdio transport, no network calls, no telemetry, no accounts. Your documents are read from disk by this process and never uploaded anywhere. AIS decryption happens entirely on-device with Node's crypto -- the reverse-engineered password scheme has un-peppered fallbacks and an explicit `password` override in case the format rotates.
- **What your MCP client still sees.** Parsed output is returned to whatever client you connected, so if that client is a hosted LLM, the parsed contents reach that provider like any other message. PAN is masked in the human-readable text mirror, but the `structuredContent` payload carries the full parsed document (PAN, TANs, deductor names, amounts) because downstream tools need it. Local-only describes this server, not your whole stack -- for maximum privacy, run it against a local model.
- **The LLM never does math.** Every rupee is computed by pure functions over `data/fy2025-26.json`. 151 tests pin the engine to published worked examples and to statute: the 12L zero-tax case, the 12,10,000 marginal-relief case, the 12,70,588 relief exhaustion point on both sides, the 13,25,000 total-income case that loses the rebate, the surcharge bands with the First Schedule exclusion of capital-gains income, all three old-regime age bands, and the 234A/234B/234C/HRA/80GG golden cases.
- **The agent drives, the engine decides.** The interview sequencing is a prompt; every number and every form rule is deterministic code. Nothing is estimated.
- **Year-parameterized.** Rules live in per-FY JSON packs. FY 2026-27 (Income-tax Act 2025 and Income-tax Rules 2026: Form 16 becomes Form No. 130 under Rule 215, the HRA metros become eight under Rule 279; Finance Act 2026: buyback reverts to capital gains) lands as a new pack, not code changes. Rule 164(14) of the 2026 Rules keeps FY 2025-26 returns on this year's forms, so none of it touches the pack shipped here.
- **Not tax advice.** Every tool that computes a rupee figure returns a `disclaimers` array and the fiscal year it applied; `compute_tax`, `compute_hra` and `list_tax_years` also return the exact `rulePackVersion`. Verify against the official utility before filing.

## Roadmap

- [x] **v0.1** -- tax engine (both regimes + CG + surcharge + cess), regime comparison, advance tax, deduction checklist, 26AS text parser
- [x] **v0.2** -- `parse_ais` (encrypted AIS JSON, on-device decrypt), `reconcile_documents` (the #1-notice-trigger checks), 234B/234C interest with golden-case tests, HRA + 80GG calculators, old-regime 87A semantics fix
- [x] **v0.3** -- renamed to **itr-agent**; `recommend_itr_form` with loss-continuity awareness ([#3](https://github.com/Sagargupta16/itr-agent/issues/3)), `filing_checklist`, the `file_my_itr` guided interview prompt
- [x] **v0.4** -- engine correctness pass (senior/super-senior slab sets, surcharge marginal relief on tax + surcharge, the s.111A/112A basic-exemption set-off, s.288A/288B rounding), positional 26AS amount extraction, s.234A + the s.234B(2) payment ladder, reconcile M4/M5, belated-filing guidance, security pins on the SDK's transitives, an OIDC-with-provenance publish workflow (no run of it has reached npm yet; the npmjs.com trusted-publisher link is pending), and an MCP registry manifest ([`server.json`](server.json))
- [x] **v0.5** -- fact-check of every constant against primary sources; s.87A on total income; AY 2026-27 form changes (two house properties, Schedule AL at 1 crore, Finance Act 2026 deadlines with citations); employer NPS and house-property loss inputs; 44AD/44ADA ceilings and s.194N in the form picker; 26AS booking status, TCS separation and reconcile M2; path allow-list on the parsers
- [x] **v0.5.2** -- a validation table against the Budget Speech 2025-26 figures and hand-worked statute cases, enforced in CI; the `.mcpb` one-click Claude Desktop bundle, attached to each release from v0.5.3 on; a README demo rendered from a real stdio session
- [x] **v0.5.3** -- architecture and filing-flow diagrams rendered from [`docs/diagrams/`](docs/diagrams) with orrery (light and dark, reviewed at README width) in place of the mermaid sketch; the Income-tax Rules 2026 citations (Rules 164, 205, 215, 245, 269, 279) recorded for the FY 2026-27 pack; the README says what npm serves today
- [ ] **v0.6** (priorities validated against a real AY 2026-27 filing) -- `compute_loss_setoff` (BFLA/CFL engine, [#4](https://github.com/Sagargupta16/itr-agent/issues/4)), `parse_form16` (TRACES PDF), broker capital-gains parsers -- Groww first, then Zerodha ([#7](https://github.com/Sagargupta16/itr-agent/issues/7))
- [ ] **v0.7** -- `compute_schedule_fa` (foreign assets/RSU, Rule 115 rates, [#5](https://github.com/Sagargupta16/itr-agent/issues/5)), portal quirks playbook ([#6](https://github.com/Sagargupta16/itr-agent/issues/6)), mutual fund CAS via casparser, draft ITR JSON export

## Development

```bash
pnpm install
pnpm test          # vitest: engine golden files + in-memory MCP client tests
pnpm build
pnpm inspect       # MCP inspector against dist/index.js
pnpm validate      # docs/validation.md cases against the built server; --write regenerates it
pnpm bundle        # build/itr-agent-<version>.mcpb, the Claude Desktop bundle
node scripts/demo.mjs   # the README demo session
```

## Contributing

Tax software has a higher correctness bar than most OSS, so the ground rules are written down: [CONTRIBUTING.md](CONTRIBUTING.md) (tax constants live in `data/*.json` with a cited source, every calculator change ships a golden test, never commit a real tax document). Version history and every constant that moved: [CHANGELOG.md](CHANGELOG.md). Found a vulnerability? [SECURITY.md](SECURITY.md) has the private reporting path -- please do not open a public issue for it.

## Disclaimer

itr-agent is an open-source calculator, document parser, and filing guide. It is not a substitute for professional tax advice, and it never files anything -- output is meant to be verified against the official income tax utility, and the return is always submitted by you on the portal.

## License

[MIT](LICENSE)

TDQS

A4.2/5.0

Scored across 12 tools

Disambiguation5/5

Each tool targets a distinct operation in a clear tax-filing pipeline: computation (compute_tax, compare_regimes, compute_hra, compute_interest_234), form guidance (recommend_itr_form, filing_checklist), reference data (list_tax_years, list_deductions), document ingestion (parse_form26as, parse_ais), and cross-checking (reconcile_documents). The closest pairs (compute_tax vs compare_regimes, list_deductions vs compute_hra) are explicitly differentiated in their descriptions (both-regime comparison; reference caps vs actual exemption calculation). No two tools appear to do the same job.

Naming Consistency4/5

Names are consistently snake_case and almost all follow a verb_noun pattern (compute_tax, list_deductions, parse_ais, recommend_itr_form, reconcile_documents). The main deviation is filing_checklist, which is a bare noun phrase with no verb, and parse_form26as embeds a format token, but both remain readable and predictable.

Tool Count5/5

Twelve tools is well within the sweet spot for a domain this broad, and each one maps to a real step a filer needs (compute, compare, recommend form, checklist, deductions, advance tax, 26AS/AIS parsing, interest, HRA, reconciliation). There is no filler or redundant tool.

Completeness4/5

The surface covers the full individual-filer lifecycle from income computation through document reconciliation, form selection, and deadlines. Minor gaps: there is no Form 16 parser (reconcile_documents checks Form 16 vs 26AS per-TAN totals but must receive Form 16 data as input), and presumptive 44AD/44ADA income computation is only checked for turnover ceilings in recommend_itr_form rather than computed.

Maintenance

ActivityMaintained
ResponsivenessUnresponsive