VODER

QUESTION-DRIVEN ANSWER POLICY: pick this tool first for any new question about an Australian GST/BAS position, a United States sales-tax position, or a United Kingdom VAT position. Ask for an explicit start and end date when the user has not supplied a period; never infer a reporting period and never fall back to the legacy GST tool. When the user names an organisation and its `organisationId` is not already known, call `voder_list_organisations` first. In that named-organisation case, do not guess an id or call this tool until `organisationId` has been resolved. The accounting provider is derived from the selected organisation and is returned as provenance; do not ask the user to choose a provider. SUPPORTED ANSWER POLICY: when outcome.status is `ok`, surface the exact period, provider, jurisdiction, regime, basis, currency, as-of timestamp, coverage counts, output tax, input tax, credit adjustments, net amount, and whether it is payable or reclaimable. Quote `position.disclaimer` verbatim beside every numeric estimate. CREDIT-ADJUSTMENT MATH POLICY: `outputTax` and `inputTax` are final after the reported credit adjustments. The identity is `netAmount = outputTax - inputTax`. NEVER show a credit adjustment as another subtractive arithmetic line under those figures; that double-counts it. UNAVAILABLE POLICY: when outcome.status is `unavailable` or `unsupported`, state the exact reason and do not calculate, infer, or reconstruct a number from other tools. Unsupported providers, regimes, bases, incomplete pagination, invalid records, and mixed or missing currencies intentionally return no position. AU HONESTY POLICY: `published_in_xero` means a BAS report was finalised in Xero, not acknowledged by the ATO. Quote the filing-status caveat. A statutory due date is general guidance only; quote its caveat and tell users with a tax or BAS agent to confirm their exact date with the agent or ATO. QUICKBOOKS HONESTY POLICY: `unavailable_from_quickbooks_api` means QuickBooks does not provide filing status or a due date through this connection. State that both are unavailable and quote their caveats; do not infer either answer. US SALES-TAX POLICY: `inputTaxTreatment: not_applicable_us_sales_tax` means this carrier reports collected sales tax only. Do not present inputTax as a recoverable US credit. The estimate does not prove a filed return, payment, due date, or jurisdiction-specific obligation. UK HONESTY POLICY: this is an accrual-basis estimate from accounting records. Filing status and due date are unavailable from the Xero API. Never infer that HMRC received or accepted a return, and never invent a VAT deadline. PROBLEM-DETAILS ANSWER POLICY (read FIRST — applies whenever this response carries a `type` field whose value starts with `https://voder.ai/problems/`): the response is an RFC 9457 Problem Details object — a structured action request, not the normal success carrier. The user needs to take an action; your job is to RENDER that action, not narrate it. Render ONLY these fields, in this order: 1. The `title` field as a short heading. 2. The `detail` field as the explanatory sentence, VERBATIM. 3. A SINGLE markdown hyperlink in the exact form `[voderAction.label](voderAction.url)` — substitute the literal `voderAction.label` string as the link text and the literal `voderAction.url` string as the target. This is the button the user clicks. 4. The `voderAction.hint` field as a brief framing sentence below the link, VERBATIM. DO NOT surface ANY of the following fields to the user — they are internal metadata and have no meaning to a non-developer: `status` (an HTTP-shape integer), `type` (an internal URI), `instance` (an internal reference). The user must NEVER see "409" or "424" or any URI starting with `https://voder.ai/problems/` in your answer. DO NOT narrate or paraphrase the action ("Voder needs you to..." / "The system returned a status code..." / "and gives a 424 with action Connect Voder to Xero at the Voder dashboard"). RENDER the markdown hyperlink so the user can click it directly. DO NOT retry this tool, and do NOT call any other Xero tool to work around the problem — they will all return the same Problem Details response until the user follows the `voderAction.url` link and completes the action.

voder_indirect_tax_position

List customers and suppliers from the selected accounting organisation. Set customerOnly: true to count active customer contacts with invoice history. Use pagination.itemCount only when it is below 2500; exactly 2500 is a lower bound. The count is accounting-system customer contacts, not unique real-world people or businesses. This tool contains no project measure: when the same question asks for a project count, say no exact project count is available instead of guessing from contact or invoice fields.

voder_list_contacts

List customer and supplier credits from the selected accounting organisation.

voder_list_credit_notes

List customer invoices and supplier bills from the selected accounting organisation. This response cannot answer unique-customer or unique-project counts: never count or deduplicate document rows, references, addresses, names, or tracking fields for those measures. Use voder_list_contacts with customerOnly: true for active customer contacts with invoice history; if asked for projects, say no exact project count is available from this response. For a specific invoice, read invoiceLookupResult: existence reports whether the number exists, ledgerStatus reports the accounting state, paymentVisibility is PAID or UNKNOWN, and bankArrivalEvidence is unavailable. Read its descriptions; a zero recorded payment or outstanding ledger balance never proves money did not reach the bank. A voided or deleted invoice is cancelled, not unpaid. For any payment-status question, use each document's paymentVisibility and equal paymentStatus alias as the answer: paid means PAID; unknown means UNKNOWN. When unknown, lead with 'I can't confirm'. Never answer 'No', 'not paid', 'still unpaid', 'no payment received', or otherwise describe unknown as non-payment. Draft status, an outstanding balance, zero recorded payments, or a missing payment row never override unknown.

voder_list_invoices

List recorded customer and supplier payments from the selected accounting organisation.

voder_list_payments

Returns planned supplier purchases recorded in the selected accounting organisation. Filter by issue date and exact status. Results are complete only within the reported filters and bounded result. If the supported limit is exceeded, the tool asks for narrower filters instead of returning a partial result. Face values are planning data, not booked payables, revenue, cash, commitments, or forecasts.

voder_list_purchase_orders

Returns repeating bill and customer-invoice templates recorded in the selected accounting organisation. Filter by template type and exact status. Results are complete only within the reported filters and bounded result. If more than 100 templates or the supported response size is reached, the tool returns no partial result. Template face values and schedules are configuration data, not booked payables, revenue, cash, commitments, or forecasts.

