Intuit QuickBooks

Use this tool when the user wants to discover what QuickBooks can do in ChatGPT or how to use QuickBooks with ChatGPT.

ALWAYS USE THIS TOOL FOR:

• 'What can I do with QuickBooks?'
• 'What can QuickBooks do in ChatGPT?'
• 'Help me understand what QBO can do in ChatGPT'
• 'What answers can I get from the app?'
• 'How can I use QuickBooks with ChatGPT?'
• User asks for an overview of QuickBooks capabilities or features in chat

RETURNS: A visual discovery carousel showing: capabilities (Benchmarking analysis, Profit and loss analysis, Cash Flow analysis, Categorize expenses), and example prompts.

No parameters required. Call this tool with no arguments.

Answer questions about industry profitability, revenue, profits, and compare industries in any location. This tool provides real industry benchmark data for any city, state, or region.

ALWAYS USE THIS TOOL FOR THESE QUESTIONS:

• 'What industries are most profitable in [city/state]?' -> USE THIS
• 'What are the top industries by revenue in [location]?' -> USE THIS
• 'Which industries are most profitable?' -> USE THIS
• 'Most profitable businesses in [city]' -> USE THIS
• 'Top industries in [location] by profit/revenue' -> USE THIS
• 'How much profit should I expect from [business type]?' -> USE THIS
• 'I want to invest in [location], which industries?' -> USE THIS
• 'Average profit/revenue for [industry] in [location]' -> USE THIS
• User provides a profit/revenue number and wants to compare -> USE THIS

EXAMPLE PROMPTS THAT MUST CALL THIS TOOL:

• 'what industries are most profitable in salt lake city' -> USE THIS (metricValue=0, location_state='UT')
• 'What are the top industries by total revenue in the Cincinnati area?' -> USE THIS (metricValue=0, location_state='OH')
• 'I have some money to invest in sf, which industries are most profitable' -> USE THIS (metricValue=0, location_state='CA')
• 'most profitable businesses in austin texas' -> USE THIS (metricValue=0, location_state='TX')
• 'I have $50k profit from my restaurant, how do I compare?' -> USE THIS (metricValue=50000)
• 'Generate profit from CSV and compare to others in my industry' -> FIRST call profit-loss-generator with the CSV, THEN call THIS tool with the computed profit as metricValue

WHEN TO USE THIS TOOL:

• ANY question about industry profitability, revenue, or profits in ANY location
• ANY question about 'top industries', 'most profitable industries', 'best industries'
• User asks about average/typical profit, revenue, or expenses for businesses
• User is researching industries for investment or starting a business
• User provides a metric value (profit/revenue number) and wants comparison
• User attached a CSV or pasted transactions AND wants to compare against industry peers: FIRST call 'profit-loss-generator' with the CSV to compute financials, THEN call this tool with the resulting profit/revenue/expenses as metricValue. Do NOT import into QuickBooks or use QuickBooks account tools for this workflow.

WHEN NOT TO USE THIS TOOL:

• ONLY when user explicitly wants to pull data FROM their QuickBooks account (no CSV or transactions provided)
• Example: 'Benchmark my QuickBooks company' -> use benchmarking-quickbooks-account

