Intuit TurboTax

Use this when the user wants to book an appointment with a tax expert they've viewed. REQUIRES a prior expert_search call in this conversation. REQUIRED WORKFLOW: 1. expert_search must have been called first 2. From the search response's structuredContent, extract: - search_id (from structuredContent.search_id) - id (from structuredContent.experts[].id for the chosen expert) - availability_id (from structuredContent.experts[].closest_availability[].slots[].id for the time slot) 3. Collect from user: - first_name: User's first name - last_name: User's last name - phone_number: User's phone number (should be numbers only - you can remove formatting characters like +, -, ., spaces, or parentheses before passing) - email: User's email address 4. MANDATORY CONFIRMATION - You MUST explicitly confirm ALL booking details with the user and wait for their response: Display these details clearly: - Name (first and last) - Phone number - Email address - Expert name - Date and time of appointment Then ask: 'Please confirm these details are correct before I proceed with the booking.' 5. Only after user explicitly confirms (e.g., 'yes', 'looks good', 'confirm'), call this tool CRITICAL RULES: - NEVER skip the confirmation step - you MUST always confirm details and wait for user response before booking - ONLY use search_id, id, and availability_id from expert_search's structuredContent - NEVER make up or guess these values - NEVER show IDs (search_id, availability_id, etc.) to the user in conversation - If you don't have a recent expert_search result, call expert_search first - The availability_id must be from the specific time slot the user wants to book RETRY BEHAVIOR: - If the booking did not go through for any reason and the user wants to retry, you MAY retry the booking with the same parameters or different parameters DO NOT use this tool for: - Searching for experts (use expert_search instead) - Modifying or canceling bookings

book_appointment

Internal tool for uploading files. Called by the file upload widget with all files in a single call. Accepts a JSON array of file objects. For small static content files like tax forms.

document_upload_private

Fetch detailed availability for a specific expert. Use this tool when a user wants to see more time slots for an expert or schedule an appointment at a specific time. PARAMETERS: - search_id: REQUIRED. The search_id from the previous expert_search call - date: Optional date filter (YYYY-MM-DD). If not provided, returns all available slots RETURNS: - Expert basic info (name, photo, rating, experience) - Available time slots grouped by date - Widget UI for slot selection IMPORTANT: - DO NOT list specific times or time slots in your response to the user - DO NOT show internal IDs (search_id, availability_id, etc.) to the user - Let the widget display all time options interactively - Simply tell the user to select a time from the widget

expert_availability

Use this tool when the user wants help with their U.S. taxes or wants to find, search, or connect with a TurboTax tax expert. This tool only supports U.S. tax situations. Do not use it for users filing taxes in other countries. When invoked, display expert profiles with a single available time slot. **ConnectIntent Determination Rules** * First, call expert_search() without connect_intent parameter to discover available options * ONLY provide this parameter if you receive a validation error asking you to choose between options. * If you receive a validation error listing the available options, then present these options to the user and ask them to choose * After user selects an option, follow the next steps based on their selection. * If the user explicitly states they want to "book appointment", "schedule", or similar then use connect_intent='Book Appointment'. * If the user explicitly states they want to "connect now", "talk now", or similar then use connect_intent='Connect Now'. **After user selects connect_intent:** - If user selected 'Connect Now': Call expert_search(connect_intent='Connect Now') **ONLY IF user selected 'Book Appointment', ask about their tax situation BEFORE calling the tool:** When user selects 'Book Appointment', ask them to select one or more tax situations. Present the following list as clear selectable options: - "Job (W-2)" - "Self-employed/freelance" - "Sold stock" - "Sold crypto" - "Retirement income" - "Multiple states" - "Rental properties" - "Other income" Then call expert_search with both connect_intent='Book Appointment' AND the selected tax situations. IMPORTANT: Tax situations are NOT required for "Connect Now" option. - **Timezone parameter rules (Book Appointment only)** - Timezone is ONLY required for "Book Appointment". It is NOT required for "Connect Now". - NEVER guess or invent a timezone. - ONLY ask this parameter if you receive a validation error saying timezone is missing. When you do receive that error, then ask the user for their timezone and retry with the timezone parameter. - Ask the user for their timezone in a user-friendly way ("What's your timezone?" or "What city are you in?"). - The user may answer in any format. YOU must convert it to a valid IANA timezone string for the tool parameter. IMPORTANT - Connect Now Flow: - If structuredContent contains 'connect_link', NEVER mention or display the URL to the user. - Simply inform them that they can click the button in the widget to connect. - The connect_link is for widget use only and should never be exposed in your response text WHEN NOT TO USE THIS TOOL: - The user is filing taxes outside the United States. This tool only connects users with U.S. tax experts via TurboTax. - The user clicks "More times" → use `expert_availability` instead. - The user says "see more times" or "show more availability" → use `expert_availability`. - The user wants all available slots for a specific expert → use `expert_availability`. - The user is asking general questions about taxes, deductions, forms, timelines, rules, or strategies. - DO NOT use this tool for General tax questions, Filing returns, Tax calculations. ALLOWED TOOL INVOCATION CONDITIONS: - If connect_intent='Book Appointment': The user MUST have selected one or more tax situations from the required list. - If connect_intent='Connect Now': Tax situations are NOT required. You may call the tool without tax situations. - The user is not asking for more times, more availability, or detailed scheduling for a specific expert. **If any of these conditions are missing, incomplete, or ambiguous: DO NOT CALL THE TOOL. Ask the necessary questions to the user instead.**