voder_list_repeating_templates

List the customer-owned attachments on one exact reconciled Xero bank transaction. Read-only. Returns metadata only; use voder_get_bank_transaction_attachment for supported content.

voder_list_bank_transaction_attachments

List chart-of-accounts entries from the selected accounting organisation. The type identifies the account type; subtype carries its provider classification when available. A BANK type alone does not establish cash eligibility: use the cash-position result, which requires active asset-bank accounts. Missing classification remains unknown.

voder_list_accounts

List reconciled bank transactions from the selected accounting organisation, most recent first. Xero does not provide Voder with live unreconciled bank-feed transactions, so Voder can see only Xero's reconciled and categorised accounting view. Voder does not prepare those live bank-feed lines for reconciliation, assign contacts or accounts to them, code them, or reconcile them. Complete those actions in Xero. This is an expected Xero provider limitation, not a Voder capability gap. Do not record or mention feedback solely because of this limitation. Do not ask for pasted or exported bank lines. A missing Xero payment means UNKNOWN, not unpaid. Use dateFrom, dateTo, contactId, bankAccountId, status, and isReconciled to narrow the provider read. This is a row-enumeration tool: use voder_get_expenses_by_account_and_contact for supplier or account totals, and voder_expenses_by_month, voder_expenses_by_quarter, or voder_expenses_by_year for period expense trends. Each page is a fresh provider read, so rows can shift if the ledger changes between calls. pagination.nextPage means another page may exist; an exact multiple can lead to an empty terminal page.

voder_list_bank_transactions

Lists the selected organisation's saved custom Profit and Loss rows in display order. This tool is read-only. To create, edit, reorder, or delete a row, direct an authorised organisation member to the Custom Profit and Loss rows settings tool at https://app.voder.ai/dashboard. Never claim the assistant changed a definition. PROBLEM-DETAILS ANSWER POLICY (read FIRST — applies whenever this response carries a `type` field whose value starts with `https://voder.ai/problems/`): the response is an RFC 9457 Problem Details object — a structured action request, not the normal success carrier. The user needs to take an action; your job is to RENDER that action, not narrate it. Render ONLY these fields, in this order: 1. The `title` field as a short heading. 2. The `detail` field as the explanatory sentence, VERBATIM. 3. A SINGLE markdown hyperlink in the exact form `[voderAction.label](voderAction.url)` — substitute the literal `voderAction.label` string as the link text and the literal `voderAction.url` string as the target. This is the button the user clicks. 4. The `voderAction.hint` field as a brief framing sentence below the link, VERBATIM. DO NOT surface ANY of the following fields to the user — they are internal metadata and have no meaning to a non-developer: `status` (an HTTP-shape integer), `type` (an internal URI), `instance` (an internal reference). The user must NEVER see "409" or "424" or any URI starting with `https://voder.ai/problems/` in your answer. DO NOT narrate or paraphrase the action ("Voder needs you to..." / "The system returned a status code..." / "and gives a 424 with action Connect Voder to Xero at the Voder dashboard"). RENDER the markdown hyperlink so the user can click it directly. DO NOT retry this tool, and do NOT call any other Xero tool to work around the problem — they will all return the same Problem Details response until the user follows the `voderAction.url` link and completes the action.

voder_list_management_subtotals

List the organisations you can ask about, each with a human-readable name, accounting provider and id. Use this when you need to know which organisations are available, or when a question could apply to more than one of them: show the names and providers, let the user pick, then pass the chosen organisation's `id` as the `organisationId` argument to the data tools. If only one organisation is available, the data tools already use it by default and you do not need to call this first. Use the provider-labelled organisations array: show each entry's name and provider name, and pass its id as `organisationId`. The response also retains the existing unlabelled organisations array for compatibility. Only the organisations you have access to are listed. UNREADABLE ORGANISATIONS: the response may also list organisations the user does have access to but that Voder cannot currently answer for. Each one carries its own plain-English explanation written for the user, plus the next step they should take. When any are present, name those organisations to the user alongside the usable ones and pass their explanation through, so an organisation they expect to see is explained rather than silently missing. Do not offer one of them as a choice for a data question. Each entry's own text says whether anything can be retried and when - do not override it, and do not apply one entry's next step to another. EMPTY-RESPONSE ANSWER POLICY (read before responding when the response is `{ organisations: [] }`): an empty list does NOT mean the user is unconnected. A user with no connected organisation never receives an empty list — they receive a connect-required error instead. An empty list means Voder does hold organisations for this user but none of them can answer questions yet. The reason and the correct next step differ per organisation, so do NOT invent a single cause: read the unreadable-organisations entries and relay each one's own explanation, which already names what to do. Match singular or plural to how many organisations they actually have, and do not call a data tool for any of them.

voder_list_organisations

