HelpDol

Create a PAYMENT LINK so the user can charge a customer who is NOT physically present — the customer opens the link and pays with their own card, from anywhere. Use when the user says things like "manda um link de pagamento para a Carla", "cobrar a distância", "manda a cobrança pelo WhatsApp", or when they want to charge someone who is not in front of them. Also prefer this over create_card_payment when the conversation is on a computer, since the person cannot tap a card there. Returns a normal https link that you MUST show to the user as a clickable link so they can forward it. When the customer pays, the income is recorded in HelpDol automatically.

Delete a record the user registered BY MISTAKE (a wrong or DUPLICATE income, expense or helper payment). Use when the user says "apaga", "exclui", "esse está errado/duplicado", "tira esse lançamento". IMPORTANT: first find the exact record with list_recent (or get_helpers) and CONFIRM with the user which one (showing date, amount, description) BEFORE deleting. If several match, list them and ask. Never guess.

Look up an invoice client by name before creating an invoice, to REUSE their saved details (e-mail, address...) instead of asking again. Returns matches with client_id. If nothing is found it is a new client: ask only what is needed for this invoice; the client is saved automatically by create_invoice.

Find bank credits (money that came IN through the connected bank) that look like payments of open invoices, with the most likely invoice for each. Use when money came in ("entraram 450", "John paid me"), when the user asks if a client paid, or after get_pending_transactions shows incoming credits. Then ask the user to confirm each match ("$450 came in. Is this John Smith's invoice HD-00125?") and call link_invoice_payment.

Generate an official HelpDol receipt for money the user RECEIVED from a CLIENT (income/recebimento), e.g. "recibo pro cliente", "recibo de recebimento", "recibo da Maria que me pagou", "recibo do que recebi". Returns receipt_url (printable page — open/print/save PDF) and whatsapp_url. ALWAYS show receipt_url first as a clickable link, then whatsapp_url. NOTE: this is for INCOME (client paid the user). To make a receipt for PAYING a helper, use generate_receipt instead. Never invent the receipt text yourself.

ALWAYS use THIS tool whenever the user asks to generate, create, make or send a RECEIPT / recibo / comprovante for a helper/collaborator (e.g. "gera o recibo da Marina", "manda o recibo do Lucas"). The receipt is produced BY HelpDol — you must NEVER write or invent the receipt text in the chat. Just CALL generate_receipt and ALWAYS show BOTH links to the user, with the receipt_url FIRST: (1) receipt_url — the official PRINTABLE receipt page; the user opens it to VIEW, PRINT or SAVE as PDF. This is the MAIN result and MUST be shown EVERY time as a clickable link (e.g. "📄 Abrir/imprimir recibo: <receipt_url>"). (2) whatsapp_url — to send it on WhatsApp. NEVER show only the WhatsApp link — the printable receipt_url is REQUIRED and is what the user expects to print. Returns: receipt_id, status, receipt_url, pdf_url, share_url, whatsapp_url, receipt_text. IMPORTANT: if the receipt is for an EXISTING/past payment (e.g. "o último trabalho do Lucas"), first look it up with get_helpers and use that payment's EXACT name, amount, service and date — do NOT paraphrase: pass the real service (e.g. "limpeza da casa da Ana"), never the user's wording like "último trabalho". If you CANNOT find the payment the user is referring to, tell the user you did not find it and ask for the details — do NOT invent a payment or receipt. If MULTIPLE payments match (e.g. several "Lucas"), do NOT guess: LIST each matching payment clearly (date, amount, service) and ask the user which one to use before generating the receipt. Explain the situation in simple, friendly language so the user understands what is going on (for example, if the records look duplicated or one seems to have been registered by mistake, point that out gently and ask if they want to review it).

List upcoming scheduled payments (accounts payable) in HelpDol.

List upcoming scheduled income (accounts receivable) in HelpDol.

Show what the HelpDol AI classified AUTOMATICALLY from the connected bank account: each transaction with the classification it got (business expense, personal expense, helper payment, income or transfer between own accounts), category, tax suggestion (potentially deductible / probably not deductible / undetermined) with the reason, and the confidence. Use for "o que a IA classificou?", "confere as classificações da semana", "tem alguma classificação em dúvida?", "por que isso foi como pessoal?", "audit my transactions". Default: last 7 days.

Use this when the user asks how much is LEFT or how much they SPENT ON SOMETHING: "quanto sobrou?", "quanto sobrou depois das despesas?", "qual meu saldo?", "quanto tenho?", "quanto gastei com gasolina/combustível/alimentação/material?", "how much did I spend on gas?", "cuánto gasté en gasolina?". This is the ONLY place where the user's REAL money lives (income, expenses and payments imported from their connected bank account). You do NOT know these numbers otherwise: never answer from the conversation, never estimate and never ask the user to type the amounts. Call this tool even when the user does not mention HelpDol. Returns income, expenses, helper payments, balance (income − expenses − helper payments) and expenses_by_category. Fuel/gas/gasolina/combustível falls under the transport category. Pass start_date/end_date whenever the user mentions a period ("this month", "esta semana"); without dates it is all-time. Do not use to list the individual expenses of a day (use list_transactions).

