Xero

Retrieve the Xero report summary needed to review or prepare year-end 1099 forms, including 1099-NEC and 1099-MISC box decisions, service-calculated thresholds, IRS filing deadlines, W-9 identity and source status, missing-detail flags, overrides, e-filing validation errors, TIN-matching statuses, and possible third-party-payment matches. This covers Xero data only. PayPal, Stripe, and other payment sources must be obtained and combined separately. W-9 status is enriched from Tax.W9.Service and is independent of whether a tax ID is recorded in the US1099 report. <discrimination> Do NOT use get_bills to decide who needs a 1099 or whether a payee crossed a tax threshold; get_bills returns individual supplier documents and line items, while this tool returns the US1099 service's tax-year classification. Use get_bills only when the user asks to inspect bills. Do NOT use get_contacts for 1099 eligibility, missing tax information, or contractor payment totals; get_contacts only looks up contact identity and email. </discrimination> <hints> - tax_year is required. Preserve the user's calendar year exactly. - Inspect xero_configuration_status before interpreting any report data. If it is not_configured, explain that the report cannot establish W-9 status or whether reportable payees exist, surface xero_1099_report_link, and ask the user to set up 1099 reporting before rerunning. Never describe W-9 status as "unknown" based on an unconfigured report. - Use form_totals for filing deadlines rather than assuming a date. - Use boxes as the source of truth. reported_total and override_total are separate values supplied by the service; do not silently combine them. Interpret boxes by name and do not sum unlike boxes unless the user's question requires it. CREDIT_CARD_PAYMENT exclusions report zero because this endpoint does not expose their underlying amount. - Use w9_status.code as the primary W-9 classification and w9_status.description as its Xero UI meaning. KEY_W9_DETAILS_STORED means key W-9 details are stored and valid for the W-9-details check; do not report that payee as missing W-9 details. RESPONSE_RECEIVED and W9_RECEIVED_MANUALLY mean a W-9 was received. has_manually_received_w9 is the underlying manual-receipt source signal. - Use legal_name for the accountant-facing payee identity. business_name and business_type support corporation-exemption review, but never automatically exclude a payee based on them. - Review legal_name, missing_details, warnings, validation_errors, and efiling_organisation_errors together when assessing preparation or e-filing issues. PAYMENTS_CHANGED_AFTER_EFILED requires review because current payment data no longer matches the e-filed form. Do not infer readiness merely because no validation error was returned. Legal name is required; business name is optional. - Treat tin_match_result as the last raw status returned by the US1099 service, not proof of a real-time IRS check. A null result means no status was returned; the status value none is distinct. TIN matching is per form and does not establish whether a W-9 is on file. - Treat third_party_payment_review_required as a review flag, not proof of PayPal or Stripe usage. - form_type is supplied by the service and may contain a rules-version year; tax_year is the filing year. </hints> <examples> - "who do i need to send 1099s to for 2025" - "get my contractor tax forms ready for the accountant" - "which vendors are missing tax info for last year's 1099s" - "show contractors just under the filing threshold in 2025" - "how much federal tax was withheld on contractor forms in 2025" - "did any contractors fail TIN matching for 2025" </examples>

get_1099_report_summary