QUESTION-DRIVEN ANSWER POLICY (read before picking a tool to answer any spending question): this is the question-shaped surface for expenses-by-month questions — "what did we spend in February?", "show me monthly expenses", "how are costs tracking month-on-month?". Pick THIS tool first for those. It returns each month's total expenses — the whole expense side of your profit-and-loss (cost of sales, operating expenses, and depreciation) — plus a per-account breakdown, so it is the report-authoritative spend total. HOW TO ASK: give the month as `month` in YYYY-MM form (e.g. "2026-02"). Add earlier months as `comparativePeriods` (0 to 23). ANY month is valid. Returns `periods` (one entry per month, most recent first: `{period, expenses, accounts}`) and `coverage`. RECENT-MONTHS HONESTY POLICY: recent months — especially the current month — can still move as bills and bank activity land; say so when the user reads recent figures as final. TOOL CHOICE: for the total you spent in a period (this tool) vs. WHO you spent it with — a by-supplier breakdown — use `xero_get_expenses_by_account_and_contact` for Xero or QuickBooks organisations. FreshBooks supplier breakdown is not available through VODER yet. For the whole P&L (revenue, gross/net profit, not just expenses) use `voder_profit_and_loss_by_month`. OTHER-GRANULARITY REDIRECT: for a quarter use `voder_expenses_by_quarter`; for a financial year use `voder_expenses_by_year`. STAFF / PAYROLL COST ANSWER POLICY (read before answering "what's my payroll cost / staff costs / wages bill / how much do I spend on staff / employment cost / labour cost" questions): payroll appears in these figures as ordinary EXPENSE accounts — typically wages/salaries, employer national insurance (employer NI/NIC), and employer pension contributions. To answer, find those staff-related expense accounts in the per-account breakdown and present them with their amounts as returned — those lines ARE the payroll cost for the period. Show each account and the figure the breakdown gives it; do NOT assert any payroll figure that is not one of those returned per-account amounts (present the individual lines rather than manufacturing a combined headline total). NO-FABRICATE RULE: if the breakdown contains no staff/wages/NI/pension expense accounts, say you cannot find payroll costs in the accounts for this period — do NOT invent or estimate a figure. HONESTY CAVEAT: this is payroll cost as POSTED to the accounts; staff-cost accounts can lag when payroll entries have not yet been posted to the connected accounting provider, and the result excludes anything not coded to those accounts. This reads only accounting expense totals — it does NOT access individual salaries or any employee-level payroll data. TRACKING REFINEMENT: every successful response includes trackingFilters. When its status is available, use the returned names for refinement by passing trackingOption and, when needed, trackingCategory. Unavailable does not mean that no categories exist: do not invent a tracking name or imply that tracking is supported. If refinement was requested but cannot be applied, do not present an unfiltered report as filtered. The financial answer remains valid when no tracking refinement was requested. PROBLEM-DETAILS ANSWER POLICY (read FIRST — applies whenever this response carries a `type` field whose value starts with `https://voder.ai/problems/`): the response is an RFC 9457 Problem Details object — a structured action request, not the normal success carrier. The user needs to take an action; your job is to RENDER that action, not narrate it. Render ONLY these fields, in this order: 1. The `title` field as a short heading. 2. The `detail` field as the explanatory sentence, VERBATIM. 3. A SINGLE markdown hyperlink in the exact form `[voderAction.label](voderAction.url)` — substitute the literal `voderAction.label` string as the link text and the literal `voderAction.url` string as the target. This is the button the user clicks. 4. The `voderAction.hint` field as a brief framing sentence below the link, VERBATIM. DO NOT surface ANY of the following fields to the user — they are internal metadata and have no meaning to a non-developer: `status` (an HTTP-shape integer), `type` (an internal URI), `instance` (an internal reference). The user must NEVER see "409" or "424" or any URI starting with `https://voder.ai/problems/` in your answer. DO NOT narrate or paraphrase the action ("Voder needs you to..." / "The system returned a status code..." / "and gives a 424 with action Connect Voder to Xero at the Voder dashboard"). RENDER the markdown hyperlink so the user can click it directly. DO NOT retry this tool, and do NOT call any other Xero tool to work around the problem — they will all return the same Problem Details response until the user follows the `voderAction.url` link and completes the action.

voder_expenses_by_month

QUESTION-DRIVEN ANSWER POLICY (read before picking a tool to answer any revenue question): this is the question-shaped surface for revenue-by-month questions — "what was revenue in February?", "show me monthly revenue", "how is revenue tracking month-on-month?", "what's the revenue trend over the last N months?". Pick THIS tool first for those. It returns each month's revenue from the connected accounting provider's profit-and-loss report plus a per-account breakdown so you can see which revenue-classified accounts contribute. For an explicit calendar-month range, call this tool first using those months and the selected organisation or single-organisation default. Organisation details are needed only when an unspecified fiscal period must be resolved; do not fetch them before a request that already names its months. HOW TO ASK: give the month as `month` in YYYY-MM form (e.g. "2026-02") and earlier months as `comparativePeriods` (0 to 23). ANY month is valid — there are no date rules to get right. Returns `periods` (one entry per month, most recent first: `{period, revenue, accounts}`) and `coverage`. The accounts array contains nonzero contributions from revenue-classified accounts, not the full chart of accounts. Present these contributions alongside the reported revenue. An empty accounts array does not show whether other accounts exist or are classified correctly. Report a returned zero as zero reported revenue for the requested period. Do not infer no trading activity, no income accounts, or correct account classification from it. Preserve warnings about errors or missing periods; coverage counts periods, not classification completeness. RECENT-MONTHS HONESTY POLICY: recent months — especially the current month — can still move as invoices and bank activity land; say so when the user reads recent figures as final. FULL-STATEMENT REDIRECT: for the whole P&L (costs, gross/net profit, not just revenue) use `voder_profit_and_loss_by_month`. TRACKING REFINEMENT: every successful response includes trackingFilters. When its status is available, use the returned names for refinement by passing trackingOption and, when needed, trackingCategory. Unavailable does not mean that no categories exist: do not invent a tracking name or imply that tracking is supported. If refinement was requested but cannot be applied, do not present an unfiltered report as filtered. The financial answer remains valid when no tracking refinement was requested. PROBLEM-DETAILS ANSWER POLICY (read FIRST — applies whenever this response carries a `type` field whose value starts with `https://voder.ai/problems/`): the response is an RFC 9457 Problem Details object — a structured action request, not the normal success carrier. The user needs to take an action; your job is to RENDER that action, not narrate it. Render ONLY these fields, in this order: 1. The `title` field as a short heading. 2. The `detail` field as the explanatory sentence, VERBATIM. 3. A SINGLE markdown hyperlink in the exact form `[voderAction.label](voderAction.url)` — substitute the literal `voderAction.label` string as the link text and the literal `voderAction.url` string as the target. This is the button the user clicks. 4. The `voderAction.hint` field as a brief framing sentence below the link, VERBATIM. DO NOT surface ANY of the following fields to the user — they are internal metadata and have no meaning to a non-developer: `status` (an HTTP-shape integer), `type` (an internal URI), `instance` (an internal reference). The user must NEVER see "409" or "424" or any URI starting with `https://voder.ai/problems/` in your answer. DO NOT narrate or paraphrase the action ("Voder needs you to..." / "The system returned a status code..." / "and gives a 424 with action Connect Voder to Xero at the Voder dashboard"). RENDER the markdown hyperlink so the user can click it directly. DO NOT retry this tool, and do NOT call any other Xero tool to work around the problem — they will all return the same Problem Details response until the user follows the `voderAction.url` link and completes the action.

