Provides authentication brokering for the FreeTaxUSA MCP server using Hermes, enabling cookie session injection without direct credentials.
Click on "Deploy 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., "@FreeTaxUSA MCP Server Help me file my W-2"
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.
An MCP server that lets AI agents file your taxes through FreeTaxUSA -- the free federal tax filing service.
Instead of paying $120+ for TurboTax's guided interview, this MCP gives any AI assistant (Claude, etc.) the ability to navigate FreeTaxUSA's interface, fill forms, check your refund, and walk you through filing -- conversationally.
Federal filing is free. State is $15.99. That's it.
This is not an API wrapper. FreeTaxUSA has no public API.
This MCP uses Playwright to drive a real Chromium browser session against FreeTaxUSA's web interface. It reads forms via the accessibility tree, fills fields, navigates between sections, and returns structured data to the AI agent -- which then talks to you like a human tax preparer would.
You: "Here's my W-2, help me file"
|
[Claude / AI Agent]
|
[FreeTaxUSA MCP] <-- this project
|
[Playwright + Chromium]
|
[freetaxusa.com]
|
[IRS e-file]Related MCP server: Cloudflare Playwright MCP
15 tax filing tools across personal info, income, deductions, review, and filing
Session persistence -- login once, cookies survive between invocations
PII protection -- SSNs, account numbers, and EINs are automatically redacted from all tool outputs
Dynamic navigation -- discovers FreeTaxUSA's section structure at runtime
Anti-bot mitigations -- realistic viewport, disabled automation flags
State paywall detection -- warns before triggering the $15.99 state filing purchase
Prior year support -- configurable tax year for filing back taxes
Tool | Description |
| Log in. With Hermes configured, the session is brokered (no credentials needed). Otherwise pass email/password — used once, never stored. |
| Check if session is active, which tax year and section is loaded. |
Tool | Description |
| Read all form fields and their current values on the active page. |
| Submit the current page and advance to the next. |
| Jump to a section by name ("income", "deductions") or SID number. |
Tool | Description |
| Fill name, SSN, DOB, occupation, and address. |
| Set filing status (single, married joint, head of household, etc.). |
Tool | Description |
| Get return overview: refund/owed, AGI, filing status, completed sections. |
| Get current federal and state refund or amount owed. |
Tool | Description |
| Enter W-2 wage and withholding data. |
| Enter 1099 income (INT, DIV, MISC, NEC, R, G, SSA). |
Tool | Description |
| Enter standard or itemized deductions. |
| Run error check and get review results before filing. |
| File Form 4868 for an automatic 6-month extension. |
| Get which sections are complete, incomplete, or have errors. |
Phase 2 and 3 tools are stubbed and will be implemented in upcoming releases.
Node.js 20+
A FreeTaxUSA account (free to create)
git clone https://github.com/schwarztim/freetaxusa-mcp.git
cd freetaxusa-mcp
npm install
npm run buildPlaywright will automatically install Chromium during npm install.
Add to your Claude Code MCP configuration (~/.claude/user-mcps.json):
{
"mcpServers": {
"freetaxusa": {
"type": "stdio",
"command": "node",
"args": ["/path/to/freetaxusa-mcp/dist/index.js"]
}
}
}Or for Claude Desktop (claude_desktop_config.json):
{
"mcpServers": {
"freetaxusa": {
"command": "node",
"args": ["/path/to/freetaxusa-mcp/dist/index.js"]
}
}
}Variable | Default | Description |
| (unset) | Hermes broker URL. When set with |
| (unset) | Bearer token for the Hermes broker (from |
|
| Service name registered with Hermes. |
|
| Credential scheme to request from Hermes. |
|
| Opt back into the embedded Playwright login even when Hermes is configured-but-down. Default fails loudly on a broker outage. |
|
| Set to |
|
| Browser profile directory |
|
| Tax year to file (change for prior years) |
FreeTaxUSA has no API — authentication is a browser login session (cookies). By
default this server drives an embedded Playwright login with the email/password
you pass to the authenticate tool.
When the Hermes auth broker is configured, it becomes the
authoritative auth path: Hermes performs the login on the host (handling SSO,
MFA, captcha) and hands this server a fresh cookie session, which is injected
into the browser context. In this mode the authenticate tool needs no
email/password — just call it.
export HERMES_URL=http://127.0.0.1:9876
export HERMES_CLIENT_TOKEN="$(cat ~/.hermes/client.token)"
# optional overrides:
# export HERMES_SERVICE=freetaxusa
# export HERMES_SCHEME=cookie-sessionBehavior:
Hermes configured + reachable → cookie session brokered by Hermes; embedded login is skipped.
Hermes configured + unreachable → authentication fails loudly (does not silently fall back to the embedded login). Set FREETAXUSA_LEGACY_AUTH=true to opt into the embedded fallback and supply email/password.
Hermes not configured → embedded Playwright login as before (email/password required).
Operator setup required: this server becomes Hermes-capable in code, but runtime success depends on the operator registering FreeTaxUSA
cookie-sessioncredentials with the Hermes broker. Until that is done, setFREETAXUSA_LEGACY_AUTH=true(or leave Hermes unconfigured) to use the embedded login.
Once configured, start a conversation with Claude:
You: I need to file my taxes. Log me in to FreeTaxUSA.
Claude: I'll authenticate you now. What's your FreeTaxUSA email and password?
You: email is me@example.com, password is hunter2
Claude: [calls authenticate tool] You're logged in for tax year 2025.
Let's start with your personal information. What's your full name?
You: John Smith, SSN 123-45-6789, born 01/15/1990
Claude: [calls fill_taxpayer_info] Done. Your address?
You: 123 Main St, Anytown PA 19301
Claude: [fills address, calls save_and_continue]
Personal info is saved. Your current refund estimate is $2,847.
Let's move to income. Do you have W-2s to enter?src/
index.ts # Entry point (stdio transport)
server.ts # MCP server + tool registration
browser/
context.ts # Persistent browser context + async mutex
navigation.ts # SID-based navigation + dynamic discovery
forms.ts # Form reading/filling via accessible labels
tools/
session.ts # authenticate, get_session_status
overview.ts # get_tax_summary, get_refund_estimate
personal.ts # fill_taxpayer_info, fill_filing_status
income.ts # fill_w2_income, fill_1099_income
deductions.ts # fill_deductions
review.ts # review_return
filing.ts # file_extension, get_form_status
page.ts # read_current_page, save_and_continue, navigate_section
security/
pii-filter.ts # SSN/EIN/account number redaction
types/
tax.ts # TypeScript interfaces
sections.ts # SID mapping + section aliasesAccessibility tree over CSS selectors. Form elements are targeted by their accessible label (role + name), not by CSS class or ID. This survives UI redesigns that change styling but preserve semantics.
Dynamic SID discovery. FreeTaxUSA uses ?sid=N URL parameters for navigation. SID values can change between tax years. On first page load, the MCP scrapes navigation links to build a live SID map, with a static fallback.
PII filter on all outputs. Every string returned by every tool passes through filterPII() before reaching the MCP transport. SSNs are masked to ***-**-NNNN, EINs to **-***NNNN, and account numbers to ****NNNN. This protects against accidental PII exposure in AI conversation logs.
Single-page mutex. The browser has one active page. An async mutex serializes all tool calls to prevent race conditions from concurrent invocations.
Credentials never stored. Email and password are accepted as tool inputs, used to fill the login form, and discarded. The persistent browser context retains session cookies only. The profile directory is chmod 0700.
This MCP handles sensitive financial data. The security model:
PII redaction: All tool outputs are filtered. SSNs, EINs, and account numbers are automatically masked.
No credential storage: Login credentials are provided per-call and never written to disk.
Restricted browser profile: The session directory (~/.freetaxusa-mcp/browser-profile/) is created with 0700 permissions.
State paywall guard: Navigation that would trigger a $15.99 purchase throws an error instead of proceeding.
Session expiry detection: Every tool checks for redirect to the login page before acting.
# Build
npm run build
# Run in development (auto-recompile)
npm run dev
# Run tests
npm test
# Watch tests
npm run test:watch
# Run with visible browser for debugging
FREETAXUSA_HEADLESS=false npm run startTo file back taxes, set the tax year:
FREETAXUSA_TAX_YEAR=2024 node dist/index.jsFreeTaxUSA supports free federal filing for prior years. Note that prior year returns cannot be e-filed -- they must be printed and mailed.
Phase 1: Session, navigation, personal info, tax summary
Phase 2: W-2 and 1099 income entry
Phase 3: Deductions, review, extension filing
Phase 4: W-2/1099 PDF import via Claude vision, section walkthroughs
Phase 5: Multi-year batch filing for back taxes
This project is not affiliated with, endorsed by, or associated with FreeTaxUSA, TaxHawk Inc., or Intuit. FreeTaxUSA is a registered trademark of TaxHawk, Inc. Use of this tool is subject to FreeTaxUSA's Terms of Use. This tool automates a web browser -- the same actions a human would perform manually. You are responsible for the accuracy of your tax return.
MIT
Log in to FreeTaxUSA. When Hermes is configured (HERMES_URL/HERMES_CLIENT_TOKEN), the session is brokered by Hermes and no email/password is needed. Otherwise, pass email and password for the embedded browser login (credentials are used once and never stored).
| Name | Required | Description | Default |
|---|---|---|---|
| No | FreeTaxUSA account email (not required when Hermes brokers the login) | ||
| mfaCode | No | MFA code if prompted | |
| password | No | FreeTaxUSA account password (not required when Hermes brokers the login) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It covers the two authentication paths, credential handling (used once, not stored), and the optional MFA code. It doesn't specify session duration or error behavior, but for an authentication tool, the key behaviors are adequately described.
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, front-loaded with the main purpose. No unnecessary words or repetition. Every sentence provides essential information, making it highly concise and well-structured.
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 tool has 3 parameters, no output schema, and no annotations, the description is fairly complete. It explains the two login paths, credential handling, and MFA. It could mention what happens on authentication failure or what the output looks like, but for the complexity level, it is sufficient.
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 100%, so baseline is 3. The description adds meaningful context: email and password are not required when Hermes brokers the login, and MFA code is used if prompted. This goes beyond the schema descriptions, adding conditional logic and usage nuance.
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: logging in to FreeTaxUSA. It specifies the two distinct authentication modes (Hermes-brokered vs. direct email/password), making the purpose precise and unambiguous.
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 explains when to use email/password (when Hermes is not configured) and when not to (when Hermes is configured). It also mentions that credentials are used once and never stored. While it doesn't explicitly list when-not-to-use alternatives, the context is clear enough for an agent to decide.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[Phase 3 - Not yet implemented] File Form 4868 for an automatic extension.
| Name | Required | Description | Default |
|---|---|---|---|
| estimatedPayments | No | Estimated payments already made | |
| estimatedTaxLiability | No | Estimated total tax liability |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It only says 'File Form 4868 for an automatic extension' without disclosing side effects, required authentication, or what happens after filing.
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 a single sentence but includes an unnecessary status note '[Phase 3 - Not yet implemented]', which could mislead or clutter. It is moderately concise but not optimally structured.
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 no output schema and minimal description, the tool lacks context about the filing process, expected response, or next steps. The description is insufficient for an agent to fully understand the tool's behavior.
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 description coverage is 100%, so the baseline is 3. The description adds no additional meaning beyond what is provided in the input schema's property descriptions.
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 verb 'File', the resource 'Form 4868', and the purpose 'automatic extension'. It effectively distinguishes from sibling tools, none of which involve filing extensions.
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?
No guidance is provided on when to use this tool versus others. There is no mention of prerequisites, context, or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[Phase 2 - Not yet implemented] Enter 1099 income data.
| Name | Required | Description | Default |
|---|---|---|---|
| type | Yes | Type of 1099 form | |
| amount | Yes | Primary amount | |
| payerEin | No | Payer EIN | |
| payerName | Yes | Payer name | |
| federalWithheld | No | Federal income tax withheld |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are absent, so the description carries full burden. It does mention the tool is not yet implemented, which is a critical behavioral fact. However, it provides no other behavioral traits—no mention of side effects (e.g., data mutation), auth requirements, or response format. The disclosure of non-implementation is the only transparency.
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 very brief at two short phrases. While concise, it is under-specified and would benefit from more detail on usage. The '[Phase 2 - Not yet implemented]' prefix is front-loaded and important, but the lack of substantive content makes it merely adequate.
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 tool has five params, no output schema, and no annotations, the description is severely incomplete. It does not explain what happens on successful entry, validation rules, or integration with the tax return workflow. The non-implementation note is the only contextual element, which is insufficient for an agent to effectively use this 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?
Schema description coverage is 100%, so the input schema already documents all five parameters with descriptions. The description adds no extra meaning beyond 'Enter 1099 income data,' which does not enrich parameter understanding. Baseline 3 is appropriate as the description does not detract but provides no added 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 states 'Enter 1099 income data' which clearly identifies the resource and action, but the '[Phase 2 - Not yet implemented]' prefix indicates the tool is non-functional, undermining clarity. It does differentiate from sibling tools like fill_w2_income, but the misleading claim of functionality reduces the score.
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?
No usage context is provided. There is no guidance on when to use this tool versus alternatives like fill_w2_income or fill_deductions, nor prerequisites such as being on the appropriate form section. The description implies it should be used for 1099 forms, but lacks explicit context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[Phase 3 - Not yet implemented] Enter deduction information (standard or itemized).
| Name | Required | Description | Default |
|---|---|---|---|
| type | Yes | Deduction type | |
| items | No | Itemized deduction items (required if type is "itemized") |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description discloses the tool is not yet implemented, but lacks details on expected behavior, authorization, side effects, or what happens upon call. With no annotations, more transparency is needed.
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?
Single sentence is concise and front-loaded with the implementation status. However, the description could be slightly more structured to separate the status note from the purpose.
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?
No output schema, and description does not explain return values or side effects. Missing guidance on how this tool fits with siblings (e.g., order of operations). Incomplete for a tool with two modes.
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 100%, so the schema already documents parameters. Description 'Enter deduction information (standard or itemized)' adds no extra meaning beyond the schema. Baseline 3 is appropriate.
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?
Description clearly states the verb 'Enter' and the resource 'deduction information,' specifying two modes (standard or itemized). It distinguishes from sibling tools like fill_1099_income or fill_w2_income which handle other tax sections.
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?
No guidance on when to use this tool versus alternatives, or when to choose standard vs itemized. The '[Phase 3 - Not yet implemented]' note indicates non-functionality but does not provide usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Set the filing status (single, married_joint, married_separate, head_of_household, qualifying_widow).
| Name | Required | Description | Default |
|---|---|---|---|
| status | Yes | Filing status |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are available, and the description only states the action without disclosing behavioral traits like overwrite behavior, validation rules, or side effects. For a mutation tool, this lacks transparency.
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 a single, efficient sentence that conveys the core purpose without waste. It is front-loaded with the verb and resource.
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 simplicity of the tool (one parameter, no output schema, no annotations), the description is minimally adequate. It lacks details on return values, errors, or prerequisites, but the tool is straightforward.
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 100% with a clear enum description. The description redundantly lists enum values but adds no additional meaning beyond the schema. Baseline 3 is appropriate.
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 uses the verb 'Set' and specifies the resource 'filing status', listing all possible enum values. This clearly states the tool's action and distinguishes it from sibling tools like fill_taxpayer_info.
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?
No guidance is provided on when to use this tool versus alternatives such as fill_taxpayer_info, which may also affect filing status. There are no when-not-to-use or prerequisite conditions mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fill the taxpayer personal information section (name, SSN, DOB, address, occupation).
| Name | Required | Description | Default |
|---|---|---|---|
| dob | Yes | Date of birth (MM/DD/YYYY) | |
| ssn | Yes | Social Security Number (XXX-XX-XXXX) | |
| suffix | No | Suffix (Jr, Sr, II-VI) | |
| address | Yes | ||
| lastName | Yes | Last name | |
| firstName | Yes | First name | |
| occupation | Yes | Occupation | |
| middleInitial | No | Middle initial |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden for behavioral disclosure. It only says 'Fill' which implies modification, but omits details on overwrite behavior, validation requirements, side effects, or required prior state (e.g., navigation). This is insufficient for a mutation tool.
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 exceptionally concise at one sentence. It efficiently lists the core fields. Minor improvement could be adding a brief note about the address subfields, but overall it's well-structured.
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 complexity (8 parameters, nested address object, 6 required), and no output schema, the description is too sparse. It does not explain what happens after filling (e.g., form update confirmation), error scenarios, or how the nested address should be provided.
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 88%, so parameters are already well-documented in the schema. The description adds no semantic value beyond listing field categories. Baseline 3 is appropriate as it neither adds nor detracts significantly.
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 explicitly states the tool fills the taxpayer personal information section and lists the fields (name, SSN, DOB, address, occupation). This clearly distinguishes it from sibling tools like fill_1099_income or fill_w2_income.
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?
No guidance is provided on when to use this tool versus alternatives, when not to use it, or prerequisites (e.g., must be on the correct section of the form). The description lacks any strategic context for the agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[Phase 2 - Not yet implemented] Enter W-2 wage data.
| Name | Required | Description | Default |
|---|---|---|---|
| state | No | State code (Box 15) | |
| wages | Yes | Wages, tips, other compensation (Box 1) | |
| stateId | No | Employer's state ID (Box 15) | |
| employerEin | Yes | Employer EIN (XX-XXXXXXX) | |
| employerName | Yes | Employer name | |
| medicareWages | No | Medicare wages (Box 5) | |
| stateWithheld | No | State income tax withheld (Box 17) | |
| federalWithheld | Yes | Federal income tax withheld (Box 2) | |
| socialSecurityWages | No | Social security wages (Box 3) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must disclose behavioral traits. 'Enter' implies a write operation, but it does not detail side effects (e.g., whether it overwrites existing W-2 data or appends), authentication requirements, or potential error states. The status note 'Not yet implemented' adds confusion about reliability but is not a behavioral trait.
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 extremely short (one sentence), which is concise but under-informative. The inclusion of '[Phase 2 - Not yet implemented]' adds implementation status rather than usage guidance, reducing its helpfulness for an AI agent. It could be restructured to front-load critical usage info.
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 tool has 9 parameters (4 required) and no output schema, the description is insufficient. It does not explain return values, confirmation of entry, or whether the tool is additive or replaceable. For a complex data-entry tool, the agent needs more context to avoid misuse.
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 has 100% description coverage for all 9 parameters, providing clear definitions for each field (e.g., 'Wages, tips, other compensation (Box 1)'). The tool description adds no further meaning beyond the schema, so a baseline score of 3 is appropriate.
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 'Enter W-2 wage data,' which specifies the action (enter) and the resource (W-2 wage data). This distinguishes it from sibling tools like fill_1099_income, which targets a different form. However, the term 'enter' is somewhat generic and could imply creation or editing, but the context of tax forms clarifies it.
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?
There is no guidance on when to use this tool versus alternatives like fill_1099_income or fill_deductions. The description does not mention prerequisites, such as the need for an existing tax return or session, nor does it specify when not to use it. The agent is left to infer usage from the tool name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[Phase 3 - Not yet implemented] Get which sections are complete, incomplete, or have errors.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses that the tool is not yet implemented, which is a key behavioral trait. No annotations provided, so description carries full burden; additional details on side effects or permissions would improve score.
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?
Extremely concise single sentence with no unnecessary words. Front-loaded with purpose.
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?
Adequate for a tool with no parameters and no output schema. Lacks context about what form or sections are referenced; the 'not implemented' note is important but leaves uncertainty about expected behavior when implemented.
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?
No parameters exist, so baseline is 4. Description adds meaning by specifying the tool returns section status, which is sufficient for a parameterless tool.
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?
Description clearly states the tool retrieves section completion status (complete, incomplete, errors). Distinguishes from sibling tools like fill_ forms and read_current_page. However, the '[Phase 3 - Not yet implemented]' prefix may cause confusion about actual availability.
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?
No guidance on when to use this tool versus alternatives like get_tax_summary or navigate_section. Lacks context for preferred usage scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the current calculated federal and state refund or amount owed.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must carry full burden. It only states 'get current calculated', but does not disclose side effects, idempotency, authentication needs, or rate limits.
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?
Single sentence, front-loaded with key information. No extraneous text.
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?
Tool has no output schema and minimal description. Does not explain return format (e.g., number, string) or what 'current calculated' means. Adequate for simple tool but leaves ambiguity.
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?
No parameters exist (schema coverage 100%), so description cannot add more meaning. Baseline for 0 parameters is 4, and no additional info is needed.
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?
Description clearly states verb 'get', resource 'refund estimate', and specifies scope ('federal and state refund or amount owed'). It is distinct from sibling tools like get_tax_summary or get_form_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?
No guidance on when to use this tool versus alternatives (e.g., get_tax_summary). Does not specify prerequisites or context for calling.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check if the FreeTaxUSA session is active and which tax year/section is loaded.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description correctly implies a non-destructive read operation ('Check'). Without annotations, it adequately communicates that the tool is safe and does not modify state. No contradiction.
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 a single, well-structured sentence that conveys the purpose without extraneous words. It front-loads the key action 'Check'.
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 does not specify the return format (e.g., boolean, object), which is needed since no output schema is provided. Users cannot infer what 'session active' or 'tax year/section' looks like in the response.
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 tool has no parameters, so schema coverage is 100%. Baseline for zero-parameter tools is 4. The description does not need to explain parameter meaning as none exist.
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 specifies the verb 'Check' and the resource 'FreeTaxUSA session', distinguishing from sibling tools like authenticate (creates session) and get_form_status (checks form status). It directly states the two checks: session activity and tax year/section.
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 for simple status queries but lacks explicit guidance on when to use this tool over alternatives like get_form_status or navigate_section. No mention of prerequisites or exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the tax return overview: refund/owed amount, AGI, filing status, completed sections.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description does not disclose read-only nature, side effects, authentication needs, or any behavioral traits beyond 'get'. Burden falls on description, which is insufficient.
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?
Single, front-loaded sentence with clear purpose; no wasted words.
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?
Adequately describes input (none) and output fields for a simple overview tool; lacks details on format or prerequisites but sufficient given no output schema and zero params.
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?
No parameters (schema coverage 100% for zero params), description adds value by listing returned fields, making it clear what the tool provides.
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?
Description clearly specifies verb 'Get' and resource 'tax return overview', listing specific data points (refund/owed, AGI, filing status, completed sections), distinguishing it from siblings like get_refund_estimate or get_form_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?
Implied usage for obtaining a tax return summary, but no explicit when-to-use or when-not-to-use guidance; alternatives like get_refund_estimate are not mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read all form fields and their values on the current FreeTaxUSA page.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. Description indicates read-only behavior but lacks details on authentication requirements, whether it triggers any state changes, or scope of fields returned.
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?
Single sentence, no extraneous words. Front-loaded with key 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?
Sufficient for a simple read operation with no params and no output schema, but could elaborate on return format and how this fits into the overall workflow (e.g., use before filling).
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?
No parameters defined; schema coverage 100%. Description adds no parameter info but none needed.
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?
Description clearly states verb 'Read', resource 'form fields and their values', and context 'current FreeTaxUSA page'. Distinguishes from sibling fill_* tools which are for writing.
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?
Implied usage for reading data before filling, but no explicit when/when-not or alternatives. Could mention it's best used before a fill operation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[Phase 3 - Not yet implemented] Run error check and get review results before filing.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description only mentions the tool is not yet implemented. It does not disclose any behavioral traits such as side effects, authentication needs, or rate limits, which is insufficient for a non-existent tool.
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 a single sentence that efficiently communicates the purpose and implementation status. However, the bracket notation for the phase could be slightly distracting.
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 no parameters, no output schema, and a 'not yet implemented' status, the description is minimally adequate. It warns the agent of non-functionality but lacks details on expected behavior when implemented.
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 has zero parameters, so the description does not need to add parameter semantics. The baseline of 4 applies, and the description does not contradict this.
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 runs an error check and gets review results before filing, providing a specific verb and resource. However, it does not differentiate from sibling tools like get_form_status or get_refund_estimate.
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 'before filing,' giving context, but it lacks explicit when-not-to-use or alternative tool mentions, leaving ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Submit the current FreeTaxUSA page and advance to the next page.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description bears full responsibility for behavioral disclosure. It states the action ('submit' and 'advance') but does not reveal potential side effects (e.g., validation failures, loss of unsaved changes, or idempotency). 'Submit' implies mutation but lacks detail on error handling or confirmation.
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 a single sentence that clearly conveys both actions (submit and advance) with no wasted words. It is front-loaded with the primary verb 'Submit' 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?
For a parameter-free tool, the description covers the essential purpose. However, given the lack of annotations and output schema, it could benefit from mentioning that submission implies saving, or that the tool triggers page transition. It is nearly complete but lacks minor behavioral 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 has zero parameters, so schema description coverage is 100%. No parameter documentation is needed. The description appropriately focuses on the action, adding no extraneous information.
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 uses specific verbs ('submit' and 'advance') and explicitly identifies the resource ('current FreeTaxUSA page'), making the tool's function unambiguous. It clearly distinguishes from siblings like 'navigate_section' (which moves without submitting) and 'read_current_page' (which only reads).
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 should be used after filling a page to save progress and continue. However, it offers no explicit guidance on when to avoid it (e.g., if validation errors occur) or alternatives like 'navigate_section' for non-submission navigation.
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.
v1.0.0authenticatefile_extensionfill_1099_incomefill_deductionsfill_filing_statusfill_taxpayer_infofill_w2_incomeget_form_statusget_refund_estimateget_session_statusget_tax_summarynavigate_sectionread_current_pagereview_returnsave_and_continueScored across 15 tools
Each tool targets a distinct action or entity: authentication, filing status, taxpayer info, refund estimate, session status, tax summary, navigation, page reading, and saving. There is no overlap between the implemented tools.
All tools follow a consistent verb_noun pattern (e.g., fill_filing_status, get_refund_estimate, navigate_section). Even the unimplemented tools follow this pattern, indicating a well-thought-out naming convention.
With 15 tools total (9 implemented), the count is within the typical 3-15 range. However, the presence of 6 placeholder tools that are not yet implemented slightly inflates the count, but overall it is appropriate for the scope.
The tool set is missing essential functionalities for tax preparation, such as entering W-2 income, 1099 income, deductions, and filing extensions. Most data entry tools are marked as not implemented, leaving a significant gap that prevents completing a tax return.
Verifiable US tax oracle for AI agents: cited, machine-checkable federal and state tax computation
AI-powered browser automation — navigate, click, fill forms, and extract data from any website.
Stealth web automation for AI agents. Login, signup, navigate, screenshot.
Stealth web automation for AI agents. Login, signup, navigate, screenshot.
