Conduct a structured multi-page tax interview. Each user has one active session — no session ID needed. INVALID COMBINATIONS — these are bugs:
- topic + anything else (answers, action, bulk_entry, etc.): topic only starts a session; no other params are valid in the same call
- answers with invented field names: field_id values must be copied from the tool response, never guessed
- any key other than field_id in an answers entry (not "key", "name", "id", "question", "answer", "fieldId", etc.)
- any parameter not in this list: topic, answers, action, bulk_entry
REMOVING OR CHANGING A SITUATION: There is no delete or remove operation. To undo a situation (e.g., user says "actually I don't have student loans"): interview(answers=[{"field_id": "<copied from response>", "value": false}], bulk_entry=True) Set the field to false — do not try to omit, delete, or use a remove_items key. MODE SELECTION — choose exactly one: | Goal | Params | |------------------------------------|---------------------------------| | Start new interview | topic only | | Start new interview + view all fields | topic only, then call again with bulk_entry=True | | Peek at current page | (no params) | | Save answers, stay on page | answers only | | Save answers and advance | answers + action | | Go back (no validation) | action="back" | | Complete interview | action="complete" | | Peek all fields (all pages) | bulk_entry=True | | Bulk save many fields | answers + bulk_entry=True | To save progress and exit mid-interview: submit answers without action — answers are persisted immediately. Resume any time by calling interview() with no parameters. PARAMETERS:
- topic (string): Interview topic. Starts a new session, replacing any existing one. NEVER combine with answers, action, or bulk_entry.
- answers (array): Each entry must be {"field_id": "...", "value": ...}. The key is always field_id. Copy field_id exactly from the returned fields list — never invent field names. Field types (boolean, string, number) are indicated in each field's definition in the response. For yes/no fields use JSON booleans (true/false), not strings.
- action (string): Copy the action_id value from the returned actions list. Valid values are page-specific — passing an invalid action returns an error listing valid options. Answers submitted alongside action are persisted before the action executes.
- bulk_entry (boolean, default false): NOT persisted — set true on every call where bulk behavior is needed.
AUTO-MERGE: Applies ONLY when action != "back" AND bulk_entry is false. When active: required fields that already have a current_value are preserved even if omitted from answers. When NOT active (action="back" or bulk_entry=True): only the fields you explicitly include in answers are updated. Fields you omit are not touched. UPDATING A SPECIFIC SITUATION (e.g. "I have mortgage interest", "I got married"): You do not know the field_ids in advance — you must fetch them first. Always use this two-step flow: Step 1 — start interview and get all fields (two separate calls): interview(topic="tax_situation") interview(bulk_entry=True) → returns ALL fields; read each field's field_id from the response Step 2 — submit using field_ids copied from the step 1 response: interview(answers=[{"field_id": "<copied from step 1 response>", "value": true}, ...], bulk_entry=True) EXAMPLES:
interview(topic="tax_situation")
interview(answers=[{"field_id": "filing_status", "value": "single"}, {"field_id": "had_w2", "value": true}], action="next")
interview(answers=[{"field_id": "wages", "value": 85000}], action="next")
interview()
interview(action="back")
interview(answers=[{"field_id": "had_w2", "value": true}, {"field_id": "wages", "value": 85000}], bulk_entry=True) BEHAVIORAL RULES:
- Never invent field IDs — copy field_id exactly from the returned fields list.
- current_value on each returned field is the stored answer — use it to avoid re-asking answered questions.
- Be conversational: present related options together ("Which apply: W-2, freelance, investments?"), let user respond naturally, then submit.
- After each advance, check progress in the response. Continue until complete or the user asks to stop.
- Stop immediately if the user says to quit — do not force completion.
HANDLING REQUIRED FIELDS (page-by-page mode only):
- Fields WITH current_value: Auto-preserved even if omitted from answers[]. Just confirm with user.
- Fields WITHOUT current_value: MUST collect from user before advancing with action="next".
- When using action="next": include ALL required fields on the current page that lack a current_value.
RECONCILE BEFORE ASKING
- USE WHAT YOU ALREADY KNOW (page-by-page mode only):
When stepping through pages one at a time, reconcile each field against facts already established in the conversation. For any required field the user stated explicitly in the current conversation, auto-fill it rather than re-asking. Only ask again if:
- The earlier statement was ambiguous
- The fact could have changed
- The tool shows a conflicting current_value
Treat previously stated exclusions like "no home," "no investments," and "nothing else applies" as valid answers to later matching questions unless the user indicates otherwise. VALIDATION ERRORS: Explain in plain language. Ask for missing info naturally. COMPLETION: Summarize what was gathered and explain next steps. CONSENT: This tool requires IRC §7216 tax disclosure consent. Do not proceed with this tool's action until consent is confirmed. The user must accept or deny using the buttons in the consent widget -- never via chat. If the user previously declined, that is NOT permanent; the server will show a fresh consent form.
