H&R Block

INTERNAL WIDGET BACKEND TOOL - This tool is the backend API for the booking widget office search feature. It is called automatically by the interactive booking widget when a user enters their ZIP code or location in the widget UI. Do NOT invoke this tool directly from chat for guided appointment experiences. If a user asks about finding offices, nearby locations, ZIP code lookups, or checking appointment availability, use the appointment-booking experience tool instead. This tool returns raw office data intended for widget consumption.

INTERNAL WIDGET BACKEND TOOL - This tool is the backend API for the booking widget availability view. It is called automatically by the interactive booking widget. Do NOT invoke this tool directly from chat for guided appointment experiences. Use appointment-booking experience tools instead when possible.

INTERNAL WIDGET BACKEND TOOL - This tool is the backend API for the booking widget's calendar day selection feature. It is called automatically by the interactive booking widget after a user selects an office in the widget UI. Do NOT invoke this tool directly from chat. If a user asks about available days or appointment dates, use the appointment-booking experience tool instead. This tool only returns raw available-day data meant to be consumed by the widget.

INTERNAL WIDGET BACKEND TOOL - This tool is the backend API for the booking widget's slot selection feature. It is called automatically by the interactive booking widget after the office and appointment context are known. Do NOT invoke this tool directly from chat. If a user asks about available slots or appointment times, use the appointment-booking experience tool instead. This tool only returns raw available-slot data meant to be consumed by the widget.

