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., "@yardstick-mcp Break down my spending by category for the last three months."
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.
Talk to your Yardstick money in plain language. This is an MCP server that lets an AI assistant like Claude read your Yardstick data, so instead of tapping through the app you can just ask: "how much did I spend on eating out last month?", "what's my net worth?", "which subscriptions am I still paying for?"
It runs on your own machine and, out of the box, it can only read: your data goes to your assistant and nowhere else, and nothing can be changed. If you want it to add things for you as well, there's an opt-in switch for that. More on all of this in How your data is handled below, because with a tool that can see your finances you should expect a straight answer before you install anything.
Once it's connected, your assistant can answer things like:
"What's my net worth, and how has it changed over the last year?"
"Break down my spending by category for the last three months."
"How much do I spend at Tesco in a typical month? Is that a lot compared to similar people?"
"List my accounts and their balances."
"Find every transaction over £200 since June."
"How many months of outgoings could I cover from my current balances?"
It can read your accounts, transactions, holdings (assets and liabilities), net worth and your monthly financial vitals. It can never move money or make a payment. By default it can't change anything at all, so there's nothing it can do that you'd need to undo.
Related MCP server: Lunch Flow MCP Server
You'll need:
Node.js 20 or newer. Check with node --version; if you haven't got it, nodejs.org has installers.
A Yardstick account.
npx -y yardstick-mcp loginYour browser opens on Yardstick's normal sign-in page. Approve it, and you'll see a "you can close this tab" message. That's it, you're signed in. Your session is saved under ~/.config/yardstick-mcp/ (readable only by you) and refreshes itself from then on, so this is a one-time step. To sign out again, run yardstick-mcp logout.
Pick the one you use.
Claude Desktop. Open your config file (Settings → Developer → Edit Config, or ~/Library/Application Support/Claude/claude_desktop_config.json on a Mac) and add:
{
"mcpServers": {
"yardstick": {
"command": "npx",
"args": ["-y", "yardstick-mcp"]
}
}
}Restart Claude Desktop. You'll see the Yardstick tools appear, and you can start asking questions.
Claude Code. One command:
claude mcp add yardstick -- npx -y yardstick-mcpAny other MCP client. Anything that speaks MCP over stdio works the same way: run yardstick-mcp as the command with no arguments. Check your client's docs for where its server config lives.
Not on npm yet? Until the package is published, run it from a checkout instead: clone the repo,
pnpm install && pnpm build, then usenode /path/to/yardstick-mcp/dist/cli.jswherever the instructions above saynpx -y yardstick-mcp.
Try "what's my net worth?" to check it's working. If the assistant says it isn't signed in, run the login step again; sessions last until you log out or revoke them, but this is the first thing to retry.
By default the tool talks to production, your real Yardstick account, and if that's you, you can skip this section. For the Yardstick team and testers it can point at staging, uat or local (a dev stack on localhost:8080) instead: add --env <name> to the command, or set env=<name> in the server's environment (handy where env vars are easier to pass than arguments, e.g. claude mcp add yardstick -e env=local -- npx -y yardstick-mcp). The shorthands prod, stage, dev and development also work.
Each environment is its own world with its own sign-in and its own stored session. Sessions are kept side by side, so you can be signed in to several at once and configure them as separate servers:
{
"mcpServers": {
"yardstick": {
"command": "npx",
"args": ["-y", "yardstick-mcp"]
},
"yardstick-uat": {
"command": "npx",
"args": ["-y", "yardstick-mcp", "--env", "uat"]
}
}
}Or in Claude Code:
claude mcp add yardstick-uat -- npx -y yardstick-mcp --env uatSign in to the matching environment first:
npx -y yardstick-mcp login --env uatSign-in works out of the box on all four; each environment's client id is built in (uat and local share one, since they share a sign-in instance).
When it's connected to anything other than production, the server tells the assistant it's looking at test data, so staging numbers don't get presented as your real finances.
Your assistant picks these automatically; you don't need to name them. For reference:
Tool | What it gives you |
| Assets, liabilities and net worth, broken down by group, class, liquidity and how liabilities are secured |
| Month-end asset totals over time, for charting the trend |
| Your connected accounts with their latest balances |
| Everything on your balance sheet: property, pensions, investments, savings, mortgages, loans |
| One holding in full, with its valuation history and (for a liability) its terms and payments |
| Your transactions, filtered by date, amount, merchant, category or free text |
| Totals grouped by merchant, category, type or period, worked out on the server |
| How much of your history is categorised (so you know how complete an answer will be) |
| Where you spend most, by number of visits and total spend |
| Your spending at one merchant, with an anonymous benchmark of what similar people spend |
| Income and spending by category, month by month |
| Monthly surplus, steady outgoings, wealth added and how many months your savings would cover |
| Search the category list to find the right ones to filter by |
A couple of conventions, in case you're reading the raw output: money comes back both as an exact whole-number amount in minor units (pence) and as a ready-formatted string like £1,234.56, and spending amounts are always positive with the direction shown separately, so "money out" doesn't come through as a negative number.
There's an optional set of tools for putting things into Yardstick: adding a holding (a property, a pension, a loan) and recording what it's worth. Handy for "add my flat, worth about £250k, I own half of it" rather than filling in a form.
They're off unless you ask for them, because most people install this to ask questions and shouldn't have an assistant able to edit their records by accident. Turn them on with --allow-writes:
claude mcp add yardstick -- npx -y yardstick-mcp --allow-writesor YARDSTICK_ALLOW_WRITES=true in the server's environment. That adds four tools: list_economic_units and get_asset_taxonomy (both read-only, they work out where a holding belongs and which classifications are valid), plus create_holding and add_valuation.
Worth knowing before you switch it on. There's no undo through this tool, so removing something means going into the app. There's also no duplicate protection: creating the same holding twice gives you two of them, so if you're not sure whether something worked, ask the assistant to list your holdings rather than try again. Your assistant should confirm the details with you before each write, and the tools are marked so your client can prompt you for approval; keep those prompts switched on. Still nothing here can move money or make a payment: the strongest thing it can do is add a record to your balance sheet.
Fair question to ask of anything that can see your bank data. The short version:
It runs on your machine. There's no yardstick-mcp server in the middle. The tool talks straight to the Yardstick API, as you, and hands the results to your assistant.
It's read-only by default. Nothing can be changed unless you opt in to writes, and even then the most it can do is add a holding or record a valuation. It can never spend or move money, and it has no way to delete anything.
You only ever see your own data. The tool signs in as you and sends no account identifier of its own; the Yardstick API decides what you can see from your sign-in alone, exactly as the app does. You can't point it at someone else's account, and it can't accidentally return one either. (This was checked with an independent security review before release.)
No telemetry. The tool phones nothing home. It makes no network calls except to Yardstick and to Yardstick's sign-in provider.
Your session stays local. Sign-in tokens are stored under ~/.config/yardstick-mcp/, in files only your user account can read.
The one judgement that's yours: your assistant sees whatever data it fetches. Connect an assistant you're happy having read your finances, the same way you'd think twice before pasting a bank statement into any app.
Most people never need to set any of these; they're here for other environments and advanced setups.
Variable | What it does | Default |
| OAuth client id for sign-in | built in per environment |
| Expose the tools that add holdings and valuations; same as |
|
| Which Yardstick to use: |
|
| Point at a specific API base URL | set by |
| Point sign-in at a specific domain | set by |
| The API version the tool targets |
|
| Only if your OAuth client is a confidential one | none |
| OAuth scopes to request |
|
| Local port the sign-in redirect comes back on |
|
| Use this bearer token as-is and skip sign-in | none |
| A command that prints a bearer token, run when one's needed | none |
| Which OAuth token to send: |
|
| Where the session is stored |
|
| HTTP mode only: this server's public URL | request Host |
"Not signed in to Yardstick." Run the login step. If you've moved machines or logged out, you'll need to sign in again there.
The browser didn't open during sign-in. The command also prints the sign-in URL; paste it into a browser yourself.
"Could not listen on 127.0.0.1:33418." Something's using that port. Set YARDSTICK_OAUTH_REDIRECT_PORT to a free one, but note the port has to be registered on the OAuth client, so if you're not the one who set that up, ask whoever did.
The assistant can't see the tools. Make sure you restarted it after editing the config, and that node --version is 20 or higher. In Claude Desktop, Settings → Developer shows whether the server started and any error it hit.
A tool says the session expired. Sign in again with yardstick-mcp login. Sessions refresh on their own, so if this keeps happening, your session may have been revoked on Yardstick's side.
There's also an HTTP mode, for building a hosted connector rather than running per-person on a laptop:
yardstick-mcp serve --http --port 3555It serves MCP over Streamable HTTP at /mcp, and every request has to carry its own bearer token, which is passed straight through to the Yardstick API; the process keeps no credentials of its own. It's experimental: run it behind TLS, and set YARDSTICK_PUBLIC_URL to its real address. docs/AUTH.md has the detail.
pnpm install
pnpm build
pnpm testThe tests run the whole server against a fake Yardstick API, so they need no account and no network. docs/AUTH.md covers how sign-in works and how to set up an OAuth client for testing against staging.
Group and total transactions server-side: by merchant, category, code and/or one of day/month/year. Returns per-group counts, totalAmountMinor (magnitude of all items) and netAmountMinor (credits minus debits, signed). Minor units; with no period filter the last 3 months are used. The go-to tool for questions like "top categories by spend this quarter" or "monthly spend at Tesco".
| Name | Required | Description | Default |
|---|---|---|---|
| to | No | End of period, exclusive. RFC3339 or "YYYY-MM-DD". | |
| from | No | Start of period, inclusive. RFC3339 or "YYYY-MM-DD". | |
| page | No | ||
| size | No | Page size, default 50, max 200. | |
| type | No | DEBIT = money out, CREDIT = money in. | |
| codes | No | Transaction codes, e.g. DIRECT_DEBIT, TRANSFER, PURCHASE. | |
| query | No | Free-text search across merchant name and description. | |
| sortBy | No | Default: totalAmount. | |
| groupBy | Yes | Grouping keys; at most one of day/month/year. | |
| minItems | No | Only return groups with at least this many transactions. | |
| merchantId | No | ||
| monthStart | No | A single calendar month "YYYY-MM"; alternative to from/to. | |
| categoryIds | No | Only items the user has categorised with these category ids. | |
| hasCategory | No | true = only user-categorised items; false = only items without one. | |
| merchantName | No | Exact merchant name (case-insensitive). | |
| sortDirection | No | Default: desc. | |
| maxAmountMinor | No | ||
| minAmountMinor | No | Minimum amount in minor units (inclusive). Amounts are unsigned. | |
| linkedToHoldingId | No | Only items linked to this holding. | |
| effectiveCategoryIds | No | Only items whose effective category (user-set, else auto-suggested) is one of these ids. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint annotation, the description discloses highly useful behavioral details: it operates server-side, returns per-group counts, distinguishes totalAmountMinor (magnitude) from netAmountMinor (signed credits minus debits), uses minor units, and defaults to the last 3 months if no period filter is provided. This significantly aids the agent in interpreting results and making assumptions.
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?
The description is compact and front-loaded, with the core purpose in the first sentence. Every sentence adds information: operation, grouping, return values, unit convention, default period, and usage examples. No filler or redundancy.
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?
Despite having no output schema, the description covers the key return fields (counts, totalAmountMinor, netAmountMinor), the default period, and gives real-world usage examples. With 20 parameters, the description cannot enumerate all filters, but the schema already does so. The description provides sufficient context for an agent to confidently use the tool without surprises.
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 high (85%), so the baseline is 3. The description adds value by clarifying the groupBy semantics (enumerating keys and the constraint 'at most one of day/month/year') and explaining the meaning of totalAmountMinor vs netAmountMinor, which helps the agent understand output-related parameters like sortBy. It does not duplicate the schema's parameter descriptions.
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 clearly states the tool's function: 'Group and total transactions server-side' with specific grouping keys (merchant, category, code, day/month/year). It distinguishes itself from sibling tools by positioning as 'the go-to tool' for spend aggregation questions like 'top categories by spend this quarter' or 'monthly spend at Tesco', which separates it from search_transactions and other stats 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 description provides clear context for when to use this tool (aggregation/spend analysis questions) and gives concrete example queries. However, it stops short of explicitly naming alternatives or stating when NOT to use it, so it doesn't fully meet the 5-level standard seen in the get_calls example.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
How much of the user's transaction history is categorised: counts and minor-unit totals for user-categorised, auto-categorised (suggestion pending) and uncategorised items, split by direction. Useful for judging how complete category-based analysis will be.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already covers the read-only nature. The description adds meaningful behavioral detail by explaining the output dimensions (counts and minor-unit totals split by direction) and the three categorisation states. No contradictions detected.
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?
The description is a single, well-structured sentence that front-loads the core purpose and includes a practical use case. No wasted words or redundant content.
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 no-parameter, read-only tool with no output schema, the description is complete: it explains what is returned (counts and totals by categorisation type and direction) and why it is useful. Nothing essential 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?
The tool has zero parameters, so the schema coverage is vacuously 100%. The description doesn't need to explain parameter semantics, and the baseline of 4 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?
The description clearly states the tool's purpose: to provide categorisation coverage stats (counts and minor-unit totals) for user-categorised, auto-categorised, and uncategorised transactions, split by direction. This is distinct from sibling tools like get_spending_breakdown or list_categories, making the purpose unambiguous.
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 provides a clear use case: 'Useful for judging how complete category-based analysis will be.' It does not explicitly mention when to avoid this tool or point to alternatives, but the use case is specific enough to guide an agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
One holding in full: its valuation history, and for liabilities the terms (rate, term, secured-on links) and recorded payments.
| Name | Required | Description | Default |
|---|---|---|---|
| holdingId | Yes | Holding id from list_holdings. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already ensures the agent knows this is a safe read operation. The description goes beyond annotations by specifying what content will be returned: valuation history, and for liabilities the rate, term, secured-on links, and recorded payments. This gives valuable context about the tool's output behavior, which is particularly useful given there is no output schema.
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?
The description is a single, tightly packed sentence that front-loads the core concept ('One holding in full') before detailing what is included. Every part of the sentence earns its place, with no filler or redundancy. It is appropriately sized for the tool's simplicity.
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?
Given the tool has one parameter, no output schema, and a readOnly annotation, the description is fully sufficient. It tells the agent exactly what will be returned (valuation history; for liabilities, terms and payments), covers the main distinctions, and is complete for the tool's purpose. There is no missing critical context for selecting or invoking this tool.
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 input schema already provides full coverage with a clear description for holdingId ('Holding id from list_holdings.'), so the baseline is 3. The tool description does not add any additional parameter semantics or usage notes beyond what the schema already states. It correctly points to list_holdings as the source of the ID, but this is already in the schema.
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 clearly states this tool returns the full detail of a single holding, including valuation history and for liabilities the terms and recorded payments. It distinguishes itself from sibling tools like list_holdings, which would provide an overview rather than full detail. The phrase 'One holding in full' immediately conveys the scope and purpose.
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 use this tool when you need complete details of a specific holding, as opposed to list_holdings which likely provides a summary. It doesn't explicitly name alternatives or exclusions, but the context is clear that this is for single-holding deep-dive, not list-level operations. This is stronger than mere implication but falls short of explicit when/when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Spending profile for one merchant over a window (1m, 3m, 6m, 1y or all): visits, totals, averages, first/last visit, and an anonymous cohort benchmark of what similar users spend there (null when unavailable). Get merchantId from search_transactions or get_top_merchants.
| Name | Required | Description | Default |
|---|---|---|---|
| window | No | Default: 3m. | |
| merchantId | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the safety profile is known. The description adds useful behavioral context about the anonymous cohort benchmark being null when unavailable and the window options, but does not disclose other behaviors such as rate limits or authentication requirements, which are not covered by annotations.
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 concise sentences that front-load the tool's purpose and output contents, followed by a practical source for the required parameter. No redundant or wasted language.
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 simple read-only tool with no output schema, the description thoroughly covers purpose, inputs, outputs (visits, totals, averages, first/last, benchmark), the null case, and how to obtain the required ID. It also mentions window options. This is sufficient for an agent to invoke it 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?
Schema coverage is only 50% (merchantId lacks description). The description compensates by telling users exactly where to find merchantId ('Get merchantId from search_transactions or get_top_merchants'), and it restates the window options. It does not add the default window value, but that is already in the schema.
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 uses a specific verb-phrase 'Spending profile for one merchant over a window' and enumerates concrete outputs (visits, totals, averages, first/last visit, benchmark), clearly distinguishing it from sibling tools that cover multiple merchants or general spending breakdowns.
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 provides clear context that this tool is for a single merchant's spending profile and implies prerequisites by directing users to obtain merchantId from search_transactions or get_top_merchants. However, it does not explicitly contrast with alternative tools like get_spending_breakdown or aggregate_transactions, so it stops short of full when/when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The user's current net worth: total assets, total liabilities and accessible (liquid) assets, with breakdowns by asset group, asset class, liquidity, liability type and liability security. Values are integer minor units (fields ending Minor) with pre-formatted display strings alongside.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Even though readOnlyHint=true already signals a safe read, the description adds meaningful detail by explaining that values are in integer minor units with pre-formatted display strings alongside, plus the breakdown categories. This goes beyond the annotation and gives the agent useful knowledge about output formatting without contradicting the read-only nature.
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?
The description is two sentences, front-loaded with the main purpose and followed by concise details on breakdowns and value formatting. Every word earns its place, with no redundancy or 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?
Despite lacking an output schema, the description provides sufficient detail about what is returned (totals, liquid assets, breakdowns) and how values are represented. It doesn't explicitly describe the top-level structure (e.g., object vs. list), but for a zero-parameter read-only tool, the description covers the essential context.
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?
With zero parameters and 100% schema coverage (no properties), the description doesn't need to explain parameters. The baseline of 4 is appropriate because the description focuses on the return payload instead, making the tool's behavior clear without needing parameter explanations.
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 clearly states the tool reports the user's current net worth, specifying the exact components (total assets, total liabilities, liquid assets) and breakdown dimensions. It distinguishes itself from sibling tools like get_net_worth_history by emphasizing 'current' net worth, making the scope unmistakable.
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 context makes it obvious this is for a current snapshot of net worth, and the straightforward scope implies it should be used when current values are needed rather than historical trends. No explicit exclusions or alternative tool mentions are given, but the purpose is clear enough to guide selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Month-end asset totals over time (with a by-group breakdown per month), for charting how wealth has changed. Note: history covers assets only; liabilities are not included. Defaults to the last 12 months.
| Name | Required | Description | Default |
|---|---|---|---|
| months | No | Calendar months as "YYYY-MM". Defaults to the last 12 months. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With readOnlyHint already provided, the description adds meaningful context: the asset-only scope, the by-group breakdown, and the default period. These details go beyond the annotation and help set expectations about what data is returned and its limitations.
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?
Three tightly packed sentences convey purpose, scope, and default behavior without redundancy. The most important information is front-loaded, and every sentence contributes to understanding.
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 tool with no output schema, the description covers the return type (monthly period totals with by-group breakdown), the asset-only limitation, and the default range. This is sufficient for an agent to invoke it 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?
The single parameter 'months' is fully documented in the input schema, including format and default behavior. The tool description adds no additional parameter-level insight, so the schema carries the weight, yielding the baseline score.
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 clearly states the tool returns month-end asset totals over time with a by-group breakdown, explicitly distinguishing it from a current net worth snapshot. The verb 'get' plus the resource 'net worth history' and the asset-only caveat make the purpose unambiguous.
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 provides contextual guidance: 'for charting how wealth has changed' and notes the default 12-month window. It cautions that liabilities are excluded, which helps the agent decide when this tool is inappropriate, though it does not explicitly name alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Per-month income and spending totals broken down by category (minor units, with category labels resolved). Only user-confirmed categories are bucketed; everything else is in uncategorised. Views: mine = the user alone, shared = joint finances, partner = partner's share, all = whole household; household views are null for users without a household.
| Name | Required | Description | Default |
|---|---|---|---|
| months | No | Calendar months as "YYYY-MM". Defaults to the last 3 months. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the read-only nature is known. The description adds useful context about minor units, category label resolution, confirmed-category bucketing with an 'uncategorised' fallback, and null household views. However, it describes 'views' without a corresponding parameter in the schema, which is confusing and potentially misleading about how to select a view.
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?
The description is relatively short, but the 'Views:' portion is long and lists definitions for four views without explaining how they are selected or returned. It could be more concise and better aligned with the actual schema.
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 tool with no output schema, the description explains some return details (per-month, minor units, category labels, uncategorised) but leaves the view structure unexplained. It is unclear whether the tool returns all views or requires a view selection that is not present in the input schema, which is a significant gap for an agent comparing this tool to siblings.
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 fully describes the only parameter 'months' with format and default. Description coverage is 100%, so the description adds no additional parameter meaning beyond what the schema already provides, resulting in the baseline score.
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 clearly states the tool returns per-month income and spending totals broken down by category, with units and label resolution. However, it does not explicitly distinguish this from sibling tools like get_categorisation_stats or aggregate_transactions, and the 'views' detail introduces some ambiguity about the tool's scope.
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 usage for monthly income/spending breakdown by category but provides no explicit guidance on when to use this tool versus alternatives, nor any exclusions or when-not-to-use conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The user's most visited merchants by spend (DEBIT items), with visit counts and category. valueMinor is total spend in minor units over the window.
| Name | Required | Description | Default |
|---|---|---|---|
| month | No | Calendar month "YYYY-MM". Defaults to the last 3 months. | |
| minVisits | No | Only merchants with at least this many visits. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite readOnlyHint=true annotation, the description adds meaningful context: it restricts to DEBIT items, defines valueMinor as total spend in minor units, and hints at a time window. These details go beyond what the annotation alone gives, without contradicting it.
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?
The description is concise, using two sentences with zero waste. It front-loads the main purpose and then clarifies the spend unit, making it easy to parse quickly.
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 only two optional parameters, the description covers the core output fields (merchants, spend, visits, category) and relevant details like DEBIT and valueMinor. The only minor gap is the ambiguity of 'window', but overall it is sufficiently complete for selection and invocation.
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 baseline is 3. The description does not add extra meaning about the parameters; it only explains valueMinor, which is a return field, not a parameter. Thus no additional value beyond the schema.
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 clearly states the tool retrieves the user's most visited merchants by spend, specifying DEBIT items, visit counts, and category. This is a specific verb+resource that distinguishes it from sibling tools like get_merchant_summary or get_spending_breakdown.
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 its use case: when you need top merchants by spend. It provides clear context but does not explicitly mention when not to use it or alternatives, which would push it to a 5. Still, there's enough implied guidance for an agent to select it appropriately.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The user's monthly financial vitals (minor units): monthlySurplus (incomings, outgoings and what's left), steadyOutgoings (with rolling average), addingWealth (amount moved into savings/investments) and emergenciesCovered (months of average outgoings the month-end cash balance would cover). Each section has {personal, household} views; household is null without one.
| Name | Required | Description | Default |
|---|---|---|---|
| months | No | Calendar months as "YYYY-MM". Defaults to the last 6 months. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint annotation, the description adds meaningful behavioral details: values are in 'minor units,' each section has personal/household views with household potentially null, and metrics are defined with calculation context (e.g., rolling average, month-end cash balance). It doesn't cover edge cases like missing data, but the added null behavior and view structure are useful context beyond the annotation.
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?
The description is a single, information-dense sentence that efficiently defines every metric and notes the view structure and units. It is front-loaded with the resource name and contains no filler or redundancy, earning its length.
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?
The description thoroughly defines the output metrics and view structure, but it leaves ambiguity about whether the result covers a single month or multiple months (since the 'months' parameter is an array), and what the top-level return shape looks like. With no output schema, the description should clarify this aspect to be 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?
The schema fully describes the only parameter 'months' (format, default), so schema coverage is 100%. The description does not mention this parameter at all, which is acceptable per the baseline rule; it neither adds nor detracts from the schema's explanation of parameter semantics.
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 clearly enumerates the specific metrics (monthlySurplus, steadyOutgoings, addingWealth, emergenciesCovered) that this tool returns, distinguishing it from sibling tools like get_net_worth or get_spending_breakdown. However, it lacks an explicit verb like 'returns' or 'retrieves,' presenting the resource as a noun phrase instead.
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 that this tool is for reviewing monthly financial health by defining the vitals, but it does not provide explicit guidance on when to use it over alternatives, nor does it state any exclusion conditions. Usage context is inferred rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The user's connected bank accounts with their latest balances. Pseudo accounts represent manually tracked money rather than a live bank connection.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already declares the safe read nature. The description adds valuable context about pseudo accounts, which is a behavioral aspect of the returned data (distinguishing manual vs live connections). This goes beyond annotation and informs agent expectations.
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?
The description is a single, efficient sentence that conveys the core purpose and a key nuance. Every word contributes value.
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-parameter, read-only list tool with no output schema, the description is sufficiently complete. It names the resource (accounts), the output (balances), and clarifies an edge case (pseudo accounts).
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 tool takes no parameters, so the baseline is 4. The description doesn't need to explain parameters, and it correctly focuses on output semantics.
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 explicitly states the tool lists connected bank accounts with latest balances, which is a specific verb+resource. It clearly differs from sibling tools like list_holdings or search_transactions, so there's no ambiguity.
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?
Usage is implied: one would use this to get account balances. However, there is no explicit mention of when to use it vs alternatives, nor any exclusion criteria. The pseudo account clarification helps interpret results but not tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find category ids to filter by. The taxonomy has around 180 entries, so pass query to search it rather than pulling the lot: "eating out", "fuel", "childcare", "rent". The search covers each category's label, description and its built-in search terms, so everyday words find the right one. Add type: "DEBIT" for spending or "CREDIT" for income.
Categories are hierarchical (Group > Subgroup > Leaf) and you filter on the leaf ids. A word like "food" spans several branches (eating out, groceries, takeaways), so check the labels and use every id that fits the question. isNetNeutral marks categories left out of spending analysis, such as transfers between the user's own accounts.
| Name | Required | Description | Default |
|---|---|---|---|
| type | No | DEBIT = spending categories, CREDIT = income categories. | |
| query | No | Case-insensitive search across label, description and search terms. Omit only when you genuinely need the whole taxonomy. | |
| includeInactive | No | Also return retired categories. Default false. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With readOnlyHint=true, the description still adds rich behavioral context: taxonomy hierarchy, search coverage (label/description/search terms), and isNetNeutral semantics. No annotation contradiction; it substantially enhances the safety profile already declared.
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?
The description is dense but every sentence serves a purpose. It starts with the main use case, then provides search guidance, examples, hierarchy explanation, and edge cases (isNetNeutral) without redundancy.
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 lookup tool without output schema, the description fully accounts for taxonomy size, search behavior, type filtering, hierarchy, and special flags. It equips the agent to correctly select all relevant leaf IDs for a query.
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%, but the description adds meaningful examples for `query` ('eating out', 'fuel') and clarifies `type` values (DEBIT=spending, CREDIT=income). It goes beyond the schema by explaining hierarchical filtering implications.
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 opens with 'Find category ids to filter by', immediately stating the tool's verb and resource. It clearly differentiates from sibling analytics tools by focusing on category discovery and filtering.
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 instructs to pass `query` for searching rather than pulling all 180 entries, and clarifies how to filter by DEBIT/CREDIT type. It also advises checking multiple leaf IDs for ambiguous terms like 'food' and explains the meaning of isNetNeutral, giving practical when-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
All holdings on the balance sheet: assets (property, pensions, investments, savings, valuables) and liabilities (mortgages, loans, credit cards). ownershipPercent is the user's share; latestValue is the most recent valuation.
| Name | Required | Description | Default |
|---|---|---|---|
| nature | No | Only return assets or only liabilities. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With readOnlyHint=true, the description adds value by explaining the scope ('on the balance sheet') and defining key response fields (ownershipPercent, latestValue). This clarifies what data the user will receive. It does not address pagination or ordering, but the read-only annotation already covers the safety profile.
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?
The description is two sentences, concise and front-loaded with the core purpose. The first sentence lists what is included, the second defines two important fields. Every word adds value with no redundancy or 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?
Given the tool's simplicity (one optional param, no output schema), the description provides enough context: it specifies what holdings are included, the optional filter, and the meaning of two key fields. It does not explicitly state that omitting nature returns both types, but 'All holdings' implies this. The lack of an output schema is mitigated by the field definitions.
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% for the only parameter 'nature', which already explains its purpose and enum values. The description does not add any additional parameter semantics beyond what the schema provides. It does mention asset and liability categories that align with the enum, but this is redundant.
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 clearly states what the tool does: it lists all holdings on the balance sheet, distinguishing assets and liabilities with examples. The verb 'list' is implicit in the name and the description's 'All holdings' makes the purpose unambiguous. It also differentiates from sibling tools like list_accounts (accounts vs holdings) and get_holding (singular vs plural).
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 usage: use this tool to get a full list of holdings, optionally filtered by nature. However, it provides no explicit guidance on when to choose this over alternatives like list_accounts or get_holding, nor does it mention any exclusions. The context of siblings is present but the description itself does not reference them.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search the user's bank transactions with filters and pagination. Amounts are unsigned minor units; type gives direction (DEBIT = money out). Each item carries its effective category (user-confirmed, else auto-suggested) with a resolved label. For totals over many transactions prefer aggregate_transactions.
| Name | Required | Description | Default |
|---|---|---|---|
| to | No | End of period, exclusive. RFC3339 or "YYYY-MM-DD". | |
| from | No | Start of period, inclusive. RFC3339 or "YYYY-MM-DD". | |
| page | No | 1-indexed page, default 1. | |
| size | No | Page size, default 25, max 200. | |
| type | No | DEBIT = money out, CREDIT = money in. | |
| codes | No | Transaction codes, e.g. DIRECT_DEBIT, TRANSFER, PURCHASE. | |
| query | No | Free-text search across merchant name and description. | |
| sortBy | No | Default: date. | |
| merchantId | No | ||
| monthStart | No | A single calendar month "YYYY-MM"; alternative to from/to. | |
| categoryIds | No | Only items the user has categorised with these category ids. | |
| hasCategory | No | true = only user-categorised items; false = only items without one. | |
| merchantName | No | Exact merchant name (case-insensitive). | |
| sortDirection | No | Default: desc. | |
| maxAmountMinor | No | ||
| minAmountMinor | No | Minimum amount in minor units (inclusive). Amounts are unsigned. | |
| linkedToHoldingId | No | Only items linked to this holding. | |
| effectiveCategoryIds | No | Only items whose effective category (user-set, else auto-suggested) is one of these ids. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the safe-read nature is covered. The description adds valuable behavioral context: amounts are unsigned minor units, 'type' gives direction (DEBIT = money out), and each item carries its effective category with resolved label. This goes beyond the annotations without contradicting them.
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?
Three sentences, each earning its place: purpose and core features, key data semantics, and an alternative. No repetition of schema details or fluff, making it highly efficient.
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?
The tool has 18 parameters and no output schema, so the description must carry a fair burden. It covers the searchable resource, pagination, and key semantic quirks (unsigned amounts, effective category). Minor gaps remain (e.g., default sort/filter behaviors are left to the schema), but the description is sufficient for selecting and invoking the tool.
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 high (89%), so the baseline is 3. The description adds meaning by explaining the unsigned minor units convention and the effective category semantics, which map to relevant parameters (minAmountMinor, maxAmountMinor, type, effectiveCategoryIds). This provides a small but useful increment above the schema.
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 opens with 'Search the user's bank transactions with filters and pagination', a specific verb and resource that clearly distinguishes this from sibling tools. It also explicitly names aggregate_transactions as the alternative for totals, reinforcing differentiation.
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 explicitly states when to prefer an alternative: 'For totals over many transactions prefer aggregate_transactions.' This provides a clear when-not-to-use and points to the correct sibling, satisfying the highest bar for usage 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.
v0.2.0aggregate_transactionsget_categorisation_statsget_holdingget_merchant_summaryget_net_worthget_net_worth_historyget_spending_breakdownget_top_merchantsget_vitalslist_accountslist_categorieslist_holdingssearch_transactionsScored across 13 tools
Each tool targets a distinct resource and query type: categorisation stats, net worth, holdings, transactions search vs aggregate, merchant list vs single merchant summary, spending breakdown, vitals, and category lookup. Even closely related tools like get_top_merchants and get_merchant_summary differ clearly by collection vs single entity.
All tool names use a consistent snake_case verb_noun pattern. The verbs are semantically accurate: 'get' for single/computed values, 'list' for collections, 'search' for filtered queries, and 'aggregate' for grouped totals. No mixed conventions or vague names.
With 13 tools, the server is well-scoped for a personal finance analytics domain. Each tool covers a distinct aspect (transactions, holdings, net worth, categories, merchants, vitals) without redundancy or bloat, fitting comfortably in the ideal 3-15 range.
The surface covers the core analytics workflows: transaction search and server-side aggregation, merchant profiling, category discovery, spending breakdowns, net worth with history, holdings detail, and monthly vitals. Minor gaps exist, like no explicit tool for individual transaction details or liability history, but these are not critical for the stated purpose.
Connect AI agents to bank accounts, transactions, balances, and investments.
Ask your AI about bank accounts, spending, debts, holdings, and investment activity.
Read-only bank access for your AI agent. Connects Claude, ChatGPT, Cursor, Gemini, Codex.
Connects AI agents to live, verified financial data from 18,000+ institutions — ready to reason from
