Skip to content

SPEC-011: What Claude sees ​

Business intent ​

Every turn of a conversation with GetMy Books carries the server instructions and every tool's description and schema: about 15,700 tokens on 2026-10-07 (30 tools, about 14,900; the instructions, about 770). A bank_reconciliation_check reply for one month is 10,000 to 20,000 tokens, most of it lines already matched and reconciled. The same rules are repeated in full in four or five places, three confirm tools exist that no longer write, and some descriptions contradict each other (bank_outstanding says it is for "reconcile an account"). That costs money on every turn, crowds Claude's context, and makes it more likely Claude follows the wrong rule. The Product Owner wants the surface cheaper and clearer, with no capability lost.

It governs the MCP surface of the bank tools (CAP-02.7) first, and the receipt (CAP-02.9), connection (CAP-01.1) and activity log (CAP-02.10) tools where an item touches them.

User story ​

As the owner talking to Claude, I want each turn to carry only what Claude needs, each rule said once where it applies, and each tool's purpose plain, so Claude answers faster, costs less and picks the right tool.

Scope ​

One scenario per item of the Product Owner's track C list (2026-10-06): reply size (C1), rules once (C2), schema hygiene (C3), one status tool (C4), routing (C5), prompt order (C6) and fewer tools (C7).

Kept, whatever changes:

  • Every capability. Nothing a tool could do before is lost; a removed tool's job is done by the tool that replaces it.
  • The approval path (AUDIT C5). Approve in the card is still the only way anything is written to Xero. No new or renamed tool writes.
  • The activity log (SPEC-010). Every preview, decision and write outcome is still logged, through any renamed or merged tool.
  • Server-side validation. Inputs are refused exactly as before.

Out of scope ​

  • Changing what any check, preview or write works out.
  • Changing the owner-facing summaries (the text built by code), except where a removed tool is named.

Scenarios ​

All approved 2026-10-06 by the Product Owner, pre-sale review, track C.

S1: A check's reply leaves out lines already reconciled (C1) ​

Given a month in which most bank lines are matched and reconciled in Xero When Claude calls bank_reconciliation_check Then the reply's JSON lists only the lines that are not matched and reconciled, with how many were left out and their net total in pence And each line, record and candidate carries only what Claude uses: IDs, dates, amounts, direction, contact or counterparty, reference, and the account and tax type where shown And the summary text shown to the owner is exactly as before And bank_explain_line still explains any line, a matched and reconciled one included

S2: Each rule is said once, where it applies (C2) ​

Given the server instructions and the tool descriptions When Claude reads them Then the statement-files rule is in full only in the instructions and bank_statement_files, and the receipts-first rule in full only in the instructions and bank_entries_preview And the "Approve puts the outcome in your context" rule is in full only in the instructions, with one line in each preview tool And the Xero Documents note is only in receipts_inbox, and the no-VAT-costs rule (SPEC-003 S73) only in the instructions and bank_entries_preview And every other tool that the rules govern carries a one-line pointer to them And the instructions' reconcile rules read as their own paragraph

S3: Tool schemas carry no noise (C3) ​

Given the tool list When Claude reads it Then no input schema carries $schema, and no uuid field carries a pattern beside its format: uuid And no model-facing text names a SPEC, ADR or AUDIT reference And every input is still validated by the server exactly as before

S4: One status tool, which never writes (C4) ​

Given a preview shown to the owner in an approval card When Claude needs to know what became of it Then Claude calls write_status with the previewId And it reports whether the card wrote it (with what the activity log recorded), or that it is still waiting for the owner, was declined, has expired or is not found And it never writes, whatever the preview's state And bank_entries_confirm, vat_corrections_confirm and attachments_confirm are gone And nothing but the card's Approve can claim a preview: there is no claim without the card's token (AUDIT C5)

A preview approved but never claimed (only possible before SPEC-003 S38, when Approve and the write were two steps) is reported as approved but not written, and must be previewed again: nothing can write it now. Added in review of PR #212.

S5: Each bank tool says what it is for, and works for every account (C5) ​

Given the owner asks to reconcile an account, or to clear a backlog across months When Claude chooses a tool Then bank_reconciliation_check says it is for one period, and bank_outstanding that it is for a backlog across months, and the instructions say the same And bank_outstanding and bank_explain_line take the checkId a check returned, with the same rules as the other tools, so an account read from attached statement text (Amex) works in every bank tool And the vat-ready prompt passes the checkId to bank_outstanding instead of working round it

S6: Receipts are looked for in Xero before email (C6) ​

Given the owner runs the reconcile-account prompt When the prompt reaches receipts Then it looks in the Xero Files inbox and runs receipts_reconcile before searching email And it searches email only for what is still missing And it asks once to compare the Statements received table

S7: Fewer tools for the same jobs (C7) ​