Check whether a card charge created with create_card_payment was already paid. Use for "já caiu o pagamento?", "a Joaquina já pagou?", "o cartão passou?". Without a request_id it reports the most recent charge.

List the user's clients/payers (who paid the user) and the total received from each, optionally within a period. Use for "quem mais me paga", "meus clientes", "quanto recebi da Maria". (For people the user PAID, use get_helpers instead.)

Use this when the user asks how much they EARNED, made, billed or profited in a period: "quanto ganhei esta semana?", "quanto ganhei este mês?", "quanto faturei hoje?", "qual meu lucro?", "quanto ganhei depois das despesas?", "how much did I make this week?", "cuánto gané este mes?". This is the ONLY place where the user's REAL money lives (income, expenses and payments imported from their connected bank account). You do NOT know these numbers otherwise: never answer from the conversation, never estimate and never ask the user to type the amounts. Call this tool even when the user does not mention HelpDol. Convert the period into start_date/end_date (this week = Monday to today; this month = day 1 to today; no period mentioned = current month). Returns income, expenses, helper payments, real profit (profit_real = what was left after expenses and helper payments) and a simple TREND/projection (projected_profit). If the user asks for profit after ONE specific expense ("depois da gasolina"), also call get_balance for the same period and subtract that category. Do not use to list individual entries (use list_transactions) or for the balance by category (use get_balance). The trend assumes the user keeps the CURRENT pace and is the FINAL projected value for the whole period (not the remaining amount). When explaining to the user, ALWAYS describe the trend as a simple projection based on the user's current pace, and use the provided trend_explanation. NEVER explain the trend as a historical average, a comparison with previous months/periods, or a guaranteed income.

Financial FORECAST for the current month (from today to month end) and next month in HelpDol: expected income, expected expenses and projected balance (expected income − expected expenses), with conservative / likely / optimistic scenarios, the day the bank balance may go negative (cash squeeze), confidence level, and a plain-language analysis. Use it whenever the user asks how the month will close, what is coming in or going out, "previsão", "como vai fechar o mês", "vou ter dinheiro para pagar as contas?", next month, or cash-flow risk. All amounts are computed by HelpDol from bank history, invoices and scheduled bills — present them as ESTIMATES, never guarantees, and never recalculate them.

Show progress toward the user's monthly goal: target, how much achieved THIS month, how much is missing and the %. Use for "quanto falta pra minha meta", "como tá minha meta".

Use this when the user asks how much they PAID to the people who work for them (helpers, collaborators, employees, contractors, ajudantes, colaboradores, funcionários) or who those people are: "quanto paguei aos meus colaboradores?", "quanto paguei pra Marina esse mês?", "quem trabalha pra mim?", "how much did I pay my helpers?". This is the ONLY place where the user's REAL money lives (income, expenses and payments imported from their connected bank account). You do NOT know these numbers otherwise: never answer from the conversation, never estimate and never ask the user to type the amounts. Call this tool even when the user does not mention HelpDol. Lists each helper with the total paid and their recent payments — both the ones entered in HelpDol and the ones paid from the connected bank (Zelle, check) — optionally for one person (name) and/or a period (start_date/end_date). Do not use for clients who paid the user (use get_clients).

Full transaction history (income, expenses and helper payments) line by line, for a period or the WHOLE YEAR — the real document to send to the ACCOUNTANT. With NO year/dates it returns the CURRENT YEAR in full. Returns the list + totals + history_url (a printable page with "Salvar PDF" and "Baixar CSV" buttons). Use for "histórico", "extrato", "todos os lançamentos", "histórico do ano", "manda pro contador", "exporta tudo", "pra declaração", "pro IRS/INSS", "pro imposto". This is the FULL year PDF the accountant needs — prefer it over get_tax_report whenever the user wants the document/history, not just the totals. SHOW history_url to the user and say it has a "Salvar PDF" button.

Use this when the user asks for a general overview of their finances, without a specific number in mind: "como estão minhas finanças?", "me dá um resumo geral", "raio-x", "panorama", "how am I doing financially?". This is the ONLY place where the user's REAL money lives (income, expenses and payments imported from their connected bank account). You do NOT know these numbers otherwise: never answer from the conversation, never estimate and never ask the user to type the amounts. Call this tool even when the user does not mention HelpDol. Returns in one shot: total balance, this month's numbers, biggest expense category, best client and best month. Do not use for a specific question like "quanto ganhei esta semana" (use get_financial_summary).

