Integrates with Xero in read-only mode to connect multiple client organisations via OAuth2. It syncs and normalizes invoices, bills, contacts, bank balances, and reports into a cross-org view, enabling practice-wide tools such as overdue invoice reporting, payroll risk ranking, client health scoring, practice dashboards, and Excel month-end packs.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Xero Practice Aggregator MCP Show me all clients with invoices over 90 days overdue"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
One view across every client's Xero org, for accountants and bookkeepers. Each client connects their own Xero organisation, read-only. Your agent can then answer practice-wide questions that Xero itself can't: which clients have invoices more than 90 days overdue, who is closest to missing payroll, which clients are trending toward trouble, and what is my practice's total revenue and average DSO. It also produces a ready-to-send Excel month-end pack per client.
This is not a general-purpose Xero plugin. It has no write access to Xero at all.
A practice with 40 clients has 40 Xero logins and no cross-client view. Spotting the client who will bounce payroll next week means opening every org. This server polls every connected org on a schedule, normalizes invoices, bills, contacts, bank balances and reports into one cross-org model held in memory, and runs transparent, explainable rules over it. Every number it reports comes with the formula or rule that produced it.
Related MCP server: Python Xero MCP Server for BYB
Tool | What it does | Writes? |
| Connected orgs, sync status, currency, counts. Start here. | no |
| Creates a Xero OAuth2 sign-in link (authorization code + PKCE, read-only scopes) | no |
| Exchanges the code from Xero's redirect, stores only the tokens, encrypted | tokens file |
| Re-fetches all orgs into the in-memory cache (also runs on a timer) | no |
| Sales invoices more than 30, 60 or 90 days overdue across all clients, per org and per currency | no |
| Ranks orgs by how close they are to missing payroll, with the formula shown | no |
| Override an org's payroll amount and date (memory only) | memory |
|
| export folder |
| 0-100 score from transparent rules (expense spike z-score, growing director loan, ...) | no |
| Total revenue across clients (by currency), average DSO, health band per client | no |
| Clients under a health threshold, worst first, with reasons | no |
| Revokes the Xero connection and deletes its tokens (preview, then | tokens file |
Three skills ship with the plugin and teach the agent how to use these tools: connect-xero-orgs, practice-review and month-end-pack.
Ageing. Days overdue = as-of date minus due date. Buckets: Current (not yet due), 1-30, 31-60, 61-90, 90+. Only AUTHORISED invoices with an amount still due are included, and part-payments count at the amount still due. overdue_invoices with min_days: 30 means more than 30 days.
Payroll risk.
coverage = (cash in all bank accounts - bills due on or before next payroll date) / payroll amount
headroom = cash - those bills - payroll amountBelow 1.0 is a SHORTFALL, 1.0 to 1.5 is tight, and anything higher is ok. Cash is the closing balance from Xero's Bank Summary. The payroll amount defaults to the average of the P&L lines named wages, salaries, payroll, PAYE, pension or super over the last 3 months. The next payroll date defaults to the next 25th. Use set_payroll_profile to supply the real figures; the read-only scopes deliberately exclude Xero Payroll.
Health score. Starts at 100 and loses points for each rule that fires:
Rule | Points |
More than 10% of receivables are 90+ days overdue | -15 |
Payroll coverage < 1.0 | -25 |
Payroll coverage 1.0 to 1.5 | -10 |
Expense spike: latest month's total expenses z-score >= 2.0 against the trailing months (sample std dev, needs 3+ trailing months) | -15 |
Growing director loan: the absolute balance of any balance-sheet account named like "Director ... Loan / Current Account" rose in each of the last 3 months | -15 |
DSO > 60 days | -10 |
Unreconciled bank items > 10% of cash | -10 |
Income fell in each of the last 3 months | -10 |
A score of 80 or more is healthy, 60-79 is watch, and under 60 is at risk. These are prioritisation heuristics, not credit ratings or advice.
DSO = receivables outstanding / P&L income for the last 3 months × days in those months. The practice average is the simple mean across clients. Revenue is P&L income, summed per currency; different currencies are never added together.
Requires Node 20+.
The default .mcp.json runs with XERO_AGG_DEMO=1. Two fixture orgs (Harbour Bakery Ltd and Northwind Joinery Ltd, both synthetic, GBP, as at 2026-09-30) are served through the same normalization code as live data. Add the plugin and ask "list my Xero clients".
{
"mcpServers": {
"xero-aggregator": {
"command": "npx",
"args": ["-y", "https://github.com/ppiotis/xero-aggregator-mcp/archive/refs/tags/v1.0.0.tar.gz"],
"env": {
"XERO_CLIENT_ID": "your-xero-app-client-id",
"XERO_AGG_TOKEN_KEY": "output of: openssl rand -base64 32",
"XERO_REDIRECT_URI": "http://localhost:5173/oauth/callback"
}
}
}
}Locally nothing listens on the redirect URI. After approving in Xero, the browser shows a "can't connect" page; copy that page's full URL and give it to the agent, which passes it to connect_org_complete. The code in that URL is single-use, expires in minutes, and is useless without the PKCE verifier held by your server.
git clone https://github.com/ppiotis/xero-aggregator-mcp && cd xero-aggregator-mcp
npm ci && npm run build
export XERO_CLIENT_ID=... XERO_CLIENT_SECRET=... XERO_AGG_TOKEN_KEY="$(openssl rand -base64 32)"
export XERO_REDIRECT_URI=https://your-host/oauth/callback MCP_AUTH_TOKEN="$(openssl rand -hex 32)"
export HOST=0.0.0.0 PORT=3000 XERO_AGG_TOKEN_FILE=/data/tokens.enc XERO_AGG_EXPORT_DIR=/data/exports
npm run start:http # MCP endpoint: https://your-host/mcp, health: /healthOr use docker build -t xero-aggregator . && docker run -p 3000:3000 -v xagg:/data -e ... xero-aggregator. Put it behind HTTPS, and connect your MCP client to https://your-host/mcp with header Authorization: Bearer $MCP_AUTH_TOKEN. The server is single-practice: one deployment holds one practice's connections. Don't share an instance between practices.
Variable | Default | Purpose |
| none | Xero app client id (live mode) |
| none | Only for Xero "Web app" type. Omit for PKCE-only apps |
|
| Must exactly match the app's redirect URI |
| none | Required in live mode. 16+ chars; encrypts the token file |
|
| Encrypted token store |
|
| Where month-end packs are written |
|
| Poll interval; |
| granular | Set |
| none | Explicit scope list; anything not |
| off |
|
| none | Bearer token required on |
Go to developer.xero.com/app/manage, then New app.
For local use choose Mobile or desktop app (PKCE, no secret). For a server choose Web app and set XERO_CLIENT_SECRET.
Set the redirect URI to exactly your XERO_REDIRECT_URI.
Copy the client id into XERO_CLIENT_ID.
Scopes requested (read-only, granular, as required for apps created on or after 2 March 2026):
openid profile email offline_access accounting.settings.read accounting.contacts.read accounting.invoices.read accounting.banktransactions.read accounting.reports.profitandloss.read accounting.reports.balancesheet.read accounting.reports.banksummary.read.
Older apps can use XERO_SCOPE_SET=broad (accounting.transactions.read accounting.reports.read), which works until Xero's 13 September 2027 deadline. If Xero's consent screen reports an invalid scope, set XERO_SCOPES explicitly.
To try it, connect Xero's Demo Company (in Xero: My Xero → Try the Demo Company), then ask the agent to "connect a client Xero org".
Xero limits each app to 60 calls per minute per org and 5 concurrent calls. The poller syncs orgs one at a time (about 7 calls per org), honours Retry-After on 429 responses, and refreshes tokens once on a 401.
Read-only. The server only requests .read scopes; config that asks for anything else is rejected at startup. Every Xero API call is a GET (tested). The only non-GET is DELETE /connections/{id}, used by disconnect_org to revoke its own access.
Tokens only on disk. The token file holds OAuth tokens plus tenant ids and names, encrypted with AES-256-GCM under a key derived by scrypt from XERO_AGG_TOKEN_KEY. It is written atomically with mode 0600. A wrong key or a tampered file fails closed.
No financial data persisted. Invoices, bills, contacts, balances and reports are normalized into an in-memory cache only, so a restart clears them. A test asserts that after a full sync the only file on disk is the encrypted token file, and that it contains no customer names or invoice numbers. The single exception is the month-end pack you explicitly ask for, written to XERO_AGG_EXPORT_DIR (filenames are slugged; path traversal is tested).
OAuth done properly. Authorization code with PKCE S256, a single-use state that expires after 10 minutes, and refresh-token rotation: every refresh stores the new refresh token, and concurrent refreshes are de-duplicated so a rotated token is never reused. The client secret is sent via HTTP Basic only when configured.
HTTP mode. /mcp requires Authorization: Bearer $MCP_AUTH_TOKEN, compared in constant time, with a 1 MB body limit. /oauth/callback is protected by the PKCE state, and it never echoes codes or tokens back.
No telemetry, no third parties. The server only contacts login.xero.com, identity.xero.com and api.xero.com.
Secrets never go in chat. Configure them as environment variables; the skills tell the agent never to ask for tokens.
Everything below runs in demo mode (the default .mcp.json), as an accountant opening the plugin for the first time. The data is as at 2026-09-30, in GBP.
1. "List my Xero clients."
Expect list_orgs to show 2 orgs: Harbour Bakery Ltd (5 open invoices, 3 open bills, 2 bank accounts) and Northwind Joinery Ltd (6 open invoices, 4 open bills, 1 bank account), mode: "demo".
2. "Show me every invoice more than 30 days overdue across all my clients." Then "...and over 90?" Expect 6 invoices totalling £20,435.50: Harbour Bakery 2 (£3,310.00), Northwind 4 (£17,125.50). The most overdue is INV-B101, Oakridge Homes, 112 days, £6,800.00 due. It's a part-paid £8,800 invoice, so check the amount due is used, not the total. Over 60 days: 4 invoices, £15,810.00. Over 90 days: 2 invoices (INV-B101, INV-B102), £11,050.00, both Northwind. Draft and voided invoices in the fixtures (INV-A006, INV-B107) must not appear.
3. "Which client is closest to missing payroll? Show the working."
Expect Northwind Joinery Ltd, SHORTFALL: coverage = (cash 7212.4 - bills due on or before 2026-10-25 9530) / payroll 12000 = -0.19, headroom -£14,317.60. Harbour Bakery is ok: (28,420.35 - 4,150) / 9,000 = 2.70. Then "Harbour's payroll is actually £20,000 on 8 October": expect coverage 1.31, tight (only the £2,300 VAT bill falls before 8 Oct).
4. "Make me Northwind's month-end pack."
Expect an .xlsx named northwind-joinery-ltd-month-end-2026-09-30.xlsx with 3 sheets. Open it:
Aged Receivables: 6 invoice rows, then a Total row of Current 2,600.00 | 1-30 1,480.00 | 31-60 2,175.50 | 61-90 3,900.00 | 90+ 11,050.00 | Total 21,205.50.
Bank Reconciliation: Business Current Account, closing 7,212.40, 7 unreconciled items, 6,495.24.
P&L Snapshot: Sep 26 income 23,300.00, expenses 33,600.00, net -10,300.00. The 6-month total net is -900.00. For comparison, Harbour Bakery's pack shows an aged total of 8,150.00, 3 unreconciled items for 475.50, and a Sep net profit of 7,350.00.
5. "Which of my clients are trending toward trouble, and why?" Expect only Northwind Joinery Ltd, score 10/100, at risk, with six reasons. 90+ receivables are 52.1% of the total (-15). Payroll coverage is -0.19 (-25). Sep expenses of 33,600 are a spike against a trailing mean of 26,080 (sd 192.35, z = 39.09) (-15). The director's loan account grew 5,200 → 7,800 → 10,400 → 14,100 (-15). Unreconciled items of 6,495.24 compare with cash of 7,212.40 (-10). Income fell 27,200 → 26,400 → 24,900 → 23,300 (-10). Harbour Bakery scores 100, healthy (expense z-score 0.34).
6. "Give me the practice dashboard." Expect 2 clients, total revenue (last 3 months) £145,100.00 (Harbour 70,500 + Northwind 74,600), and average DSO 18.4 days (Harbour 10.6, Northwind 26.2). Asking for 6 months gives £300,100.00.
7. Safety checks.
"Make a pack for Ltd" should fail with "matches several orgs". overdue_invoices with min_days: 45 should be rejected. "Disconnect Northwind" should be refused in demo mode. In live mode, disconnect_org previews first and acts only with confirm=true.
Live mode (optional). Create a Xero app as above, set XERO_CLIENT_ID and XERO_AGG_TOKEN_KEY, and remove XERO_AGG_DEMO. Then ask "connect a client Xero org", approve the Demo Company, paste the redirect URL, and ask "list my Xero clients".
npm ci
npm test # build + all suites
npm run test:integration # real Xero API, see belowSuite | Covers |
| Xero date formats, numbers, invoice status filtering, part-payments, report parsing (P&L, Bank Summary, Balance Sheet), unreconciled grouping |
| Ageing buckets and boundaries, cross-org overdue (incl. mixed currency), payroll formula and overrides, health rules, DSO, dashboard |
| AES-GCM round-trip, wrong key, tampering, |
| Opens the generated workbooks and checks sheet names, every row, the bucket totals (and that they equal the column sums), bank rec and P&L totals, and path traversal |
| The reviewer scenarios above, over stdio and Streamable HTTP (plus 401s, |
| Real Xero API, skipped unless credentials are set |
Integration tests (real Xero). These are skipped unless XERO_CLIENT_ID and XERO_AGG_TOKEN_KEY are set, together with either XERO_REFRESH_TOKEN or an XERO_AGG_TOKEN_FILE created by connecting via connect_org_start/connect_org_complete. Web apps also need XERO_CLIENT_SECRET. The tests sync every connected org (e.g. the Demo Company), check that the normalized model is internally consistent, and write a pack. They only use GET requests. Xero rotates the refresh token on every use, so keep XERO_AGG_TOKEN_FILE on a persistent path between runs. The Demo Company's data changes when Xero resets it, so these tests check invariants rather than fixed numbers.
The fixtures are synthetic data in Xero API response shape, generated by fixtures/generate.mjs.
"Unreconciled" uses Xero bank transactions with IsReconciled=false. The Accounting API does not expose unmatched bank statement lines.
Payroll is estimated from P&L lines unless you set it, because Xero Payroll scopes are intentionally not requested.
Reports cover the as-of month plus the 5 months before it. Expense z-scores therefore use up to 5 trailing months.
Multi-currency orgs are reported in each org's base currency, and practice totals are kept per currency.
npm ci && npm run build && npm test
npm run fixtures # regenerate demo fixturesMIT © 2026 Paris Piotis
0-100 health score per client from transparent rules (each rule and its points is listed): 90+ day receivables share, payroll coverage, expense spike (z-score of latest month vs trailing months), growing director loan, DSO, unreconciled items, falling income. >=80 healthy, 60-79 watch, <60 at risk. Omit org for all clients.
| Name | Required | Description | Default |
|---|---|---|---|
| org | No | Client org: tenant id or (part of) the organisation name, e.g. 'Northwind'. | |
| as_of | No | Report date (YYYY-MM-DD). Defaults to today (demo mode: 2026-09-30). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare this read-only, idempotent and non-destructive, so safety needs no restating. The description adds genuinely useful behavioral context beyond that: the score is built from transparent rules with per-rule points listed, and the omit-org behavior fans out to all clients. Not a 5 because no output shape or volume of returned clients is indicated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One dense but well-ordered paragraph: score definition first, then the rule inputs, then the band thresholds, then the omit-org behavior. Every clause carries information, though the rule list reads as a run-on.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
A two-parameter read tool with 100% schema coverage and no output schema: the description is complete enough to call correctly, explaining the metric composition and all-client behavior. Minor gap is the absence of return-shape detail, which is more tolerable for a scoring tool with stated bands.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents org ('tenant id or part of organisation name') and as_of (YYYY-MM-DD, defaults today). The description's 'Omit org for all clients' is useful secondary context but largely overlaps the schema, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific artifact, a 0-100 health score per client, and enumerates the exact inputs driving it (receivables share, payroll coverage, expense spike z-score, director loan, DSO, unreconciled items, falling income). Distinct from siblings like payroll_risk or overdue_invoices, which cover only single signals.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The scoring bands (>=80 healthy, 60-79 watch, <60 at risk) imply interpretation, but there is no explicit when-to-use guidance and no routing to alternatives such as overdue_invoices or payroll_risk when only one signal is needed. Usage is inferable rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Clients whose health score is below the threshold (default 80), worst first, with the reasons.
| Name | Required | Description | Default |
|---|---|---|---|
| as_of | No | Report date (YYYY-MM-DD). Defaults to today (demo mode: 2026-09-30). | |
| threshold | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, non-destructive and open-world behavior, so the safety profile is covered. The description adds useful behavioral detail — result ordering and inclusion of reasons — but says nothing about result caps, pagination, or what a 'reason' consists of.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single tight sentence with no filler, front-loading the filter condition and following immediately with ordering and payload. Every clause carries information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a parameterless-filter read tool with no output schema, the description covers the selection rule, default, ordering, and payload. Only the omission of any result-size or time-scope caveat keeps it from being fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 50% (as_of is documented, threshold is not), and the description compensates by defining the threshold's meaning and its default of 80. The sort semantics ('worst first') also add interpretation the schema cannot express, though as_of is never mentioned in prose.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific output: clients with health score below a threshold, sorted worst-first, with reasons included. An agent can tell this is an at-risk-client listing rather than a general health lookup. It does not, however, explicitly differentiate itself from the sibling client_health tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the use case (surfacing clients trending toward trouble) but gives no explicit when-to-use, when-not-to-use, or alternative routing. With siblings like client_health and practice_dashboard present, an agent is left to infer which one to pick.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Exchanges the authorization code from Xero's redirect for tokens, encrypts them at rest, and syncs the new org. Pass the full redirect URL (contains code and state).
| Name | Required | Description | Default |
|---|---|---|---|
| redirect_url | Yes | The full URL the browser was redirected to after approving in Xero. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare the safety profile (not read-only, not idempotent, open-world), but the description adds substantive side-effect detail beyond them: it encrypts tokens at rest and syncs the new org, which tells an agent what state changes to expect. It stops short of covering failure modes such as an expired or already-used code.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no waste. The operation is front-loaded and the parameter instruction follows immediately. Every clause earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter connection-finishing tool with no output schema, the description covers the operation and the required input adequately. It could be slightly more complete by noting the dependency on connect_org_start, but nothing essential to invocation is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents the single parameter. The description nonetheless adds meaning by explaining why the full URL is needed — it 'contains code and state' — which clarifies that a bare code will not suffice.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific multi-step operation: exchanging a Xero authorization code for tokens, encrypting them, and syncing the org. This clearly distinguishes it from sync_now or list_orgs. However, it does not explicitly name connect_org_start as the required predecessor, leaving the sibling relationship to inference from the name.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'from Xero's redirect' and 'Pass the full redirect URL' implies this runs after the user approves in Xero, but the description never states the prerequisite (call connect_org_start first) or any when-not conditions. Usage is implied rather than specified.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Creates a Xero OAuth2 (authorization code + PKCE) sign-in link with READ-ONLY scopes. Give the link to the client (or open it yourself if you are their adviser user); they pick their org and approve. Then call connect_org_complete with the URL they were redirected to. Not needed in demo mode.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false and idempotentHint=false, but the description adds real value: the link carries READ-ONLY scopes, the flow is human-in-the-loop, and it is inert in demo mode. It stops short of saying whether the link expires or whether repeated calls create multiple pending links, which matters for a non-idempotent tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tightly packed sentences that front-load what is created, then the handoff, then the required follow-up call and the demo-mode caveat. No filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and no parameters, the description carries the workflow burden and does so well, including the downstream call. It omits link lifetime/retry semantics, the only material gap for an agent that may be asked to re-run it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has zero parameters, so there is nothing to document and the baseline is 4. The description correctly implies no inputs are required before the link is produced.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and artifact: creates a Xero OAuth2 authorization-code + PKCE sign-in link. It also scopes the operation (READ-ONLY scopes) so the agent cannot confuse it with connect_org_complete, the sibling that finishes the flow.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly describes the human step (hand the link to the client or open it as their adviser), the follow-up call (connect_org_complete with the redirect URL), and an exclusion (not needed in demo mode). Both the trigger and the next action are spelled out.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Revokes this app's Xero connection for one org and deletes its stored tokens and cached data. Call first with confirm=false to see what will happen, ask the user, then confirm=true.
| Name | Required | Description | Default |
|---|---|---|---|
| org | Yes | Client org: tenant id or (part of) the organisation name, e.g. 'Northwind'. | |
| confirm | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, so the risk class is known; the description adds the concrete blast radius (tokens and cached data are deleted) and the non-obvious two-phase preview-then-confirm behavior, which annotations cannot express. It does not mention that reconnection requires the connect_org flow, leaving reversibility implicit.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no filler, and the destructive effect is front-loaded before the procedural instruction. Every clause carries information the agent needs.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive two-parameter tool with no output schema, the description covers impact, safety sequencing, and the meaning of both parameters. The only minor omission is what the confirm=false preview actually returns, but the agent has enough to act safely.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 50%: 'org' is well documented in-schema, but 'confirm' has only a type and default with no description. The description compensates by explaining what each confirm value does, so the undocumented parameter is covered in prose.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (revokes/disconnect) plus the exact resource (this app's Xero connection for one org) and enumerates the side effects (deletes stored tokens and cached data). It is clearly distinguishable from the sibling connect_org_start / connect_org_complete tools, which do the opposite.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives an explicit operating procedure: call with confirm=false first, ask the user, then call with confirm=true. That is strong when-to-use guidance. It stops short of naming alternatives (e.g. use list_orgs to resolve the org identifier) or saying when not to disconnect.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Lists every connected Xero org with sync status, currency and counts. Start here.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and openWorldHint=true, carrying the safety and idempotency profile. The description adds what data is surfaced (sync status, currency, counts), but does not discuss pagination, freshness, or auth. Adequate against the lower bar annotations set.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, front-loaded with the verb and resource, and the "Start here" call to action is placed last for emphasis. Nothing wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-argument read of an open-world list with no output schema, the description covers what is returned and where it fits in the workflow. Slightly more detail on result shape or ordering would make it complete, but it is sufficient to call correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Zero parameters, so the baseline is 4. The description correctly implies a no-argument enumeration and adds nothing to mislead.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (lists) and resource (connected Xero orgs), plus the fields returned (sync status, currency, counts). Among siblings like connect_org_complete, sync_now, and disconnect_org, this is clearly the enumeration/discovery tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
"Start here" gives a clear usage cue that this is the entry point before connecting, syncing, or disconnecting orgs. It stops short of explicit when-not-to or naming the alternatives, but the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Writes an Excel workbook for ONE client with three sheets: Aged Receivables (per invoice, bucketed current/1-30/31-60/61-90/90+ with totals), Bank Reconciliation (closing balance, unreconciled count and amount per account) and P&L Snapshot (latest month and period total). Saved in XERO_AGG_EXPORT_DIR; returns the path and the totals written so you can quote them.
| Name | Required | Description | Default |
|---|---|---|---|
| org | Yes | Client org: tenant id or (part of) the organisation name, e.g. 'Northwind'. | |
| as_of | No | Report date (YYYY-MM-DD). Defaults to today (demo mode: 2026-09-30). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare write-not-read (readOnlyHint=false), openWorld, idempotent and non-destructive. The description adds real context beyond that: what is written (three specific sheets with their aggregates), where it is written (XERO_AGG_EXPORT_DIR), and what the caller receives back (path plus totals). It does not spell out overwrite/re-run semantics or permissions, which keeps it off a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single dense sentence, front-loaded with the verb and scope, followed by the sheet breakdown and the return payload. Every clause carries information, though the sheet enumeration is long enough that it could be trimmed in favour of the arc.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description correctly carries the return contract (file path and totals to quote) and names the destination directory and the exact sheets produced. An agent has everything needed to call it and interpret the result.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so both params are already documented in the schema, and the description adds little syntax detail. Its only contribution is confirming the single-org scope ('ONE client'), implying org must identify exactly one tenant — baseline 3 for full schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (writes an Excel workbook) and a precisely scoped resource (ONE client, three named sheets with their contents). No sibling tool produces a file export, so the agent can immediately tell this apart from sync/log/report siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Clearly frames the operating context: one client per call, output lands in XERO_AGG_EXPORT_DIR, and the totals come back in the response. It stops short of naming when an agent should prefer this over e.g. overdue_invoices or client_health for the same data, so no explicit alternatives or exclusions are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Every client invoice (receivable) more than 30, 60 or 90 days past its due date, across all connected orgs, with per-org and per-currency totals. Uses amount still due (part-payments excluded).
| Name | Required | Description | Default |
|---|---|---|---|
| as_of | No | Report date (YYYY-MM-DD). Defaults to today (demo mode: 2026-09-30). | |
| min_days | No | Overdue by MORE than this many days. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds real domain behavior: receivables only (not payables), aging measured against due date with strict 'more than' semantics, part-payments excluded via amount-still-due, and per-org/per-currency totals in the output.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no filler; scope and aggregation are front-loaded and the calculation caveat (part-payments excluded) is placed last where it belongs.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only report with no output schema, the description covers scope, aging basis, calculation rule and result granularity adequately. Minor gaps remain: no mention of sorting/pagination or how multi-currency totals are consolidated, which an agent producing a report might want to know.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so both parameters are documented in the schema, including the YYYY-MM-DD pattern and the demo-mode default. The description restates the 30/60/90 thresholds and the due-date basis but adds no syntax or edge-case detail beyond the schema — the baseline 3 for full coverage applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific resource (client invoices / receivables) and a precise scope (more than 30/60/90 days past due, across all connected orgs), which cleanly separates it from per-client siblings like client_health or practice_dashboard.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'across all connected orgs' phrasing implies a portfolio-wide reporting use case, but the description never says when to pick this over client_health, practice_dashboard or clients_trending_trouble, and names no alternatives or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Ranks orgs by how close they are to missing their next payroll. coverage = (cash in bank - bills due on or before payroll date) / payroll amount. Below 1.0 means a shortfall. Payroll amount defaults to the average of wages/salaries P&L lines over the last 3 months, next payroll date to the next 25th; override with set_payroll_profile. Shows the formula with numbers for each org.
| Name | Required | Description | Default |
|---|---|---|---|
| as_of | No | Report date (YYYY-MM-DD). Defaults to today (demo mode: 2026-09-30). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful behavior beyond that: how coverage is computed, the exact default assumptions (3-month average of wages/salaries P&L lines, next 25th payroll date), and that the formula is returned with numbers per org.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four tight sentences: the purpose and threshold first, then the formula, then the defaults and the override path, then the output note. Nothing is redundant and the most decision-relevant facts are front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only, single-optional-parameter ranking tool with no output schema, the description covers purpose, metric definition, default assumptions, and output shape adequately. Minor gaps remain: it doesn't say whether results cover all connected orgs or how the ranking is ordered/limited.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There is a single optional parameter (as_of) with 100% schema description coverage, including its format pattern and demo-mode default, so the schema carries the load. The description adds nothing about as_of semantics (e.g. whether historical dates recompute defaults), which is the baseline-3 expectation when schema coverage is complete.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb and resource ('Ranks orgs') plus the exact quantity ranked ('how close they are to missing their next payroll'). It also defines the metric outright (coverage formula, 1.0 threshold), so an agent can distinguish it from siblings like client_health or overdue_invoices without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives concrete context for invocation (assessing payroll shortfall risk) and explicitly routes the agent to set_payroll_profile when the default payroll amount or date assumptions must be overridden. It does not state when NOT to use this versus other risk-oriented siblings, so it falls short of a full when/when-not/alternatives treatment.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Practice-level totals: revenue (P&L income) across all clients for the last N months, grouped by currency (never mixes currencies), average DSO, and each client's health band.
| Name | Required | Description | Default |
|---|---|---|---|
| as_of | No | Report date (YYYY-MM-DD). Defaults to today (demo mode: 2026-09-30). | |
| months | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish the safe read profile (readOnly, idempotent, non-destructive), so the description's burden is light. It does add genuine behavioral detail beyond the annotations: currency grouping is enforced so results are 'never mixed', and the last-N-months window is fixed. It does not mention row counts, performance, or result shape.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence that names the resource first and then enumerates the returned measures. Dense but each clause carries information; the parenthetical '(P&L income)' and '(never mixes currencies)' are the only marginal additions.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, and the description effectively enumerates the returned measures (revenue by currency, average DSO, health band), which is what an agent needs to decide if this fits. Annotations cover the safety profile, so only minor gaps remain around result size/format.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 50%: as_of is documented in the schema, months is not. The description compensates for the undocumented months parameter by defining it as the lookback window ('last N months'), but adds nothing about as_of beyond what the schema already says.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific resource (practice-level totals) and enumerates exactly what is returned: revenue/P&L income across all clients, DSO, and client health bands. The stated scope ('across all clients', 'practice-level') implicitly separates it from per-client siblings like client_health or overdue_invoices, though no sibling is named explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The practice-level framing implies when to reach for it (aggregate overview rather than per-client drill-down), but there is no explicit when-to-use statement, no exclusion of scenarios better served by client_health or month_end_pack, and no prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Overrides the estimated payroll amount and/or next payroll date for one org. Held in memory only (cleared on restart); nothing is sent to Xero.
| Name | Required | Description | Default |
|---|---|---|---|
| org | Yes | Client org: tenant id or (part of) the organisation name, e.g. 'Northwind'. | |
| amount | No | ||
| next_payroll_date | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only mark this as a non-readonly, idempotent, non-destructive write. The description adds genuinely useful behavior the annotations cannot convey: the override is held in memory only, cleared on restart, and nothing is sent to Xero. That persistence scope and absence of external side effects are exactly what an agent needs, though it omits what happens if the org is not found or whether at least one field must be supplied.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two compact sentences, no filler. The core action is front-loaded and the ephemerality caveat immediately follows it.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema and only three parameters, with annotations carrying the mutation/safety profile, so the description is close to sufficient. It misses edge-case behavior (org not found, whether amount and date are independently optional) but covers the two things an agent would most likely get wrong: persistence and Xero side effects.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 33% — 'org' is documented but 'amount' and 'next_payroll_date' have no schema descriptions. The description compensates partially by framing both as optional ('and/or') overrides of estimates, but gives no currency/units for amount or any semantics beyond the regex pattern for the date. Adequate but leaves gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('Overrides'), the exact resources modified (estimated payroll amount and/or next payroll date), and the scope ('for one org'). This is distinguishable from siblings like payroll_risk or practice_dashboard without opening any schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The word 'Overrides' and 'estimated' imply the use case (correcting an estimate the system computed), but the description never states when to reach for this versus payroll_risk or other payroll siblings, nor any prerequisites or exclusions. Usage is inferable but not spelled out.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Re-fetches invoices, bills, contacts, bank balances and reports for every connected org into the in-memory cache (nothing financial is written to disk). The poller also does this automatically every XERO_AGG_SYNC_MINUTES.
| Name | Required | Description | Default |
|---|---|---|---|
| as_of | No | Report date (YYYY-MM-DD). Defaults to today (demo mode: 2026-09-30). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover readOnly, idempotent and non-destructive, but the description adds genuinely new behavioral facts: the write target is an in-memory cache and 'nothing financial is written to disk', and the operation spans all orgs rather than one. It does not disclose whether the call blocks until completion or how long a full multi-org refetch takes, which would matter for a sync trigger.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, zero filler. Scope and effect come first, the no-disk guarantee is parenthetical, and the poller cadence is appended as context rather than padding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With rich annotations and a fully described single parameter, the definition covers scope, side effects and the automatic-update alternative. The one remaining gap is that no output schema exists and the description says nothing about what a sync call returns or whether it is synchronous, which an agent invoking a long-running org-wide refetch would want to know.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There is a single optional parameter and schema coverage is 100%, so the schema already documents as_of fully, including the YYYY-MM-DD pattern and the demo-mode default. The description's mention of 'reports' loosely corresponds to that date knob but adds no syntax or defaulting detail, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('Re-fetches') and enumerates the resources (invoices, bills, contacts, bank balances, reports) across an explicit scope ('every connected org'). No sibling tool performs a sync, so the agent can distinguish it immediately from list_orgs, overdue_invoices, or the connect_org_* tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The sentence about the poller running automatically every XERO_AGG_SYNC_MINUTES gives the agent a clear reason to call this only when it needs data refreshed immediately rather than waiting. It stops short of an explicit when/when-not statement or naming an alternative data source, so it is strong context rather than full routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.0.0client_healthclients_trending_troubleconnect_org_completeconnect_org_startdisconnect_orglist_orgsmonth_end_packoverdue_invoicespayroll_riskpractice_dashboardset_payroll_profilesync_nowScored across 12 tools
Most tools target clearly distinct resources or analyses (overdue aging, payroll risk, health scoring, exports), and descriptions are unusually detailed. Minor overlap exists among the health/analytics cluster — client_health, clients_trending_trouble and practice_dashboard all surface client health — but their scopes (per-client score, filtered list, practice totals) are explained well enough to route correctly.
All names are snake_case, which keeps them readable, but the pattern is mixed: some are verb_noun (list_orgs, sync_now, disconnect_org, set_payroll_profile) while others are bare noun phrases (overdue_invoices, payroll_risk, month_end_pack, client_health, practice_dashboard, clients_trending_trouble). No predictable verb convention ties the set together.
12 tools sits squarely in the well-scoped range for a multi-org finance aggregator. Each tool maps to a distinct capability (auth, sync, org management, several reports, export) and none appear redundant filler.
The lifecycle is well covered: OAuth connect start/complete, list, sync, disconnect, plus a rich analytics/reporting surface and an Excel export. Gaps are minor — there's no per-client drill-down or raw invoice/contact retrieval, but agents can work around this via the existing reports.
Query financial statements, KPIs, ratios, cash forecasts and budgets from your general ledger
Month-end billing for consulting, architecture and engineering firms: your AI assistant previews each invoice from approved time, retainers and progress billing, then drafts them for your review. Also reports utilization, project profitability, WIP and cash flow.
Startup books from live bank and billing feeds: P&L, balances, approvals, period close.
Every company's money in one ledger: cash, runway, invoices, payroll. Records money, never moves it.
