Skip to main content
Glama

Start filing session

create_filing_session
Destructive

Starts a filing session when the taxpayer asks to file a US federal individual income tax return. Receives no tax facts. Takes the taxpayer's answers to where they live now (residenceState), which state returns this filing carries (stateReturns) and whether anyone on the return lives in Connecticut or lived there this year (anyoneInConnecticut), and returns a continuationHandle, which identifies this filing session in later calls. Without a filingSessionUrl in the answer, the one link is returned when the service accepts the complete packet. A Connecticut filer's return is sent only after the taxpayer's own permission, so where those answers point to Connecticut or are not given, a deployment that files real returns also returns the filingSessionUrl at once and the packet follows that permission. Federal only: covers the US federal individual return and no state or local return. What can be filed: one original TY2025 federal Form 1040 or 1040-SR, or a tax year 2025 Form 1040-SS for a single bona fide resident of Puerto Rico with no Form 1040 filing requirement who owes self-employment tax on Schedule C business profit (net self-employment earnings of $400 or more), with no other income, credits, wages, estimated tax, or farm, partnership or church self-employment income; no state or local return, amendment, extension or 1040-NR. Accepted situations include W-2 wages (with the Form 2555 foreign earned income exclusion), 1099-INT and 1099-DIV with Schedule B, the foreign tax credit on dividends, some 1099-B/1099-DA sales, 1099-G, 1099-C (with the Form 982 bankruptcy, insolvency or principal residence exclusion), 1099-R with the Form 5329 additional taxes and Form 8606 IRA basis and Roth conversions, SSA-1099, W-2G, rental and royalty income (2025-placed rental depreciation and vehicle expenses on each rental's own Form 4562), some K-1 income, up to five Schedule C sole proprietorships (either spouse on a joint return) with Schedule SE and Form 1099-NEC, the self-employed health insurance deduction (Form 7206) and one SEP, SIMPLE IRA or solo 401(k) per person, head of household, some HSA (Form 8889), Archer or Medicare Advantage MSA distributions (Form 8853, filingChoices.form8853), Additional Medicare Tax, educator expenses, the residential clean energy credit, the clean vehicle credit for one new personal-use vehicle (Form 8936), the Lifetime Learning Credit, the refueling property credit (Form 8911), household employment taxes (Schedule H Part I, no federal unemployment tax), unreported tips (Form 4137, with Form 8959 above the threshold), Form 1099-NEC compensation reported as wages (Form 8919), dependents with the Child Tax Credit, Additional Child Tax Credit, Credit for Other Dependents and Earned Income Credit, the dependent care credit for children under 13, Form 8862 after an earlier-year disallowance, a decedent's return (a joint return signed by the surviving spouse, whose primary may be the spouse who died via filingChoices.jointReturnSignerFacts.primaryTaxpayerDied, or a single, head of household or married filing separately return signed by the personal representative, via filingChoices.decedentReturnSignerFacts, with a refund on Form 1310 via filingChoices.form1310), married filing separately in a community property state with wages, interest and dividends (Form 8958, filingChoices.communityPropertyAllocation), a cash-method Schedule F farm with a profit or an at-risk, materially participated loss and a profitable Form 4835 farm rental (each with the Form 8995 qualified business income deduction when all of its profit is qualified business income), Schedule 1-A deductions, standard or itemized deductions, student-loan interest, the qualified business income deduction (Form 8995; Form 8995-A for one Schedule C business and Schedule K-1 trades above the threshold), the American Opportunity Credit at the taxpayer's own Form 8863 amounts, the Saver's Credit, the premium tax credit (Form 8962), Net Investment Income Tax (Form 8960), K-1 returns included, Form 8615, estimated payments, and a refund or balance due (electronic funds withdrawal and Form 9465 included). Refused today: an EIC needing a disability answer, a Form 8862 child born or died in 2025, a dependent care credit for anyone 13 or older, a decedent's refund with a court-appointed representative, a joint return whose two spouses both died, community property married filing separately beyond allocated wages, interest and dividends, on a rental, section 179, a depreciated vehicle or 2025 amortization, a zero-profit Schedule C, a Schedule C loss without material participation or needing Form 6198, more than one business beside section 179 in two of them, statutory-employee income, Form 4361, Schedule C tips, Schedule F or Form 4835, the self-employed health insurance or retirement deduction beside the owner's own Schedule F, a K-1 or Marketplace coverage credits, a second plan of either kind for one person, and on Schedule C depletion (line 12), employee benefit programs (line 14) and the energy efficient commercial buildings deduction (line 27a). Blind, 65-or-older and no-one-can-claim-as-dependent are each required as an explicit answer; a blank is not read as no.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
emailNoThe taxpayer's email address, used only to email the verification code for the filing page, under the Terminal Tax privacy notice.
stateReturnsNoThe two-letter codes of the state returns this filing will carry; [] for a federal-only filing.
residenceStateNoThe state the taxpayer lives in now, as its two-letter code, e.g. NJ.
anyoneInConnecticutNoThe taxpayer's own yes or no: whether anyone on this return (the taxpayer, a spouse or a dependent) lives in Connecticut now or lived there at any time this tax year.

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
blockersNo
filingSessionUrlNo
continuationHandleNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A3.8/5.0
Behavior4/5

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

Despite safety annotations already being present, the description adds substantial behavioral context beyond them: it takes no tax facts, returns a continuationHandle, gates the filingSessionUrl behind Connecticut-filer permission, and notes required explicit answers (blind/65+/dependent) that cannot be blank. It does not, however, explain the destructiveHint=true implication or the irreversibility of filing.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness2/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The purpose is front-loaded in the first sentence, but the body is an enormous run-on crammed with exhaustive eligibility lists that overwhelm the reader. Far more prose than an agent needs to select and invoke the tool, and the density makes it hard to parse rather than concise.

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

Completeness4/5

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

The tool is complex (mutation-style session creation) with an output schema and full annotation coverage, and the description supplies the scope, permission gating and return handle needed to call it correctly. The output schema carries return-value detail, so the remaining gap around failure modes is minor rather than disqualifying.

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

Parameters4/5

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

With 100% schema coverage the baseline is 3, and the description adds meaning beyond the schema: it frames residenceState/stateReturns/anyoneInConnecticut as the taxpayer's own answers and explains the Connecticut permission rationale behind that flag. It omits any description of the email parameter, but the schema covers it.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The first sentence gives a specific verb and resource ('Starts a filing session') plus a clear trigger ('when the taxpayer asks to file a US federal individual income tax return'). It distinguishes the start of a session from a continuation by stating it returns a continuationHandle for later calls, though it never names the sibling continue_filing_session directly.

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

Usage Guidelines4/5

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

It states the trigger condition and provides extensive when-not coverage through the 'Accepted situations' and 'Refused today' lists, so an agent can judge whether this tool can handle a given return. It stops short of naming alternatives, so it does not reach the explicit when/when-not/alternatives bar of a 5.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.