expert_search

Display the tax document checklist showing required and completed documents. USE THIS WHEN: - User wants to see what tax documents are needed - User asks about their tax document checklist or status - User wants to know what documents they still need to provide UPDATING TAX SITUATION DATA: If the user's current message contains new tax situation information (e.g., mentions a new job, a new dependent, rental income, mortgage interest, or any other change), update that data using the interview tool before calling this tool. To update a single field: call interview(topic='tax_situation'), then interview(bulk_entry=True) to get field_ids, then interview(answers=[{"field_id": "<id>", "value": ...}], bulk_entry=True) to submit. To update multiple fields or complete a full interview: call interview(topic='tax_situation') and step through all pages. Call this tool after either flow completes. Users can always change their answers (e.g., 'I don't have a W-2 after all'). Use the interview tool to set the relevant field to false — the checklist will update to reflect the new situation. UPLOADED DOCUMENTS -- IMPORTANT: - Once a document has been uploaded, it CANNOT be deleted, removed, or modified through this tool or through chat. - There are no 'delete', 'remove', or 'undo upload' actions available. - If the user asks to delete or remove an uploaded document, tell them: 'Uploaded documents cannot be removed here. To manage uploaded files, use Continue in TurboTax.' - Never suggest or imply that uploaded documents can be deleted via chat. PARAMETER RULES: - DO NOT set the 'mode' parameter. Always omit it and let it default. - The 'mode' parameter is reserved for internal widget use only. - You must NEVER pass mode='full' unless the user's message explicitly contains the exact phrase 'mode full' or the widget instructs you to. - If you are unsure, do not set mode. The default behavior is correct. This tool supports mixed authentication. If the user has not authenticated, a preview screen is shown with an overview of checklist capabilities and a prompt to connect their TurboTax account. After authentication, the full personalized checklist is returned grouped by category with completion status. AFTER THE WIDGET (AUTHENTICATED FULL CHECKLIST): The tool result includes model-only instructions and neutral facts for a brief follow-up you compose for the user. Do not read the instruction block verbatim. After you show the checklist, speak to the user in a conversational tone (no bullet walls). Cover: (1) categories and items on their checklist, (2) documents already uploaded or connected, (3) an invitation to update in natural language, (4) next steps: they can upload documents in this checklist (per-item or dropzone) or use Continue in TurboTax to continue or file; do not imply uploads only happen in TurboTax (do not paste URLs). Use structuredContent.followUp and the 'facts' / 'prompt' lines in the text as inputs; translate them into natural second-person speech. 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.

tax_checklist

