Xero

Retrieve the aged payables report (accounts payable / creditor aging) for the connected 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 the connected 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

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 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 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

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 the connected 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

Retrieve a filtered list of individual sales invoices (accounts receivable) for the connected Xero organisation. Shows per-invoice detail: customer name, invoice/reference number, amount due, due date, and status. By default the response is header-only; set include_line_items to True to also return line items — description, quantity, unit amount, line amount, and (for inventory-backed lines) the inventory item id, code, and name. Detailed responses are larger. Use this only when the request is scoped to a SPECIFIC filter: one or more named customers' invoices (pass contact_ids), PAID invoices, an explicit calendar issued-date range (e.g. "invoices between January and March"), or when the user wants individual per-invoice document fields such as invoice / reference numbers or line-item detail. Also use it to browse recent or latest *individual* invoices (e.g. "my recent invoices") — a list of documents, as opposed to a rolled-up period total, which is show_invoices_summary. Results are paginated — see the pagination hint below to retrieve further pages. When the request names a customer (or several) — e.g. "invoices for Acme", "what has Acme and Globex bought" — this tool filters by contact_ids, which are UUIDs, not names. You MUST first call get_contacts for each named customer 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 customer name to this tool directly. <discrimination> Do NOT use for generic "unpaid / overdue / outstanding / due-soon" receivables questions, who owes money, the biggest debtors, who to chase, or how many invoices are awaiting payment — use get_aged_receivables for those (it is the default receivables tool). This holds even when the request is phrased as a list ("list all unpaid invoices", "show me overdue invoices") or asks what is "due this week / this month / next week / coming due": an unqualified unpaid, overdue, or upcoming-due list of customer invoices is a receivables question — use get_aged_receivables. Do NOT use for an aging breakdown of invoices bucketed by days overdue — use get_aged_receivables for that. Do NOT use for "show me my invoices" with no filter, or a rolled-up "how much did we invoice this period" summary grouped by currency and top customers — use show_invoices_summary for that. Do NOT use for aggregate totals or a single outstanding/receivables figure without per-invoice breakdown (total receivables, total payables, working capital) — use get_cash_position. Do NOT use for cash-coverage / liquidity questions — use get_cash_position for that. </discrimination> <hints> - By default both paid and unpaid invoices are returned; set status to "UNPAID" or "PAID" to filter to a single payment state. - Filter by due date (due_date_start / due_date_end), issued/invoice date (issued_date_start / issued_date_end), or both together — e.g. invoices 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 invoices"), 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 customer 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_receivables. - To scope to one or more customers, use the two-step contact flow — contact_ids are UUIDs, never names: 1. Call get_contacts to resolve each named customer to its contact ID(s). 2. Call this tool a SINGLE time, populating contact_ids with EVERY ID returned in step 1. For several customers, collect all their IDs into that one contact_ids list rather than calling this tool once per customer, 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 customers' invoices (the last-month default is not applied). Combine contact_ids with date/status filters to narrow further (e.g. "Acme's paid invoices last quarter"). Never put a customer 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 invoices have been paid?" - "Show me all invoices between January and March" - "List all invoices issued to Acme" (resolve "Acme" via get_contacts, then call with its contact_ids) - "Show me invoices for Acme and Globex" (resolve both via get_contacts, then one call with both IDs) - "I want to see my recent invoices" - "Invoices issued last month that are due this month" </examples>

get_invoices

This tool returns the current financial year start and end dates for the connected Xero organisation. WHEN TO USE THIS TOOL: - When the user specifies a financial date or date range: - Financial year - Financial quarter - Financial half year - The user mentions fiscal, financial, FY, FYTD etc. date or date range DO NOT USE THIS TOOL IF: - The user mentions only a date or date range <examples> - "When does my financial year start?" - "What are the dates for FY25?" - "Show me profit for this financial year" - "What's the start of our fiscal year?" - "Give me revenue for the current FYTD" </examples>

get_organisation_financial_year

Return information about the connected Xero organisation. Use this tool to retrieve details about region, currency, timezone, business industry and company registration number. <discrimination> Do NOT use for financial data (P&L, balance sheet, cash) — use the appropriate financial tool. Do NOT use for financial year dates — use get_organisation_financial_year for that. </discrimination> <hints> - Use when you need to know the base currency, region, country, or timezone of the organisation. - Use when you need to know the line of business or industry of the organisation as context for seasonality benchmarking or marketing/content planning - Use when you need information about the organisation or company </hints> <examples> - "What country is my organisation in?" - "What's my base currency?" - "What timezone is my org set to?" - "What line of business is my organisation in?" - "What industry is my company in?" - "What region is my Xero org?" </examples>

get_organisation_info

Retrieve a profit and loss statement for the given period, optionally compared against another period. Shows net profit, income, expenses, and all accounts for the connected Xero organisation. Use for questions about profit, revenue, turnover, expense breakdown, or general business performance. 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 queries asking for broad financial overview, point-in-time financial snapshot, financial healthcheck or business valuation / worth — use get_financial_position instead </discrimination> <hints> - Only use the get_organisation_financial_year tool when the user explicitly mentions "financial year", "fiscal year", "FY", or similar. Queries like "year to date", "this year", or "last year" refer to the calendar year, not the financial year. - For calendar-based queries (e.g. "this month", "last quarter", "year to date"), derive start_date and end_date from the current date without using the get_organisation_financial_year tool. - If the user does not specify any date or period, omit dates from the request and use the tool defaults. - If the user asks for cash-basis P&L reporting, set accounting_basis to CASH. If the user does not ask for cash basis, omit accounting_basis or use ACCRUAL. - Never make up dates or periods that are not explicitly mentioned by the user. - For in-progress periods ("this month", "this quarter", "this financial year"), always use today's date as end_date — never the period boundary (e.g. end of quarter or end of financial year). - When comparing against a completed past period ("last financial year", "last quarter"), use the full period boundaries. When comparing against "the same point" in a past period, match today's date in that period. - Only set comparison_start_date and comparison_end_date when the user explicitly asks for a comparison (e.g. "compared to last month", "vs FY24"). - The comparison period must end before start_date (i.e. comparison_end_date < start_date). Ensure both comparison_start_date and comparison_end_date fall entirely before the primary period. </hints> <examples> - "How much profit did we make this month?" - "What's our revenue for last quarter?" - "Show me the P&L" - "What are our biggest expenses?" - "How does this month's income compare to last month?" </examples>

get_profit_and_loss