Quickbooks

QuickBooks

Use QuickBooks data to answer business questions and complete supported actions.

Connecting

Run quickbooks status first. If disconnected, run quickbooks authorize-url and share only the returned connect_url. After the user connects, run status again. Run quickbooks disconnect only when the user explicitly asks.

Every QuickBooks tool in this catalogue requires a connected company; use quickbooks call-tool for all of them. Each tool also needs the 3LO scopes of its permission tier. Hatch approval still applies to every write.

Connecting grants read access only. Before a write or deletion, or after one fails for missing access, run quickbooks status --for-command <tool-name>, for example quickbooks status --for-command qbo_sales_create_invoice. Every account write and deletion shares one write-access tier, so the first request covers all of them, including sending and deleting, and not only the requested action; say so. When it returns scope_status: not_granted, copy scope_add_url exactly and post it on its own line as [Additional QuickBooks access](<scope_add_url>), then wait for the user to finish before retrying. Unlike a record link, this link gets its own line. granted means the recorded scopes cover the command; Intuit can still reject the token or the company's access. unavailable means the grant is unknown. For a read that fails for missing access, use the same status command to request the read tier. Never construct OAuth URLs or ask for tokens in chat.

Common flows

Use quickbooks list-tools only to discover which tools exist. Immediately before every provider call, run quickbooks list-tools --name <exact-tool-name> and read that tool's current input_schema; never guess a field name, nesting shape, type, or enum value from another tool. Exact lookup uses the connected user's token, like the call. The CLI rechecks that schema immediately before dispatch and rejects mismatches rather than letting Intuit silently ignore them. Call only a reviewed tool and pass an object to
--arguments-json:

quickbooks call-tool --name company_info --arguments-json '{}'
quickbooks call-tool --name profit_loss_quickbooks_account_text --arguments-json '<JSON object>'
quickbooks call-tool --name qbo_sales_get_invoices --arguments-json '<JSON object>'

For a broad business-health question, ask for the period, accounting method, and desired scope in one message. Call company_info, then only the relevant text report tools. Prefer each report's built-in comparison instead of making duplicate calls for another period. Combine the results into one answer. For reports, verify the period in every result; if it differs from the user's request, do not present the figures as the requested report.

For industry research or figures supplied by the user, use the industry benchmark tool. For the connected company's own performance, use benchmarking_quickbooks_account_text. State when peer data or company data is missing.

For receivables or payables, start with the corresponding A/R or A/P aging summary. Fetch detail only when the user asks for a customer, vendor, aging bucket, or reminder. Prefer _text report variants for broad synthesis; use the reviewed widget/non-text variant when the user directly requests that report or its richer presentation. Link an invoice using its reference_number as the label and its returned link as the target. Use its full id only in tool calls.

Before creating an invoice or estimate, resolve the customer and products. Ask before creating any missing customer or product. Treat each line's amount as its unit price, not its extended total. Create the document once, compare the returned total with the proposal, and show the created document before any send.

QuickBooks invoices have no draft state. Once a create succeeds, the invoice is live in the user's company, even before it is sent. Never call it a draft, say it is in draft, or offer to finalize it, even where a tool description mentions draft invoices. If it has not been sent, say it is created but not yet sent.

Hatch keeps editing, sending, recurring billing, and deletion under separate permissions. Approval cards show the specific operation and request details.

Apply the same preview, confirmation, and read-back pattern to invoice or estimate updates and deletions, recurring invoices, payment links, sales settings, transaction imports, and company-profile changes. For duplicate operations, show the source record and intended copy before acting. Never blindly retry these operations after an uncertain result.