Gate tool execution on IRC §7216 tax disclosure consent for tools that have no widget. This is an INTERNAL gate tool -- it must ONLY be called when another tool's response explicitly directs you to call it. Pass originating_tool and originating_action so the consent widget can route the user back after acceptance; omitting them disables that routing. Do not proceed with the original tool's action until the user confirms consent via this widget. 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 -- always call this tool when directed; the server will show a fresh consent form. NEVER CALL THIS TOOL WHEN: - The user directly asks about consent (e.g. 'I want to give consent', 'show me the consent form', 'let me consent'). - The user mentions consent in any way without another tool's response directing you. - You think consent might be needed but no tool response has told you to call this. This tool is triggered ONLY by other tools' responses, NEVER by user messages alone. REVOCATION -- IMPORTANT: - This tool does NOT support revoking consent. It can only grant consent. - If the user asks to revoke, withdraw, or cancel their consent, do NOT call this tool. - Instead, tell the user: 'Consent cannot be revoked here. To revoke your 7216 consent, please reach out to TurboTax support for assistance.' - Never suggest or imply that revocation is possible through this tool or through chat. BEFORE CALLING -- CHECK YOUR CONTEXT FIRST: - Review the conversation history to determine if the user has ALREADY accepted consent. - If a previous tool response indicated 'already_consented' or consent was accepted earlier in this conversation, do NOT call this tool again. - Only call this tool if you have NO evidence of prior consent acceptance in the current session. - However, if the user previously DECLINED consent and a prior tool response already directed you to call this tool in this conversation, you MAY call this tool again to show a fresh consent form.

tax_consent_gate

Internal tool to record the user's 7216 consent decision. Called by the consent widget after user accepts or declines.

tax_consent_record_private

IMPORTANT: Only tax year 2025 estimates are supported. If the user asks for a different tax year, inform them that only 2025 estimates are currently available. USE THIS WHEN - the user explicitly requests a US federal tax estimate, refund or amount owed and required minimum info is provided. - If unclear or incomplete, ask clarifying questions before invoking. MINIMUM INFO - Filing status, confirm MFJ vs MFS - Age - Income and withholdings details - If filing status is MFJ or MFS, ask for spouse income and withholdings details. - Whether the tax payer can be claimed as a dependent on another person's tax return. CRITICAL BEHAVIORS (MUST FOLLOW): - **DO NOT USE WORLD KNOWLEDGE OR MAKE ASSUMPTIONS. USE ONLY THE CONTENT PROVIDED IN THE TOOL DESCRIPTION.** - Do NOT ask the user for the standard deduction amount. This is automatically calculated based on filing status. If its provided, ignore it. DO NOT INVOKE - For general tax questions, non-calculation requests, or when the user declines an estimate. PRIOR ESTIMATES - If a prior estimate exists and inputs haven't changed, reference it. Invoke only if values change or the user requests recalculation. INVOCATION RULES - Do NOT ask the user for the standard deduction amount. This is automatically calculated based on filing status. If its provided, ignore it. - Use only user-provided fields. Omit keys entirely if not provided. Do not send null, empty strings, or 0 unless the user stated 0 explicitly. - Do not invent values. Only pass fields the user provided. Don't pick values from examples. - Accept $ and commas; strip formatting before sending. Preserve cents when provided. - Do not annualize per-paycheck or monthly amounts unless the user provides frequency and you confirm conversion. - Use the latest values; ask if user is providing conflicting information. AFTER INVOKING - After invoking, use the tool response as a driver for follow-up questions. - The tool response includes follow-up questions. ALWAYS ask all the follow-up questions. They are NOT OPTIONAL. - ALWAYS suggest the next_actions included in the tool response. - Do not modify the tool's call-to-action text or link and any other returned values. - Present the summary and offer to re-run if inputs change. - The needs follow up status is included in the tool response. If it is "needs_follow_up", then ask all the follow-up questions and suggest the next actions also.

tax_estimate

Use this when user expresses intent to start filing, file taxes, or wants to know filing options. Display TurboTax filing options to help users choose how to file their taxes. Shows DIY, Expert Review, and Full Service options in a carousel format with features and call-to-action buttons. Post-Invocation Guidelines After the carousel is rendered, you must strictly present the next_actions provided in the tool's JSON response that lead to a tax expert consultation for personalized advice

tax_filing_options

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: # PAGE-BY-PAGE FLOW (typical linear interview): # Step 1 — start, get first page interview(topic="tax_situation") # Step 2 — collect answers from user, submit and advance interview(answers=[{"field_id": "filing_status", "value": "single"}, {"field_id": "had_w2", "value": true}], action="next") # Step 3 — repeat for each page until is_complete=True interview(answers=[{"field_id": "wages", "value": 85000}], action="next") # Peek at current page (resume after a break) interview() # Go back interview(action="back") # Bulk save across pages (no auto-merge, no navigation) 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.

interview