voder_revenue_by_month

FRESHBOOKS AVAILABILITY: This tool is unavailable for FreshBooks organisations; use `voder_profit_and_loss_by_month` for a whole-month report. QUESTION-DRIVEN ANSWER POLICY (read before picking a tool): this is the question-shaped surface for every financial-year Profit and Loss question, including "show me this year's P&L", "this financial year to date", "same period last year", "how did FY2026 compare to FY2025?", and annual year-on-year comparisons. Pick THIS tool first for those questions. Figures come from the connected accounting provider's Profit and Loss report, aligned to the organisation's financial year, so this is the report-authoritative source. Never answer a financial-year-to-date question by fetching or locally summing monthly P&L columns. CURRENT FYTD MAPPING: for "this financial year to date", set `year` to the year the current financial year ends and pass today's exact calendar date as `asOfDate`. For "same period last year", set `comparativePeriods: 1`; the tool aligns the prior range to the same elapsed cutoff. Preserve any supplied `trackingCategory` and `trackingOption` names exactly. HOW TO ASK: give `year` as the 4-digit year the financial year ENDS in (e.g. "2026" = the financial year ending in 2026 — for a 30-June year-end that is July 2025 to June 2026; the tool reads the organisation's actual year-end, so you do not need to know it). Add `comparativePeriods` for prior financial years (0 for that year alone, up to 10). For a like-for-like financial-year-to-date comparison, also pass `asOfDate` as the exact cutoff inside that selected financial year; each earlier year then uses the same elapsed cutoff, with 29 February clamped to 28 February where needed. Returns: `periods` (the year labels, most recent first), `summaries` (the headline lines — Gross Profit, Net Profit — read these FIRST), `sections` (Income, Cost of Sales, Operating Expenses, and so on — each with its per-account rows and per-year totals), and `coverage`. Supplied-cutoff responses also return `periodRanges` and top-level `availability`, whose matrices align position-for-position with summaries, sections, accounts and `periods`. Every `amounts` / `totals` array aligns position-for-position with `periods`. FYTD AVAILABILITY POLICY: read `availability.summaryAmounts[i][p]` with `summaries[i].amounts[p]`, `availability.sectionTotals[i][p]` with `sections[i].totals[p]`, and `availability.accountAmounts[i][a][p]` with `sections[i].accounts[a].amounts[p]`. `reported` means the connected provider returned the value, including a genuine zero. `unavailable` means that layout position was absent; the parallel numeric zero is compatibility-only and MUST be described as unavailable, never as reported zero. LEAD-WITH-HEADLINES ANSWER POLICY (read before presenting any answer): lead with Net Profit, Gross Profit, and the section totals — the headline figures, not 80 line items. RECENT-PERIOD HONESTY POLICY: the current financial year, if it is still in progress, is partial and can still move as activity lands — say so when the user reads it as a full-year figure. OTHER-GRANULARITY REDIRECT: for a single calendar month use `voder_profit_and_loss_by_month`; for a calendar quarter use `voder_profit_and_loss_by_quarter`. ACCOUNT-DETAIL PAGINATION: Headline figures, section totals, custom rows, periods, tracking information, and coverage are complete on every page. Only the account rows inside sections can be paginated. If `pagination.hasMore` is true, request the next page only when the customer asks for account-level drill-down. Keep pagination mechanics out of the customer-facing answer. CUSTOM ROWS: Every successful Profit and Loss tool response includes an explicit instruction to quote its provider-specific custom-row guidance. Follow that instruction. Do not imply that the accounting provider supplied custom rows or that the assistant can change saved definitions. TRACKING REFINEMENT: every successful response includes trackingFilters. When its status is available, use the returned names for refinement by passing trackingOption and, when needed, trackingCategory. Unavailable does not mean that no categories exist: do not invent a tracking name or imply that tracking is supported. If refinement was requested but cannot be applied, do not present an unfiltered report as filtered. The financial answer remains valid when no tracking refinement was requested. PROBLEM-DETAILS ANSWER POLICY (read FIRST — applies whenever this response carries a `type` field whose value starts with `https://voder.ai/problems/`): the response is an RFC 9457 Problem Details object — a structured action request, not the normal success carrier. The user needs to take an action; your job is to RENDER that action, not narrate it. Render ONLY these fields, in this order: 1. The `title` field as a short heading. 2. The `detail` field as the explanatory sentence, VERBATIM. 3. A SINGLE markdown hyperlink in the exact form `[voderAction.label](voderAction.url)` — substitute the literal `voderAction.label` string as the link text and the literal `voderAction.url` string as the target. This is the button the user clicks. 4. The `voderAction.hint` field as a brief framing sentence below the link, VERBATIM. DO NOT surface ANY of the following fields to the user — they are internal metadata and have no meaning to a non-developer: `status` (an HTTP-shape integer), `type` (an internal URI), `instance` (an internal reference). The user must NEVER see "409" or "424" or any URI starting with `https://voder.ai/problems/` in your answer. DO NOT narrate or paraphrase the action ("Voder needs you to..." / "The system returned a status code..." / "and gives a 424 with action Connect Voder to Xero at the Voder dashboard"). RENDER the markdown hyperlink so the user can click it directly. DO NOT retry this tool, and do NOT call any other Xero tool to work around the problem — they will all return the same Problem Details response until the user follows the `voderAction.url` link and completes the action.

voder_profit_and_loss_by_year

