Tax software: your AI agent sends the facts, we calculate and e-file; you review and sign.
Scored across 3 tools
The three tools map cleanly to distinct lifecycle stages: starting a session, retrieving the packet schema, and continuing with a completed packet. There is no meaningful overlap, and the descriptions make the boundaries explicit.
All tool names use a consistent snake_case verb_noun pattern: create_filing_session, get_packet_schema, continue_filing_session. The convention is predictable throughout.
Three tools are well matched to this narrow filing handoff workflow: session creation, schema retrieval, and packet continuation. Each tool has a clear, non-redundant role.
The surface covers the core flow from session creation through schema retrieval to submitting a packet for a filing link. Minor lifecycle operations such as checking session status or explicitly cancelling a session are absent, though expiry and new sessions provide workarounds.
Checks the taxpayer's completed draft packet for a federal return and, when it passes, holds it as an unsigned draft and returns the link to the filing page; otherwise returns a list of problems to correct. This call files nothing and sends nothing to the IRS: the taxpayer reviews, signs and files on the filing page.
Inputs: the filing session's continuationHandle, completedReturnPacketJson (the whole packet as one JSON string, in this server's packet schema) and packetSchemaSha256 (that schema's digest); other arguments are refused by name. The tax year is return.taxYear=2025 inside the packet. The packet carries the facts the taxpayer stated in this chat and the figures printed on documents the taxpayer gave in it; a fact the taxpayer has not stated is left out rather than written as no, none or 0, and a required fact that is left out comes back as a blocker asking for the taxpayer's answer.
Output: status filing_session_ready with a filingSessionUrl when the packet is accepted; the taxpayer opens that link to give permission, review the return and sign it. Otherwise, blockers (each with a path, a rule and a plain detail) and no link; that packet is not kept, and the same handle accepts a corrected packet. Nothing is filed or charged through a link that expires or is left unfinished, and the same packet sent again with a new filing session's handle returns a fresh link. An accepted packet is held until the taxpayer gives permission on the filing page; declining there, or expiry, erases it. Federal returns: no state, territory or local return is filed. The return has no taxpayer identity fields: the taxpayer's own details go in the packet's separate, required agentIdentity section, which the filing page shows for the taxpayer to confirm. Business identifiers printed on each source form, such as an employer's or payer's name and EIN, are packet fields.
| Name | Required | Description | Default |
|---|---|---|---|
| continuationHandle | No | ||
| packetSchemaSha256 | No | The current digest returned by get_packet_schema. The server checks it against the current packet schema; packet-schema-stale means the submitted digest no longer matches that schema. | |
| completedReturnPacketJson | No | The complete return packet as one JSON string, in this server's packet schema. Its values are the facts the taxpayer stated and the figures printed on the taxpayer's documents. |
| Name | Required | Description |
|---|---|---|
| status | No | |
| blockers | No | |
| filingSessionUrl | No | |
| readBackToTaxpayer | No | With the filing link: the packet's own answers to the which-apply questions, in plain words, to read to the taxpayer before they open the link. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds substantial behavioral context beyond the annotations: nothing is filed or sent to the IRS, accepted packets are held only until taxpayer permission, declining or expiry erases them, rejected packets are not kept, and federal-only scope applies. These details clarify the destructive and idempotent behavior implied by the annotations without contradicting them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded and every section contributes useful information about behavior, inputs, and outputs. It is long and dense, with some run-on sentences, but the length is largely justified by the complexity of the filing handoff.
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 complex, mutating, potentially destructive filing tool, the description is complete: it covers what is filed or not filed, what happens on acceptance and rejection, retry semantics, expiry and erasure, federal-only scope, and identity handling. With an output schema present, it does not need to explain return-value structure further.
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?
Although schema coverage is 67%, the description adds meaningful semantics for all key inputs: continuationHandle, completedReturnPacketJson as the whole packet in this server's schema, packetSchemaSha256 as the schema digest, the required tax year inside the packet, and the required agentIdentity section. It also explains that omitted taxpayer facts become blockers rather than default zero/no values, which is valuable guidance beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a precise verb and resource: it checks a completed draft federal return packet, holds an accepted packet as an unsigned draft, and returns a filing-page link or blockers. This is clearly differentiated from creating a filing session or retrieving the packet schema, so an agent can identify the tool's role immediately.
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?
It makes clear when this call is appropriate: after a completed return packet exists for a filing session, and when the taxpayer needs review/signature or correction feedback. It also explains retry behavior with blockers and corrected packets, but it does not explicitly name sibling tools or state when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Starts a filing session for a US federal individual income tax return when the taxpayer asks to file. Input: none. Output: a continuationHandle that identifies this filing session in later calls, and packetRules, the packet rules as text. This call receives no tax facts and creates no return and no link; the filing link comes with an accepted packet. A new filing session is also how a fresh link replaces one that expired or was left unfinished, through which nothing was filed or charged: the same packet sent on the new handle returns the new link.
Covered returns: one original tax year 2025 US federal individual income tax return (Form 1040 or 1040-SR, and some Form 1040-SS and Form 1040-NR situations), with no state or local return. The packet rules this call returns list each covered and refused situation.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| blockers | No | |
| packetRules | No | |
| continuationHandle | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations, it discloses that the call receives no tax facts, creates no return and no link, returns a continuationHandle and packetRules, and that the filing link comes only with an accepted packet. It also explains replacement behavior for expired or unfinished sessions and what happens when the same packet is sent on the new handle.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with purpose and output, and most sentences carry useful routing or behavioral information. It is somewhat long and occasionally wordy, especially around the expired/unfinished-link case and covered-returns paragraph, which keeps it from being maximally concise.
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 complex filing domain, zero-parameter schema, rich annotations, and existing output schema, the description provides enough scope and behavioral context for an agent to call it correctly. It covers the return types handled and clearly states what the call does and does not create.
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 zero input parameters, so the baseline is 4. The description reinforces this with 'Input: none', but there is no additional parameter meaning to explain.
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 a specific verb and resource: starting a filing session for a US federal individual income tax return when the taxpayer asks to file. It distinguishes the call from continuing an existing session by explaining that it creates a continuationHandle for later calls and that a fresh link replaces an expired or unfinished one.
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 gives clear usage context: use it when the taxpayer asks to file, and use a new session when a link expired or was left unfinished. It does not explicitly name continue_filing_session as the alternative for an existing valid handle, so the routing guidance is strong but not fully explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Takes the filing session's continuationHandle. Returns the packet schema a completed return packet is checked against (the packet holds no Social Security number, ITIN or PIN: the taxpayer types those on the filing page): requestPacketSchema=true returns the schema digest (packetSchemaSha256, sent with the completed packet), an outline whose larger parts are named sections, the section list and the packetStarterTemplates list; packetSchemaSection= returns one section and packetStarterTemplate= one complete starter packet, in which each taxpayer-specific value is the placeholder REPLACE_WITH_TAXPAYER_VALUE, refused by path until replaced, with its askTheTaxpayer messages (the questions for the taxpayer) and each preset answer listed in presets with how it is settled. Read-only: no tax facts are sent here and no return is written. The tax year is return.taxYear=2025 inside the packet, not a tool argument; any other argument is refused by name.
| Name | Required | Description | Default |
|---|---|---|---|
| continuationHandle | No | ||
| packetSchemaSection | No | One section of the packet schema, by a name from packetSchemaSections. Returns that section's members exactly as they sit in the full schema, where the outline shows {"x-section":"<name>"}, with the section's own sha256. | |
| requestPacketSchema | No | Returns the packet schema outline, its section list and digest, and the starter-template list; no tax facts are sent and no return is written. | |
| packetStarterTemplate | No | One complete starter packet, by an id from packetStarterTemplates.templates, with its askTheTaxpayer messages and its presets. |
| Name | Required | Description |
|---|---|---|
| blockers | No | |
| packetSchemaSha256 | No | SHA-256 of the compact JSON serialization of the FULL packet schema: the outline with every section's members put back in place of its marker. |
| packetSchemaOutline | No | The packet JSON Schema with each sectioned member replaced by {"x-section":"<section name>"}. |
| packetSchemaSection | No | One section: name, covers, parentPointer (JSON Pointer of the properties object its members belong to), sha256 and members. |
| packetSchemaSections | No | Every schema section left out of the outline: name, what it covers and its size in characters; the section's sha256 comes with the section. |
| packetSchemaRetrieval | No | |
| packetStarterTemplate | No | One starter template: id, shape, askTheTaxpayer, packet and presets. |
| packetStarterTemplates | No | How to use a starter template, the presets every template carries, and the list of templates; a template's packet comes back with packetStarterTemplate. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint/idempotent/destructive=false, so safety is covered, yet the description adds meaningful context: no tax facts are sent, no return is written, PII (SSN/ITIN/PIN) is deliberately absent and typed by the taxpayer, placeholders are refused by path until replaced, and unknown arguments are rejected by name. These are error-behavior and data-handling facts not derivable from the annotations or schema.
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?
Almost every clause carries information, so there is little padding, but the text is a single sprawling construction stitched together with colons and parentheses, which makes the three modes hard to scan. It is front-loaded only weakly, starting with continuationHandle rather than the purpose or the mode switch.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present, return values need not be described, yet the description covers them plus PII handling, placeholder refusal, tax-year location, and rejection of extraneous arguments. The mutual exclusivity of the three modes is enforced by the oneOf schema but only implied in prose, which is the one small gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 75% schema coverage the baseline is 3, and the description goes beyond it by explaining what each mode returns (outline shape {"x-section":"<name>"}, section-level sha256, presets and askTheTaxpayer messages, REPLACE_WITH_TAXPAYER_VALUE refusal semantics). It adds little about continuationHandle itself beyond naming it as the filing session handle, which keeps it below a 5.
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 a specific verb and resource ('Returns the packet schema a completed return packet is checked against') and enumerates the three retrieval modes, so an agent knows exactly what it gets. It does not distinguish itself from the siblings (create_filing_session, continue_filing_session), though their names suggest session mutation versus schema retrieval, making confusion unlikely.
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?
Mode selection is spelled out: requestPacketSchema=true for the digest/outline/section list, packetSchemaSection=<name> for one section, packetStarterTemplate=<id> for one starter packet. It also states what is not accepted ('any other argument is refused by name' and the tax year is not a tool argument), covering the when-not side. There is no explicit comparison to alternatives, but no real alternative exists among the siblings.
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.
get_packet_schema1 field changedOutput schema / properties / packetSchemaSha256 / constPrevious value: -"479843a3601eb03666dd41d05adc06d3ba0aa3e637ec279078aceb63d6a1ee2b"New value: +"34c2ce7e97cbec6df34f25178711020da3901c795f9b75f9f88401ea28ffba52"get_packet_schema1 field changedOutput schema / properties / packetSchemaSha256 / constPrevious value: -"7104f06daf589121a1be2c5cc87371346a0b8ccfaf724c15161eabfa7d897206"New value: +"479843a3601eb03666dd41d05adc06d3ba0aa3e637ec279078aceb63d6a1ee2b"get_packet_schema1 field changedOutput schema / properties / packetSchemaSha256 / constPrevious value: -"152387020477190adcc83d7ccd0554d5c95bf41db02f8800171419e7ae67f449"New value: +"7104f06daf589121a1be2c5cc87371346a0b8ccfaf724c15161eabfa7d897206"get_packet_schema1 field changedOutput schema / properties / packetSchemaSha256 / constPrevious value: -"d86b91d5a6b48d7442799ced5fb6f85b51a47eb1321f168c663c5140c2431d55"New value: +"152387020477190adcc83d7ccd0554d5c95bf41db02f8800171419e7ae67f449"continue_filing_sessioncreate_filing_sessionget_packet_schemaVerifiable US tax oracle for AI agents: cited, machine-checkable federal and state tax computation
Fax a form from your AI assistant. XipFax finds the right IRS fax number and shows the price first.
Brazilian AI-powered accounting & tax automation: NFS-e invoicing, CBS/IBS tax reform, compliance.
Merchant-of-record MCP: AI agents sell software & digital goods, global tax handled, BYO key.
Add one secure layer between your agents and this server.