Given the tool list When Claude needs the Xero inbox address, or to check the connection Then receipts_inbox returns the inbox address with the files, and receipts_inbox_address is gone And connection_check says the server is reachable and which companies are connected to Xero, and ping and xero_list_tenants are gone And the instructions and prompts name the new tools

S8: A switch to drop the duplicate JSON text, for testing (approved 2026-10-07 by the Product Owner) ​

Given a tool reply that carries structuredContent When MCP_REPLY_JSON_TEXT is unset or on Then the reply is exactly as before: the summary text, the JSON text and structuredContent When MCP_REPLY_JSON_TEXT is off Then the content array carries only the summary text, and structuredContent is unchanged And error replies, and replies without structuredContent, are unchanged either way And the switch is off by default and exists to test token savings in Claude Desktop; the default behaviour does not change, except for card-bearing replies (S9)

S9: A card-bearing reply carries no JSON text, and every tool has a title (approved 2026-10-30 by the Product Owner, issue #303) ​

The owner saw raw JSON with Approve and Decline in Claude Desktop (issue #303) and asked for the card to read as a document. Two things can put JSON in front of the owner: the JSON text block every preview reply carried beside its summary, which a host may show beside or instead of the card; and Claude Desktop's own permission dialog, which shows a tool's name and arguments before it runs. This scenario removes the first and names the tool in plain words for the second.

Given a preview tool whose reply is shown in an approval card (bank_entries_preview, vat_corrections_preview, attachments_preview, bank_statement_mapping_preview) When Claude calls it Then the reply's content is exactly one text block, the summary built by code, whatever MCP_REPLY_JSON_TEXT says And structuredContent carries the full data, and the one-time token is only in _meta And every other reply is as S8 says And every tool carries a title in plain words (under 60 characters, no governance reference), which a host shows in place of the tool's name, for example "Preview bank entries for approval" And the card renders the summary as a document: its first heading as the title, the preview ID and expiry as a quiet line, money right-aligned with a bold Total row, and "Check before saying yes" and "Left out" in a highlighted block, with Approve in the confirm colour and Decline plain (DESIGN.md rules 1, 2 and 7)

S10: The owner's decisions come as questions to tap (issue #419) ​

In the owner session of 15 Nov 2026, decisions put as a numbered list in a long reply went unanswered; the same decisions asked as multiple-choice questions were answered, eleven in about three minutes, from a phone.

Given a reply from bank_outstanding, receipts_reconcile, receipts_received or bank_account_add that leaves a choice to the owner (how to code a payee's payments missing from Xero, which payment a receipt is for, how to code a payment a receipt needs entered first, who paid a receipt on a card that is not the company's, or which Xero bank account the statements are for) When Claude reads it Then its JSON carries a decisions list, one entry per choice, built by code And each entry has a header of at most 12 characters; a question that stands on its own, naming the amount, date and payee where there are any; 2 to 4 options, each a short label with a one-line consequence; and freeText: true And no question, label or consequence carries an ID (file, bank line, record or account ID) or a tool name; file names, which come from emails, are left out too And a recommended option is given only where code can justify it, with why saying what justifies it (for a payee's coding: the earlier records coded the same way, and never when that tax type would block the VAT return); where it is given, that option comes first And the server instructions tell Claude to put the decisions to the owner with the client's multiple-choice question tool where it has one, at most four a round with the most blocking first, the recommended option first and marked, and as a short numbered list otherwise And they say the owner may answer in their own words ("check the other company first"), which Claude follows rather than forcing it into an option And they say an answer is never approval to write: it only shapes the next preview, and Approve in the card (or on the approval page) stays the only way anything is written And payees' coding decisions come largest sum first, and a header with nothing left once cleaned falls back to a plain word ("Payee", "Receipt") And a reply with no choice for the owner carries no decisions

MCP elicitation (the server asking the client for an answer mid-call) was looked at on 2026-11-17 and not built: the tool call would have to wait on the owner inside the request, the hosted connector runs without sessions (stateless HTTP), and not every client the owner uses declares the capability. The decisions list works in every client; elicitation can be added later for the stdio server without changing it.

Exit test ​

On real FEAW data, the Product Owner reconnects the connector in Claude Desktop, reconciles a Starling month and an Amex month through the reconcile-account prompt, approves one card, and asks Claude what became of it. Every step works as before, and the per-turn token count and the check's reply size are lower than on 2026-10-07.

S9: after a deploy and a restart of the desktop app, the Product Owner approves one real preview in Claude Desktop and confirms the card reads well and no raw JSON is shown beside it.

S10: the Product Owner runs bank_outstanding and receipts_reconcile on a real month in Claude Desktop, and confirms the choices come as questions to tap, with amounts, dates and payees, and that answering one writes nothing until a card is approved.