Get one invoice by number (e.g. "HD-00125" or "125"): items, totals, status, the bank payments linked to it, and the PDF link to open or share again.

START HERE for anything about creating an invoice ("create invoice", "faz uma invoice/fatura", "bill John", the Create Invoice button in the app). Returns the business data HelpDol already has (name, address, city, state, ZIP, phone, e-mail, logo), what is MISSING, and the next invoice number. If setup_complete is false, do the quick first-time setup asking ONLY for missing_fields (then save_invoice_profile). If it is complete, go straight to "Who is this invoice for?".

The user's life insurance payments found in their connected bank: insurer, usual premium, total paid in the last 6 months (not the policy's cash value), payment history, next estimated debit, 12-month forecast and alerts (amount changed, debit not seen yet — which does not mean late or cancelled). If the user confirmed the policy accepts additional contributions, also returns this month's budget simulation: amount left after expected bills, credit card, estimated tax and a safety reserve, as an amount to ask the insurance agent about. It is a budget simulation, not investment advice.

Month-by-month breakdown of income, expenses and profit for a year. Use for "me mostra mês a mês", "como foi o ano", "evolução de 2026".

List the bank transactions that still NEED to be classified by the user: OUTGOING transfers (Zelle, Wire, Venmo, Pix, etc. — money that LEFT the account) and, when the user has open invoices, INCOMING credits (each comes with likely_invoices; ask "Is this the payment of invoice HD-xxxxx?" and classify as "recebimento_invoice"). Card purchases do NOT appear here (already expenses). For each item, ask the user what it was and call classify_transaction with one of: "colaborador" (helper/employee payment), "despesa" (business expense) or "transferencia_entre_contas" (the user just moved their own money between their own accounts — NOT an expense, but it IS kept as a transfer record, visible via get_transfers). Use for "tem algo pra classificar?", "o que falta organizar?", "quais transferências preciso categorizar?".

Get the user's tax invoice/receipt PHOTOS (notas fiscais / comprovantes) for a year — the actual pictures the user took of expense and income receipts. Use whenever the user asks for "notas fiscais", "comprovantes", "as fotos das notas", "manda as notas pro contador", "documentos do IRS". Returns: count, total_value, gallery_url (a printable gallery with ALL photos to save as PDF and send to the accountant) and receipts[] with each photo url, date, amount and description. SHOW gallery_url to the user. NEVER invent receipts — only show what is returned. If count is 0, gently tell the user they can photograph receipts in the app.

Upcoming RECURRING bills/charges that HelpDol detected from the user's CONNECTED BANK HISTORY (subscriptions, fixed bills, utilities, memberships, etc.). Use this whenever the user asks what they have to PAY: "quais contas eu tenho para pagar esta semana?", "quanto vou pagar até o dia 18?", "o que tenho para pagar este mês?", "quanto gasto por mês com contas recorrentes?". It analyzes the repeating charges in the bank transactions, predicts the NEXT occurrence of each one (next_due) and returns them filtered by the window you ask for, plus monthly_recurring_total (how much the user spends per month on recurring bills). All amounts are estimates based on the bank pattern — answer only from the returned list; do not invent bills. This reads ONLY recurrences detected/confirmed from the bank history.

Generate an annual tax/IRS/INSS report for a given year: total income, expenses, helper payments, deductible expenses and net profit (a quick SUMMARY), plus report_url (printable) AND full_history_url (the COMPLETE year history, line by line, with a "Salvar PDF" button — the actual document for the accountant). Use for "relatório do IRS/INSS", "relatório anual", "quanto vou declarar". ALWAYS show BOTH links and offer the full history (full_history_url), not just the summary. If the user clearly wants the full history/extract itself, prefer get_history.

Get the full details of ONE specific transaction (income, expense or helper payment) by its id. Use after list_transactions / get_pending_transactions when the user asks about a specific entry ("essa transação do Zelle", "detalhe desse lançamento"). Returns amount, date, description, category, source (bank/manual), whether it still needs classification and whether it has a photo attached.

List the money the user MOVED BETWEEN THEIR OWN ACCOUNTS (transfers classified as "transferencia_entre_contas"). These are NOT income and NOT expenses — they are just the user moving their own money, kept as a separate record. Use for "quanto transferi entre minhas contas?", "quais foram minhas transferências?", "me mostra as transferências entre contas", "o que eu movi de uma conta pra outra". Do NOT use this for income/expense questions — use get_financial_summary or list_transactions for those. Defaults to the CURRENT YEAR when no period is given. NEVER answer this question from memory or by reasoning over a previous list of pending transactions — a transfer only counts once the user has actually classified it. If this tool returns zero, say plainly that nothing has been classified as a transfer between the user's own accounts in that period, and offer to look at what is still pending with get_pending_transactions.