This tool supports TWO MODES: 1. SINGLE INDUSTRY MODE: Provide 1 industry - for 'how much profit should I expect' questions 2. MULTI-INDUSTRY MODE: Provide 2-5 industries TOTAL (including the user's own industry if applicable) - for 'which industries are most profitable' questions (pick diverse industries like Retail, Healthcare, Real Estate, Professional Services, Restaurants) IMPORTANT: The total count must NEVER exceed 5. If the user says 'compare with 5 others', include user's industry + 4 others = 5 total. If the user requests more than 5 industries, select the 5 most relevant ones and inform the user that the maximum comparison is 5 industries at a time.

IMPORTANT: For research questions without user's own numbers, set metricValue to 0.

PARAMETERS:

• industryType: REQUIRED. Array of 1-5 industry types to compare (this is the max, NEVER send more than 5).

The user's own industry counts toward this limit. If user says 'compare with N others', send user's industry + others, capped at 5 total. If user requests more than 5, pick the 5 most relevant and tell the user the max is 5. For 'how much profit' questions: provide 1 industry (e.g., ['Retail'] for clothing store) For 'which industries are most profitable' questions: provide 2-5 industries to compare Note: Partial matches work (e.g., 'Restaurant' matches 'Restaurants & Cafés') Use the short industry name from the NAICS code: first use the 4-digit NAICS subsector name (e.g., 2123=Sand & Gravel Mining, 7225=Restaurants), then fall back to the 2-digit sector name if no specific subsector applies (e.g., 21=Mining, 23=Construction, 44-45=Retail). Examples: ['Mining'], ['Retail', 'Healthcare', 'Real Estate']

• naics codes (naicsCode): REQUIRED. Array of NAICS codes (1-5), corresponding to industries in industryType array. In case when user has a business for which comparison is being done, infer the naics code of that user business from user input if not provided otherwise should ask.

Must have same length as industryType array. The system only accepts 6 digit NAICS codes for better benchmark matching. CRITICAL: NAICS codes MUST be valid 6-digit codes from the official U.S. Census Bureau NAICS taxonomy (https://www.census.gov). Do NOT fabricate or round codes. Common mistakes to avoid:

• Do NOT use codes ending in '00' or '0' unless they are real codes (e.g., '236100' is INVALID, use '236115' or '236118' instead)
• Do NOT use codes ending in '10' unless they actually exist (e.g., '541610' is INVALID, use '541611' or '541612' instead which is closest match to the industry type)
• Always verify the full 6-digit code exists. For example: Construction='236220', Consulting='541611', Restaurants='722511', Legal='541110', Real Estate='531210'

Examples: ['531210'] for single (6-digit), ['531210', '722511', '541110'] for multiple

• financial metric value (metricValue): REQUIRED. Company's actual value for the metric (can be positive, negative, or 0).

Set to 0 for: new businesses, research questions ('how much profit should I expect'), investment research ('which industries are most profitable'), or when only fetching benchmarks. Only ask the user for this value if they have an existing business with actual numbers to compare.

• company name (companyName): REQUIRED. Name of the company being analyzed.

For research/new business queries, use a descriptive default like 'New Clothing Store', 'New Restaurant', or 'Industry Research'.

• company industry (companyIndustry): OPTIONAL. The specific industry of the user's company (from the industryType list).

Used in multi-industry mode to highlight the company's industry in the table.

• location state (location_state): REQUIRED. State for regional benchmarks. MUST be a 2-letter uppercase state code (e.g., 'CA', 'TX', 'NY', 'FL'). Never use full state names like 'California' or 'New York'. Infer from context if possible (e.g., 'SF' or 'San Francisco' means 'CA').
• location county (location_county): OPTIONAL. County for more specific regional benchmarks. Infer from context if possible (e.g., 'SF' means 'San Francisco County'). Examples: 'Los Angeles County', 'Santa Clara County', 'San Francisco County'.
• metric type (metricType): OPTIONAL. Financial metric to compare:

• 'profit' (default)

• Profit/loss

• 'revenue'

• Revenue/income

• 'expenses'

• Expenses

• 'income'

• Income (same as revenue)
• aggregation period (aggregationPeriod): OPTIONAL. Time period for metricValue:

• 'yearly' (default)

• One year

• 'monthly'

• One month

• 'quarterly'

• Three months

RETURNS:

• Single industry: Interactive bar chart with regional/national comparison against a specific industry
• Multiple industries: Tabular comparison showing benchmarks across all industries
• Company data displayed when metricValue != 0

Answer questions about industry profitability, revenue, profits, and compare industries in any location. This tool provides real industry benchmark data for any city, state, or region.

ALWAYS USE THIS TOOL FOR THESE QUESTIONS:

• 'What industries are most profitable in [city/state]?' -> USE THIS
• 'What are the top industries by revenue in [location]?' -> USE THIS
• 'Which industries are most profitable?' -> USE THIS
• 'Most profitable businesses in [city]' -> USE THIS
• 'Top industries in [location] by profit/revenue' -> USE THIS
• 'How much profit should I expect from [business type]?' -> USE THIS
• 'I want to invest in [location], which industries?' -> USE THIS
• 'Average profit/revenue for [industry] in [location]' -> USE THIS
• User provides a profit/revenue number and wants to compare -> USE THIS

EXAMPLE PROMPTS THAT MUST CALL THIS TOOL:

• 'what industries are most profitable in salt lake city' -> USE THIS (metricValue=0, location_state='UT')
• 'What are the top industries by total revenue in the Cincinnati area?' -> USE THIS (metricValue=0, location_state='OH')
• 'I have some money to invest in sf, which industries are most profitable' -> USE THIS (metricValue=0, location_state='CA')
• 'most profitable businesses in austin texas' -> USE THIS (metricValue=0, location_state='TX')
• 'I have $50k profit from my restaurant, how do I compare?' -> USE THIS (metricValue=50000)
• 'Generate profit from CSV and compare to others in my industry' -> FIRST call profit-loss-generator with the CSV, THEN call THIS tool with the computed profit as metricValue

WHEN TO USE THIS TOOL:

• ANY question about industry profitability, revenue, or profits in ANY location
• ANY question about 'top industries', 'most profitable industries', 'best industries'
• User asks about average/typical profit, revenue, or expenses for businesses
• User is researching industries for investment or starting a business
• User provides a metric value (profit/revenue number) and wants comparison
• User attached a CSV or pasted transactions AND wants to compare against industry peers: FIRST call 'profit-loss-generator' with the CSV to compute financials, THEN call this tool with the resulting profit/revenue/expenses as metricValue. Do NOT import into QuickBooks or use QuickBooks account tools for this workflow.

WHEN NOT TO USE THIS TOOL:

• ONLY when user explicitly wants to pull data FROM their QuickBooks account (no CSV or transactions provided)
• Example: 'Benchmark my QuickBooks company' -> use benchmarking-quickbooks-account

This tool supports TWO MODES: 1. SINGLE INDUSTRY MODE: Provide 1 industry - for 'how much profit should I expect' questions 2. MULTI-INDUSTRY MODE: Provide 2-5 industries TOTAL (including the user's own industry if applicable) - for 'which industries are most profitable' questions (pick diverse industries like Retail, Healthcare, Real Estate, Professional Services, Restaurants) IMPORTANT: The total count must NEVER exceed 5. If the user says 'compare with 5 others', include user's industry + 4 others = 5 total. If the user requests more than 5 industries, select the 5 most relevant ones and inform the user that the maximum comparison is 5 industries at a time.

IMPORTANT: For research questions without user's own numbers, set metricValue to 0.

PARAMETERS:

• industryType: REQUIRED. Array of 1-5 industry types to compare (this is the max, NEVER send more than 5).

The user's own industry counts toward this limit. If user says 'compare with N others', send user's industry + others, capped at 5 total. If user requests more than 5, pick the 5 most relevant and tell the user the max is 5. For 'how much profit' questions: provide 1 industry (e.g., ['Retail'] for clothing store) For 'which industries are most profitable' questions: provide 2-5 industries to compare Note: Partial matches work (e.g., 'Restaurant' matches 'Restaurants & Cafés') Use the short industry name from the NAICS code: first use the 4-digit NAICS subsector name (e.g., 2123=Sand & Gravel Mining, 7225=Restaurants), then fall back to the 2-digit sector name if no specific subsector applies (e.g., 21=Mining, 23=Construction, 44-45=Retail). Examples: ['Mining'], ['Retail', 'Healthcare', 'Real Estate']

• naics codes (naicsCode): REQUIRED. Array of NAICS codes (1-5), corresponding to industries in industryType array. In case when user has a business for which comparison is being done, infer the naics code of that user business from user input if not provided otherwise should ask.

Must have same length as industryType array. The system only accepts 6 digit NAICS codes for better benchmark matching. CRITICAL: NAICS codes MUST be valid 6-digit codes from the official U.S. Census Bureau NAICS taxonomy (https://www.census.gov). Do NOT fabricate or round codes. Common mistakes to avoid:

• Do NOT use codes ending in '00' or '0' unless they are real codes (e.g., '236100' is INVALID, use '236115' or '236118' instead)
• Do NOT use codes ending in '10' unless they actually exist (e.g., '541610' is INVALID, use '541611' or '541612' instead which is closest match to the industry type)
• Always verify the full 6-digit code exists. For example: Construction='236220', Consulting='541611', Restaurants='722511', Legal='541110', Real Estate='531210'

Examples: ['531210'] for single (6-digit), ['531210', '722511', '541110'] for multiple

• financial metric value (metricValue): REQUIRED. Company's actual value for the metric (can be positive, negative, or 0).

Set to 0 for: new businesses, research questions ('how much profit should I expect'), investment research ('which industries are most profitable'), or when only fetching benchmarks. Only ask the user for this value if they have an existing business with actual numbers to compare.

• company name (companyName): REQUIRED. Name of the company being analyzed.

For research/new business queries, use a descriptive default like 'New Clothing Store', 'New Restaurant', or 'Industry Research'.

• company industry (companyIndustry): OPTIONAL. The specific industry of the user's company (from the industryType list).

Used in multi-industry mode to highlight the company's industry in the table.

• location state (location_state): REQUIRED. State for regional benchmarks. MUST be a 2-letter uppercase state code (e.g., 'CA', 'TX', 'NY', 'FL'). Never use full state names like 'California' or 'New York'. Infer from context if possible (e.g., 'SF' or 'San Francisco' means 'CA').
• location county (location_county): OPTIONAL. County for more specific regional benchmarks. Infer from context if possible (e.g., 'SF' means 'San Francisco County'). Examples: 'Los Angeles County', 'Santa Clara County', 'San Francisco County'.
• metric type (metricType): OPTIONAL. Financial metric to compare:

• 'profit' (default)

• Profit/loss

• 'revenue'

• Revenue/income

• 'expenses'

• Expenses

• 'income'

• Income (same as revenue)
• aggregation period (aggregationPeriod): OPTIONAL. Time period for metricValue:

• 'yearly' (default)

• One year

• 'monthly'

• One month

• 'quarterly'

• Three months

RETURNS:

• Single industry: Interactive bar chart with regional/national comparison against a specific industry
• Multiple industries: Tabular comparison showing benchmarks across all industries
• Company data displayed when metricValue != 0

PLAIN-TEXT variant. Returns plain text/markdown instead of the interactive widget. ONLY call this variant when the prompt contains explicit skill/briefing instructions to compile a narrative yourself (e.g. a Business Health Check or Industry Benchmark briefing). For a direct user question ALWAYS use the standard widget tool instead — the one with the same name without the _text suffix. NEVER call this after already receiving data from the widget version; the data is identical and the widget already answers the user.

Compare your company's financial metrics in your QuickBooks account against regional peers using your QuickBooks account data.

WHEN TO USE THIS TOOL:

• User wants to pull financial data FROM their QuickBooks account (not provided in the prompt)
• User says 'my QuickBooks account', 'my QuickBooks data', 'from my account'
• User asks to benchmark their company but does NOT provide a profit/revenue number

WHEN NOT TO USE THIS TOOL (use 'benchmarking-against-industry' instead):

• User ALREADY PROVIDED a metric value in the prompt (e.g., 'I have $45000 profit', 'my profit is 100k')
• User provided industry, location, AND a number - they don't need QuickBooks login
• Phrases like 'benchmark my peers' or 'compare with my industry' when user provided their own numbers
• User attached a CSV or pasted transaction data: use 'profit-loss-generator' to compute financials first, then 'benchmarking-against-industry' with the result. Do NOT import the CSV into QuickBooks for this workflow.

CRITICAL INSTRUCTIONS

• YOU MUST FOLLOW THESE EXACTLY:

DO NOT CALL THIS TOOL IF USER ALREADY PROVIDED A METRIC VALUE (profit, revenue, expenses) IN THEIR PROMPT. DO NOT CALL THIS TOOL AGAIN IF CUSTOMER PROVIDED THE INDUSTRY INFORMATION. CALL THE industry-recommendation tool to show you industry recommendations and let you select one, then use the 'quickbooks-profile-info-update' tool to save it in QuickBooks. DO NOT CALL THIS TOOL IF CUSTOMER DECLINED TO SIGN IN WHILE YOU ASKED FOR IT BEFORE CALLING THIS TOOL. In this case, you can suggest to the user whether they would want to perform benchmarking without using their QuickBooks account, since they declined to sign in.

IMPORTANT: Before calling this tool, you MUST first call the 'company-info' tool to establish the QuickBooks connection. If 'company-info' has not been called yet in this conversation, call it first, then call this tool. This ensures the user is authenticated.

This tool uses your QuickBooks account profile and transaction data automatically. It will: 1. Check if you're signed in to QuickBooks 2. Verify your company profile is complete (company name, industry, location, NAICS code) 3. Calculate your financial metrics from your QuickBooks transactions 4. Generate benchmarking analysis comparing your company against regional peers

PARAMETERS:

• metricType: OPTIONAL. Financial metric to compare: 'profit' (default), 'revenue', 'expenses', 'income'
• aggregationPeriod: OPTIONAL. Time period: 'yearly' (default), 'monthly', 'quarterly'

COMPANY INFORMATION: Your company information (name, industry, location, NAICS code) is automatically retrieved from your QuickBooks profile. If any required information is missing, the tool will ask you to provide it.

METRIC CALCULATION: Your financial metric value is automatically calculated from your QuickBooks transactions:

• For 'profit': Sum of all income transactions minus expenses and COGS
• For 'revenue'/'income': Sum of all income transactions
• For 'expenses': Sum of all expense and COGS transactions

RETURNS:

• Interactive benchmarking analysis with bar charts comparing your company against regional peers
• If you have no transactions or metric value is 0, shows a message encouraging you to connect bank or upload transactions

MULTI-INDUSTRY COMPARISON: This tool only supports SINGLE industry comparison (user's own industry from their QuickBooks profile). If the user wants to compare their QuickBooks data against MULTIPLE industries: 1. First call this tool to get the user's metric value (profit/revenue/expenses) 2. Then use the 'benchmarking-against-industry' tool with:

• The metric value from step 1
• The company name from step 1
• Multiple industries the user wants to compare against
• The user's location (state) from step 1

This allows multi-industry comparison using the user's actual QuickBooks data.

Compare your company's financial metrics in your QuickBooks account against regional peers using your QuickBooks account data.

WHEN TO USE THIS TOOL:

• User wants to pull financial data FROM their QuickBooks account (not provided in the prompt)
• User says 'my QuickBooks account', 'my QuickBooks data', 'from my account'
• User asks to benchmark their company but does NOT provide a profit/revenue number

WHEN NOT TO USE THIS TOOL (use 'benchmarking-against-industry' instead):

• User ALREADY PROVIDED a metric value in the prompt (e.g., 'I have $45000 profit', 'my profit is 100k')
• User provided industry, location, AND a number - they don't need QuickBooks login
• Phrases like 'benchmark my peers' or 'compare with my industry' when user provided their own numbers
• User attached a CSV or pasted transaction data: use 'profit-loss-generator' to compute financials first, then 'benchmarking-against-industry' with the result. Do NOT import the CSV into QuickBooks for this workflow.

CRITICAL INSTRUCTIONS

• YOU MUST FOLLOW THESE EXACTLY:

DO NOT CALL THIS TOOL IF USER ALREADY PROVIDED A METRIC VALUE (profit, revenue, expenses) IN THEIR PROMPT. DO NOT CALL THIS TOOL AGAIN IF CUSTOMER PROVIDED THE INDUSTRY INFORMATION. CALL THE industry-recommendation tool to show you industry recommendations and let you select one, then use the 'quickbooks-profile-info-update' tool to save it in QuickBooks. DO NOT CALL THIS TOOL IF CUSTOMER DECLINED TO SIGN IN WHILE YOU ASKED FOR IT BEFORE CALLING THIS TOOL. In this case, you can suggest to the user whether they would want to perform benchmarking without using their QuickBooks account, since they declined to sign in.

IMPORTANT: Before calling this tool, you MUST first call the 'company-info' tool to establish the QuickBooks connection. If 'company-info' has not been called yet in this conversation, call it first, then call this tool. This ensures the user is authenticated.

This tool uses your QuickBooks account profile and transaction data automatically. It will: 1. Check if you're signed in to QuickBooks 2. Verify your company profile is complete (company name, industry, location, NAICS code) 3. Calculate your financial metrics from your QuickBooks transactions 4. Generate benchmarking analysis comparing your company against regional peers

PARAMETERS:

• metricType: OPTIONAL. Financial metric to compare: 'profit' (default), 'revenue', 'expenses', 'income'
• aggregationPeriod: OPTIONAL. Time period: 'yearly' (default), 'monthly', 'quarterly'

COMPANY INFORMATION: Your company information (name, industry, location, NAICS code) is automatically retrieved from your QuickBooks profile. If any required information is missing, the tool will ask you to provide it.

METRIC CALCULATION: Your financial metric value is automatically calculated from your QuickBooks transactions:

• For 'profit': Sum of all income transactions minus expenses and COGS
• For 'revenue'/'income': Sum of all income transactions
• For 'expenses': Sum of all expense and COGS transactions

RETURNS:

• Interactive benchmarking analysis with bar charts comparing your company against regional peers
• If you have no transactions or metric value is 0, shows a message encouraging you to connect bank or upload transactions

MULTI-INDUSTRY COMPARISON: This tool only supports SINGLE industry comparison (user's own industry from their QuickBooks profile). If the user wants to compare their QuickBooks data against MULTIPLE industries: 1. First call this tool to get the user's metric value (profit/revenue/expenses) 2. Then use the 'benchmarking-against-industry' tool with:

• The metric value from step 1
• The company name from step 1
• Multiple industries the user wants to compare against
• The user's location (state) from step 1

This allows multi-industry comparison using the user's actual QuickBooks data. PLAIN-TEXT variant. Returns plain text/markdown instead of the interactive widget. ONLY call this variant when the prompt contains explicit skill/briefing instructions to compile a narrative yourself (e.g. a Business Health Check or Industry Benchmark briefing). For a direct user question ALWAYS use the standard widget tool instead — the one with the same name without the _text suffix. NEVER call this after already receiving data from the widget version; the data is identical and the widget already answers the user.

Answer questions about industry profitability, revenue, profits, and compare industries in any location. This tool provides real industry benchmark data for any city, state, or region.

ALWAYS USE THIS TOOL FOR THESE QUESTIONS:

• 'What industries are most profitable in [city/state]?' -> USE THIS
• 'What are the top industries by revenue in [location]?' -> USE THIS
• 'Which industries are most profitable?' -> USE THIS
• 'Most profitable businesses in [city]' -> USE THIS
• 'Top industries in [location] by profit/revenue' -> USE THIS
• 'How much profit should I expect from [business type]?' -> USE THIS
• 'I want to invest in [location], which industries?' -> USE THIS
• 'Average profit/revenue for [industry] in [location]' -> USE THIS
• User provides a profit/revenue number and wants to compare -> USE THIS

EXAMPLE PROMPTS THAT MUST CALL THIS TOOL:

• 'what industries are most profitable in salt lake city' -> USE THIS (metricValue=0, location_state='UT')
• 'What are the top industries by total revenue in the Cincinnati area?' -> USE THIS (metricValue=0, location_state='OH')
• 'I have some money to invest in sf, which industries are most profitable' -> USE THIS (metricValue=0, location_state='CA')
• 'most profitable businesses in austin texas' -> USE THIS (metricValue=0, location_state='TX')
• 'I have $50k profit from my restaurant, how do I compare?' -> USE THIS (metricValue=50000)
• 'Generate profit from CSV and compare to others in my industry' -> FIRST call profit-loss-generator with the CSV, THEN call THIS tool with the computed profit as metricValue

WHEN TO USE THIS TOOL:

• ANY question about industry profitability, revenue, or profits in ANY location
• ANY question about 'top industries', 'most profitable industries', 'best industries'
• User asks about average/typical profit, revenue, or expenses for businesses
• User is researching industries for investment or starting a business
• User provides a metric value (profit/revenue number) and wants comparison
• User attached a CSV or pasted transactions AND wants to compare against industry peers: FIRST call 'profit-loss-generator' with the CSV to compute financials, THEN call this tool with the resulting profit/revenue/expenses as metricValue. Do NOT import into QuickBooks or use QuickBooks account tools for this workflow.

WHEN NOT TO USE THIS TOOL:

• ONLY when user explicitly wants to pull data FROM their QuickBooks account (no CSV or transactions provided)
• Example: 'Benchmark my QuickBooks company' -> use benchmarking-quickbooks-account

This tool supports TWO MODES: 1. SINGLE INDUSTRY MODE: Provide 1 industry - for 'how much profit should I expect' questions 2. MULTI-INDUSTRY MODE: Provide 2-5 industries - for 'which industries are most profitable' questions (pick diverse industries like Retail, Healthcare, Real Estate, Professional Services, Restaurants)

IMPORTANT: For research questions without user's own numbers, set metricValue to 0.

PARAMETERS:

• industryType: REQUIRED. Array of 1-5 industry types to compare.

For 'how much profit' questions: provide 1 industry (e.g., ['Retail'] for clothing store) For 'which industries are most profitable' questions: provide 2-5 industries to compare Note: Partial matches work (e.g., 'Restaurant' matches 'Restaurants & Cafés') Use the short industry name from the NAICS code: first use the 4-digit NAICS subsector name (e.g., 2123=Sand & Gravel Mining, 7225=Restaurants), then fall back to the 2-digit sector name if no specific subsector applies (e.g., 21=Mining, 23=Construction, 44-45=Retail). Examples: ['Mining'], ['Retail', 'Healthcare', 'Real Estate']

• naics codes (naicsCode): REQUIRED. Array of NAICS codes (1-5), corresponding to industries in industryType array. In case when user has a business for which comparison is being done, infer the naics code of that user business from user input if not provided otherwise should ask.

Must have same length as industryType array. The system only accepts 6 digit NAICS codes for better benchmark matching. Examples: ['531210'] for single (6-digit), ['531210', '722511', '541110'] for multiple

• financial metric value (metricValue): REQUIRED. Company's actual value for the metric (can be positive, negative, or 0).

Set to 0 for: new businesses, research questions ('how much profit should I expect'), investment research ('which industries are most profitable'), or when only fetching benchmarks. Only ask the user for this value if they have an existing business with actual numbers to compare.

• company name (companyName): REQUIRED. Name of the company being analyzed.

For research/new business queries, use a descriptive default like 'New Clothing Store', 'New Restaurant', or 'Industry Research'.

• company industry (companyIndustry): OPTIONAL. The specific industry of the user's company (from the industryType list).

Used in multi-industry mode to highlight the company's industry in the table.

• location state (location_state): REQUIRED. State for regional benchmarks. MUST be a 2-letter uppercase state code (e.g., 'CA', 'TX', 'NY', 'FL'). Never use full state names like 'California' or 'New York'. Infer from context if possible (e.g., 'SF' or 'San Francisco' means 'CA').
• location county (location_county): OPTIONAL. County for more specific regional benchmarks. Infer from context if possible (e.g., 'SF' means 'San Francisco County'). Examples: 'Los Angeles County', 'Santa Clara County', 'San Francisco County'.
• metric type (metricType): OPTIONAL. Financial metric to compare:

• 'profit' (default)

• Profit/loss

• 'revenue'

• Revenue/income

• 'expenses'

• Expenses

• 'income'

• Income (same as revenue)
• aggregation period (aggregationPeriod): OPTIONAL. Time period for metricValue:

• 'yearly' (default)

• One year

• 'monthly'

• One month

• 'quarterly'

• Three months

RETURNS:

• Single industry: Interactive bar chart with regional/national comparison against a specific industry
• Multiple industries: Tabular comparison showing benchmarks across all industries
• Company data displayed when metricValue != 0

Compare your company's financial metrics in your QuickBooks account against regional peers using your QuickBooks account data.

WHEN TO USE THIS TOOL:

• User wants to pull financial data FROM their QuickBooks account (not provided in the prompt)
• User says 'my QuickBooks account', 'my QuickBooks data', 'from my account'
• User asks to benchmark their company but does NOT provide a profit/revenue number

WHEN NOT TO USE THIS TOOL (use 'benchmarking-against-industry' instead):

• User ALREADY PROVIDED a metric value in the prompt (e.g., 'I have $45000 profit', 'my profit is 100k')
• User provided industry, location, AND a number - they don't need QuickBooks login
• Phrases like 'benchmark my peers' or 'compare with my industry' when user provided their own numbers
• User attached a CSV or pasted transaction data: use 'profit-loss-generator' to compute financials first, then 'benchmarking-against-industry' with the result. Do NOT import the CSV into QuickBooks for this workflow.

CRITICAL INSTRUCTIONS

• YOU MUST FOLLOW THESE EXACTLY:

DO NOT CALL THIS TOOL IF USER ALREADY PROVIDED A METRIC VALUE (profit, revenue, expenses) IN THEIR PROMPT. DO NOT CALL THIS TOOL AGAIN IF CUSTOMER PROVIDED THE INDUSTRY INFORMATION. CALL THE industry-recommendation tool to show you industry recommendations and let you select one, then use the 'quickbooks-profile-info-update' tool to save it in QuickBooks. DO NOT CALL THIS TOOL IF CUSTOMER DECLINED TO SIGN IN WHILE YOU ASKED FOR IT BEFORE CALLING THIS TOOL. In this case, you can suggest to the user whether they would want to perform benchmarking without using their QuickBooks account, since they declined to sign in.

IMPORTANT: Before calling this tool, you MUST first call the 'company-info' tool to establish the QuickBooks connection. If 'company-info' has not been called yet in this conversation, call it first, then call this tool. This ensures the user is authenticated.

This tool uses your QuickBooks account profile and transaction data automatically. It will: 1. Check if you're signed in to QuickBooks 2. Verify your company profile is complete (company name, industry, location, NAICS code) 3. Calculate your financial metrics from your QuickBooks transactions 4. Generate benchmarking analysis comparing your company against regional peers

PARAMETERS:

• metricType: OPTIONAL. Financial metric to compare: 'profit' (default), 'revenue', 'expenses', 'income'
• aggregationPeriod: OPTIONAL. Time period: 'yearly' (default), 'monthly', 'quarterly'

COMPANY INFORMATION: Your company information (name, industry, location, NAICS code) is automatically retrieved from your QuickBooks profile. If any required information is missing, the tool will ask you to provide it.

METRIC CALCULATION: Your financial metric value is automatically calculated from your QuickBooks transactions:

• For 'profit': Sum of all income transactions minus expenses and COGS
• For 'revenue'/'income': Sum of all income transactions
• For 'expenses': Sum of all expense and COGS transactions

RETURNS:

• Interactive benchmarking analysis with bar charts comparing your company against regional peers
• If you have no transactions or metric value is 0, shows a message encouraging you to connect bank or upload transactions

MULTI-INDUSTRY COMPARISON: This tool only supports SINGLE industry comparison (user's own industry from their QuickBooks profile). If the user wants to compare their QuickBooks data against MULTIPLE industries: 1. First call this tool to get the user's metric value (profit/revenue/expenses) 2. Then use the 'benchmarking-against-industry' tool with:

• The metric value from step 1
• The company name from step 1
• Multiple industries the user wants to compare against
• The user's location (state) from step 1

This allows multi-industry comparison using the user's actual QuickBooks data.

Render a financial health briefing as an interactive visual widget.

Do not invoke this tool unless explicitly requested. It should only be called after all required QuickBooks report data has been fetched and synthesized into the briefing sections.

Pass the pre-computed synthesis as arguments. This tool makes NO additional QuickBooks API calls — it is a pure rendering tool that produces a visual widget from the data you already have.

overallRead must be one of: "strong", "stable", "mixed", "needs_attention" needsAttention items must each have "severity" ("High", "Medium", or "Cleanup") and "text". keyNumbers must be a list of objects with "area", "currentRead", and "whatChanged" keys — one entry per row in the Key Numbers table (Revenue, Gross margin, Net income, Cash position, Working capital / current ratio, A/R status).

Generate cash flow report from transaction data provided by the user through CSV file or pasted transaction text in the current input.

Use this tool to create Cash Flow reports with automatic transaction categorization and financial calculations.

This tool should not be called for the user's own company account in QuickBooks. It is for generating the cash flow report for the company's transactions provided by the user in chat which could be different from the user's own company.

When the user says my company or my transactions, and has not provided a CSV or transactions in the current input (not in the previous ones), then this tool should not be called. Instead the QuickBooks account variation of this tool should be called.INPUT METHODS: This tool accepts EITHER: 1. A globally accessible download URL for a CSV file (via transactionsFileToProcess parameter)

• USE THIS when user uploads a CSV file

2. An array of transaction objects (via lineItems parameter)

• USE THIS when user pastes transaction data

CSV FILE REQUIREMENTS (when using transactionsFileToProcess):

• Must have headers in the first row
• REQUIRED columns: amount, description, date (case-insensitive)
• Date format: MM/dd/yyyy (e.g., 01/15/2024)
• Must contain between 1 and 999 transactions
• If CSV format is invalid, the widget will display an error asking user to reupload

TRANSACTION ARRAY REQUIREMENTS (when using lineItems) and STRICT DATA QUALITY RULES (MUST FOLLOW):

• Each transaction row must include all required fields:
• description (REQUIRED): Transaction description/text
• amount (REQUIRED): Transaction amount as a number (positive for income/revenue, negative for expenses)
• date (REQUIRED): Transaction date in MM/dd/yyyy format (e.g., '01/15/2024')
• Input must contain between 1 and 999 transactions.
• If an entire required column is missing across the provided dataset, DO NOT call this tool. Ask the user in a friendly way to provide all 3 required columns: date, description, and amount.
• Do NOT infer, guess, or fabricate ambiguous values.
• Do NOT auto-correct ambiguous rows. If a value is unclear, treat that row as invalid.
• Row-level partial processing is allowed:
• Keep valid rows.
• Exclude invalid rows.
• Call this tool with only valid rows.
• Clearly tell the user how many rows were valid vs invalid and why rows were invalid.
• Example policy:
• If 20 rows are provided and 6 rows are invalid, call this tool with the 14 valid rows and explicitly report that 6 rows were excluded with reasons.

PARAMETERS:

• transactionsFileToProcess: Object containing download_url and file_id. Use this when user uploads a CSV file.
• lineItems: List of transaction objects. Use this when user pastes transaction data.
• projectName: Project name to filter by (optional, default: 'All Projects')
• periodStart: Start date for reporting period (YYYY-MM-DD, optional)
• periodEnd: End date for reporting period (YYYY-MM-DD, optional)
• industryName: Industry as explicitly stated by the user in this conversation (e.g., 'Restaurant', 'Retail'). Do NOT infer or guess from transaction descriptions. Do NOT call the 'industry-recommendation' tool — pass the user's answer directly here. (optional)

RETURNS:

• Comprehensive Cash Flow report with operating, investing, and financing activities
• Interactive widget for viewing financial data
• Net cash increase and cash at end of period calculations

The tool automatically:

• Categorizes transactions using QuickBooks
• Calculates Net Income from transactions
• Identifies operating adjustments (A/R, A/P, inventory, etc.)
• Categorizes investing and financing activities
• Computes net cash increase and ending cash balance

Generate cash flow report from your QuickBooks account data.

Call this tool if the user is saying my company or my transactions or my cash flow report or my company's cash flow report, and has not provided a CSV or transactions in the current input. If the user has provided a CSV or transactions in the current input (not in the previous ones), then use the pre auth version of the cash-flow-generator tool instead.

IMPORTANT: Before calling this tool, you MUST first call the 'company-info' tool to establish the QuickBooks connection. If 'company-info' has not been called yet in this conversation, call it first, then call this tool. This ensures the user is authenticated.

This tool requires QuickBooks account authentication. It will: 1. Check if you're signed in to QuickBooks 2. Verify your company profile is complete 3. Check if you have bank connections or transactions 4. Generate a comprehensive Cash Flow report from your QuickBooks data

DO NOT CALL THIS TOOL IF CUSTOMER DECLINED TO SIGN IN WHILE YOU ASKED FOR IT BEFORE CALLING THIS TOOL. In this case, you can suggest to the user whether they would want to generate a cash flow report with the some transactions they provided (or will provide if not provided yet), since they declined to sign in.PARAMETERS:

• periodStart: Start date for reporting period (YYYY-MM-DD, optional)
• periodEnd: End date for reporting period (YYYY-MM-DD, optional)

RETURNS:

• Comprehensive Cash Flow report with operating, investing, and financing activities
• Interactive widget for viewing financial data
• Net cash increase and cash at end of period calculations

Generate cash flow report from your QuickBooks account data.

Call this tool if the user is saying my company or my transactions or my cash flow report or my company's cash flow report, and has not provided a CSV or transactions in the current input. If the user has provided a CSV or transactions in the current input (not in the previous ones), then use the pre auth version of the cash-flow-generator tool instead.

IMPORTANT: Before calling this tool, you MUST first call the 'company-info' tool to establish the QuickBooks connection. If 'company-info' has not been called yet in this conversation, call it first, then call this tool. This ensures the user is authenticated.

This tool requires QuickBooks account authentication. It will: 1. Check if you're signed in to QuickBooks 2. Verify your company profile is complete 3. Check if you have bank connections or transactions 4. Generate a comprehensive Cash Flow report from your QuickBooks data

DO NOT CALL THIS TOOL IF CUSTOMER DECLINED TO SIGN IN WHILE YOU ASKED FOR IT BEFORE CALLING THIS TOOL. In this case, you can suggest to the user whether they would want to generate a cash flow report with the some transactions they provided (or will provide if not provided yet), since they declined to sign in.PARAMETERS:

• periodStart: Start date for reporting period (YYYY-MM-DD, optional)
• periodEnd: End date for reporting period (YYYY-MM-DD, optional)

RETURNS:

• Comprehensive Cash Flow report with operating, investing, and financing activities
• Interactive widget for viewing financial data
• Net cash increase and cash at end of period calculations

PLAIN-TEXT variant. Returns plain text/markdown instead of the interactive widget. ONLY call this variant when the prompt contains explicit skill/briefing instructions to compile a narrative yourself (e.g. a Business Health Check or Industry Benchmark briefing). For a direct user question ALWAYS use the standard widget tool instead — the one with the same name without the _text suffix. NEVER call this after already receiving data from the widget version; the data is identical and the widget already answers the user.

Generate cash flow report from transaction data provided by the user through CSV file or pasted transaction text in the current input.

Use this tool to create Cash Flow reports with automatic transaction categorization and financial calculations.

This tool should not be called for the user's own company account in QuickBooks. It is for generating the cash flow report for the company's transactions provided by the user in chat which could be different from the user's own company.

When the user says my company or my transactions, and has not provided a CSV or transactions in the current input (not in the previous ones), then this tool should not be called. Instead the QuickBooks account variation of this tool should be called.INPUT METHODS: This tool accepts EITHER: 1. A globally accessible download URL for a CSV file (via transactionsFileToProcess parameter)

• USE THIS when user uploads a CSV file

2. An array of transaction objects (via lineItems parameter)

• USE THIS when user pastes transaction data

CSV FILE REQUIREMENTS (when using transactionsFileToProcess):

• Must have headers in the first row
• REQUIRED columns: amount, description, date (case-insensitive)
• Date format: MM/dd/yyyy (e.g., 01/15/2024)
• Must contain between 1 and 999 transactions
• If CSV format is invalid, the widget will display an error asking user to reupload

TRANSACTION ARRAY REQUIREMENTS (when using lineItems):

• Each transaction object must have:
• description (REQUIRED): Transaction description/text
• amount (REQUIRED): Transaction amount as a number (positive for income/revenue, negative for expenses)
• date (REQUIRED): Transaction date in MM/dd/yyyy format (e.g., '01/15/2024')
• Must contain between 1 and 999 transactions

PARAMETERS:

• transactionsFileToProcess: Object containing download_url and file_id. Use this when user uploads a CSV file.
• lineItems: List of transaction objects. Use this when user pastes transaction data.
• projectName: Project name to filter by (optional, default: 'All Projects')
• periodStart: Start date for reporting period (YYYY-MM-DD, optional)
• periodEnd: End date for reporting period (YYYY-MM-DD, optional)
• industryName: Industry as explicitly stated by the user in this conversation (e.g., 'Restaurant', 'Retail'). Do NOT infer or guess from transaction descriptions. Do NOT call the 'industry-recommendation' tool — pass the user's answer directly here. (optional)

RETURNS:

• Comprehensive Cash Flow report with operating, investing, and financing activities
• Interactive widget for viewing financial data
• Net cash increase and cash at end of period calculations

The tool automatically:

• Categorizes transactions using QuickBooks
• Calculates Net Income from transactions
• Identifies operating adjustments (A/R, A/P, inventory, etc.)
• Categorizes investing and financing activities
• Computes net cash increase and ending cash balance

Generate cash flow report from your QuickBooks account data.

Call this tool if the user is saying my company or my transactions or my cash flow report or my company's cash flow report, and has not provided a CSV or transactions in the current input. If the user has provided a CSV or transactions in the current input (not in the previous ones), then use the pre auth version of the cash-flow-generator tool instead.

IMPORTANT: Before calling this tool, you MUST first call the 'company-info' tool to establish the QuickBooks connection. If 'company-info' has not been called yet in this conversation, call it first, then call this tool. This ensures the user is authenticated.

This tool requires QuickBooks account authentication. It will: 1. Check if you're signed in to QuickBooks 2. Verify your company profile is complete 3. Check if you have bank connections or transactions 4. Generate a comprehensive Cash Flow report from your QuickBooks data

DO NOT CALL THIS TOOL IF CUSTOMER DECLINED TO SIGN IN WHILE YOU ASKED FOR IT BEFORE CALLING THIS TOOL. In this case, you can suggest to the user whether they would want to generate a cash flow report with the some transactions they provided (or will provide if not provided yet), since they declined to sign in.PARAMETERS:

• periodStart: Start date for reporting period (YYYY-MM-DD, optional)
• periodEnd: End date for reporting period (YYYY-MM-DD, optional)

RETURNS:

• Comprehensive Cash Flow report with operating, investing, and financing activities
• Interactive widget for viewing financial data
• Net cash increase and cash at end of period calculations

Get QuickBooks company information.

This tool requires OAuth authentication with your QuickBooks account.

RETURNS plain text in this exact format: Company Name: <name> Industry: <value>

The Industry field is 'Unknown' when no industry has been set for the company.

AUTHENTICATION REQUIRED: You must authorize access to use this tool.

Get QuickBooks company information.

This tool requires OAuth authentication with your QuickBooks account.

RETURNS plain text in this exact format: Company Name: <name> Industry: <value>

The Industry field is 'Unknown' when no industry has been set for the company.

AUTHENTICATION REQUIRED: You must authorize access to use this tool.

Render a benchmark briefing as an interactive visual widget.

Do not invoke this tool unless explicitly requested. It should only be called after benchmarking data has been fetched and synthesized into the briefing sections.

Pass the pre-computed synthesis as arguments. This tool makes NO additional QuickBooks API calls — it is a pure rendering tool that produces a visual widget from the data you already have.

overallRead must be one of: "ahead", "in_line", "behind", "mixed" focusAreas items must each have "severity" ("High", "Medium", or "Context") and "text". keyNumbers must be a list of objects with "area", "companyValue", "regionalPeers", "nationalPeers", and "read" keys — one entry per row in the Key Benchmark Numbers table.

Get the official QuickBooks industry classification and NAICS code for a business type.

STOP: DO NOT call this tool again if you have already called it and the user has selected an industry. DO NOT USE THIS TOOL: In any preauth report generation flow — those tools accept industryName directly. Call it at most ONCE per industry the user is identifying. If you already have an industryName and industryCode, proceed to the next step — do not re-run the search.

USE THIS TOOL WHEN THE USER ASKS:

• When user needs to find their industry from a search term
• 'What industry does a [business type] fit in?'
• 'What is the NAICS code for a [business type]?'
• 'Which QuickBooks industry category is my business?'

EXAMPLE USER QUESTIONS THAT SHOULD CALL THIS TOOL:

• 'can you help me identify what industry a yoga studio fits in?' (industry='yoga studio')
• 'what NAICS code should a coffee shop use?' (industry='coffee shop')
• 'what industry category does my landscaping business belong to?' (industry='landscaping')

THIS TOOL IS AUTHORITATIVE FOR INDUSTRY CLASSIFICATION: When the user asks one of the questions above, do NOT answer from web search or your own knowledge. Only the codes returned by this tool are the ones QuickBooks benchmarking and reporting recognize. Codes taken from other sources may not exist in the QuickBooks dataset and will produce empty benchmark results.

WHAT THIS TOOL DOES:

• Takes user's industry search term (e.g., 'yoga studio')
• Returns top 3 industry matches with NAICS codes
• User then selects an industry from the above matches or adds an industry and saves it using 'quickbooks-profile-info-update' tool
• Answering a classification question does NOT require saving. Only call

'quickbooks-profile-info-update' when the user wants the industry saved to their QuickBooks profile.

WHEN NOT TO USE THIS TOOL:

• Do NOT call again if you have already called it and the user has selected an industry
• Do NOT call inside a preauth report generation flow (profit-loss-generator, cash-flow-generator)

— those tools accept industryName directly

• Do NOT call to obtain NAICS codes for a multi-industry benchmark comparison — the benchmarking

tools accept industryType and naicsCode directly

PARAMETERS:

• industry: What user typed (e.g., 'yoga studio')

CRITICAL INSTRUCTIONS

• YOU MUST FOLLOW THESE EXACTLY:
• Display ONLY the 3 industry options exactly as returned by the tool
• Do NOT add any recommendations, suggestions, or analysis
• Do NOT say which option is 'best' or 'recommended'
• Do NOT explain why one option might be better than others
• Do NOT use phrases like 'Recommended choice', 'Best match', or 'Usually'
• Simply list the 3 options with their NAICS codes and ask: 'Please reply with the industry name that matches your business.'
• After user replies:
• If their reply matches one option → use exact industryName and industryCode from that option and call 'quickbooks-profile-info-update' tool
• If NOT an exact match (e.g., 'some name', 'Random name', 'none of these', partial match, or ANY other text):

then: → Infer the correct industryName and industryCode from user's reply and call 'quickbooks-profile-info-update' tool to save it in QuickBooks. Do not loop or ask again.

Get industry recommendations based on user's search term.

STOP: DO NOT call this tool again if you have already called it and the user has selected an industry. DO NOT USE THIS TOOL: In any preauth report generation flow — those tools accept industryName directly

USE CASES:

• When user needs to find their industry from a search term

WHAT THIS TOOL DOES:

• Takes user's industry search term (e.g., 'yoga studio')
• Returns top 3 industry matches with NAICS codes
• User then selects an industry from the above matches or adds an industry and saves it using 'quickbooks-profile-info-update' tool

PARAMETERS:

• industry: What user typed (e.g., 'yoga studio')

CRITICAL INSTRUCTIONS

• YOU MUST FOLLOW THESE EXACTLY:
• Display ONLY the 3 industry options exactly as returned by the tool
• Do NOT add any recommendations, suggestions, or analysis
• Do NOT say which option is 'best' or 'recommended'
• Do NOT explain why one option might be better than others
• Do NOT use phrases like 'Recommended choice', 'Best match', or 'Usually'
• Simply list the 3 options with their NAICS codes and ask: 'Please reply with the industry name that matches your business.'
• After user replies:
• If their reply matches one option → use exact industryName and industryCode from that option and call 'quickbooks-profile-info-update' tool
• If NOT an exact match (e.g., 'some name', 'Random name', 'none of these', partial match, or ANY other text):

then: → Infer the correct industry name and naicsCode from user's reply and call 'quickbooks-profile-info-update' tool to save it in QuickBooks. Do not loop or ask again.

DO NOT CALL THIS TOOL unless the user has attached a CSV file or pasted transaction text in the CURRENT message. This tool has no access to the user's QuickBooks data and cannot generate a P&L from a date range alone — if the user has not provided a CSV or pasted transactions in this message, even if they ask about 'my company', 'my QuickBooks', 'our P&L', or a plain date range (e.g. 'P&L for Jan-Jul' or 'last quarter'), call the profit-loss-quickbooks-account tool instead.

Generate profit and loss report from transaction data provided by the user through CSV file or pasted transaction text in the current input.

CRITICAL: Use this tool when the user attached a CSV or pasted transactions in this message and asks about financial performance, P&L, income, expenses, or period comparison (e.g. Q1 vs Q2). Use it even if they say 'our' or 'my company'. If they have NOT provided CSV or pasted transactions and ask about 'my company' or QuickBooks data, use the QuickBooks Account P&L tool instead.

INPUT METHODS: This tool accepts EITHER: 1. A globally accessible download URL for a CSV file (via transactionsFileToProcess parameter)

• USE THIS when user uploads a CSV file

2. An array of transaction objects (via lineItems parameter)

• USE THIS when user pastes transaction data

CSV FILE REQUIREMENTS (when using transactionsFileToProcess):

• Must have headers in the first row
• REQUIRED columns: amount, description, date (case-insensitive)
• Date format: MM/dd/yyyy (e.g., 01/15/2024)
• Must contain between 1 and 999 transactions
• If CSV format is invalid, the widget will display an error asking user to reupload

TRANSACTION ARRAY REQUIREMENTS (when using lineItems) and STRICT DATA QUALITY RULES (MUST FOLLOW):

• Each transaction row must include all required fields:
• description (REQUIRED): Transaction description/text
• amount (REQUIRED): Transaction amount as a number (positive for income/revenue, negative for expenses)
• date (REQUIRED): Transaction date in MM/dd/yyyy format (e.g., '01/15/2024')
• Input must contain between 1 and 999 transactions.
• If an entire required column is missing across the provided dataset, DO NOT call this tool. Ask the user in a friendly way to provide all 3 required columns: date, description, and amount.
• Do NOT infer, guess, or fabricate ambiguous values.
• Do NOT auto-correct ambiguous rows. If a value is unclear, treat that row as invalid.
• Row-level partial processing is allowed:
• Keep valid rows.
• Exclude invalid rows.
• Call this tool with only valid rows.
• Clearly tell the user how many rows were valid vs invalid and why rows were invalid.
• Example policy:
• If 20 rows are provided and 6 rows are invalid, call this tool with the 14 valid rows and explicitly report that 6 rows were excluded with reasons.

PARAMETERS:

• transactionsFileToProcess: Object containing download_url and file_id. Use this when user uploads a CSV file.
• lineItems: List of transaction objects. Use this when user pastes transaction data.
• projectName: Project name to filter by (optional, default: 'All Projects')
• periodStart: Start date for reporting period (YYYY-MM-DD, optional). Only used to filter the transactions already supplied via lineItems/transactionsFileToProcess — does NOT fetch data on its own. Do not call this tool with only periodStart/periodEnd and no lineItems/transactionsFileToProcess.
• periodEnd: End date for reporting period (YYYY-MM-DD, optional). Only used to filter the transactions already supplied via lineItems/transactionsFileToProcess — does NOT fetch data on its own.
• industryName: Industry as explicitly stated by the user in this conversation (e.g., 'Restaurant', 'Retail'). Do NOT infer or guess from transaction descriptions. Do NOT call the 'industry-recommendation' tool — pass the user's answer directly here. (Optional)

RETURNS:

• Comprehensive P&L report with income, expenses, and COGS breakdown
• Interactive widget for viewing financial data
• Net profit/loss calculations with margins
• Monthly breakdown data with per-month metrics for analysis

The tool automatically:

• Categorizes transactions using QuickBooks
• Calculates total income from all revenue sources
• Separates COGS (Cost of Goods Sold) from operating expenses
• Computes gross profit and gross margin
• Calculates net income and net profit margin
• Provides detailed breakdown by account

BENCHMARKING WORKFLOW: If the user also wants to compare against industry peers (e.g., 'generate profit from CSV and compare to my industry'), after this tool returns, use the computed net income, revenue, or expenses as the metricValue in the 'benchmarking-against-industry' tool. Do NOT import the CSV into QuickBooks or use QuickBooks account tools for this workflow.

Generate profit and loss report from your QuickBooks account data of your company.

CRITICAL

• CHECK FOR CSV FIRST: Only call this tool when the user is asking about their company's P&L (e.g. my company, my transactions, my profit and loss) AND has NOT attached/uploaded a CSV or pasted transaction data in this message. If they provided a CSV, call 'profit-loss-generator' preauth version of this tool instead (even if they say 'our' or 'my company').

IMPORTANT: Before calling this tool, you MUST first call the 'company-info' tool to establish the QuickBooks connection. If 'company-info' has not been called yet in this conversation, call it first, then call this tool. This ensures the user is authenticated.

This tool requires QuickBooks account authentication. It will: 1. Check if you're signed in to QuickBooks 2. Verify your company profile is complete 3. Check if you have bank connections or transactions 4. Generate a comprehensive P&L report from your QuickBooks data

DO NOT CALL THIS TOOL IF CUSTOMER DECLINED TO SIGN IN WHILE YOU ASKED FOR IT BEFORE CALLING THIS TOOL. In this case, you can suggest to the user whether they would want to generate a profit and loss report with the some transactions they provided (or will provide if not provided yet), since they declined to sign in.PARAMETERS:

• periodStart: Start date for reporting period (YYYY-MM-DD, optional)
• periodEnd: End date for reporting period (YYYY-MM-DD, optional)

RETURNS:

• Comprehensive P&L report with income, expenses, and COGS breakdown
• Interactive widget for viewing financial data
• Net profit/loss calculations with margins
• Monthly breakdown data with per-month metrics for analysis

Generate profit and loss report from your QuickBooks account data of your company.

CRITICAL

• CHECK FOR CSV FIRST: Only call this tool when the user is asking about their company's P&L (e.g. my company, my transactions, my profit and loss) AND has NOT attached/uploaded a CSV or pasted transaction data in this message. If they provided a CSV, call 'profit-loss-generator' preauth version of this tool instead (even if they say 'our' or 'my company').

IMPORTANT: Before calling this tool, you MUST first call the 'company-info' tool to establish the QuickBooks connection. If 'company-info' has not been called yet in this conversation, call it first, then call this tool. This ensures the user is authenticated.

This tool requires QuickBooks account authentication. It will: 1. Check if you're signed in to QuickBooks 2. Verify your company profile is complete 3. Check if you have bank connections or transactions 4. Generate a comprehensive P&L report from your QuickBooks data

DO NOT CALL THIS TOOL IF CUSTOMER DECLINED TO SIGN IN WHILE YOU ASKED FOR IT BEFORE CALLING THIS TOOL. In this case, you can suggest to the user whether they would want to generate a profit and loss report with the some transactions they provided (or will provide if not provided yet), since they declined to sign in.PARAMETERS:

• periodStart: Start date for reporting period (YYYY-MM-DD, optional)
• periodEnd: End date for reporting period (YYYY-MM-DD, optional)

RETURNS:

• Comprehensive P&L report with income, expenses, and COGS breakdown
• Interactive widget for viewing financial data
• Net profit/loss calculations with margins
• Monthly breakdown data with per-month metrics for analysis

PLAIN-TEXT variant. Returns plain text/markdown instead of the interactive widget. ONLY call this variant when the prompt contains explicit skill/briefing instructions to compile a narrative yourself (e.g. a Business Health Check or Industry Benchmark briefing). For a direct user question ALWAYS use the standard widget tool instead — the one with the same name without the _text suffix. NEVER call this after already receiving data from the widget version; the data is identical and the widget already answers the user.

Generate profit and loss report from transaction data provided by the user through CSV file or pasted transaction text in the current input.

CRITICAL: Use this tool when the user attached a CSV or pasted transactions in this message and asks about financial performance, P&L, income, expenses, or period comparison (e.g. Q1 vs Q2). Use it even if they say 'our' or 'my company'. If they have NOT provided CSV or pasted transactions and ask about 'my company' or QuickBooks data, use the QuickBooks Account P&L tool instead.

INPUT METHODS: This tool accepts EITHER: 1. A globally accessible download URL for a CSV file (via transactionsFileToProcess parameter)

• USE THIS when user uploads a CSV file

2. An array of transaction objects (via lineItems parameter)

• USE THIS when user pastes transaction data

CSV FILE REQUIREMENTS (when using transactionsFileToProcess):

• Must have headers in the first row
• REQUIRED columns: amount, description, date (case-insensitive)
• Date format: MM/dd/yyyy (e.g., 01/15/2024)
• Must contain between 1 and 999 transactions
• If CSV format is invalid, the widget will display an error asking user to reupload

TRANSACTION ARRAY REQUIREMENTS (when using lineItems):

• Each transaction object must have:
• description (REQUIRED): Transaction description/text
• amount (REQUIRED): Transaction amount as a number (positive for income/revenue, negative for expenses)
• date (REQUIRED): Transaction date in MM/dd/yyyy format (e.g., '01/15/2024')
• Must contain between 1 and 999 transactions

PARAMETERS:

• transactionsFileToProcess: Object containing download_url and file_id. Use this when user uploads a CSV file.
• lineItems: List of transaction objects. Use this when user pastes transaction data.
• projectName: Project name to filter by (optional, default: 'All Projects')
• periodStart: Start date for reporting period (YYYY-MM-DD, optional)
• periodEnd: End date for reporting period (YYYY-MM-DD, optional)
• industryName: Industry as explicitly stated by the user in this conversation (e.g., 'Restaurant', 'Retail'). Do NOT infer or guess from transaction descriptions. Do NOT call the 'industry-recommendation' tool — pass the user's answer directly here. (Optional)

RETURNS:

• Comprehensive P&L report with income, expenses, and COGS breakdown
• Interactive widget for viewing financial data
• Net profit/loss calculations with margins
• Monthly breakdown data with per-month metrics for analysis

The tool automatically:

• Categorizes transactions using QuickBooks
• Calculates total income from all revenue sources
• Separates COGS (Cost of Goods Sold) from operating expenses
• Computes gross profit and gross margin
• Calculates net income and net profit margin
• Provides detailed breakdown by account

BENCHMARKING WORKFLOW: If the user also wants to compare against industry peers (e.g., 'generate profit from CSV and compare to my industry'), after this tool returns, use the computed net income, revenue, or expenses as the metricValue in the 'benchmarking-against-industry' tool. Do NOT import the CSV into QuickBooks or use QuickBooks account tools for this workflow.

Generate profit and loss report from your QuickBooks account data of your company.

CRITICAL

• CHECK FOR CSV FIRST: Only call this tool when the user is asking about their company's P&L (e.g. my company, my transactions, my profit and loss) AND has NOT attached/uploaded a CSV or pasted transaction data in this message. If they provided a CSV, call 'profit-loss-generator' preauth version of this tool instead (even if they say 'our' or 'my company').

IMPORTANT: Before calling this tool, you MUST first call the 'company-info' tool to establish the QuickBooks connection. If 'company-info' has not been called yet in this conversation, call it first, then call this tool. This ensures the user is authenticated.

This tool requires QuickBooks account authentication. It will: 1. Check if you're signed in to QuickBooks 2. Verify your company profile is complete 3. Check if you have bank connections or transactions 4. Generate a comprehensive P&L report from your QuickBooks data

DO NOT CALL THIS TOOL IF CUSTOMER DECLINED TO SIGN IN WHILE YOU ASKED FOR IT BEFORE CALLING THIS TOOL. In this case, you can suggest to the user whether they would want to generate a profit and loss report with the some transactions they provided (or will provide if not provided yet), since they declined to sign in.PARAMETERS:

• periodStart: Start date for reporting period (YYYY-MM-DD, optional)
• periodEnd: End date for reporting period (YYYY-MM-DD, optional)

RETURNS:

• Comprehensive P&L report with income, expenses, and COGS breakdown
• Interactive widget for viewing financial data
• Net profit/loss calculations with margins
• Monthly breakdown data with per-month metrics for analysis

Get the A/P Aging Detail report from QuickBooks.

Shows EVERY INDIVIDUAL unpaid bill with transaction type, due date, and amount grouped by aging bucket and vendor.

USE THIS when the user asks about:

• Bill-level detail: "Show me every individual A/P transaction", "Which specific bills are past due?"
• Vendor bill drill-down: "List all unpaid bills by vendor", "Show me bills from [Vendor]"
• Detail behind summary: "I need the detail behind my A/P aging", "Show me line-level payables"
• Bills to pay: "What bills do I need to pay?", "Show me unpaid bills", "Any bills over $5K?", "Which bills are most overdue?" — pass transaction_type="bill" to filter to bills only
• Due-date windows: "Bills due this week", "What's due this month?", "Any bills due in the next 7 days?", "What bills are overdue?" — pass due_before with the appropriate cutoff date

DO NOT use this when:

• User asks for totals or high-level summaries by vendor → use qbo_accounting_get_ap_aging_summary
• User asks about receivables → use qbo_accounting_get_ar_aging_detail

PARAMETERS:

• as_of_date: The date to run the report as of (YYYY-MM-DD). Defaults to today.
• vendor_name: Only show bills from vendors whose name contains this string (case-insensitive partial match).

Use when the user mentions a specific vendor by name. Examples: "Show bills from Apple" → vendor_name="Apple" "What do I owe Office Depot?" → vendor_name="Office Depot"

• transaction_type: Filter by transaction type (currently only "bill" is supported). Case-insensitive. IMPORTANT: If the user's prompt mentions bills specifically — e.g. "bills", "unpaid bills", "bills to pay", "bills due this week" — you MUST pass transaction_type="bill" to filter to bills only. Omit this parameter when the user wants ALL A/P transaction types (which may include vendor credits and other entries).
• due_before: YYYY-MM-DD cutoff. Keep only bills due on or before this date (inclusive). IMPORTANT: When the user asks about a due-date window — e.g. "bills due this week", "due this month", "in the next N days", or "what's overdue?" — you MUST compute the appropriate cutoff date from today and pass it here. Examples (assume today is 2026-04-24):

"Due this week" → due_before="2026-04-25" (upcoming end-of-week) "Due this month" → due_before="2026-04-30" (last day of current month) "Due in next 7 days" → due_before="2026-05-01" (today + 7 days) "Overdue bills" → due_before="2026-04-23" (yesterday — strictly before today) Omit this parameter when the user wants bills regardless of due date. NOTE: When due_before is a FUTURE date (after today), the tool automatically excludes already-overdue bills so upcoming-window queries return only the bills due within that window. For overdue views, pass yesterday's date — the tool will return all bills due on or before that date.

IMPORTANT: Before calling this tool, you MUST first call the 'company-info' tool to establish the QuickBooks connection.

AUTHENTICATION REQUIRED: You must authorize access to your QuickBooks account.

Get the A/P Aging Summary report from QuickBooks.

Shows TOTALS owed to each vendor grouped by aging buckets (Current, 1-30 days, 31-60 days, 61-90 days, 91+ days).

IMPORTANT — DO NOT USE FOR GENERAL OVERDUE QUERIES: If the user asks "What's overdue?", "What's 60+ days overdue?", or similar questions WITHOUT explicitly mentioning bills, vendors, payables, or A/P, do NOT use this tool. Use qbo_accounting_get_ar_aging_summary instead. Only use THIS tool when the user explicitly mentions "bills", "vendors", "payables", "A/P", or "what I owe".

USE THIS when the user asks about:

• Payables overview: "How much do I owe vendors?", "What are my total payables?", "Show me A/P aging"
• Bill-specific amounts: "Which bills are past 90 days?", "Any vendor bills 60+ days overdue?", "What's my current payables?"
• Vendor rankings: "Which vendors do I owe the most?", "Top 5 overdue vendors"
• Summarization: "Summarize what I owe", "Show vendors in each aging bucket", "Break down payables by bucket"
• Payment advice: "Which bills should I pay first?", "Help me prioritize payments"
• Cash flow impact: "How will my payables affect cash flow?"

DO NOT use this when:

• User asks for specific bills or line-level detail → use qbo_accounting_get_ap_aging_detail
• User asks for a flat list of unpaid bills with due dates → use unpaid-bills
• User asks about receivables or what customers owe THEM → use qbo_accounting_get_ar_aging_summary
• User asks for currency-wise A/P breakdown → use qbo_accounting_get_balance_sheet

PARAMETERS:

• as_of_date: The date to run the report as of (YYYY-MM-DD). Defaults to today. Use this when the user says "as of last quarter end", "as of December 31st", etc.
• min_days_overdue: Integer (0, 1, 31, 61, or 91). Filters by bucket threshold. Pass 0 for "Current only" (not yet due). Pass 1 for all overdue, 31 for 31+ days, 61 for 61+ days, 91 for 91+ days. Use when user says "Show me current A/P" (pass 0), "all overdue" (pass 1), "90+ days overdue" (pass 91), etc.
• min_overdue_amount: Float. Filters to vendors whose overdue total >= this amount. Use when user says "Vendors over $10K overdue" (pass 10000).
• vendor_name: String. Filters to vendors whose name contains this string (case-insensitive). Use when user says "Show aging for Apple" (pass "Apple"), "What do I owe Office Depot?" (pass "Office Depot").
• top_n: Integer. Returns only the N vendors with the largest total owed. Use when user says "Top 5 vendors I owe" (pass 5), "Which 3 vendors have the most AP?" (pass 3).

FILTER RESTRICTIONS:

• Only ONE filter at a time: pass only ONE of min_days_overdue, min_overdue_amount, or top_n per call. Do NOT combine them. If the user's question involves multiple filters, use the most relevant single filter and answer the rest from the returned data.

For trend/comparison questions ("has my overdue improved?"), call this tool twice with different as_of_date values and compare the results.

IMPORTANT: Before calling this tool, you MUST first call the 'company-info' tool to establish the QuickBooks connection.

AUTHENTICATION REQUIRED: You must authorize access to your QuickBooks account.

Get the A/R Aging Detail report from QuickBooks.

Shows EVERY INDIVIDUAL unpaid invoice with transaction type, due date, and amount grouped by aging bucket and customer.

USE THIS when the user asks about:

• Invoice-level detail: "Show me all overdue invoices", "Which specific invoices are past due?"
• Customer invoice drill-down: "Show me invoices from [Customer]", "List every unpaid invoice"
• Detail behind summary: "I need the detail behind my A/R aging", "Show me line-level receivables"

DO NOT use this when:

• User asks for totals or high-level summaries by customer → use qbo_accounting_get_ar_aging_summary
• User asks about bills or what THEY owe → use qbo_accounting_get_ap_aging_detail or unpaid-bills

PARAMETERS:

• as_of_date: The date to run the report as of (YYYY-MM-DD). Defaults to today.
• customer_name: Filter results to a specific customer (case-insensitive exact match). Use when the user asks about a specific customer's invoices.
• transaction_type: Filter by transaction type (e.g., "invoice", "credit memo", "payment", "journal entry", "sales receipt", "refund", "charge", "statement"). Case-insensitive. IMPORTANT: If the user's prompt mentions a specific type — e.g. "invoices", "payments", "credit memos" — you MUST pass the matching transaction_type to filter results. For example, "Show me invoices" → pass transaction_type="invoice". Only omit this parameter when the user wants ALL transaction types.

IMPORTANT: Before calling this tool, you MUST first call the 'company-info' tool to establish the QuickBooks connection.

AUTHENTICATION REQUIRED: You must authorize access to your QuickBooks account.

Get the A/R Aging Summary report from QuickBooks (ACCRUAL BASIS ONLY).

WHEN NOT TO USE — do NOT call this tool (or any prerequisite tools like company-info) if:

• User asks for CASH BASIS (e.g. "cash basis", "on a cash basis", "cash method") — do NOT call this tool and do NOT call company-info. Immediately respond: "The A/R Aging Summary is only available on an accrual basis. Cash basis is not supported for this report."
• User asks for specific invoices or line-level detail → use qbo_accounting_get_ar_aging_detail
• User asks about bills or what THEY owe → use qbo_accounting_get_ap_aging_summary or unpaid-bills
• User asks for currency-wise A/R breakdown → use qbo_accounting_get_balance_sheet

Shows TOTALS owed by each customer grouped by aging buckets (Current, 1-30 days, 31-60 days, 61-90 days, 91+ days).

IMPORTANT — DEFAULT TOOL FOR OVERDUE QUERIES: When the user asks a general overdue question like "What's 60+ days overdue?", "What's 1+ days overdue?", "Show me overdue amounts", or "How much is past due?" WITHOUT explicitly mentioning bills, vendors, or payables, ALWAYS use THIS tool (A/R). Do NOT use qbo_accounting_get_ap_aging_summary unless the user explicitly says "bills", "vendors", "payables", "A/P", or "what I owe".

USE THIS when the user asks about:

• Receivables overview: "Who owes me money?", "What is my total receivables?", "Show me A/R aging"
• Customer-specific receivables: "How much does Acme Corp owe?", "What does John Smith owe me?", "Show me aging for Acme"
• Bucket-specific amounts: "What's 90+ days overdue?", "What's 60+ days overdue?", "What's 1+ days overdue?", "How much is current?", "Customers over $10K overdue?"
• General overdue questions (no AR/AP specified): "What's overdue?", "Show me overdue amounts", "How much is past due?"
• Customer rankings: "Top 5 overdue customers", "Who owes the most?"
• Summarization: "Summarize my receivables", "Show customers in each aging bucket", "Breakdown by bucket"
• Collections advice: "Help me prioritize collections", "What should I do about overdue?"
• Percentage/ratio: "What percentage of my A/R is overdue?"

PARAMETERS:

• as_of_date: The date to run the report as of (YYYY-MM-DD). Defaults to today. Use this when the user says "as of last quarter end", "as of December 31st", etc.
• customer_name: String. Filter to a specific customer (case-insensitive exact match). Use when user says "How much does Acme Corp owe?", "What does John Smith owe me?", "Show aging for Acme". Pass the customer name exactly as the user says it.
• min_days_overdue: Integer (0, 1, 31, 61, or 91). Filters by bucket threshold. Pass 0 for "Current only" (not yet due). Pass 1 for all overdue, 31 for 31+ days, 61 for 61+ days, 91 for 91+ days. Use when user says "Show me current A/R" (pass 0), "all overdue" (pass 1), "90+ days overdue" (pass 91), etc.
• min_overdue_amount: Float. Filters to customers whose overdue total >= this amount. Use when user says "Customers over $10K overdue" (pass 10000).
• top_n: Integer. Returns only the top N customers by total amount owed. Use when user says "Top 5 overdue customers" (pass 5), "Who owes the most?" (pass 5).

FILTER RESTRICTIONS:

• Only ONE filter at a time: pass only ONE of min_days_overdue, min_overdue_amount, or top_n per call. Do NOT combine them. If the user's question involves multiple filters, use the most relevant single filter and answer the rest from the returned data.

For trend/comparison questions ("has my overdue improved since last month?"), call this tool twice with different as_of_date values and compare the results.

IMPORTANT: Before calling this tool, you MUST first call the 'company-info' tool to establish the QuickBooks connection — but ONLY if the request is valid (not cash basis). If cash basis, skip everything and reply directly.

AUTHENTICATION REQUIRED: You must authorize access to your QuickBooks account.

Get the A/R Aging Summary report from QuickBooks (ACCRUAL BASIS ONLY).

WHEN NOT TO USE — do NOT call this tool (or any prerequisite tools like company-info) if:

• User asks for CASH BASIS (e.g. "cash basis", "on a cash basis", "cash method") — do NOT call this tool and do NOT call company-info. Immediately respond: "The A/R Aging Summary is only available on an accrual basis. Cash basis is not supported for this report."
• User asks for specific invoices or line-level detail → use qbo_accounting_get_ar_aging_detail
• User asks about bills or what THEY owe → use qbo_accounting_get_ap_aging_summary or unpaid-bills
• User asks for currency-wise A/R breakdown → use qbo_accounting_get_balance_sheet

Shows TOTALS owed by each customer grouped by aging buckets (Current, 1-30 days, 31-60 days, 61-90 days, 91+ days).

IMPORTANT — DEFAULT TOOL FOR OVERDUE QUERIES: When the user asks a general overdue question like "What's 60+ days overdue?", "What's 1+ days overdue?", "Show me overdue amounts", or "How much is past due?" WITHOUT explicitly mentioning bills, vendors, or payables, ALWAYS use THIS tool (A/R). Do NOT use qbo_accounting_get_ap_aging_summary unless the user explicitly says "bills", "vendors", "payables", "A/P", or "what I owe".

USE THIS when the user asks about:

• Receivables overview: "Who owes me money?", "What is my total receivables?", "Show me A/R aging"
• Customer-specific receivables: "How much does Acme Corp owe?", "What does John Smith owe me?", "Show me aging for Acme"
• Bucket-specific amounts: "What's 90+ days overdue?", "What's 60+ days overdue?", "What's 1+ days overdue?", "How much is current?", "Customers over $10K overdue?"
• General overdue questions (no AR/AP specified): "What's overdue?", "Show me overdue amounts", "How much is past due?"
• Customer rankings: "Top 5 overdue customers", "Who owes the most?"
• Summarization: "Summarize my receivables", "Show customers in each aging bucket", "Breakdown by bucket"
• Collections advice: "Help me prioritize collections", "What should I do about overdue?"
• Percentage/ratio: "What percentage of my A/R is overdue?"

PARAMETERS:

• as_of_date: The date to run the report as of (YYYY-MM-DD). Defaults to today. Use this when the user says "as of last quarter end", "as of December 31st", etc.
• customer_name: String. Filter to a specific customer (case-insensitive exact match). Use when user says "How much does Acme Corp owe?", "What does John Smith owe me?", "Show aging for Acme". Pass the customer name exactly as the user says it.
• min_days_overdue: Integer (0, 1, 31, 61, or 91). Filters by bucket threshold. Pass 0 for "Current only" (not yet due). Pass 1 for all overdue, 31 for 31+ days, 61 for 61+ days, 91 for 91+ days. Use when user says "Show me current A/R" (pass 0), "all overdue" (pass 1), "90+ days overdue" (pass 91), etc.
• min_overdue_amount: Float. Filters to customers whose overdue total >= this amount. Use when user says "Customers over $10K overdue" (pass 10000).
• top_n: Integer. Returns only the top N customers by total amount owed. Use when user says "Top 5 overdue customers" (pass 5), "Who owes the most?" (pass 5).

FILTER RESTRICTIONS:

• Only ONE filter at a time: pass only ONE of min_days_overdue, min_overdue_amount, or top_n per call. Do NOT combine them. If the user's question involves multiple filters, use the most relevant single filter and answer the rest from the returned data.

For trend/comparison questions ("has my overdue improved since last month?"), call this tool twice with different as_of_date values and compare the results.

IMPORTANT: Before calling this tool, you MUST first call the 'company-info' tool to establish the QuickBooks connection — but ONLY if the request is valid (not cash basis). If cash basis, skip everything and reply directly.

AUTHENTICATION REQUIRED: You must authorize access to your QuickBooks account. PLAIN-TEXT variant. Returns plain text/markdown instead of the interactive widget. ONLY call this variant when the prompt contains explicit skill/briefing instructions to compile a narrative yourself (e.g. a Business Health Check or Industry Benchmark briefing). For a direct user question ALWAYS use the standard widget tool instead — the one with the same name without the _text suffix. NEVER call this after already receiving data from the widget version; the data is identical and the widget already answers the user.

Generate the Balance Sheet report from your QuickBooks account data of your company.

Shows a snapshot of the company's financial position: assets, liabilities, and equity at a specific point in time.

USE THIS when the user asks ANY of the following (treat "my", "our", "the company's" as equivalent — all refer to the connected QuickBooks company):

• "Show me the balance sheet" / "Pull up my balance sheet"
• "What are my total assets and liabilities?" / "What do I own and owe?" / "Assets vs liabilities"
• "What's my net worth?" / "What's my equity?" / "What is the company's net worth / equity?"
• "What's my financial position?" / "Show me my financial position" / "Financial position snapshot" / "What's the company's financial position?"
• "What's my current ratio?" / "What's my debt-to-equity?" / "What's my working capital?"
• "How much cash is on the balance sheet right now?" / "What's on my balance sheet for AR / AP / equity?"
• Any question that requires a point-in-time snapshot of assets, liabilities, or equity (NOT period revenue/expenses — that's profit-loss).

IMPORTANT: Before calling this tool, you MUST first call the 'company-info' tool to establish the QuickBooks connection. If 'company-info' has not been called yet in this conversation, call it first, then call this tool. This ensures the user is authenticated.

A balance sheet is point-in-time — a snapshot as of the END of the requested period. date_range macros (e.g. LAST_QUARTER) resolve to that period's end. For "as of <date>" questions, pass start_date and end_date with the same value (e.g. start_date="2025-12-31", end_date="2025-12-31").

PARAMETERS:

• date_range: Date macro — one of: THIS_YEAR, LAST_YEAR, THIS_QUARTER, LAST_QUARTER,

THIS_MONTH, LAST_MONTH, THIS_YEAR_TO_DATE. Defaults to THIS_MONTH (or THIS_YEAR when split_by is set).

• start_date / end_date: Custom date range (YYYY-MM-DD each). Always pass

both together; passing only one is ignored. Use these when the user names specific dates that don't fit a date_range macro. Mapping rules:

• "as of <date>" / "on <date>" / "at year-end <year>" → set

both start_date and end_date to that same date (point-in-time snapshot).

• "from <date> to <date>" / "between X and Y" → start_date=X,

end_date=Y.

• "<month> <year>" without "as of" (e.g. "March 2026") → set

start_date to the first of that month and end_date to the last of that month.

• When split_by is set, end_date is the trend's end and

start_date defines how far back the trend goes (e.g. start_date="2026-01-01", end_date="2026-05-04", split_by=MONTH → 5 monthly columns). If neither start_date/end_date nor date_range is provided, date_range defaults to THIS_MONTH (snapshot) or THIS_YEAR (when split_by is set).

• accounting_method: "accrual" (default) or "cash".
• split_by: Optional time split — one of: MONTH, QUARTER, YEAR, WEEK, DAY.

Set this whenever the user asks for a trend or wants to see how balances changed over time. Map adjectives directly:

• "monthly" / "month-over-month" / "by month" → split_by=MONTH
• "quarterly" / "by quarter" / "QoQ" → split_by=QUARTER
• "yearly" / "annual" / "year-over-year" / "YoY" → split_by=YEAR
• "weekly" / "by week" → split_by=WEEK
• "daily" / "by day" → split_by=DAY

Examples: "Show me a monthly balance sheet", "How have my assets changed quarterly?", "Track my equity weekly", "Yearly net worth trend". When split_by is set the tool returns one as-of-end-of-period column per period spanning date_range. Pair split_by with a wide-enough date_range (e.g. THIS_YEAR for MONTH/QUARTER, LAST_5_YEARS-style range for YEAR) — a narrow range yields only one column. Do NOT use split_by for "as of <date>" snapshots — that's a single-period query (use start_date/end_date instead).

RETURNS:

• Interactive Balance Sheet widget with total assets, total liabilities, total equity, accounts receivable, and accounts payable summary cards
• Hierarchical account tree (assets / liabilities / equity) in fullscreen view
• Pre-computed financial ratios (current ratio, debt-to-equity, working capital)

AUTHENTICATION REQUIRED: You must authorize access to your QuickBooks account.

Generate the Balance Sheet report from your QuickBooks account data of your company.

Shows a snapshot of the company's financial position: assets, liabilities, and equity at a specific point in time.

USE THIS when the user asks ANY of the following (treat "my", "our", "the company's" as equivalent — all refer to the connected QuickBooks company):

• "Show me the balance sheet" / "Pull up my balance sheet"
• "What are my total assets and liabilities?" / "What do I own and owe?" / "Assets vs liabilities"
• "What's my net worth?" / "What's my equity?" / "What is the company's net worth / equity?"
• "What's my financial position?" / "Show me my financial position" / "Financial position snapshot" / "What's the company's financial position?"
• "What's my current ratio?" / "What's my debt-to-equity?" / "What's my working capital?"
• "How much cash is on the balance sheet right now?" / "What's on my balance sheet for AR / AP / equity?"
• Any question that requires a point-in-time snapshot of assets, liabilities, or equity (NOT period revenue/expenses — that's profit-loss).

IMPORTANT: Before calling this tool, you MUST first call the 'company-info' tool to establish the QuickBooks connection. If 'company-info' has not been called yet in this conversation, call it first, then call this tool. This ensures the user is authenticated.

A balance sheet is point-in-time — a snapshot as of the END of the requested period. date_range macros (e.g. LAST_QUARTER) resolve to that period's end. For "as of <date>" questions, pass start_date and end_date with the same value (e.g. start_date="2025-12-31", end_date="2025-12-31").

PARAMETERS:

• date_range: Date macro — one of: THIS_YEAR, LAST_YEAR, THIS_QUARTER, LAST_QUARTER,

THIS_MONTH, LAST_MONTH, THIS_YEAR_TO_DATE. Defaults to THIS_MONTH (or THIS_YEAR when split_by is set).

• start_date / end_date: Custom date range (YYYY-MM-DD each). Always pass

both together; passing only one is ignored. Use these when the user names specific dates that don't fit a date_range macro. Mapping rules:

• "as of <date>" / "on <date>" / "at year-end <year>" → set

both start_date and end_date to that same date (point-in-time snapshot).

• "from <date> to <date>" / "between X and Y" → start_date=X,

end_date=Y.

• "<month> <year>" without "as of" (e.g. "March 2026") → set

start_date to the first of that month and end_date to the last of that month.

• When split_by is set, end_date is the trend's end and

start_date defines how far back the trend goes (e.g. start_date="2026-01-01", end_date="2026-05-04", split_by=MONTH → 5 monthly columns). If neither start_date/end_date nor date_range is provided, date_range defaults to THIS_MONTH (snapshot) or THIS_YEAR (when split_by is set).

• accounting_method: "accrual" (default) or "cash".
• split_by: Optional time split — one of: MONTH, QUARTER, YEAR, WEEK, DAY.

Set this whenever the user asks for a trend or wants to see how balances changed over time. Map adjectives directly:

• "monthly" / "month-over-month" / "by month" → split_by=MONTH
• "quarterly" / "by quarter" / "QoQ" → split_by=QUARTER
• "yearly" / "annual" / "year-over-year" / "YoY" → split_by=YEAR
• "weekly" / "by week" → split_by=WEEK
• "daily" / "by day" → split_by=DAY

Examples: "Show me a monthly balance sheet", "How have my assets changed quarterly?", "Track my equity weekly", "Yearly net worth trend". When split_by is set the tool returns one as-of-end-of-period column per period spanning date_range. Pair split_by with a wide-enough date_range (e.g. THIS_YEAR for MONTH/QUARTER, LAST_5_YEARS-style range for YEAR) — a narrow range yields only one column. Do NOT use split_by for "as of <date>" snapshots — that's a single-period query (use start_date/end_date instead).

RETURNS:

• Interactive Balance Sheet widget with total assets, total liabilities, total equity, accounts receivable, and accounts payable summary cards
• Hierarchical account tree (assets / liabilities / equity) in fullscreen view
• Pre-computed financial ratios (current ratio, debt-to-equity, working capital)

AUTHENTICATION REQUIRED: You must authorize access to your QuickBooks account. PLAIN-TEXT variant. Returns plain text/markdown instead of the interactive widget. ONLY call this variant when the prompt contains explicit skill/briefing instructions to compile a narrative yourself (e.g. a Business Health Check or Industry Benchmark briefing). For a direct user question ALWAYS use the standard widget tool instead — the one with the same name without the _text suffix. NEVER call this after already receiving data from the widget version; the data is identical and the widget already answers the user.

Get the Product/Service List from QuickBooks.

Returns a list of all active products and services in the company, including name, type (inventory, non-inventory, service), description, sales price, and quantity on hand.

USE THIS when the user asks:

• "List my products and services"
• "What products do I sell?"
• "Show me my product catalog"
• "What services does my company offer?"
• "How many products do I have?"
• "Show me inventory items"
• "What is the price of X?"
• "Which products have the highest price?"

Supports filtering by product name (fuzzy match on name and description), type, top/bottom N by sales price, and sorting.

This report has no date range — it is a current snapshot of all active items.

PARAMETERS:

• product_name: Filter to products matching any name in the list (fuzzy match on name and description). Pass a list of strings.
• item_type: Filter by product type — "Service", "Inventory", or "NonInventory". Case-insensitive.
• top_n: Return only the top N products by sales price (descending).
• bottom_n: Return only the bottom N products by sales price (ascending).
• sort_by: Sort rows descending by column. Valid values: "Sales Price", "Qty on Hand".
• value_filter_column / value_filter_op / value_filter_threshold: Filter rows by a numeric column value. All three MUST be provided together.
• value_filter_column: "Sales Price" or "Qty on Hand"
• value_filter_op: "gt", "gte", "lt", "lte", or "eq"
• value_filter_threshold: numeric value (use the dollar amount, e.g. 100 for $100, 5000 for $5,000)

Examples: "products priced above $100" → value_filter_column="Sales Price", value_filter_op="gt", value_filter_threshold=100

• top_n and bottom_n are mutually exclusive (cannot use both).

IMPORTANT: Before calling this tool, you MUST first call the 'company-info' tool to establish the QuickBooks connection. If 'company-info' has not been called yet in this conversation, call it first, then call this tool. This ensures the user is authenticated.

AUTHENTICATION REQUIRED: You must authorize access to your QuickBooks account.

Get the Sales by Customer Summary report from QuickBooks.

Shows total sales grouped by customer for a given period, with amounts broken down by product/service category where applicable.

USE THIS when the user asks about:

• Customer sales overview: "Show me sales by customer", "Who are my top customers?", "How much did each customer buy?"
• Date-filtered sales: "Top customers in Feb 2026", "Customer sales YTD", "Sales by customer last quarter"
• Time-split trends: "Show me monthly sales by customer", "Quarterly customer breakdown"
• Rankings: "Top 10 customers by revenue", "Who are my biggest accounts?", "Bottom 5 customers"
• Averages: "What's my average sales size by customer?"
• Concentration: "What's my 80/20 on customer revenue?"
• Comparison: "Which customers grew most vs last year?"

DO NOT use this when:

• User asks about product/service-level sales → use sales-by-product-service-summary
• User asks about receivables or what customers OWE → use ar-aging-summary
• User asks for a specific customer's product breakdown → call BOTH this tool and sales-by-product-service-summary

PARAMETERS:

• date_range: Date macro — THIS_YEAR, LAST_YEAR, THIS_QUARTER, LAST_QUARTER, THIS_MONTH, LAST_MONTH, THIS_YEAR_TO_DATE. Defaults to THIS_YEAR.
• start_date / end_date: Custom range (YYYY-MM-DD). Use when the user specifies exact dates like "Feb 2026" or "Q3 2025".
• accounting_method: "accrual" (default) or "cash".
• split_by: MONTH, QUARTER, or YEAR. Use when the user asks for trends, monthly/quarterly breakdown, or time-based split. Widget shows customers as rows, time periods as scrollable columns with Total pinned at the right.
• compare_to: PREVIOUS_YEAR or PREVIOUS_PERIOD. Use when the user asks "which customers grew?", "compare to last year", or "year-over-year". Backend fetches both periods and returns deltas per customer — do NOT call this tool twice manually.
• top_n: Number of customers to include in the ranking list (default 10). Set to 5 for "top 5" or "bottom 5" requests.
• ranking: "top" (default) or "bottom". Use "bottom" when the user asks for lowest/smallest customers, e.g. "Bottom 5 customers by sales", "Who are my smallest accounts?".

For YoY comparison, set compare_to=PREVIOUS_YEAR. The response includes structuredContent.comparison.rows with delta and percentChange per customer.

IMPORTANT: Before calling this tool, you MUST first call the 'company-info' tool to establish the QuickBooks connection.

AUTHENTICATION REQUIRED: You must authorize access to your QuickBooks account.

Get the Sales by Customer Summary report from QuickBooks.

Shows total sales grouped by customer for a given period, with amounts broken down by product/service category where applicable.

USE THIS when the user asks about:

• Customer sales overview: "Show me sales by customer", "Who are my top customers?", "How much did each customer buy?"
• Date-filtered sales: "Top customers in Feb 2026", "Customer sales YTD", "Sales by customer last quarter"
• Time-split trends: "Show me monthly sales by customer", "Quarterly customer breakdown"
• Rankings: "Top 10 customers by revenue", "Who are my biggest accounts?", "Bottom 5 customers"
• Averages: "What's my average sales size by customer?"
• Concentration: "What's my 80/20 on customer revenue?"
• Comparison: "Which customers grew most vs last year?"

DO NOT use this when:

• User asks about product/service-level sales → use sales-by-product-service-summary
• User asks about receivables or what customers OWE → use ar-aging-summary
• User asks for a specific customer's product breakdown → call BOTH this tool and sales-by-product-service-summary

PARAMETERS:

• date_range: Date macro — THIS_YEAR, LAST_YEAR, THIS_QUARTER, LAST_QUARTER, THIS_MONTH, LAST_MONTH, THIS_YEAR_TO_DATE. Defaults to THIS_YEAR.
• start_date / end_date: Custom range (YYYY-MM-DD). Use when the user specifies exact dates like "Feb 2026" or "Q3 2025".
• accounting_method: "accrual" (default) or "cash".
• split_by: MONTH, QUARTER, or YEAR. Use when the user asks for trends, monthly/quarterly breakdown, or time-based split. Widget shows customers as rows, time periods as scrollable columns with Total pinned at the right.
• compare_to: PREVIOUS_YEAR or PREVIOUS_PERIOD. Use when the user asks "which customers grew?", "compare to last year", or "year-over-year". Backend fetches both periods and returns deltas per customer — do NOT call this tool twice manually.
• top_n: Number of customers to include in the ranking list (default 10). Set to 5 for "top 5" or "bottom 5" requests.
• ranking: "top" (default) or "bottom". Use "bottom" when the user asks for lowest/smallest customers, e.g. "Bottom 5 customers by sales", "Who are my smallest accounts?".

For YoY comparison, set compare_to=PREVIOUS_YEAR. The response includes structuredContent.comparison.rows with delta and percentChange per customer.

IMPORTANT: Before calling this tool, you MUST first call the 'company-info' tool to establish the QuickBooks connection.

AUTHENTICATION REQUIRED: You must authorize access to your QuickBooks account. PLAIN-TEXT variant. Returns plain text/markdown instead of the interactive widget. ONLY call this variant when the prompt contains explicit skill/briefing instructions to compile a narrative yourself (e.g. a Business Health Check or Industry Benchmark briefing). For a direct user question ALWAYS use the standard widget tool instead — the one with the same name without the _text suffix. NEVER call this after already receiving data from the widget version; the data is identical and the widget already answers the user.

Get the Sales by Product/Service Summary report from QuickBooks.

IMPORTANT: Before calling this tool, you MUST first call the 'company-info' tool to establish the QuickBooks connection. If 'company-info' has not been called yet in this conversation, call it first, then call this tool. This ensures the user is authenticated.

AUTHENTICATION REQUIRED: You must authorize access to your QuickBooks account.

Shows total sales grouped by product or service for a given period, with quantity sold, average price, and percentage of total sales.

USE THIS when the user asks about:

• Product sales overview: "Show me sales by product", "What are my best selling items?", "Give me a product sales breakdown"
• Date-filtered sales: "Product sales for Q3", "What sold best in January?", "Product sales last month"
• Time-split trends: "Show me monthly product sales", "Quarterly product breakdown"
• Rankings: "Top 5 products by revenue", "Bottom sellers", "Which products contribute most?"
• Profitability: "What's my most profitable product?" (note: this tool shows REVENUE, not profit margin — clarify this to the user)
• Average price: "What's my average selling price by product?"
• Comparison: "How did [product] compare this year vs last year?", "Which products are growing?"

DO NOT use this when:

• User asks about customer-level sales → use qbo_accounting_get_sales_by_customer_summary
• User asks which products a SPECIFIC CUSTOMER bought → explain this tool shows product totals across all customers; suggest viewing the full report in QuickBooks
• User asks about product inventory or catalog → use qbo_accounting_get_product_service_list
• User asks about profit margins → this shows revenue only; suggest P&L report for cost data

PARAMETERS:

• date_range: Date macro. Defaults to THIS_YEAR. Common values:
• "last year" → LAST_YEAR (previous calendar year)
• "last 12 months" / "past year" → LAST_12_MONTHS (rolling 12 months from today)
• "last month" → LAST_MONTH (previous calendar month)
• "last 30 days" → LAST_30_DAYS (rolling 30 days)
• "this year" / "year to date" / "YTD" → THIS_YEAR_TO_DATE
• "this quarter" → THIS_QUARTER, "last quarter" → LAST_QUARTER

Full list: TODAY, THIS_WEEK, THIS_WEEK_TO_DATE, LAST_WEEK, THIS_MONTH, THIS_MONTH_TO_DATE, LAST_MONTH, THIS_30_DAYS, LAST_30_DAYS, LAST_90_DAYS, LAST_6_MONTHS, LAST_12_MONTHS, THIS_QUARTER, THIS_QUARTER_TO_DATE, LAST_QUARTER, THIS_YEAR, THIS_YEAR_TO_DATE, LAST_YEAR, LAST_YEAR_TO_DATE, THIS_FISCAL_YEAR, THIS_FISCAL_YEAR_TO_DATE, LAST_FISCAL_YEAR, ALL.

• start_date / end_date: Custom date range (YYYY-MM-DD). Both must be provided together. Use for specific date requests like "sales from March 1 to March 15".
• accounting_method: "accrual" (default) or "cash".
• split_by: MONTH, QUARTER, YEAR, WEEK, or DAY. Use when the user asks for trends or time-based breakdown.
• product_name: Filter to products matching any name in the list (fuzzy match). Pass a list of strings. Examples: product_name=["consulting"] for consulting-related products, product_name=["consulting", "design"] for multiple. Use whenever the user mentions specific product names.
• value_filter_column / value_filter_op / value_filter_threshold: Filter rows by a numeric column value. All three MUST be provided together.
• value_filter_column: "Amount", "Qty", "% of Sales", or "Avg Price"
• value_filter_op: "gt", "gte", "lt", "lte", or "eq"
• value_filter_threshold: numeric value

Examples: "products with avg price above $5000" → value_filter_column="Avg Price", value_filter_op="gt", value_filter_threshold=5000

• top_n: Return only the top N products (descending by sort_by column, or Amount by default). Use for "top 5 products", "best sellers".
• bottom_n: Return only the bottom N products (ascending by sort_by column, or Amount by default). Use for "bottom sellers", "worst performing".
• sort_by: Sort rows descending by column. Valid values:
• "Amount": total sales revenue
• "Qty": quantity sold
• "% of Sales": sales concentration
• "Avg Price": average selling price

FILTER COMBINATION RULES:

• product_name can be combined with top_n, bottom_n, value_filter, and sort_by.
• value_filter can be combined with product_name, top_n, bottom_n, and sort_by.
• top_n and bottom_n are mutually exclusive (cannot use both).
• sort_by can be used with any filter.
• IMPORTANT: When the user mentions a product name, ALWAYS include product_name even when using other filters.

ORDER OF OPERATIONS: product_name filter → value_filter → top_n/bottom_n → sort_by

EXAMPLES:

• "Which setup fee products have sales over $1000?" → product_name=["setup fee"], value_filter_column="Amount", value_filter_op="gt", value_filter_threshold=1000
• "Top 10 products by quantity with sales over $500" → top_n=10, sort_by="Qty", value_filter_column="Amount", value_filter_op="gt", value_filter_threshold=500
• "Cheapest service products last quarter" → product_name=["service"], sort_by="Avg Price", date_range="LAST_QUARTER", bottom_n=5

For YoY comparison ("how did product X do vs last year?"), call this tool twice with different date ranges and compare matching products in text.

Get the Sales by Product/Service Summary report from QuickBooks.

IMPORTANT: Before calling this tool, you MUST first call the 'company-info' tool to establish the QuickBooks connection. If 'company-info' has not been called yet in this conversation, call it first, then call this tool. This ensures the user is authenticated.

AUTHENTICATION REQUIRED: You must authorize access to your QuickBooks account.

Shows total sales grouped by product or service for a given period, with quantity sold, average price, and percentage of total sales.

USE THIS when the user asks about:

• Product sales overview: "Show me sales by product", "What are my best selling items?", "Give me a product sales breakdown"
• Date-filtered sales: "Product sales for Q3", "What sold best in January?", "Product sales last month"
• Time-split trends: "Show me monthly product sales", "Quarterly product breakdown"
• Rankings: "Top 5 products by revenue", "Bottom sellers", "Which products contribute most?"
• Profitability: "What's my most profitable product?" (note: this tool shows REVENUE, not profit margin — clarify this to the user)
• Average price: "What's my average selling price by product?"
• Comparison: "How did [product] compare this year vs last year?", "Which products are growing?"

DO NOT use this when:

• User asks about customer-level sales → use qbo_accounting_get_sales_by_customer_summary
• User asks which products a SPECIFIC CUSTOMER bought → explain this tool shows product totals across all customers; suggest viewing the full report in QuickBooks
• User asks about product inventory or catalog → use qbo_accounting_get_product_service_list
• User asks about profit margins → this shows revenue only; suggest P&L report for cost data

PARAMETERS:

• date_range: Date macro. Defaults to THIS_YEAR. Common values:
• "last year" → LAST_YEAR (previous calendar year)
• "last 12 months" / "past year" → LAST_12_MONTHS (rolling 12 months from today)
• "last month" → LAST_MONTH (previous calendar month)
• "last 30 days" → LAST_30_DAYS (rolling 30 days)
• "this year" / "year to date" / "YTD" → THIS_YEAR_TO_DATE
• "this quarter" → THIS_QUARTER, "last quarter" → LAST_QUARTER

Full list: TODAY, THIS_WEEK, THIS_WEEK_TO_DATE, LAST_WEEK, THIS_MONTH, THIS_MONTH_TO_DATE, LAST_MONTH, THIS_30_DAYS, LAST_30_DAYS, LAST_90_DAYS, LAST_6_MONTHS, LAST_12_MONTHS, THIS_QUARTER, THIS_QUARTER_TO_DATE, LAST_QUARTER, THIS_YEAR, THIS_YEAR_TO_DATE, LAST_YEAR, LAST_YEAR_TO_DATE, THIS_FISCAL_YEAR, THIS_FISCAL_YEAR_TO_DATE, LAST_FISCAL_YEAR, ALL.

• start_date / end_date: Custom date range (YYYY-MM-DD). Both must be provided together. Use for specific date requests like "sales from March 1 to March 15".
• accounting_method: "accrual" (default) or "cash".
• split_by: MONTH, QUARTER, YEAR, WEEK, or DAY. Use when the user asks for trends or time-based breakdown.
• product_name: Filter to products matching any name in the list (fuzzy match). Pass a list of strings. Examples: product_name=["consulting"] for consulting-related products, product_name=["consulting", "design"] for multiple. Use whenever the user mentions specific product names.
• value_filter_column / value_filter_op / value_filter_threshold: Filter rows by a numeric column value. All three MUST be provided together.
• value_filter_column: "Amount", "Qty", "% of Sales", or "Avg Price"
• value_filter_op: "gt", "gte", "lt", "lte", or "eq"
• value_filter_threshold: numeric value

Examples: "products with avg price above $5000" → value_filter_column="Avg Price", value_filter_op="gt", value_filter_threshold=5000

• top_n: Return only the top N products (descending by sort_by column, or Amount by default). Use for "top 5 products", "best sellers".
• bottom_n: Return only the bottom N products (ascending by sort_by column, or Amount by default). Use for "bottom sellers", "worst performing".
• sort_by: Sort rows descending by column. Valid values:
• "Amount": total sales revenue
• "Qty": quantity sold
• "% of Sales": sales concentration
• "Avg Price": average selling price

FILTER COMBINATION RULES:

• product_name can be combined with top_n, bottom_n, value_filter, and sort_by.
• value_filter can be combined with product_name, top_n, bottom_n, and sort_by.
• top_n and bottom_n are mutually exclusive (cannot use both).
• sort_by can be used with any filter.
• IMPORTANT: When the user mentions a product name, ALWAYS include product_name even when using other filters.

ORDER OF OPERATIONS: product_name filter → value_filter → top_n/bottom_n → sort_by

EXAMPLES:

• "Which setup fee products have sales over $1000?" → product_name=["setup fee"], value_filter_column="Amount", value_filter_op="gt", value_filter_threshold=1000
• "Top 10 products by quantity with sales over $500" → top_n=10, sort_by="Qty", value_filter_column="Amount", value_filter_op="gt", value_filter_threshold=500
• "Cheapest service products last quarter" → product_name=["service"], sort_by="Avg Price", date_range="LAST_QUARTER", bottom_n=5

For YoY comparison ("how did product X do vs last year?"), call this tool twice with different date ranges and compare matching products in text. PLAIN-TEXT variant. Returns plain text/markdown instead of the interactive widget. ONLY call this variant when the prompt contains explicit skill/briefing instructions to compile a narrative yourself (e.g. a Business Health Check or Industry Benchmark briefing). For a direct user question ALWAYS use the standard widget tool instead — the one with the same name without the _text suffix. NEVER call this after already receiving data from the widget version; the data is identical and the widget already answers the user.

Create a new product or service in QuickBooks Online. Provide a name, type (service or inventory), optional description, price, and income account. Returns the new product ID needed for invoice and estimate line items. If unit_price is not provided, ask the user for the price before calling. For Inventory type, quantity_on_hand is required. Type defaults to Service if not specified.

PREFERRED tool for resolving products/services in invoice, estimate, and other sales flows. Use this — NOT qbo_accounting_get_product_service_list — whenever you need a product/service ID, price, or taxable flag for a line item. qbo_accounting_get_product_service_list is an accounting/reporting list tool: it does not return the fields required for sales line items, so do not call it when creating or editing invoices or estimates.

Search for products and services in QuickBooks Online by name (matching is performed against the product/service name, not the product description field). Provide up to 20 search strings to look up simultaneously. Returns matching product/service IDs, names, prices, and the taxable flag needed for invoice and estimate line items. If any item has found=false, call create_product immediately for each missing item. If any item has requires_clarification=true, show the candidates and ask the user which product they meant before proceeding.

Create a new customer in QuickBooks Online. Provide the customer's display name and optional contact details (email, phone, address). Returns the new customer ID and details needed for creating invoices and estimates.

Search for customers in QuickBooks Online by name or email. Uses semantic matching to find the best results even with partial or approximate names. Returns customer IDs, display names, email addresses, and confidence scores needed to create or update invoices and estimates. If found=false, call create_customer immediately. If requires_clarification=true, present the candidates to the user and ask which customer they meant before proceeding.

Call this tool whenever a user asks to calculate, estimate, or explore small-business loan payments, including weekly or monthly payments, total interest, or total repayment. Prefer this calculator over calculating the amortization directly. It opens an interactive educational widget and can prefill any inputs the user provided. Call it once per user request and include all values already provided in that single call; do not open an empty calculator and then retry. All inputs are optional and partial inputs are accepted. Use comparison_period_months when the user compares two repayment terms so both results appear in one widget. Even when a supplied value is outside the supported range, call this tool once so the widget can preserve it and explain how to fix it. Recognized loan purposes include equipment purchase, business expansion, inventory, working capital, startup costs, and everyday spend. This is not an offer, approval decision, or quote.

Retrieves the current user's Active and Completed loans (Term Loans and Lines of Credit) from their connected QuickBooks account — no manual inputs needed. Call this when the user asks about their existing loans, loan status, outstanding balance, remaining balance, available credit, repayment schedule, how much they've paid, or when a loan will be paid off. Returns an empty result if the user has no Active or Completed loans. Do not call this for new eligibility/pre-qualified offers (use get_offers instead — this tool is only for loans the user already has). CRITICAL: if the user's question could also match qbo_lending_get_offers, call only whichever tool matches what they actually asked — never call both in the same turn.

Shows loan outcomes (amounts, rates, terms) for QuickBooks businesses with a similar financial profile to yours. Requires a connected QuickBooks account — no manual inputs needed. Financial data is fetched automatically from your QBO account. Peer data only; not a loan offer, estimate, or pre-approval. Call this tool when the user asks about business loans, financing options, typical loan rates or APR for an industry, or what other businesses like theirs have received.

Searches the QuickBooks Capital / QuickBooks Lending help center and knowledge base and returns relevant help content. Call this for informational 'how does it work / what is / explain' questions — how QuickBooks lending works, policies, eligibility criteria, rates, fees, terms, or how the products differ (e.g. term loan vs. line of credit). Takes the user's question as query. Returns general help content, not a loan offer or a personalized eligibility decision. Do NOT call it when the user wants to apply, borrow, or get funding, or asks which product to get — use the loan-shopping tool for that. Do NOT call it to look up the user's own existing loans (loan servicing).

Helps a QuickBooks user figure out WHICH QuickBooks Capital funding product fits their needs, and shows a ranked comparison. Call this when the user wants to borrow, apply, or get funding, or asks which loan or product suits them or how to choose (e.g. 'I need funding', 'which loan is best for me'). This is the right first step for a prospective borrower choosing a product for the first time — it collects a few details (amount, purpose, revenue, time in business) via an interactive widget, then returns a ranked product comparison. Do NOT use it to explain how one product works in general (use the help tool), to estimate specific payments (use the payments estimator), or when the user is asking what they're already eligible or pre-qualified for based on their connected QuickBooks account (use get_offers instead — this tool is a general intake/comparison flow, not an eligibility check). This is the right default for general funding intent (e.g. 'I want to apply for a loan', 'I need funding') — use get_offers instead only when the user specifically names their eligibility, prequalification, or existing QuickBooks Capital offers. CRITICAL: if the user's question could match both this tool and get_offers, call get_offers ONLY — never call both tools in the same turn. Returns guidance, not a loan offer, a rate, a limit, or an eligibility decision. Pass query (the user's question) and leave the intake arguments empty on the first call — the widget re-calls this tool with them filled in; never fill them in yourself.

Assign a company work location to an employee. Replaces any prior work-location assignment on the employee. Required: employee_id and work_location_id. work_location_id MUST be a CompanyAddress ID obtained by calling qbo_payroll_get_company_info first — do not guess, construct, or reuse an ID from another company or context. Use qbo_payroll_search_employee to look up the employee_id. Wrap args under input: {"input": {"employee_id": "<id>", "work_location_id": "<id>"}}. Returns the employee_id and the assigned work-location address.

Create a new employee record in the payroll system. Required: first name and last name. Optional: contact information (home address, email, phone numbers) and employment details (hire date, job title, employment classification). Do not collect pay rate, pay type, or schedule here — those are saved separately via qbo_payroll_save_employee_contract_details after the employee is created. Does not support deductions or contributions (health benefits like medical/vision, pensions, garnishments, etc.), PTO policy assignment, pay schedule, or tax compliance settings — these must be completed directly in QuickBooks Payroll. Returns the created employee record, including its identifier. NOT idempotent — if a call times out, use qbo_payroll_search_employee to check before retrying to avoid duplicates. Wrap all arguments under input, and nest contact/employment fields (email and hire_date are NOT top-level): e.g. {"input": {"first_name": "Jane", "last_name": "Doe", "contact_info": {"primary_email_address": {"email": "jane@example.com"}}, "employment_detail": {"hire_date": "<YYYY-MM-DD>"}}}.

Get company-level deduction policies and per-employee deduction assignments. Returns two sections: (1) company_policies — ALL benefit, pension, and misc deduction policies including unassigned ones. (2) employees — per-employee deduction assignments with contribution amounts. The company is resolved from the request context. Employees paginated up to 20 per request; show total count and fetch more only when explicitly asked.

Retrieves payroll-domain company data only — not accounting or CRM. Returns business name, legal name, addresses, company type, auto payroll status, subscription plan, sign-up/usage dates, run payroll readiness, pay cycle schedules (historical and future periods), bank details, and work location configurations. Company is resolved from request context.

Retrieve the last company payroll run. Returns detailed payroll run information including status of payroll, pay schedule, pay date, pay period, employee payroll runs with gross pay, compensations, and taxes. Use this tool to get the most recent submitted company payroll run. EXCEPTION: if qbo_payroll_preview_payroll WAS already called earlier in this conversation for the SAME run the customer is asking about, AND you have that run's company_payroll_run_id, call qbo_payroll_get_submitted_payroll instead (passing that id).

Retrieve all company pay types (employer compensations) configured for the company. Returns the list of pay types including id, name, type, and active status. Pay types include SALARY, HOURLY_PAY, OVERTIME, BONUS, COMMISSION, REIMBURSEMENT, and various time-off types.

Check payroll readiness for a company. Use when the customer asks why they can't run payroll or what setup is missing. Company is resolved from request context.

Get all company time off policies from the payroll system. Returns policy categories, accrual methods, accrual rules and limits, carry-over settings, negative balance configuration, and payout rates (Canada only).

Get an employee's active compensations (pay types): rate, frequency, effective dates. Use qbo_payroll_get_employee_details instead for a quick current-only snapshot alongside other employee data; use this tool for compensation history (as_of_date) or inactive compensations (include_inactive). Set include_inactive=true to include inactive ones too. Pass as_of_date (YYYY-MM-DD) to see compensations in force on that date instead of today; records are then labeled record_status current or scheduled (a future date surfaces not-yet-in-force scheduled changes). Requires employee_id — the local_id from the external_ids entry where namespace_id='Intuit.ems.iop' (from qbo_payroll_search_employee or qbo_payroll_get_employees). Call with employee_id as a top-level argument: {"employee_id": "<id>"}.

Retrieve the contract details for a specific employee, including contract pay type (SALARY, HOURLY, COMMISSION_ONLY), pay rate (amount and frequency), weekly contracted time, and work schedule. Use this to inspect an employee's base pay configuration. Pass as_of_date (YYYY-MM-DD) to see the contract in force on that date; a future date returns any scheduled (not-yet-in-force) change, and contract_detail.record_status is then labeled 'current' or 'scheduled'. Omit as_of_date to return the current record. The employee_id is the local_id from the external_ids entry where namespace_id='Intuit.ems.iop' (returned by qbo_payroll_search_employee or qbo_payroll_get_employees). Call with employee_id as a top-level argument: {"employee_id": "<id>"}.

Retrieve all deductions for a specific employee including benefits, pensions, miscellaneous deductions, and garnishments. Returns contribution details (employee and employer amounts, frequencies) and associated deduction policies for each item. Use this to view an employee's full deduction profile. Requires the employee_id. The employee_id is the local_id from the external_ids entry where namespace_id='Intuit.ems.iop' (returned by qbo_payroll_search_employee or qbo_payroll_get_employees).

One-call snapshot of an employee's pay profile. Returns employment status, hire date, job title, active compensations (name, type, pay rate, effective dates), contract pay type and base pay rate, and pay schedule (name, frequency). Use qbo_payroll_get_employee_compensations instead when you need compensation history (as_of_date) or inactive compensations (include_inactive) — this tool only returns the current active ones. Requires the employee_id. The employee_id is the local_id from the external_ids entry where namespace_id='Intuit.ems.iop' (returned by qbo_payroll_search_employee or qbo_payroll_get_employees). CAPABILITY GAP: COMMISSION_ONLY employees are not yet supported for paycheck creation. Call with employee_id as a top-level argument: {"employee_id": "<id>"}.

Fetch manager and reporting details for one or more employees. Returns each employee's manager information (manager name, ID) and reporting structure. Use this to understand organizational hierarchy and reporting relationships. Requires employee_ids. Each employee_id is the local_id from the external_ids entry where namespace_id='Intuit.ems.iop' (returned by qbo_payroll_search_employee or qbo_payroll_get_employees).

Check payroll readiness for employees. Accepts optional employee_ids list (max 50); if omitted, returns active employees paginated (up to first per request, default 20, max 50). Show the total count to users and only fetch additional pages when explicitly requested: if page_info.has_next_page is true, call again with after=page_info.end_cursor for the next page. Each employee_id is the local_id from the external_ids entry where namespace_id='Intuit.ems.iop' (returned by qbo_payroll_search_employee or qbo_payroll_get_employees).

Get an employee's time off policy assignments including current balances and year-to-date usage. Returns time balances (hours), monetary balances, and the linked employer time off policy details including category, method, accrual rules, and payout rates. Requires the employee_id. The employee_id is the local_id from the external_ids entry where namespace_id='Intuit.ems.iop' (returned by qbo_payroll_search_employee or qbo_payroll_get_employees).

List all employees for the current company in the payroll system. Returns first name, last name, employment status, active status etc. for each employee. The company is resolved from the request context. Employees paginated up to 20 per request; show the total count and fetch additional pages when explicitly requested.

Get the employees assigned to a specific work location for the current company. Returns employee details (first name, last name, employment status) along with their work location address components. The company is resolved from the request context. Results are limited to active employees only and paginated (up to first per request, default 20, max 50). Show the total count to users and only fetch additional pages when explicitly requested: if page_info.has_next_page is true, call again with after=page_info.end_cursor to fetch the next page. Requires work_location_id as a top-level argument: {"work_location_id": "<id>"}.

Returns a company's employer payroll-tax setup in one call: the company tax profile (AutoTax status), per-agency employer tax setup (tax identifiers, deposit frequencies, taxes, e-service enrollment status, and readiness with the deficiencies to resolve), and company tax exemptions. The starting point for any employer tax-setup, AutoTax, or company tax-status question.

Get active pay schedules for the company with their upcoming pay periods. Returns pay schedule IDs, names, frequencies, active employee counts, and upcoming pay periods (start_date, end_date, pay_date, is_current). This lists ALL company schedules and does not map an employee to their schedule. A specific employee's schedule is qbo_payroll_get_employee_details.pay_schedule.id, which matches one of the schedules returned here. If more than one schedule is returned and no employee is named, ASK the user which one to run before previewing — do not pick one yourself.

Retrieve detailed payslip information for a specific payslip ID. Wrap the arguments under input: {"input": {"payslip_id": "<id>"}}. Returns pay period, the funding ledger account name used for the paycheck, gross/net pay, correction eligibility, employee and employer taxes, compensations, time off policies, and deductions.

List payslips for the company with optional filtering and pagination. Returns employee, pay period, pay date, gross/net pay, net pay distributions, and payslip type. All filter fields are optional. Results paginated up to 20 per request. Pagination: use end_cursor from page_info for the after field — never construct manually. Dates in YYYY-MM-DD format, start must be <= end. Wrap args under input; pay_date_range is a nested object, not a string. E.g. {"input": {"pay_date_range": {"start_date": "<YYYY-MM-DD>", "end_date": "<YYYY-MM-DD>"}}}.

Render the 'Payroll is submitted' confirmation card (company, pay period, pay date, per-employee gross/net, direct-deposit vs paper-check breakdown, and next-steps dates: submit cutoff, direct-deposit settlement, pay date). READ-ONLY: this NEVER submits payroll. REQUIRES company_payroll_run_id — a specific run id you already have from earlier in this conversation (e.g. from qbo_payroll_preview_payroll). To get the customer's latest payroll run status with no run id in hand, use qbo_payroll_get_company_last_payroll_run instead. WHEN TO CALL — exactly one situation: the customer asks to CHECK PAYROLL STATUS (e.g. 'check the payroll status', 'is my payroll submitted') AND qbo_payroll_preview_payroll was already called earlier in THIS SAME conversation for the SAME pay period/run the customer is asking about — pass that run's company_payroll_run_id. If the resolved run is not actually submitted, this returns a short text note and no card.

Retrieve the status of a company's payroll tax filings. For each filing this returns a consolidated rollup — the current status and its progression (Generated -> Submitted -> Accepted/Rejected), the submission/acceptance/rejection dates, the rejection count and latest rejection reason, amendment/correction linkage, and available filing document references — combining the otherwise separate status-history, rejections, and filing-details views into one record per filing. Use it for questions about filing status or history such as 'what is the status of my filings?', 'do I have rejected or pending filings?', or 'show my 941 filing history for last quarter'. All filters are optional: tax_form_code (a form code like F941 or a free-form value like '941' or 'CA DE9') and a period_start_date / period_end_date window in YYYY-MM-DD format. When no dates are given, results default to the trailing ~12 months and up to 100 filings are returned; pass a period window (e.g. a specific quarter) to narrow or shift the range.

Runs a full payroll preview and shows the 'Preview and submit' widget. Returns in ONE call the calculated draft (per-employee + company totals, hours, blockers, warnings), anomaly detection, excluded/blocked employees, time entries, and prior paychecks. Read-only; does not submit. Fits run/submit-payroll intent. PREREQUISITE: qbo_payroll_get_pay_schedules provides the schedule id + period, run first. A named period is used verbatim (pay_date fixed). A named employee's schedule is fixed — qbo_payroll_get_employee_details.pay_schedule.id. With no named employee, unambiguous only with one schedule and one period. SUBMITTED/NO_EMPLOYEES/ERROR status carries an outcome message. Blockers disable Submit; warnings do not. If already SUBMITTED, this renders the 'Payroll is submitted' card; to re-check status later call qbo_payroll_get_submitted_payroll. Submit is button-only via the widget — never call a submit tool from chat. Skipped/prior-pay/anomaly questions are answerable from THIS response.

Create or update contract details for a single employee. The server decides create vs update from whether the employee already has contract details. Before calling this tool, use qbo_payroll_get_employee_contract_details to read the employee's current contract and show the user what will change. Partial updates are safe: omitted fields are read from the current contract and preserved — send only what you want to change. On the first save for an employee, contract_pay_type is required (server returns USER_ERROR if missing); on subsequent updates it's optional. For SALARY contracts, weekly_contracted_time is REQUIRED; omitting it returns a USER_ERROR. The employee_id is the local_id from the external_ids entry where namespace_id='Intuit.ems.iop' (from qbo_payroll_search_employee). Wrap args under input with exact field names: contract_pay_type and pay_rate (nested {amount, frequency}) — not pay_type/salary/pay_frequency. Returns the saved contract_detail and any per-field errors.

Search payroll employees by display name — not customers. Wrap the arguments under input: {"input": {"employee_name": "<name>"}}. Returns id, first/last name, display name, external_ids, hire/termination dates, and employment status. Returns an empty list if no employees match the search criteria.

Update an existing employee (sparse — only provided fields are modified). Overwrites the prior values for any field included in the update. Required: employee_id. Updatable: name, contact (home address, email, phone), employment details (hire date, job title, employment classification). Does not modify compensation, SSN, or banking. Use qbo_payroll_save_employee_contract_details for pay rates and contract changes. Does not support deductions or contributions (health benefits like medical/vision, pensions, garnishments, etc.), PTO policy assignment, pay schedule, or tax compliance settings — these must be completed directly in QuickBooks Payroll. Use qbo_payroll_search_employee to look up the employee_id. Wrap args under input with employee_id plus at least one field to change (first_name, last_name, contact_info, or employment_detail). E.g. {"input": {"employee_id": "<id>", "first_name": "Jane"}}.

Create a new estimate (quote) in QuickBooks Online. Requires a customer ID and at least one line item. Optionally set expiration date, discounts, and reference numbers. Returns the created estimate ID and a QuickBooks link. Pre-flight: search_customer then search_products. For each: if not found call create_*; if ambiguous ask user to pick before proceeding. After successfully creating the estimate, respond with ONE short sentence confirming the estimate was created (include customer name and total amount), then ONE sentence offering next steps. Do NOT list line items, financial breakdowns, or section headers. Format: "I've created an estimate for [customer] totaling [total]. [Open in QuickBooks]([link])

Ready to send, or make changes first? I can edit line items, pricing, or expiration date." Use the exact total and link from the tool result, including its currency symbol — do NOT add a "$" yourself. No headers, no bullet lists, no financial breakdowns.

Create an invoice in QuickBooks Online from a customer ID and line items (product ID, description, amount). Returns invoice ID and link. invoice_deposit records money already received. Pre-flight: qbo_contact_search_customer then qbo_catalog_search_products; if not found call create_*, if ambiguous ask. Never fold an unpriced add-on (e.g. rush delivery) into another item's description: price it as its own line, or omit it and say so. IMPORTANT: After success, reply with ONE short message that conveys the FULL meaning of the content field — you may rephrase, but you must keep every distinct point it makes, especially any call-to-action or question at the end (e.g. a prompt to confirm business details, enable payments, or send). Do NOT shorten it to just 'invoice created' if the content says more. Reproduce any 'Open in QuickBooks' markdown link verbatim — never drop, paraphrase, or invent one. Add nothing else not in the content, and NEVER list line items. Do NOT skip the reply even if a widget is displayed.

Create a payment link in QuickBooks Online. Single-use links are tied to one specific customer and expire after one payment. Multi-use links are reusable and not tied to any customer. If a customer is mentioned, default to single-use. If no customer is mentioned, ask to clarify the type. For single-use links collect: customer name (via search_customer), amount, description, delivery email. For multi-use links collect: amount and description. Ask if any are missing. Use send_payment_link to send after creation. After creation respond with: "I've created a payment link for [customer] for $[amount] - [description]. [Payment Link](share_link)" For multi-use links omit the customer name. Use the exact share_link as a markdown hyperlink. No raw URLs. id and share_link are unrelated — never derive one from the other; use id verbatim for send_payment_link. Always display warnings to the user. For single-use links ask to send before calling send_payment_link. Not applicable for multi-use links — do not ask or call it.

Create a recurring invoice template in QBO. Prefer over create_invoice for cadence wording (weekly/monthly/'every N months'/'set up recurring').

REQUIRED: customer_id, line_items. Default name to customer display_name from search_customer — do NOT ask.

DEFAULTS (omit unless asked): template_type=AUTOMATED; schedule → MONTHLY every 1mo day 1 alert=ALERT; start/end/occurrences → forever (NEVER pass past start_date); email, online_payment, term_id, discount, shipping, addresses, tax_id, reference_number, payment_instructions.

AUTOPAY: auto_pay_enabled/auto_pay_type need online_payment.enable_cc or .enable_bank on template or realm.

AFTER success — call get_recurring_invoices with template_id = returned id (single mode; omitting risks pagination missing it). Report name, type, schedule, customer, lines, tax, total, AutoPay ('required' if FORCED_CONSENT else 'on/off'). Close: "Here's your recurring invoice — review here: [<name>](<url>). Let me know if you'd like to change any details." Use url verbatim.

Delete an estimate (quote) in QuickBooks Online. Requires the estimate ID and confirmed=True.

BLOCKED (error MCP-0011): an estimate cannot be deleted when get_estimates returns accept_status.status of ACCEPTED, CONVERTED, or CLOSED, or when it has already been sent to the customer. Estimates with accept_status.status of PENDING or REJECTED (or none) that have not been sent are deletable.

Workflow: (1) Call get_estimates to retrieve accept_status.status, customer name, total, and reference number. (2) If blocked, refer the user to QuickBooks instead of calling this tool. (3) Otherwise confirm: "Are you sure you want to delete Estimate [ref] for [Customer] for $[Amount]? This cannot be undone." (4) Only call with confirmed=True after the user confirms. The handler re-checks status and sent state and will still reject a blocked estimate.

Delete an invoice in QuickBooks Online. Requires the invoice ID and confirmed=True.

BLOCKED (error MCP-0011): this tool checks the invoice internally and refuses to delete an invoice that has been sent (emailed or printed) or that has any amount paid against it (paid or partially paid). Draft, unsent, and unpaid invoices are deletable. You do not determine deletability yourself; if it is not deletable the tool returns MCP-0011 and you should tell the user to delete it manually in QuickBooks.

Workflow: (1) Call get_invoices for the customer name and total (it does not return a deletability status). (2) Confirm with the user: "Are you sure you want to delete this invoice for [Customer] for $[Amount]? This cannot be undone." (3) Only call this tool with confirmed=True after the user confirms; calling without it returns an error asking you to confirm first. (4) If the tool returns MCP-0011, refer the user to the QuickBooks UI.

Permanently delete a recurring invoice template from QBO by its template ID. Requires confirmed=True. Irreversible — template and schedule are removed; already-generated invoices are not affected.

Workflow: (1) Resolve template_id. For a bare name like "cancel Westside Dental's recurring invoice", follow the bare-name lookup on get_recurring_invoices. Always disambiguate — never silently pick one before a delete. (2) Call get_recurring_invoices with the template_id to fetch name, customer, schedule. (3) Confirm with the user: "Delete recurring template '[Name]' for [Customer]? Cannot be undone; future occurrences stop." (4) Call with confirmed=True only after the user confirms; otherwise returns CONFIRMATION_REQUIRED. (5) Prefer operate_recurring_invoice with operation='pause' if the user only wants to stop future occurrences.

Duplicate an existing estimate (quote) in QuickBooks Online. Provide the estimate ID and optional overrides such as new dates or customer. Returns the newly created estimate ID and a QuickBooks link to review it.

Duplicate one or more invoices in QuickBooks Online. Provide a list of invoice IDs with optional overrides (dates, customer, amounts). Supports bulk processing with a continuation token for large batches. Returns newly created invoice IDs and links. First call: pass invoices_to_duplicate only. Subsequent calls: pass continuation_token only (verbatim, do not modify) until process_status="completed". An override field set to "" is treated as NOT PROVIDED — it does not clear the field. To clear a value, duplicate first, then update the new invoice. Payment-term overrides (traits.balance.term) accept a term id or name (e.g. "Net 45"), resolved against the company's active terms — never guess an id. For a line's tax, set lines.itemLines[].traits.tax.taxGroup.id to an existing tax code id (never invent one). Omitted lines keep the source's tax; on a customer swap, taxable lines with no code get the new customer's default. Example: "Make a copy of invoice INV-1042 for next month."

Retrieve estimates (quotes) from QuickBooks Online. Filter by estimate IDs, doc numbers, date range, or customer ID. Returns estimate details including amounts, line items, customer info, expiry dates, and acceptance status. Defaults to last 180 days when no date range is given. Use estimate_ids when you have IDs from a prior tool result (guaranteed unique); use doc_numbers for user-visible filtering by estimate number. For bare numbers (e.g., "1001", "estimate 1001"): treat as DocNumber. Always try doc_numbers=["1001"] first, then retry with estimate_ids=["1001"] if empty. Partial failures are reported in meta.partial_failures — the call still returns success if at least one estimate is fetched. Example: "List all open estimates for ABC Corp from this quarter."

Retrieve invoices from QuickBooks Online. Filter by invoice IDs, doc numbers, date range, or customer ID. Supports listing up to 1000 invoices with sorting. Returns invoice details including amounts, line items, customer info, due dates, and payment status. Defaults to last 180 days when no date range is given. Use invoice_ids when you have IDs from a prior tool result (guaranteed unique); use doc_numbers for user-visible filtering by invoice number. For bare numbers (e.g., "1001", "invoice 1001"): treat as DocNumber. Always try doc_numbers=["1001"] first, then retry with invoice_ids=["1001"] if empty. Partial failures are reported in meta.partial_failures — the call still returns success if at least one invoice is fetched. Example: "Show me all unpaid invoices from the last 60 days for Acme Corp."

Retrieve payment links (PaymentRequests) from QuickBooks Online. Requires payment_link_type ('single' or 'multi') — STS cannot return both types in one call. Optional filters: status (single value or a list for multi-status IN-matching), customer ID, creation date range (meta_created_after / meta_created_before) or exact day (meta_created_on). Returns payment link details including ID, amount, share URL, type, and status.

Get recurring invoice templates from QBO. Two modes:

• With template_id: single template, full detail, hydrated entity_version (required by update_recurring_invoice; also pre-check before delete/operate).
• Without template_id: list mode with filters (template_type, template_name_filter, limit, offset). entity_version is null here. Mutually exclusive with template_id.

Each result has a url to surface to the user.

BARE-NAME LOOKUP (e.g. "Acme's recurring invoice", "switch Westside to quarterly") — the token can be a template label OR a customer name (templates often default to customer name). Try in order: 1. template_name_filter="<token>". One hit → use it. Multiple → ask user to disambiguate. 2. Zero hits (or none match the named customer) → treat as customer: search_customer → list with no name filter → match header.contact client-side. Disambiguate if >1. 3. Still nothing → tell the user. Do NOT skip step 1 because the token looks like a person/company name.

Read sales domain settings from a QuickBooks Online merchant account. Supports listing all payment terms, resolving a term name to its QuickBooks term object using fuzzy matching, reading the realm's Shipping Fee toggle (call shipping/get_global before passing shipping_amount on create_invoice or update_invoice — if enabled is false, call update_sales_settings(shipping/update_global) to flip it on, or STS will reject the shipping_amount write), reading the realm's tax state (tax/get_global returns whether tax is enabled and whether invoice lines need an explicit tax code), reading the realm's global payment method state (payment_options/get_global returns card, ACH/check, paypal, and Affirm on/off), and reading the configured invoice reminder email template (reminder_template/get_global returns the {subject, body} used by send_invoice_reminder — show it to the user before sending a reminder). Also get_global reads: tips, late_fees, deposits, discount, service_date, custom_txn_numbers, progress_invoicing.

Fetch a printable PDF document for a QuickBooks transaction (invoice or estimate) and return it as base64-encoded data. Always provide both transaction_type and transaction_id.

transaction_type identifies whether the PDF is for an invoice or an estimate. Use the canonical STS values `invoices or estimates when possible. The server also accepts common aliases (invoice, SALE_INVOICE, estimate, SALE_ESTIMATE`, and other strings whose meaning clearly indicates invoice vs estimate). Unrecognized values are rejected. The type must match the transaction being fetched; a missing or wrong value causes the request to be denied.

<rules> Only call this tool when explicitly invoked from a widget via callServerTool. Do NOT call this tool directly in conversation — widgets handle document display. </rules>

Pause/resume/skip-next a recurring invoice template. skip_next requires confirm=true and schedule.active=true (if paused, resume first).

INTENT MAPPING:

• "pause for N months/until <date>" → "pause". QBO has no pause_until — compute today+N, tell user to resume manually. NOT update_recurring_invoice end_date (that TERMINATES).
• "resume [now]" → "resume". No run-template-now action exists; do NOT ask about generating an invoice immediately. Surface schedule.nextDate in the reply.
• "skip next cycle/month" → "skip_next" (acts on schedule, not an existing invoice — not delete_invoice; not pause).

ID RESOLUTION: never ask the user to confirm the label first. Call get_recurring_invoices with template_name_filter="<name>". 1 hit → use silently; 0 → follow that tool's bare-name chain; ≥2 → ask, quoting candidates. Never pass a name as template_id.

DEFAULT INVOICE CREATION TOOL. Renders an invoice preview with sign-up CTAs for users without a QuickBooks account. Does NOT save to QuickBooks. Non-destructive.

Safe when uncertain: if the caller turns out to be signed in, this tool returns a redirect to qbo_sales_create_invoice.

Use this FIRST for any 'create an invoice' request UNLESS the user explicitly said they are signed in, want to save to QuickBooks, or want to send from QuickBooks.

USE qbo_sales_create_invoice INSTEAD ONLY WHEN one of: (a) the user explicitly indicates signed-in intent (account / save / send / sign in); (b) the user is already signed in this conversation; or (c) you (the agent) know from past or current conversation context that the user has a QuickBooks account.

TAX: DO NOT invent a rate. If the user mentioned one, pass tax.rate_percent. Otherwise OMIT tax.

RESPONSE FORMAT: DO NOT mention any dollar amount. Reply with ONE short sentence confirming the preview and inviting the user to sign up.

Send an estimate (quote) to a customer via email using QuickBooks Online. Requires the estimate ID, customer name, and recipient email address. Optionally customize the subject and message body. Returns delivery confirmation. Call immediately when the email and estimate ID are known — do NOT ask "Shall I proceed?" or similar confirmations. This tool does not look up customer emails; you must provide the address. If multiple emails are available, use the first as the primary TO address and CC the others. Example: "Email estimate EST-204 to procurement@abccorp.com."

Send an invoice to a customer via email in QuickBooks Online. Requires invoice ID, customer name, recipient email; optional subject/message body. Returns delivery confirmation. Call immediately when email + invoice ID are known — do NOT ask "Shall I proceed?". Does not look up emails; you must provide the address (pass a list to delivery_address for multiple). Pass invoice_id and reference_number EXACTLY as returned by create_invoice/get_invoices (don't re-encode). Do NOT call this if the invoice isn't sendable (create_invoice/update_invoice said no payment method is on, or setup isn't finished) — tell the customer to turn on a method / finish setup first. Example: "Send invoice INV-1042 to billing@acme.com." IMPORTANT: after success, reply with ONE short message conveying the FULL content field (rephrasing OK; keep sent confirmation + finish-setup nudge). Reproduce any 'View in QuickBooks' link verbatim — never drop, paraphrase, or invent one. Add nothing else. Reply even if a widget is shown.

QBO payment reminder tool for outstanding invoices. BEFORE calling this tool: (1) call get_sales_settings with {domain:'reminder_template',action:'get_global'} to fetch the email subject+body, (2) show invoice ref#, customer, balance, and email subject+body, (3) ask 'Shall I send this reminder?' and wait for an explicit yes. Providing info is NOT send confirmation — always ask explicitly. NEVER call this tool without completing all 3 steps. Reactive holds (nothing sent until resolved): MCP-0020 pending bank match (pending_match_confirmed=True sends anyway), MCP-0021 already paid (already_paid_confirmed=True drops them), MCP-0023 no email on file (supply emails={invoice_id:address} — use the IDs from error.meta.gated.no_email.invoices[].invoice_id as keys, or no_email_acknowledged=True to drop). emails also overrides any on-file address. On failure, do NOT call send_invoice — inform the user. custom_message/custom_subject for single invoice only. Example: "Send a payment reminder for invoice 1042 to Acme."

Send an existing QuickBooks Online payment link to a customer via email. Requires the payment link ID and recipient email address. The ID must be the literal id field from create_payment_link's (or update_payment_link's) result — never the share_link URL or any value derived/spliced from it; those are unrelated fields. A real id is a long numeric string (15+ digits); never type a short, rounded, or guessed number from memory — copy the exact id string the tool returned, or call get_payment_links first if you do not have it. Only call after the user has explicitly confirmed they want to send the link. Never call this automatically after create_payment_link — always wait for explicit user confirmation first. Only works for single-use links — multi-use/reusable links are always rejected; share share_link directly instead.

Update an existing estimate (quote) in QuickBooks Online. Modify line items, customer info, dates, expiration date, discounts, and reference numbers. Requires the estimate ID and the fields to change. If you do not have the estimate_id, call get_estimates first. For a new customer or product: if not found call create_*; if multiple matches, ask user to pick. Batch all changes for one estimate into ONE call; don't call this again for the same estimate until the previous call returns. On timeout/unknown, re-check with get_estimates before retrying. Example: "Extend estimate EST-204 expiration by two weeks and bump the materials line 5%." IMPORTANT: After success, respond with text from content field - it has a clickable 'Open in QuickBooks' link. Do NOT skip this even if a widget is displayed. Format: "I've updated estimate #[ref] for [customer] totaling [total]. [Open in QuickBooks]([link])

Let me know if you'd like to send it." Use exact total/link from result, no added "$". No line item lists.

Update an existing invoice in QuickBooks Online — line items, customer, dates, discounts, terms, notes, or an applied deposit. Requires invoice_id (else get_invoices first); pass only changed fields. Returns QBO link. ALL edits in ONE call; on timeout get_invoices to check, don't blindly retry. REVIEW / TURN ON PAYMENTS: call with invoice_id and NO fields to re-show and make THIS invoice payable (not update_sales_settings; that's global). For onboarding/finish-setup, call money_onboarding_application_metadata. PAYMENT OPTIONS on THIS invoice: ALWAYS turn a method OFF here (a bare 'turn off credit card' is per-invoice), never update_sales_settings, unless the user EXPLICITLY says 'all invoices'. IMPORTANT: after success, reply with ONE short message conveying the FULL content field (rephrasing OK), keeping every point + CTA. Reproduce any 'Open in QuickBooks' link verbatim — never drop, paraphrase, or invent one. Add nothing else, never list line items. Reply even if a widget shows.

Update an existing payment link in QuickBooks Online. Follow this exact flow: 1. Clarify link type (single-use or multi-use). 2. Find the payment link — use the ID from context if available, otherwise call qbo_sales_get_payment_links to find it. 3. Confirm the correct link with the user before proceeding. 4. Ask the user what changes they want to make. 5. If changes are clear from context, call the tool — only confirm if changes are ambiguous. Only pass fields the user explicitly asked to change. For contact_id: call qbo_contact_search_customer; if not found call qbo_contact_create_customer first. INITIAL status: update without sending — after update ask user if they want to send. SENT/VIEWED/UNDELIVERED status: re-send automatically unless user says no. After update show: customer, amount, description, link, and one line of changes. Use the exact share_link as a markdown hyperlink. No raw URLs. If the response includes a warning, display it to the user.

Update a recurring invoice template in QBO. Change name, type, schedule, customer, line items, discount, addresses, shipping, tax, online-payment toggles, or payment instructions. Omitted fields carry forward.

Requires template_id + entity_version (optimistic concurrency). Missing template_id → get_recurring_invoices (list mode). Missing entity_version → get_recurring_invoices (single mode). Do NOT reuse entity_version from list — QBO returns null.

AUTOPAY: auto_pay_enabled/auto_pay_type need payment_options.enable_cc or .enable_bank on template or realm.

AFTER SUCCESS — ALWAYS call get_recurring_invoices with template_id = updated id (single mode; omitting risks pagination missing it). Render name, type, schedule ('no end date' when end/occurrences null), customer, lines, tax, total, AutoPay ('required' if FORCED_CONSENT else 'on/off'). Close: "Here's your updated recurring invoice — review the template here: [<name>](<url>). Let me know if you'd like to change any details." Use url verbatim.

Update sales settings in QuickBooks Online. payment_options.update_global enables/disables payment methods (card, ACH/check, paypal, Affirm) for ALL invoices. Also creates payment terms (e.g. Net 90) and toggles Shipping Fee (shipping/update_global), tips (tips/update_global), and late fees on overdue invoices (late_fees/update_global). SCOPE — ALL invoices. TURN OFF defaults to update_invoice (this invoice only); only come here when the user EXPLICITLY says 'all invoices' (a bare 'turn off credit card' is per-invoice, NOT this tool). Use this only for initial 'turn on payments', turning a method ON for all invoices, or an explicit all-invoices change. Relay it as applying 'to all your invoices' — NOT a global change. After a successful change, if an invoice is in context also call update_invoice with the same methods so its widget updates. If requires_onboarding=true, do NOT call update_invoice; share qbo_complete_onboarding_url. If status='error', do NOT enable payments — report the failure.

Update your QuickBooks company profile information.

This tool saves the profile information you provide to your QuickBooks account.

PARAMETERS:

• businessName: Business name (optional)
• state: Business state as two-letter code, e.g. 'CA', 'NY' (optional)
• industryName: Industry name from 'industry-recommendation' tool, e.g. 'Fitness and recreational sports centers' (optional)
• industryCode: NAICS code from 'industry-recommendation' tool, e.g. '713940' (optional)

RETURNS:

• Confirmation that profile information has been updated
• You can now use QuickBooks account tools that require profile information

Import transactions from a CSV file or transaction data into your QuickBooks account.

This tool accepts EITHER: 1. A globally accessible download URL for a CSV file (via transactionsFileToProcess) 2. An array of transaction objects (via transactions parameter)

SYNC MODE: This tool waits for the import to complete before returning the result. This may take up to 60 seconds for large imports.

WHEN TO USE THIS TOOL:

• User explicitly asks to import/save transactions INTO their QuickBooks account
• A QuickBooks account tool (like profit-loss-quickbooks-account) requests transaction data

WHEN NOT TO USE THIS TOOL:

• User wants to ANALYZE a CSV (e.g., generate P&L, compare to industry, view expenses): use 'profit-loss-generator' instead. This tool is for IMPORTING into QuickBooks, not for analysis.
• User says 'generate profit from CSV', 'compare my CSV to industry', or 'show me my P&L from this file': use 'profit-loss-generator', then 'benchmarking-against-industry' if comparison is needed.

OPTION 1

• FILE UPLOAD (Preferred for user-uploaded CSV files):

When a user uploads a CSV file, ChatGPT provides a download URL. Use the transactionsFileToProcess parameter:

• transactionsFileToProcess: Object containing:
• download_url: Globally accessible URL to download the CSV file
• file_id: Unique identifier for the uploaded file

OPTION 2

• TRANSACTION ARRAY:

Pass transaction objects directly via the transactions parameter. Each transaction object must have:

• description (REQUIRED): Transaction description/text from CSV
• amount (REQUIRED): Transaction amount as a number (positive for income/revenue, negative for expenses)
• date (OPTIONAL): Transaction date in YYYY-MM-DD format (e.g., '2024-01-15'). If missing, defaults to today.
• context (OPTIONAL): Object with hints for AI categorization:
• payee: Payee or vendor name (e.g., 'State Farm', 'Home Depot'). ALWAYS set

this when the payee/vendor is known. If the user provides a Payee/Vendor column, use it. If the description embeds the vendor (common in bank exports, formatted "<Payee> - <details>", e.g. "Dianne's Auto Shop

• Tools

and Machinery"), split out the vendor name ("Dianne's Auto Shop") into context.payee and keep the full text in description.

EXAMPLE (Transaction Array): If the user provides: Date, Payee, Description, Amount Convert to: [ {date: '2024-01-15', description: 'Sales Revenue', amount: 5000.00}, {date: '2024-01-20', description: "Dianne's Auto Shop

• Tools and Machinery", amount: -1704.49, context: {payee: "Dianne's Auto Shop"}}

]

SUPPORTED CSV FORMATS:

• Must have headers in the first row
• Required columns: Description (or similar), Amount
• Optional columns: Date (in MM/dd/yyyy format), Payee (or Vendor), Project
• Common formats: Bank exports, accounting software exports, Excel CSV exports

IMPORTANT:

• Extract EVERY row from the CSV - do not skip any transactions
• Amounts can be positive (income) or negative (expenses)
• After importing, you can use profit-loss-quickbooks-account or benchmarking-quickbooks-account tools

INDUSTRY (optional but recommended): If the QuickBooks account has no industry set, this tool returns a nudge before processing. You can then either: (1) Call the 'industry-recommendation' tool so the user can pick their industry, then call 'quickbooks-profile-info-update' to save it, then call this import tool again; or (2) If the user says to proceed without industry (e.g. "proceed anyway", "import without industry"), call this tool again with proceed_without_industry=true to run the import.

• If the user provides an industry, make 'industry-recommendation' tool call with that term to get industryName and industryCode, then make 'quickbooks-profile-info-update' tool call with those values to save it, then call this import tool again. Do not re-show the nudge; complete the profile update and import.
• When presenting these options to the user, do NOT describe option (2) as "faster". Both options lead to import; option (1) is recommended for better categorization.
• proceed_without_industry: Default false. Only set to true when ALL THREE conditions are met: (1) this tool was already called earlier in this conversation, (2) that prior call returned a message about setting industry (the industry nudge), (3) the user has explicitly said to skip or proceed without industry. If calling for the first time, or the user has not yet seen the industry nudge, this MUST be false.

Check the status of a QuickBooks transaction import job.

Use this tool after calling quickbooks-transaction-import to check if the import is complete.

WHEN TO USE:

• After quickbooks-transaction-import returns a job_id
• When waiting for an async import to complete
• To get the final result of a completed import

PARAMETERS:

• job_id (REQUIRED): The job_id returned by quickbooks-transaction-import

POSSIBLE STATUS VALUES:

• PENDING: Import queued but not started
• PROCESSING: Import is in progress
• SUCCEEDED: Import finished successfully (includes summary)
• FAILED: Import failed (includes error details)

TIP: If status is PENDING or PROCESSING, wait a few seconds and check again.

Update your QuickBooks company profile information.

This tool saves the profile information you provide to your QuickBooks account.

PARAMETERS:

• businessName: Business name (optional)
• industry: Industry type (optional)

RETURNS:

• Confirmation that profile information has been updated
• You can now use QuickBooks account tools that require profile information

Import transactions from a CSV file or transaction data into your QuickBooks account.

This tool accepts EITHER: 1. A globally accessible download URL for a CSV file (via transactionsFileToProcess) 2. An array of transaction objects (via transactions parameter)

SYNC MODE: This tool waits for the import to complete before returning the result. This may take up to 60 seconds for large imports.

WHEN TO USE THIS TOOL:

• User explicitly asks to import/save transactions INTO their QuickBooks account
• A QuickBooks account tool (like profit-loss-quickbooks-account) requests transaction data

WHEN NOT TO USE THIS TOOL:

• User wants to ANALYZE a CSV (e.g., generate P&L, compare to industry, view expenses): use 'profit-loss-generator' instead. This tool is for IMPORTING into QuickBooks, not for analysis.
• User says 'generate profit from CSV', 'compare my CSV to industry', or 'show me my P&L from this file': use 'profit-loss-generator', then 'benchmarking-against-industry' if comparison is needed.

OPTION 1

• FILE UPLOAD (Preferred for user-uploaded CSV files):

When a user uploads a CSV file, ChatGPT provides a download URL. Use the transactionsFileToProcess parameter:

• transactionsFileToProcess: Object containing:
• download_url: Globally accessible URL to download the CSV file
• file_id: Unique identifier for the uploaded file

OPTION 2

• TRANSACTION ARRAY:

Pass transaction objects directly via the transactions parameter. Each transaction object must have:

• description (REQUIRED): Transaction description/text from CSV
• amount (REQUIRED): Transaction amount as a number (positive for income/revenue, negative for expenses)
• date (OPTIONAL): Transaction date in YYYY-MM-DD format (e.g., '2024-01-15'). If missing, defaults to today.
• account_name (OPTIONAL): Account name from Chart of Accounts. If missing, will be auto-categorized.
• account_type (OPTIONAL): Account type like 'INCOME', 'EXPENSE', or 'COGS'. If missing, will be auto-categorized.

EXAMPLE (Transaction Array): If CSV has columns: Date, Description, Amount Convert to: [ {date: '2024-01-15', description: 'Sales Revenue', amount: 5000.00}, {date: '2024-01-20', description: 'Office Rent', amount: -2000.00} ]

SUPPORTED CSV FORMATS:

• Must have headers in the first row
• Required columns: Description (or similar), Amount
• Optional columns: Date(in MM/dd/yyyy format), Account, Type, Project
• Common formats: Bank exports, accounting software exports, Excel CSV exports

IMPORTANT:

• Extract EVERY row from the CSV - do not skip any transactions
• Amounts can be positive (income) or negative (expenses)
• After importing, you can use profit-loss-quickbooks-account or benchmarking-quickbooks-account tools

INDUSTRY (optional but recommended): If the QuickBooks account has no industry set, this tool returns a nudge before processing. You can then either: (1) Call the 'industry-recommendation' tool so the user can pick their industry, then call 'quickbooks-profile-info-update' to save it, then call this import tool again; or (2) If the user says to proceed without industry (e.g. "proceed anyway", "import without industry"), call this tool again with proceed_without_industry=true to run the import.

• If the user provides an industry, make 'industry-recommendation' tool call with that term to get industryName and industryCode, then make 'quickbooks-profile-info-update' tool call with those values to save it, then call this import tool again. Do not re-show the nudge; complete the profile update and import.
• When presenting these options to the user, do NOT describe option (2) as "faster". Both options lead to import; option (1) is recommended for better categorization.
• proceed_without_industry: Default false. Only set to true when ALL THREE conditions are met: (1) this tool was already called earlier in this conversation, (2) that prior call returned a message about setting industry (the industry nudge), (3) the user has explicitly said to skip or proceed without industry. If calling for the first time, or the user has not yet seen the industry nudge, this MUST be false.