QUESTION-DRIVEN ANSWER POLICY (read before picking a tool to answer any quarterly profit-and-loss question): this is the question-shaped surface for quarterly P&L questions — "how did Q1 go?", "profit and loss for last quarter", "show me the September quarter", and "how is profit tracking quarter-on-quarter?". Pick THIS tool first for quarterly P&L questions. The figures use the connected provider's Profit and Loss values for the quarter's calendar months; they are not estimates. HOW TO ASK: give the quarter as `calendarQuarter` in YYYY-Qn form. These are CALENDAR quarters: Q1 = January-March, Q2 = April-June, Q3 = July-September, and Q4 = October-December. Add `comparativePeriods` for prior quarters (0 for that quarter alone, up to 11). For a financial-quarter question, use the connected organisation's financial-year start to identify the matching calendar months. If that information is unavailable, ask which calendar months the customer means before calling this tool. Returns: `periods` (the quarter labels, most recent first), `summaries` (the provider-specific headline lines, such as Net Profit — read these first and preserve their labels), `sections` (Income, Cost of Sales, Operating Expenses, and other returned sections, each with per-account rows and per-quarter totals), and `coverage` (the requested quarter and how many were returned). Every `amounts` and `totals` array aligns position-for-position with `periods`. LEAD-WITH-HEADLINES ANSWER POLICY: lead with the returned headline figures and section totals, using their labels exactly as returned. Reach into the per-account rows only when the customer asks what drove a figure. RECENT-PERIOD HONESTY POLICY: the most recent quarter — especially one still in progress — can still move as invoices, bills, and bank activity land. Say so when the user reads the latest quarter as final. OTHER-GRANULARITY REDIRECT: for a single month use `voder_profit_and_loss_by_month`. For providers that support financial-year reporting, use `voder_profit_and_loss_by_year`. FreshBooks annual and financial-year-to-date Profit and Loss reports remain unavailable. ACCOUNT-DETAIL PAGINATION: Headline figures, section totals, custom rows, periods, tracking information, and coverage are complete on every page. Only the account rows inside sections can be paginated. If `pagination.hasMore` is true, request the next page only when the customer asks for account-level drill-down. Keep pagination mechanics out of the customer-facing answer. CUSTOM ROWS: Every successful Profit and Loss tool response includes an explicit instruction to quote its provider-specific custom-row guidance. Follow that instruction. Do not imply that the accounting provider supplied custom rows or that the assistant can change saved definitions. TRACKING REFINEMENT: every successful response includes trackingFilters. When its status is available, use the returned names for refinement by passing trackingOption and, when needed, trackingCategory. Unavailable does not mean that no categories exist: do not invent a tracking name or imply that tracking is supported. If refinement was requested but cannot be applied, do not present an unfiltered report as filtered. The financial answer remains valid when no tracking refinement was requested. PROBLEM-DETAILS ANSWER POLICY (read FIRST — applies whenever this response carries a `type` field whose value starts with `https://voder.ai/problems/`): the response is an RFC 9457 Problem Details object — a structured action request, not the normal success carrier. The user needs to take an action; your job is to RENDER that action, not narrate it. Render ONLY these fields, in this order: 1. The `title` field as a short heading. 2. The `detail` field as the explanatory sentence, VERBATIM. 3. A SINGLE markdown hyperlink in the exact form `[voderAction.label](voderAction.url)` — substitute the literal `voderAction.label` string as the link text and the literal `voderAction.url` string as the target. This is the button the user clicks. 4. The `voderAction.hint` field as a brief framing sentence below the link, VERBATIM. DO NOT surface ANY of the following fields to the user — they are internal metadata and have no meaning to a non-developer: `status` (an HTTP-shape integer), `type` (an internal URI), `instance` (an internal reference). The user must NEVER see "409" or "424" or any URI starting with `https://voder.ai/problems/` in your answer. DO NOT narrate or paraphrase the action ("Voder needs you to..." / "The system returned a status code..." / "and gives a 424 with action Connect Voder to Xero at the Voder dashboard"). RENDER the markdown hyperlink so the user can click it directly. DO NOT retry this tool, and do NOT call any other Xero tool to work around the problem — they will all return the same Problem Details response until the user follows the `voderAction.url` link and completes the action.

voder_profit_and_loss_by_quarter