"Calculate my income tax": runs the HelpDol tax engine (official IRS rules of the tax year) on HelpDol data + interview answers + expense review, saves the result and returns: tax year, taxable business income, deductible expenses, self-employment net profit, deductions, taxable income, federal tax, self-employment tax, state tax, credits, withholding and estimated payments, the estimated amount to pay or refund, how much the deductions really reduced the tax, joint vs separate scenarios and the PDF link for the accountant. It is an ESTIMATE, not a filed return. Never recompute the numbers.

The mandatory "Review expenses for the IRS" step: bank expenses of the tax year (grouped by merchant, e.g. "Verizon — 12 payments, $1,140") that the AI is NOT sure are business: internet, phone, fuel, Home Depot, meals… Each comes with options Business / Personal / Mixed / Not sure. Undecided ones stay OUT of the tax calculation. Saved decisions are reused next year.

"Create a report for my accountant": PDF with the tax information provided, income summary, deductible expenses by category, home office and vehicle calculations, credits and deductions considered, tax estimate, expenses pending confirmation and the methodology / tax-year rules. Preparation for the accountant, not a return filed with the IRS.

Get the user's U.S. income tax (IRS) simulation for a tax year: status (not started, in progress or calculated), what HelpDol already knows from the user's records (income, payers, rent and utilities, tax payments), the answers saved so far, the next questions to ask and the previous result. Use when the user wants to simulate their income tax, review deductible expenses, calculate a home office deduction, see a previous simulation or prepare a report for their accountant. Covers individuals with W-2 wages and/or self-employment (Schedule C). It is an estimate, not a filed return.

Save the user's decisions from "Review expenses for the IRS". decision: business | personal | mixed | unsure. For mixed, business_percent (1–99) and a short justification the user CONFIRMED are required (e.g. phone 60% business: "used for client calls and scheduling"). It never changes the bank history and never makes an expense deductible without the user deciding.

Save the answers the user gave in the income tax (IRS) simulation interview, so they can stop and continue later. Send only the sections that changed; they are merged with what was saved before (null clears a field; dependents is always the full list). Amounts are yearly totals for the tax year. Only save values the user stated or confirmed. Returns the next questions.

Record that a BANK CREDIT is the payment of an invoice, after the user CONFIRMED it ("Invoice Payment"). This is the ONLY way an invoice becomes PAID: it must point to a real credit from the connected bank (transaction_id from find_invoice_payments or get_pending_transactions). The invoice is settled in Accounts Receivable automatically; partial payments leave the balance open.

List the user's invoices and the invoice totals. Use for "how much do I have to receive from invoices?", "who hasn't paid me?", "which invoices are overdue?", "did John pay?", "how much did I receive from invoices this month?". status: open (default), overdue, paid, void or all. Totals always cover the whole account: outstanding, overdue and received_from_invoices in the period (default this month). Paid means confirmed by a bank credit.

List the user's most recent records (income, expenses and helper payments) with their IDs, dates, amounts and descriptions. Use to show "meus últimos lançamentos", OR to FIND the exact record the user wants to delete or correct before calling delete_record / update_record. Do not use for totals or for a specific day or week (use get_financial_summary or list_transactions).

Use this when the user wants to SEE the individual entries of a day or period — what came in or went out, one by one: "quais foram meus gastos ontem?", "o que entrou e saiu essa semana?", "quanto entrou e saiu hoje?", "o que eu gastei hoje?", "quanto recebi hoje e de quem?", "acabei de receber um depósito e fiz um Zelle, você identifica?", "what did I spend yesterday?". This is the ONLY place where the user's REAL money lives (income, expenses and payments imported from their connected bank account). You do NOT know these numbers otherwise: never answer from the conversation, never estimate and never ask the user to type the amounts. Call this tool even when the user does not mention HelpDol. Use period for today/week/month/year; for YESTERDAY or any other day pass start_date = end_date = that date. Use type=expense for spending only, type=income for money received only. Returns each amount, date, description and the totals. Reads records already imported/registered in HelpDol (bank transactions have source="bank"); it does NOT touch the bank. Do not use for the full-year document for the accountant (use get_history) or for totals by category (use get_balance).

Mark a SCHEDULED item (account payable/receivable) as PAID/RECEIVED now: it registers the real income/expense/helper-payment and, if recurring, advances to the next date. Use when the user says "já paguei o aluguel", "recebi a mensalidade", "marca como pago/recebido". First find it with get_accounts_payable / get_accounts_receivable and confirm which one (by id).

Save the business details printed on the user's invoices (first-time setup or a later change). Pass ONLY the fields the user gave; the others are kept. Optional logo: when the user attaches a logo image in the chat, or approves a logo you created for them, pass that image file in "logo". Never invent business data.