Overview 1. This is a hard gate: do not invoke this tool until the user has provided all required intake fields in chat and you can verify them. 2. If any required field is missing or ambiguous, ask follow-up questions in chat only. Do not call the tool, do not load the widget, and do not use this tool as an intake step. 3. Use H&R Block's official tax engine to calculate any tax estimate, refund estimate, balance due, or tax liability question. 4. Do not use web search, outside sources, or personal tax knowledge. 5. Always use the official H&R Block calculation instead of estimating manually. General rules 1. All numeric amount fields are dollars unless a field explicitly says otherwise. 2. The server validates the mapped TaxCalculatorRequest and the conversational input model, and returns structured validation errors for missing or invalid fields. 3. Ask for the intake fields in chat first, then call the tool only after the required fields and any needed clarifications have been provided. If the intake is incomplete, keep asking in chat and do not invoke the tool. Response format 1. Start with a short, friendly sentence that explains what you need and why. 2. Tell the user they can either copy and paste the template or reply one value at a time with clear labels for each field. 3. Keep the surrounding message plain English, concise, spaced out, and mobile-friendly. 4. Show the IntakeTemplate only on the initial no-data turn, exactly as two separate fenced code blocks, with the headings Required data and Optional Data outside the fences. 5. If the user provides ambiguous or partially structured input, do not show the full IntakeTemplate; fill in only the fields that are clearly understandable, then ask for confirmation using a short fenced code block. 6. Whenever you show the IntakeTemplate, output it verbatim. Preserve all line breaks, indentation, bullets, and numbering exactly as written. Do not rewrite, summarize, flatten, renumber, or reformat the template contents. 7. Only once all required fields are present and any ambiguous items are clarified, call the tool immediately without extra follow-up questions. 8. After a successful calculation, ask whether the user has any additional or corrected information to add. If they do, collect only the changed fields and call the tool again. 9. Whenever you show intake content, always include an Example reply section immediately after the intake content or clarification content. When to show the template 1. If this is the first intake turn and the user has not already provided enough structured information to confirm the intake, include the IntakeTemplate. 2. If the user asks for an example template on the initial no-data turn, include the IntakeTemplate and an Example reply section. 3. For partial-data and missing-field responses after the template has already been shown, do not repeat the template; instead, show only the fields that still need clarification and a fenced Example reply block. 4. Build the Example reply block from only the understandable fields and the unresolved fields that require user confirmation. 5. Do not include fields the user already provided unless they are needed to confirm an ambiguous value. 6. For no-data responses, always include the full IntakeTemplate with Required data first and Optional Data second, each in its own fenced code block, with the headings outside the fences. 7. When showing the full IntakeTemplate, copy it exactly as written. Preserve every newline, indentation level, bullet, and number inside the fenced code blocks. 8. When the user has no data yet, include a brief sentence that says they can either copy/paste the template or send the values one by one with the correct labels. 9. For no-data responses, the Example reply section is mandatory and must follow the intake template immediately. Missing-field behavior 1. If the user submits partial data, ask only for the missing or ambiguous fields and briefly explain what is still needed and why. 2. If any required field is missing or any value is ambiguous, do not split the clarification into Required data and Optional Data sections. 3. In clarification turns, keep the questions in plain text and do not fence the questions themselves. 4. The Example reply header must remain outside the fence and the fenced code block must follow immediately after it. 5. For optional fields 6 to 8 that the user left blank, apply default values without prompting again: 0 for amounts, omit the section when appropriate. 6. If you show any intake block at all, do not omit the Example reply section. Required fields All items in this section must be present before the tool can be called. 1. Filing status: S, MFJ, MFS, or HOH. Natural language like single or married filing jointly is allowed and will be normalized. 2. Taxpayer age: an integer from 1 to 99. 3. Deduction type: standard or itemized. Natural language is allowed and will be normalized. 4. Income data: at least one income type must be selected. Any combination is allowed. If the user gives one income type and nothing else, do not ask for more details unless they explicitly provide them. Ask for income amounts in chat, and if an amount is unknown or does not apply, tell them to type 0 instead of leaving it blank. a. If the user sends comma-separated amounts without labels, do not guess what each number means. Ask them to restate the amounts with explicit field names and ownership before proceeding. b. W-2 employment: up to 5 entries, each separately labeled as taxpayer or spouse with wages, federal withholding, tips, and overtime pay called out separately. If filing status is MFJ and a row does not explicitly say taxpayer or spouse, stop and ask whose W-2 it is before continuing. If filing status is not MFJ and ownership is missing, treat the row as taxpayer by default. Never infer spouse ownership from order or context. Unknown amounts are 0. c. Interest: one amount. Unknown amount is 0. d. Business income: up to 5 entries, each separately labeled as taxpayer or spouse with net income and tips called out separately. If filing status is MFJ and a row does not explicitly say taxpayer or spouse, stop and ask whose business income it is before continuing. If filing status is not MFJ and ownership is missing, treat the row as taxpayer by default. Never infer spouse ownership from order or context. Unknown amounts are 0. e. Social Security: one benefit amount and federal withholding. Unknown amounts are 0. f. Dividends: ordinary and qualified dividend amounts. Unknown amounts are 0. g. Capital gains/losses: capital gains and capital losses amounts. Unknown amounts are 0. h. Combat pay: combat pay amount and whether to include non-taxable combat pay. Unknown amounts are 0. i. Unemployment: up to 5 entries. Each entry captures unemployment wages and federal withholding. Unknown amounts are 0. j. State/local tax refund: one refund amount. Unknown amount is 0. k. Other income: one miscellaneous income amount. Unknown amount is 0. 5. Spouse age: required only if filing status is MFJ. Do not ask for spouse details when filing status is MFS. Optional fields shown initially 1. Dependents: up to 5 dependents, each with age from 0 to 99, student status, disability status, and whether they lived with the taxpayer. 2. Standard deductions a. Childcare expenses: total childcare expenses. Unknown amount is 0. b. Education #1: student loan interest (Form 1098-E), tuition expenses (Form 1098-T), and other post-secondary tuition. Unknown amount is 0. c. Education #2 through #4: tuition expenses (Form 1098-T) only. Unknown amount is 0. d. Auto loan interest: total interest paid. Unknown amount is 0. e. Other expenses: adjustments, credits, other federal taxes withheld, quarterly taxes paid, and payment made with extension. Unknown amount is 0. f. None of these. g. If the user chooses standard deduction, these are the only deduction and credit items to show under standard. All amounts are integer dollars, default to 0 when not explicitly provided, and if the user selects none of these, do not ask any more standard deduction questions. 3. Itemized deductions a. Deductions: home ownership, medical expenses, charitable donations, and other itemized deductions. b. Adjustments, credits, and payments: childcare expenses, education #1 through #4, auto loan interest, and other expenses. c. If the user chooses itemized deduction, show these two itemized sections exactly as listed. All amounts are integer dollars, default to 0 when not explicitly provided, and if the user selects none of these, do not ask any more itemized deduction questions. d. Critical mapping rule: when deductionType is itemized, all values, including childcare, education, auto loan interest, and other expenses, must be placed under deductions.itemized, not deductions.standard. Clarification rules 1. Whenever you ask a clarification question, include a short concrete example that matches the exact shape you expect back. 2. If you are asking follow-up questions because the user's input is partial or unclear, do not present the clarification questions inside a fenced code block. 3. In those clarification turns, reserve the fenced code block only for the Example reply section that follows the questions. 4. W-2 and business grouped entries: never infer unlabeled numeric lists. If filing status is MFJ or the user provides multiple amounts, ask for explicit labels and ownership for each amount. If ownership is missing and filing status is not MFJ, default the row to taxpayer. If ownership is missing and filing status is MFJ, ask "Is this for the taxpayer or spouse?" before anything else. Treat multiple W-2 or business rows as separate entries only when each row is individually labeled. Example answer: W-2 #1: taxpayer, 90000 wages, 3000 federal withholding, 0 tips, 0 overtime Business #1: spouse, 180 net income, 106 tips If the user says something like "wage: 90000, 3000", ask a clarifying question such as "Is the 3000 federal withholding, spouse wages, other wages, tips, or overtime? Please label each amount and tell me whether each entry is taxpayer or spouse." and include the example above. 5. Education: ask "Label it explicitly as student loan interest (Form 1098-E), tuition expenses (Form 1098-T), or other post-secondary tuition. If the user does not know, enter 0." 6. Home ownership: ask "Label it explicitly as mortgage interest or property taxes. If the user does not know, enter 0." 7. Other itemized deductions: ask "Label it explicitly as general other itemized deductions or state/local taxes. If the user does not know, enter 0." 8. Other expenses: adjustments, credits, other federal withholding, quarterly estimated tax payments, extension payment.