Retrieve the aged payables report (accounts payable / creditor aging) for a Xero organisation. Returns the outstanding balance split by how overdue it is (current, < 1 month, 1 month, 2 months, 3 months, 3+ months) and the suppliers the business owes the most, each with their oldest outstanding bills. Use this to understand who the business owes money to and how overdue each balance is. This is the payables-aging slice of a multi-metric overview: when a business pulse, one-page snapshot, financial health-check, Monday brief, or "anything urgent today" check needs the payables broken down by how overdue it is, use this tool for that aging portion (alongside get_cash_position and get_profit_and_loss). <discrimination> Do NOT use for money owed TO the business (receivables / debtors) — use get_aged_receivables Do NOT use when the user asks whether the business can pay its supplier or what it owes — use get_cash_position Do NOT use when the user wants a high-level cash/payables total without an aging breakdown — use get_cash_position </discrimination> <hints> - If the user does not specify a date, omit as_of_date and the report defaults to today. - For point-in-time queries (e.g. "as of last month", "at end of Q1"), derive as_of_date from the current date and pass it in YYYY-MM-DD format. - For month-end close queries ("close the month", "month-end", "closing the books", "reconcile", "what's missing in my books", or a month-end P&L summary / narrative) — call alongside get_profit_and_loss, get_financial_position, and get_aged_receivables. - When a business pulse, one-page snapshot, health-check, Monday brief, or "anything urgent today" request needs the payables-aging breakdown, this is the payables tool for that slice — call it alongside get_cash_position and get_profit_and_loss. </hints> <examples> - "Show me the AP aging report" - "Who do we owe money to and how overdue is it?" - "Which bills are more than 90 days overdue?" - "How are our creditor days looking?" - "Show me our overdue payables breakdown" - "Which suppliers should I pay first?" - "What bills are the most overdue right now?" - "Show me how long each supplier's bills have been outstanding" </examples>

get_aged_payables

Retrieve the aged receivables report (accounts receivable / debtor aging) for a Xero organisation. Returns the outstanding balance split by how overdue it is (current, < 1 month, 1 month, 2 months, 3 months, 3+ months) and the customers who owe the most (debtors), each with their oldest outstanding invoices, plus unapplied customer credit notes and overpayments. This is the default tool for outstanding / unpaid / overdue / due-soon customer invoices (receivables): who owes the business money, the biggest debtors, who is behind or slow to pay, who to chase, how many invoices are unpaid / overdue / awaiting payment, what is due or coming due this week, this month, or next week, and how much unused customer credit is sitting on account. Use it for generic "unpaid invoices", "overdue invoices", "invoices due next week", "what's outstanding", and "who owes us" questions even when the user does not say the word "aging". This is also the receivables-aging slice of a multi-metric overview: when a business pulse, one-page snapshot, financial health-check, Monday brief, or "anything urgent today" check needs the receivables broken down by how overdue it is, use this tool for that aging portion (alongside get_cash_position and get_profit_and_loss). <discrimination> Do NOT use for money the business owes (payables / creditors) — use get_aged_payables for that. Do NOT use when the user asks for specific per-invoice document fields (invoice/reference numbers, line items, currency), a single named customer's invoices, PAID invoices, or an explicit calendar issued-date range (e.g. "invoices between January and March") — use get_invoices for that. Do NOT use for a rolled-up "how much did we invoice this period" summary grouped by currency/customer — use show_invoices_summary for that. Do NOT use for a high-level cash/receivables total without any invoice or debtor detail — use get_cash_position for that. </discrimination> <hints> - If the user does not specify a date, omit as_of_date and the report defaults to today. - For point-in-time queries (e.g. "as of last month", "at end of Q1"), derive as_of_date from the current date and pass it in YYYY-MM-DD format. - For month-end close queries ("close the month", "month-end", "closing the books", "reconcile", "what's missing in my books", or a month-end P&L summary / narrative) — call alongside get_profit_and_loss, get_financial_position, and get_aged_payables. - When a business pulse, one-page snapshot, health-check, Monday brief, or "anything urgent today" request needs the receivables-aging breakdown, this is the receivables tool for that slice — call it alongside get_cash_position and get_profit_and_loss. </hints> <examples> - "Show me the AR aging report" - "List all unpaid invoices" - "Show me invoices that are overdue" - "What invoices are due this week?" - "Who owes us money and how overdue is it?" - "Who are my biggest debtors?" - "Who's behind on paying me — who should I chase?" - "How many invoices are awaiting payment right now?" - "How much unused credit do customers have?" - "Which customers have the oldest unpaid debt?" </examples>

get_aged_receivables