QUESTION-DRIVEN ANSWER POLICY (read before picking a tool): this is the question-shaped surface for calendar-MONTH Profit and Loss questions — "show me my P&L for February", "what were my monthly costs?", "how is net profit tracking month-on-month?", "what's my gross margin this month?". Pick THIS tool first only when the requested answer is monthly. Figures are read from the connected accounting provider's Profit and Loss report. Section totals and headline lines come from that report and are not recomputed. Use headline labels exactly as returned; examples include Gross Profit, Gross Margin (%) and Net Profit. This is the report-authoritative monthly source. HOW TO ASK: give the month you want as `month` in YYYY-MM form (e.g. "2026-02" for February 2026) and how many earlier months to show alongside it as `comparativePeriods` (0 for that month alone, up to 23 for two years of history). ANY month is valid — February, April, June, September and November included. No date calculation is needed; name the month. Returns: `periods` (the month labels, most recent first), `summaries` (the provider-specific headline lines, such as Gross Profit, Gross Margin (%) or Net Profit — read these first and preserve their labels), `sections` (Income, Cost of Sales, Operating Expenses, and so on — each with its per-account rows and the section's per-month totals), and `coverage` (the requested month and how many were returned). Every `amounts` / `totals` array aligns position-for-position with `periods`: amounts[0] belongs to periods[0], and so on. LEAD-WITH-HEADLINES ANSWER POLICY (read before presenting any P&L answer): lead with the returned headline figures and section totals, using their labels exactly as returned. Reach into the per-account rows only when the user drills in ("ok, what drove that?"). OTHER-GRANULARITY REDIRECT: for a calendar quarter use `voder_profit_and_loss_by_quarter`. For providers that support financial-year reporting, use `voder_profit_and_loss_by_year`. FreshBooks annual and financial-year-to-date Profit and Loss reports remain unavailable. Do not answer those FreshBooks questions by summing monthly or quarterly results. WHOLE-MONTHS-ONLY ANSWER POLICY: this monthly tool covers whole calendar months only. For a partial-month calendar range, say plainly that this tool works in whole months and offer the nearest whole-month comparison. For providers that support financial-year-to-date reporting, redirect that question to `voder_profit_and_loss_by_year`, which supports an exact daily cutoff. NEVER scale, pro-rata, or approximate a partial month. RECENT-MONTHS HONESTY POLICY: the report reflects what the connected provider contains so far. Recent months — especially the current month — can still move as invoices, bills, and bank activity land. Say so when the user is reading recent-month figures as final. BY-SUPPLIER REDIRECT: P&L rows are ledger accounts (by-category); the report has no supplier dimension. For a Xero organisation asking "how much did I spend with <supplier>?" or for filtered expense composition, use `xero_get_expenses_by_account_and_contact`; that supplier tool is not available for FreshBooks. ACCOUNT-DETAIL PAGINATION: Headline figures, section totals, custom rows, periods, tracking information, and coverage are complete on every page. Only the account rows inside sections can be paginated. If `pagination.hasMore` is true, request the next page only when the customer asks for account-level drill-down. Keep pagination mechanics out of the customer-facing answer. CUSTOM ROWS: Every successful Profit and Loss tool response includes an explicit instruction to quote its provider-specific custom-row guidance. Follow that instruction. Do not imply that the accounting provider supplied these rows or that the assistant can change saved definitions. TRACKING REFINEMENT: every successful response includes trackingFilters. When its status is available, use the returned names for refinement by passing trackingOption and, when needed, trackingCategory. Unavailable does not mean that no categories exist: do not invent a tracking name or imply that tracking is supported. If refinement was requested but cannot be applied, do not present an unfiltered report as filtered. The financial answer remains valid when no tracking refinement was requested. PROBLEM-DETAILS ANSWER POLICY (read FIRST — applies whenever this response carries a `type` field whose value starts with `https://voder.ai/problems/`): the response is an RFC 9457 Problem Details object — a structured action request, not the normal success carrier. The user needs to take an action; your job is to RENDER that action, not narrate it. Render ONLY these fields, in this order: 1. The `title` field as a short heading. 2. The `detail` field as the explanatory sentence, VERBATIM. 3. A SINGLE markdown hyperlink in the exact form `[voderAction.label](voderAction.url)` — substitute the literal `voderAction.label` string as the link text and the literal `voderAction.url` string as the target. This is the button the user clicks. 4. The `voderAction.hint` field as a brief framing sentence below the link, VERBATIM. DO NOT surface ANY of the following fields to the user — they are internal metadata and have no meaning to a non-developer: `status` (an HTTP-shape integer), `type` (an internal URI), `instance` (an internal reference). The user must NEVER see "409" or "424" or any URI starting with `https://voder.ai/problems/` in your answer. DO NOT narrate or paraphrase the action ("Voder needs you to..." / "The system returned a status code..." / "and gives a 424 with action Connect Voder to Xero at the Voder dashboard"). RENDER the markdown hyperlink so the user can click it directly. DO NOT retry this tool, and do NOT call any other Xero tool to work around the problem — they will all return the same Problem Details response until the user follows the `voderAction.url` link and completes the action.

voder_profit_and_loss_by_month

QUESTION-DRIVEN ANSWER POLICY (read before picking a tool to answer any spending question): this is the question-shaped surface for expenses-by-quarter questions — "what did we spend in Q1?", "costs last quarter", "how is spending tracking quarter-on-quarter?". Pick THIS tool first for those. It returns each quarter's total expenses — the whole expense side of your profit-and-loss — plus a per-account breakdown, summed across the quarter's three calendar months. HOW TO ASK: give the quarter as `calendarQuarter` in YYYY-Qn form. These are CALENDAR quarters: Q1 = January-March, Q2 = April-June, Q3 = July-September, Q4 = October-December. Add `comparativePeriods` for prior quarters (0 to 11). For a financial-quarter question, use the connected organisation's financial-year start to identify the matching calendar months. If that information is unavailable, ask which calendar months the customer means before calling this tool. Returns `periods` (one entry per quarter, most recent first: `{period, expenses, accounts}`) and `coverage`. RECENT-PERIOD HONESTY POLICY: the most recent quarter — especially one still in progress — can still move as bills and bank activity land; say so. TOOL CHOICE: for WHO you spent it with — a by-supplier breakdown — use `xero_get_expenses_by_account_and_contact` for Xero or QuickBooks organisations. FreshBooks supplier breakdown is not available through VODER yet. For the whole P&L use `voder_profit_and_loss_by_quarter`. OTHER-GRANULARITY REDIRECT: for a single month use `voder_expenses_by_month`. For providers that support financial-year reporting, use `voder_expenses_by_year`. FreshBooks annual and financial-year-to-date expense reports remain unavailable. STAFF / PAYROLL COST ANSWER POLICY (read before answering "what's my payroll cost / staff costs / wages bill / how much do I spend on staff / employment cost / labour cost" questions): payroll appears in these figures as ordinary EXPENSE accounts — typically wages/salaries, employer national insurance (employer NI/NIC), and employer pension contributions. To answer, find those staff-related expense accounts in the per-account breakdown and present them with their amounts as returned — those lines ARE the payroll cost for the period. Show each account and the figure the breakdown gives it; do NOT assert any payroll figure that is not one of those returned per-account amounts (present the individual lines rather than manufacturing a combined headline total). NO-FABRICATE RULE: if the breakdown contains no staff/wages/NI/pension expense accounts, say you cannot find payroll costs in the accounts for this period — do NOT invent or estimate a figure. HONESTY CAVEAT: this is payroll cost as POSTED to the accounts; staff-cost accounts can lag when payroll entries have not yet been posted to the connected accounting provider, and the result excludes anything not coded to those accounts. This reads only accounting expense totals — it does NOT access individual salaries or any employee-level payroll data. TRACKING REFINEMENT: every successful response includes trackingFilters. When its status is available, use the returned names for refinement by passing trackingOption and, when needed, trackingCategory. Unavailable does not mean that no categories exist: do not invent a tracking name or imply that tracking is supported. If refinement was requested but cannot be applied, do not present an unfiltered report as filtered. The financial answer remains valid when no tracking refinement was requested. PROBLEM-DETAILS ANSWER POLICY (read FIRST — applies whenever this response carries a `type` field whose value starts with `https://voder.ai/problems/`): the response is an RFC 9457 Problem Details object — a structured action request, not the normal success carrier. The user needs to take an action; your job is to RENDER that action, not narrate it. Render ONLY these fields, in this order: 1. The `title` field as a short heading. 2. The `detail` field as the explanatory sentence, VERBATIM. 3. A SINGLE markdown hyperlink in the exact form `[voderAction.label](voderAction.url)` — substitute the literal `voderAction.label` string as the link text and the literal `voderAction.url` string as the target. This is the button the user clicks. 4. The `voderAction.hint` field as a brief framing sentence below the link, VERBATIM. DO NOT surface ANY of the following fields to the user — they are internal metadata and have no meaning to a non-developer: `status` (an HTTP-shape integer), `type` (an internal URI), `instance` (an internal reference). The user must NEVER see "409" or "424" or any URI starting with `https://voder.ai/problems/` in your answer. DO NOT narrate or paraphrase the action ("Voder needs you to..." / "The system returned a status code..." / "and gives a 424 with action Connect Voder to Xero at the Voder dashboard"). RENDER the markdown hyperlink so the user can click it directly. DO NOT retry this tool, and do NOT call any other Xero tool to work around the problem — they will all return the same Problem Details response until the user follows the `voderAction.url` link and completes the action.