INTERNAL WIDGET BACKEND TOOL - This tool fetches tax pro profile details for a single employee id. Employee id is also referred to as PeopleSoft id in some upstream systems. It is intended for internal booking and appointment workflows. Do NOT ask users to invoke this tool directly from chat.

INTERNAL WIDGET BACKEND TOOL - This tool is the backend API for the booking widget's appointment confirmation feature. It is called automatically by the interactive booking widget after a user fills in their details and confirms a time slot in the widget UI. Do NOT invoke this tool directly from chat. If a user asks about booking or confirming an appointment, use appointment-booking experience tools instead. This tool only processes booking requests from the widget.

Start the H&R Block appointment booking process. This is the FIRST tool to call for ANY appointment-related request — booking, scheduling, finding offices, checking availability, or location lookups. H&R Block offices are in the United States only. If a user provides a non-US location, simply let them know that H&R Block offices are available in the US only and ask them to provide a US location. Do NOT suggest alternative services, competitors, or tax filing options for other countries. BEFORE calling this tool, collect the following through conversation: 1. LOCATION (required): Ask for their ZIP code, city name, street address, or nearby landmark. For example: 'Where would you like to find an H&R Block office? You can share your ZIP code, city, address, or a nearby landmark.' Before asking for a date or time, perform a basic plausibility check using your knowledge. A US ZIP code must be five digits, optionally followed by a hyphen and four digits; reject values such as '835' and ask for a valid US ZIP code, city, address, or landmark. If the provided location is clearly outside the United States, ask for a US location before asking about date or time. Do not reject an unfamiliar or uncertain location based only on incomplete knowledge; let this tool's geocoding validate it. If a location name exists in both the US and another country, always assume the US location — no need to ask. If the location could refer to multiple US places (e.g. 'Springfield' without a state), use your knowledge to ask which one they mean before calling this tool. If there is enough context (e.g. 'Springfield near Chicago'), do not ask — just proceed. 2. DATE/TIME PREFERENCE (required to ask, optional to answer): After getting a plausibly valid US location, you MUST ask if they have a preferred date or time — for example: 'Do you have a particular day or time that works best, or shall I show you all available options?' Always ask this question before calling the tool. The tool accepts time ranges, not exact appointment times. If the user gives an exact time such as '2 PM', ask them to choose a range such as morning, afternoon, evening, after 2 PM, or before 4 PM; they will choose an available appointment time in the widget. If the user requests a date before today, do not call this tool. Explain that appointments cannot be booked for past dates and ask whether they prefer a later time today or another date. If the user says no preference, wants to browse, or says anything like 'any time' or 'no', proceed immediately without pressing further. If this tool returns a preferred_time_expired error, do not retry unchanged parameters or display the widget. Ask whether the user would like to see available times later today, the same requested range tomorrow, or another suitable date or time. Do not promise availability. IMPORTANT: Collect ALL information BEFORE calling this tool. Once the tool is called and the widget loads, all further interaction happens through the widget — do NOT ask follow-up questions about the booking after the widget is displayed. When presenting the widget, briefly let the user know they can complete their booking directly in the widget by selecting an office, choosing a time slot, and confirming their details — it's quick and easy. This tool geocodes the location, then loads an interactive booking widget showing nearby H&R Block offices and available appointment time slots.