List accounting-side bank transactions used in Xero bank reconciliation. Use for bank-reconciliation work, month-end close checks, or reviewing accounting entries still awaiting reconciliation. Currently only unreconciled transactions are available. Results cover active bank and credit-card accounts. Each response-wide page contains a bounded number of transactions, grouped by account. <discrimination> Do NOT use for cash on hand, liquidity, or aggregate bank balances — use get_cash_position. Do NOT treat this as the complete monthly transaction register or use it to claim that every duplicate, category, or receipt has been reviewed. It excludes reconciled and non-bank-account entries and does not return every line of multi-line entries. Use get_profit_and_loss for aggregate monthly financial results; request a Xero transaction-detail export when the complete register is required. Do NOT use for outstanding customer invoices or supplier bills — use get_aged_receivables or get_aged_payables. This tool returns Xero accounting entries awaiting reconciliation, not imported bank-statement lines and not payment-processor settlement data. Do NOT call get_chart_of_accounts first to identify which bank or credit-card account is involved — this tool already covers every active bank and card account and groups its results by account. </discrimination> <hints> - reconciliation_status currently accepts only UNRECONCILED; omit it to use that default. - For a broad month-end close, call alongside get_profit_and_loss, get_financial_position, get_aged_receivables, and get_aged_payables. For an explicit bank-reconciliation queue request, use this tool without automatically calling those reporting tools. - Omit both dates to use the previous calendar month in the organisation's timezone. - Supplying only one date creates an open-ended range. - Omit bank_account_ids to include all active bank and credit-card accounts. - Pages contain at most 200 transactions in total, not per account. There is no byte-size limit. - When next_cursor is not null, call again with it passed unchanged as cursor. Stop when next_cursor is null. - Do not invent, inspect, or modify cursors. Keep the same dates, status, and bank-account filters while paging. - Descriptions are previews of at most 200 characters; truncation flags identify shortened text. - Find the transaction in Xero to read full descriptions. - Account metadata and contact names may be cached for up to five minutes; transaction rows and counts are live. - Do not infer a description match or absence from a preview. References and financial fields are unchanged. - A null line_account does not prove that an entry is uncategorized, especially for multi-line entries, payments, and transfers. </hints> <examples> - "what still needs reconciling from last month" - "show me the entries waiting for bank rec" - "which July transactions haven't been matched yet" - "anything left to reconcile on the credit card" - "check the bank rec queue before we close the month" </examples>

get_bank_account_transactions