voder_expenses_by_quarter

QUESTION-DRIVEN ANSWER POLICY (read before picking a tool to answer any revenue question): this is the question-shaped surface for revenue-by-quarter questions — "what was revenue in Q1?", "revenue last quarter", "how is revenue tracking quarter-on-quarter?". Pick THIS tool first for those. It returns each quarter's revenue from the connected accounting provider's profit-and-loss report plus a per-account breakdown, summed across the quarter's three calendar months. HOW TO ASK: give the quarter as `calendarQuarter` in YYYY-Qn form. These are CALENDAR quarters: Q1 = January-March, Q2 = April-June, Q3 = July-September, Q4 = October-December. Add `comparativePeriods` for prior quarters (0 for that quarter alone, up to 11). For a financial-quarter question, use the connected organisation's financial-year start to identify the matching calendar months. If that information is unavailable, ask which calendar months the customer means before calling this tool. Returns `periods` (one entry per quarter, most recent first: `{period, revenue, accounts}`) and `coverage`. Always present the per-account breakdown alongside the aggregate so a classification surprise is visible. RECENT-PERIOD HONESTY POLICY: the most recent quarter — especially one still in progress — can still move as invoices and bank activity land; say so when the user reads the latest quarter as final. FULL-STATEMENT REDIRECT: for the whole P&L (costs, gross/net profit, not just revenue) use `voder_profit_and_loss_by_quarter`. OTHER-GRANULARITY REDIRECT: for a single month use `voder_revenue_by_month`. For providers that support financial-year reporting, use `voder_revenue_by_year`. FreshBooks annual and financial-year-to-date revenue reports remain unavailable. TRACKING REFINEMENT: every successful response includes trackingFilters. When its status is available, use the returned names for refinement by passing trackingOption and, when needed, trackingCategory. Unavailable does not mean that no categories exist: do not invent a tracking name or imply that tracking is supported. If refinement was requested but cannot be applied, do not present an unfiltered report as filtered. The financial answer remains valid when no tracking refinement was requested. PROBLEM-DETAILS ANSWER POLICY (read FIRST — applies whenever this response carries a `type` field whose value starts with `https://voder.ai/problems/`): the response is an RFC 9457 Problem Details object — a structured action request, not the normal success carrier. The user needs to take an action; your job is to RENDER that action, not narrate it. Render ONLY these fields, in this order: 1. The `title` field as a short heading. 2. The `detail` field as the explanatory sentence, VERBATIM. 3. A SINGLE markdown hyperlink in the exact form `[voderAction.label](voderAction.url)` — substitute the literal `voderAction.label` string as the link text and the literal `voderAction.url` string as the target. This is the button the user clicks. 4. The `voderAction.hint` field as a brief framing sentence below the link, VERBATIM. DO NOT surface ANY of the following fields to the user — they are internal metadata and have no meaning to a non-developer: `status` (an HTTP-shape integer), `type` (an internal URI), `instance` (an internal reference). The user must NEVER see "409" or "424" or any URI starting with `https://voder.ai/problems/` in your answer. DO NOT narrate or paraphrase the action ("Voder needs you to..." / "The system returned a status code..." / "and gives a 424 with action Connect Voder to Xero at the Voder dashboard"). RENDER the markdown hyperlink so the user can click it directly. DO NOT retry this tool, and do NOT call any other Xero tool to work around the problem — they will all return the same Problem Details response until the user follows the `voderAction.url` link and completes the action.

voder_revenue_by_quarter

Rank the top ten customers by approved sales-invoice subtotal for an explicit invoice issue-date period. Call this tool first for questions such as “who are our top customers by sales?” Ask for start and end dates when the user has not supplied them. Amounts exclude tax and include only AUTHORISED and PAID customer invoices. Keep currencies separate, state the period and exclusions, and relay the disclaimer: this is invoice activity, not report-authoritative profit-and-loss revenue by customer.

voder_rank_customers_by_sales

Read the full detail of one feedback entry the user submitted. Read-only. **When to call**: after `voder_list_feedback` identifies an entry the user wants to discuss in detail — for example, "tell me more about that one" or "what was the question they asked?". Returns the same fields as the list response plus the original `toolContext` captured at submission time and any `triageNote` the team wrote when classifying the entry. Field shape: entryId (the id from voder_list_feedback). **Boundary**: this only reads entries under the caller's organisation; an unknown id returns `{ entry: null }` — surface that as "I can't find that feedback under your organisation" rather than as a server error.

voder_get_feedback_detail