Retrieve accounts payable documents (i.e. bills) for the connected Xero organisation. Shows per-bill detail: supplier name, amount due, due date, and status. By default the response is header-only; set include_line_items to True to also return each bill's line items — description, quantity, unit amount, line amount, and (for inventory-backed lines) the inventory item id, code, and catalogue name. Detailed responses are larger. Use when the user asks for individual bill details under a specific scope: one or more named suppliers (pass contact_ids), paid bills, an issued-date window, or line-item detail. When the request names a supplier (or several) — e.g. "bills from Acme", "what have we bought from Acme and Globex" — this tool filters by contact_ids, which are UUIDs, not names. You MUST first call get_contacts for each named supplier to resolve the name(s) to contact IDs, then call this tool once with all of those IDs in the contact_ids list. Never pass a supplier name to this tool directly. Results are paginated — see the pagination hint below to retrieve further pages. <discrimination> Do NOT use for generic "unpaid / overdue / outstanding / due-soon" payables questions, who we owe money to, the biggest payables, who to pay next, or how many bills are awaiting payment — use get_aged_payables for those (it is the default payables tool). This holds even when the request is phrased as a list ("list all unpaid bills", "show me overdue bills") or asks what is "due this week / this month / next week / coming due": an unqualified unpaid, overdue, or upcoming-due list of bills is a payables question — use get_aged_payables. Do NOT use for an aging breakdown of bills bucketed by days overdue — use get_aged_payables for that. Do NOT use for recurring or repeating bills — the templates that regenerate supplier bills on a schedule (subscriptions, rent, utilities, fixed recurring supplier payments or expenses) — use get_repeating_bills for that. This tool returns only individual bills already issued, never the schedules that create them, so route any "recurring / repeating / automatically billed each month" request to get_repeating_bills even when it says "bills" or "expenses". Do NOT use for aggregate totals or a single outstanding/payables figure without per-bill breakdown (total payables, total receivables, working capital) — use get_cash_position. Do NOT use for cash-coverage / liquidity questions — use get_cash_position for that. Do NOT use bills to decide which contractors or vendors require a 1099, whether they crossed a tax threshold, or which tax details are missing — use get_1099_report_summary for that tax-year classification. Use this tool only when the user wants the underlying bill documents or lines. </discrimination> <hints> - By default both paid and unpaid bills are returned; set status to ["UNPAID"], ["PAID"], or both values to filter to the requested payment state(s). Do not pass an empty array. - Filter by due date (due_date_start / due_date_end), issued/bill date (issued_date_start / issued_date_end), or both together — e.g. bills issued last month that are due this month. Each range is independent and either end may be omitted for an open-ended filter. When the user gives no date or period at all (e.g. "show me my recent bills"), omit all four date params — the tool defaults the issued-date range to the last month, ending today. Do not invent a date range. - The due-date filter is for combining with another scope (a named supplier or an issued-date window); do not use it on its own to answer "what's due this week / this month / next week" — that upcoming-due triage is get_aged_payables. - To scope to one or more suppliers, use the two-step contact flow — contact_ids are UUIDs, never names: 1. Call get_contacts to resolve each named supplier to its contact ID(s). 2. Call this tool a SINGLE time, populating contact_ids with EVERY ID returned in step 1. For several suppliers, collect all their IDs into that one contact_ids list rather than calling this tool once per supplier, and never leave contact_ids empty after resolving the names. A get_contacts name search may match more than one contact — include each matched ID. Passing contact_ids with no date filter returns all of those suppliers' bills (the last-month default is not applied). Combine contact_ids with date/status filters to narrow further (e.g. "Acme's paid bills last quarter"). Never put a supplier name in this tool's arguments. - Pagination: to retrieve the next page, call this tool again with the same filters and page set to the current page + 1 whenever there may be more results — that is, when page_item_count equals requested_page_size (the page size returned in the response; a full page signals more may follow), or when page is less than total_page_count (returned only on detailed responses). Stop paging once page_item_count is below requested_page_size, or once page reaches total_page_count. </hints> <examples> - "Which bills have been paid?" - "Show me bills issued between January and March" - "Show me the line items on bills issued last month" - "Show me all bills from Acme" (resolve "Acme" via get_contacts, then call with its contact_ids) - "Bills issued last month that are due this month" </examples>

get_bills

Show a summary of the cash position for the connected Xero organisation. Covers aggregate totals: cash balance, total amount owed to you (receivables), and total amount you owe (payables). Only use for questions about cash on hand, cash-coverage/liquidity, or whether the business can cover its obligations. Only data for the last three financial years can be returned. <discrimination> Do NOT use for profitability or performance over a period — whether the business is profitable, income vs expenses, or spending vs earning — use get_profit_and_loss. Do NOT use for top debtors summary or summary of largest outstanding or overdue invoices — use get_aged_receivables. Do NOT use for a broad financial overview, point-in-time financial snapshot, financial healthcheck, business valuation / worth, or working capital — use get_financial_position instead. Do NOT use for questions about total amounts owed to you (receivables/debtors) without cash coverage or liquidity context — use get_aged_receivables instead. Do NOT use for questions about total amounts you owe (payables/bills/creditors) without cash coverage or liquidity context — use get_aged_payables instead. </discrimination> <examples> - "What's my cash position?" - "How much cash do I have?" - "Can I cover my bills?" - "How much do I owe vs how much is owed to me?" - "Do we have enough cash to pay what we owe?" </examples>

get_cash_position