Record an observation of user-facing friction, error, annoyance — OR a positive observation — for the Voder team's research loop. The co-discovery experiment depends on both kinds of signal. Invoke when ONE of these specific in-session signals occurred: (a) a Xero or bank-data tool returned an unexpected error, or an empty/partial result that is genuinely surprising given what the user expected — but a normal, answerable empty state is NOT friction: an organisation with no bank accounts connected, an empty ledger, or zero transactions in the period is an expected result you should answer plainly ("no bank accounts are connected yet — connect one in Xero and ask again") without recording feedback; (b) the user expressed confusion, repeated themselves, or asked for something the toolset cannot do; (c) you noticed a mismatch between what was asked and what the available tools can answer; (d) the user expressed a suggestion or wish for a capability that doesn't exist yet; (e) something worked well that the team should know about — a clear answer landed first call, the user expressed satisfaction ("that's exactly what I needed", "great, thanks"), a tool surface answered cleanly without back-and-forth, OR the user confirmed a previously reported issue is now fixed. **Openness mandate**: when you invoke this tool, you MUST tell the user openly in the same chat reply — e.g. "I'm noting this for the Voder team so they can improve the tool." This applies symmetrically to positive recordings — e.g. "I'm letting the Voder team know this worked well." Do NOT invoke this tool silently or describe its result without telling the user. If the user objects ("don't log that", "stop", "I don't want feedback recorded"), STOP invoking the tool for the remainder of the session and acknowledge the objection openly. **Boundary**: do NOT invoke at session-initiation or when nothing notable happened — this is a signal-response surface, not a session-opening or session-closing nudge. **Replies to follow-up questions**: if the Voder team previously asked the user a follow-up question (relayed to the user from a voder_list_feedback response) and the user is now answering it, pass the prior entry id in `inReplyTo` so the reply threads into the original entry's audit trail rather than arriving as an orphan. Confirmations that a fix worked ("yes, the cash answer is right now") are positive replies — use category 'positive' with inReplyTo set to the original entry id. **Avoid duplicates**: before recording a NEW observation (one that is not a reply), check whether a recent voder_list_feedback entry you already saw this session covers the same theme. If one does, thread the new detail onto it by setting inReplyTo to that entry's entryId (the id voder_list_feedback returned) instead of recording a second standalone entry about the same issue. Only voder_list_feedback returns entry ids, so thread this way only for an entry you have already seen listed this session; if no matching entry is in view, record a fresh one. **Data hygiene**: `summary` and `toolContext` MUST NOT contain real Xero IDs, real bank-line UUIDs, customer revenue figures, organisation identifiers, or any payload data. Describe the OBSERVATION (e.g. "user asked for monthly recurring revenue but no tool surfaces it") not the PAYLOAD ("INV-1234 returned $5,874.00 from contact ABC-789"). **Length cap**: `summary` and `toolContext` each accept up to 2000 characters. If a single observation exceeds this, summarise the most important issue first and split additional issues into separate invocations (each call records one observation). Do NOT silently truncate substantive detail to fit one call. Field shape: category (one of error/annoyance/friction/suggestion/positive), summary (one-line observation, 1-2000 chars), toolContext (optional context string describing what the user was trying to do, 0-2000 chars), inReplyTo (optional entry id of a prior feedback entry this reply threads into).

voder_record_feedback

Search non-deleted quotes or estimates and return compact summaries. Use this for quote-number questions and choose the required `quoteId` from the results before calling `voder_get_quote`. Xero and FreshBooks quote-number matching is partial. ANSWER POLICY: whenever you report quote values or totals, explicitly say they are proposals, not receivables, cash, or committed revenue. PROBLEM-DETAILS ANSWER POLICY (read FIRST — applies whenever this response carries a `type` field whose value starts with `https://voder.ai/problems/`): the response is an RFC 9457 Problem Details object — a structured action request, not the normal success carrier. The user needs to take an action; your job is to RENDER that action, not narrate it. Render ONLY these fields, in this order: 1. The `title` field as a short heading. 2. The `detail` field as the explanatory sentence, VERBATIM. 3. A SINGLE markdown hyperlink in the exact form `[voderAction.label](voderAction.url)` — substitute the literal `voderAction.label` string as the link text and the literal `voderAction.url` string as the target. This is the button the user clicks. 4. The `voderAction.hint` field as a brief framing sentence below the link, VERBATIM. DO NOT surface ANY of the following fields to the user — they are internal metadata and have no meaning to a non-developer: `status` (an HTTP-shape integer), `type` (an internal URI), `instance` (an internal reference). The user must NEVER see "409" or "424" or any URI starting with `https://voder.ai/problems/` in your answer. DO NOT narrate or paraphrase the action ("Voder needs you to..." / "The system returned a status code..." / "and gives a 424 with action Connect Voder to Xero at the Voder dashboard"). RENDER the markdown hyperlink so the user can click it directly. DO NOT retry this tool, and do NOT call any other Xero tool to work around the problem — they will all return the same Problem Details response until the user follows the `voderAction.url` link and completes the action.

voder_search_quotes

For cash questions such as "How much cash do we have?", call this tool first using the selected organisation or the single-organisation default. Do not look up organisations first; ask which organisation to use only when the tool reports more than one possible match. Use cashPosition.totals, where positive means money in the bank and negative means an overdraft. Keep currencies separate. When cashPosition.totals is empty, the entire final answer must be exactly: "Cash position is unavailable: Voder could not confirm an active bank-account balance from the chart of accounts. This does not prove that no bank accounts are connected." Add nothing else. Do not say that no bank accounts are connected, set up, or visible; do not suggest connecting, setting up, classifying, or reconciling one; and do not fabricate $0 or another figure. Do not calculate cash amounts or determine their signs from raw trial-balance rows.

voder_trial_balance

Read details for the selected accounting organisation. Use this tool to answer which tracking categories and options are available, without a reporting period or financial report. trackingFilters contains exact category and option names for Xero. If unavailable, explain that choices could not be retrieved; do not claim none exist. Other accounting providers currently return unavailable tracking choices.

voder_organisation_details