Retrieve the organisation's chart of accounts — the list of active accounts (the ledger accounts transactions are coded to), each with its code, name, type, class, status, tax type, and description. Only ACTIVE accounts are returned; archived and deleted accounts are excluded. There are no parameters — the full active chart of accounts for the connected organisation is returned. <discrimination> Do NOT use for account balances, financial statements, or how much is in an account — use get_financial_position / get_profit_and_loss / get_cash_position for figures. This tool returns the account definitions (code/name/type), not any monetary amounts or transactions. Do NOT use for bank reconciliation or transactions on a bank or credit-card account (the "rec", outstanding/unreconciled items) — use get_bank_account_transactions; you do not need this tool to identify which bank or card account is involved. Do NOT use for the tracking labels, tags, or dimensions used to categorise, segment, or analyse spending and income (e.g. by region or department) — use get_tracking_categories. Do NOT use for inventory items (get_inventory_items) or contacts (get_contacts). </discrimination> <hints> - Takes no arguments; it always returns the whole active chart of accounts. - Use it to look up an account code or name, or to see which accounts exist before coding a transaction (e.g. for the ap-processor bill-coding flow). - account_class is one of ASSET, LIABILITY, EQUITY, REVENUE, EXPENSE; type is the finer-grained Xero account type (e.g. BANK, CURRENT, FIXED, REVENUE, EXPENSE). </hints> <examples> - "What's our chart of accounts?" - "List all our account codes" - "Which expense accounts do we have?" - "What account code should I use for advertising?" - "Show me the revenue accounts" </examples>

get_chart_of_accounts

List every Xero organisation the signed-in user has connected to this app, so you can tell how many organisations they have and which ones are available to run org-scoped tools against. <discrimination> Do NOT use for a single organisation's details such as name, currency, country, industry or timezone — use get_organisation_info. </discrimination> <examples> - "How many Xero organisations do I have connected?" - "List all my companies" - "do i have more than one org linked" - "What other businesses can you see?" - "show me all the orgs on my account" </examples>

get_connected_organisations

Look up contacts (customers and suppliers) by UUID or by name, returning each match's name and email address. Two modes: pass contact_ids to resolve one or more known UUIDs to their names and emails, or pass contact_name to search for contacts whose name contains that text (a "contains" match that can return several contacts). Use this to answer "who is this contact", "what's their email", or "do I have a contact called X", and to turn a customer name into the contact IDs that get_invoices needs to filter by. <discrimination> Do NOT use for outstanding balances, who owes money, overdue amounts, or the biggest debtors — use get_aged_receivables for receivables questions. Do NOT use to list a customer's invoices, or to answer what a customer bought / purchased / ordered / spent, or their sales history — that is get_invoices. For these, resolving the name here is only the FIRST step: after this tool returns the contact ID(s), you MUST go on to call get_invoices with those contact_ids (set include_line_items to True for "what did they buy"). Do not stop after this tool and answer from the contact record alone — it has no invoices. This tool only returns contact identity (name, email); it does not return any financial figures, invoices, or purchase history. Do NOT use for 1099 eligibility, contractor tax-year totals, filing thresholds, or missing tax information — use get_1099_report_summary. This contact lookup does not contain those tax decisions. </discrimination> <hints> - Provide exactly one of contact_ids or contact_name. Supplying both, or neither, is an error. - contact_ids accepts a list, so several known UUIDs can be resolved in a single call. - contact_name is a "contains" search, so a partial or approximate name is fine; it may return more than one contact. Prefer contact_ids when exact UUIDs are already known (e.g. from a previous invoice or bill result). - If the underlying question is about a customer's invoices, purchases, or what they bought, this is only step one: resolve the name here, then call get_invoices with the returned contact_ids. Do not treat the resolved contact as the final answer. </hints> <examples> - "what's the email for Acme Corp" - "do I have a contact called Sarah Jones" - "look up contact d290f1ee-6c54-4b01-90e6-d701748f0851" - "who is the contact on this invoice" (when you have the contact_id) - "find John Smith's contact details" </examples>

get_contacts

Show the balance sheet and business health indicators for a Xero organisation. Use this tool for a point-in-time broad financial overview, financial snapshot, or health-check queries. This single tool covers these — do not fan out to multiple tools. Defaults to accrual basis, or returns cash basis when accounting_basis is CASH. Only data for the last three financial years can be returned. <discrimination> Do NOT use for questions about profitability or business performance over a period of time — use get_profit_and_loss instead. </discrimination> <examples> - "What's my balance sheet?" - "Give me a financial overview of the business" - "What are my total assets and liabilities?" - "How healthy is the business financially?" - "What's my net equity?" - "What's my working capital?" </examples> <hints> - If the user asks for cash-basis financial position, set accounting_basis to CASH. If the user does not ask for cash basis, omit accounting_basis or use ACCRUAL. </hints>

get_financial_position