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., "@zenmoney-mcp Show my expenses for the last 7 days"
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.
MCP server for ZenMoney — access your personal finance data from any MCP-compatible AI client (Claude Desktop, Cursor, etc.).
Tool | Description |
| Sync data with ZenMoney (run first) |
| List wallets, cards, and cash accounts |
| List expense/income categories with hierarchy |
| List known merchants/payees |
| List and filter recent transactions |
| Add an expense transaction |
| Add an income transaction |
| Transfer money between accounts (including cross-currency) |
| Change an existing transaction — category, amount, date, payee, comment, account |
| Get auto-suggested category for a payee |
Related MCP server: mcp-server-zenmoney
Node.js >= 18
A ZenMoney account
API token from zerro.app/token
No cloning or building needed — just add to your MCP client config:
Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):
{
"mcpServers": {
"zenmoney": {
"command": "npx",
"args": ["-y", "zenmoney-mcp"],
"env": {
"ZENMONEY_TOKEN": "your_token_here"
}
}
}
}Add to .cursor/mcp.json:
{
"mcpServers": {
"zenmoney": {
"command": "npx",
"args": ["-y", "zenmoney-mcp"],
"env": {
"ZENMONEY_TOKEN": "your_token_here"
}
}
}
}claude mcp add zenmoney -- npx -y zenmoney-mcpReplace your_token_here with your token from zerro.app/token.
If you prefer a one-click install without editing JSON, build a .mcpb bundle and drag it into Claude Desktop → Settings → Extensions:
npm install
npm run pack:mcpb
# → dist/zenmoney-mcp-<version>.mcpbOn install, Claude Desktop will prompt for your ZenMoney token (stored in the OS keychain).
git clone https://github.com/artarasov/zenmoney-mcp.git
cd zenmoney-mcp
npm install
npm run build
cp .env.example .env # add your tokenOnce configured, start a conversation and ask your AI client to:
Sync first — "Sync my ZenMoney data"
Browse — "Show me my accounts", "List my categories"
Query — "Show expenses for the last 7 days", "List transactions from January 1–31", "How much did I spend on groceries?"
Add transactions — "Add a 500 RUB expense for coffee today"
Transfer — "Transfer 1000 USD from Checking to Euro Card, received 920 EUR"
Fix mistakes — "Recategorize yesterday's Amazon expense to Household", "Change the comment on that 500 RUB coffee"
list_transactions prints each transaction's id, and update_transaction takes one id or a list of them — so a whole batch can be recategorized in a single call.
PRs welcome! Feel free to open issues for bugs or feature requests.
Add an expense transaction to ZenMoney. Requires account name/id, amount, and date. Optionally accepts category, payee, and comment.
| Name | Required | Description | Default |
|---|---|---|---|
| date | Yes | Transaction date in YYYY-MM-DD format | |
| payee | No | Payee/merchant name | |
| amount | Yes | Expense amount (positive number) | |
| account | Yes | Account name or UUID to deduct from | |
| comment | No | Transaction comment | |
| category | No | Category name or UUID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It never states whether the expense is persisted immediately or synced via sync_data, whether it requires authentication, how duplicate entries are handled, or what happens on invalid account/category values.
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 tight sentences with the core action and required inputs front-loaded; no filler. It could be marginally tighter by consolidating the two sentences, but it is efficiently sized.
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 six-parameter mutation tool with 100% schema coverage and no output schema, the description covers inputs adequately but omits return behavior (e.g., created transaction id) and side effects. Adequate minimum viable, but incomplete for a write operation with zero annotation coverage.
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 all six parameters are already documented in the schema, including the required set and the positive-amount constraint. The description merely restates required vs optional fields, adding no format or constraint detail 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?
States a specific verb+resource (add an expense transaction) with the target system named, ZenMoney. The word 'expense' inherently separates it from sibling tools add_income and add_transfer, though it never names them 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 description lists required vs optional parameters but gives no when-to-use guidance, no condition distinguishing it from add_income or add_transfer, and no prerequisite steps (e.g., whether list_accounts/list_categories must be called first to obtain valid ids).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add an income transaction to ZenMoney.
| Name | Required | Description | Default |
|---|---|---|---|
| date | Yes | Transaction date in YYYY-MM-DD format | |
| payee | No | Payer name | |
| amount | Yes | Income amount (positive number) | |
| account | Yes | Account name or UUID to credit | |
| comment | No | Transaction comment | |
| category | No | Category name or UUID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It signals a write operation only via 'Add' — no mention of permissions/auth, whether it mutates account balances, duplicate handling, or what is returned.
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 with zero filler. It is efficient, though arguably too terse for a six-parameter mutation tool rather than genuinely well-sized.
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 annotations, no output schema, and six parameters including money movement between accounts, the definition is materially incomplete. It should at least explain the effect on the credited account and any prerequisite lookups.
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 all six parameters (date format, positive amount, account UUID, payee, category, comment) are already documented in the schema. The description adds no parameter meaning beyond that, which is the expected baseline when the schema does the work.
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 resource ('Add an income transaction') and names the target system (ZenMoney). The 'income' qualifier implicitly separates it from add_expense and add_transfer, though it never names those siblings 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?
No guidance on when to use this versus add_expense, add_transfer, or update_transaction, and no prerequisites (e.g., account must exist, use list_accounts first). The agent must infer the routing decision entirely.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Transfer money between two accounts in ZenMoney. For cross-currency transfers, specify both outcome_amount (source) and income_amount (destination). For same-currency transfers, just use outcome_amount (or amount as alias).
| Name | Required | Description | Default |
|---|---|---|---|
| date | Yes | Transaction date in YYYY-MM-DD format | |
| amount | No | Transfer amount (alias for outcome_amount, for same-currency transfers) | |
| comment | No | Transfer comment | |
| to_account | Yes | Destination account name or UUID | |
| from_account | Yes | Source account name or UUID | |
| income_amount | No | Amount credited to destination account (in destination account currency). Required for cross-currency transfers. | |
| outcome_amount | No | Amount debited from source account (in source account currency) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. It does disclose a genuine conditional trait (cross-currency requires both outcome_amount and income_amount, same-currency only outcome_amount/amount), but says nothing about auth requirements, side effects, reversibility, or confirmation for what is clearly a money-mutating operation.
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 tight sentences with the core purpose front-loaded, followed by the currency-handling rule. Every clause carries information and there is 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?
For a 7-parameter mutating tool with no annotations and no output schema, the description covers purpose and amount handling but omits return behavior and the side effects/consequences of the transfer. It is minimally adequate rather than 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 description coverage is 100%, so the schema already documents every parameter, including that amount is an alias and that income_amount is required cross-currency. The description largely restates this, though it does synthesize the two cases into a single decision rule.
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+resource ('Transfer money between two accounts in ZenMoney'), which cleanly separates it from the sibling write tools add_income and add_expense. It never explicitly names those siblings, so differentiation is implicit rather than spelled out.
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 cross-currency vs same-currency split is really a parameter rule, not a when-to-use/alternatives rule. There is no statement of when to prefer this over add_income/add_expense or of any prerequisites, so usage is only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all user accounts (wallets, cards, cash). Sync must be done first.
| Name | Required | Description | Default |
|---|---|---|---|
| include_archived | No | Include archived accounts |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It discloses a critical precondition (sync required) and the scope of accounts (wallets, cards, cash). However, it does not state whether the operation is read-only, what happens if sync hasn't been done, or the return format, leaving notable gaps.
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: the first states the function and scope, the second provides a necessary prerequisite. Every word serves a purpose; 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?
For a simple list tool with one optional boolean and no output schema, the description covers the essential purpose and prerequisite. It lacks details about error behavior when sync hasn't been performed and does not describe the return structure, but overall it is adequate for a low-complexity 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?
There is one parameter (include_archived) with full schema coverage—its description 'Include archived accounts' is self-explanatory. The tool description adds no extra meaning about this parameter, which meets the baseline but does not elevate it.
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 ('List') and resource ('all user accounts'), with clarifying examples (wallets, cards, cash). It clearly distinguishes from sibling tools like list_categories and list_transactions by naming the exact resource type.
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?
Provides clear context by stating 'Sync must be done first', establishing a necessary precondition. It does not explicitly name alternatives or when-not-to-use, but the resource focus inherently differentiates it from other list tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all expense/income categories (tags) with their hierarchy. Sync must be done first.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses the hierarchy structure and the sync prerequisite, which is useful. However, it does not explicitly state read-only behavior or potential outcomes if sync is not performed, leaving some behavioral ambiguity.
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. It is front-loaded with the core purpose ('List all expense/income categories') and includes only essential additional context (hierarchy and sync prerequisite). No wasted words.
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 simplicity of the tool (0 parameters, no output schema), the description adequately covers purpose, scope, and a key prerequisite. It does not describe the return format, but for a straightforward list tool this is a minor omission and the description is otherwise 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 tool has 0 parameters, so the empty schema is fully described (100% coverage). The description adds contextual meaning by specifying what the listing includes (expense/income categories and hierarchy), which exceeds the baseline for parameterless tools.
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 lists all expense/income categories (tags) with hierarchy, distinguishing it from sibling list tools like list_accounts and list_merchants. The verb 'list' and specific resource 'categories' 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?
The description provides clear context by stating 'Sync must be done first,' implying the tool should be used after synchronization. It does not explicitly name alternative tools or when-not-to-use conditions, but the prerequisite offers practical guidance for correct usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List known merchants/payees. Sync must be done first.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description provides a clear read action and a precondition about sync. It doesn't describe any side effects or output details, but for a list tool the action is transparent enough. It could be more explicit about being read-only.
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 wasted words, action is front-loaded. The dependency on sync is stated efficiently.
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 list tool with no annotations, the description covers the purpose and the important sync dependency, making it sufficiently 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 input schema has zero parameters, so the baseline is 4. No parameter details are needed, and the description doesn't add anything about parameters.
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 'List known merchants/payees' with a specific verb and resource. It distinguishes itself from sibling list tools by naming merchants/payees 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?
It specifies a clear precondition: 'Sync must be done first,' implying this tool should be used only after sync_data. However, it doesn't explicitly name alternatives or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List transactions. By default returns the last 30 days; pass start_date/end_date for an arbitrary period (e.g. Jan 1–31). Sync must be done first.
| Name | Required | Description | Default |
|---|---|---|---|
| days | No | Number of days to look back from today (default 30). Ignored if start_date or end_date is provided. | |
| limit | No | Max number of transactions to return (default 50) | |
| account | No | Filter by account name or UUID | |
| category | No | Filter by category name or UUID | |
| end_date | No | End of date range (inclusive), YYYY-MM-DD. If omitted while start_date is set, defaults to today. | |
| start_date | No | Start of date range (inclusive), YYYY-MM-DD. If omitted while end_date is set, defaults to unbounded. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden for behavioral disclosure. It discloses the default date range and the sync prerequisite, which are useful traits, but it does not describe return format, ordering, pagination, or behavior when sync hasn't been performed.
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 verb, and every sentence adds value. No redundant or filler 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?
Given 6 parameters, no annotations, and no output schema, the description covers the most critical context: the sync prerequisite and default time window. However, it omits mention of filters and response format, which the agent must infer from the schema and tool name. This is adequate but not exhaustive.
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 has 100% parameter coverage, so the baseline is 3. The description adds a concrete date-range example (Jan 1–31) and clarifies the default window, providing some additional meaning beyond the schema's descriptions. It does not detail filters or limit, but the schema already covers those.
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 'List transactions', a specific verb+resource, and adds a scope qualifier (default last 30 days) that distinguishes it from sibling list tools like list_accounts and list_categories. The name itself is 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 explicitly states a prerequisite ('Sync must be done first'), giving the agent clear when-to-use context. It also explains how to request a custom date range via start_date/end_date. However, it does not name alternative tools or state when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get ZenMoney's auto-suggestion for category and merchant based on a payee name. Useful for categorizing receipts.
| Name | Required | Description | Default |
|---|---|---|---|
| payee | Yes | The payee/merchant name from the receipt |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must convey behavioral expectations. It states it is a 'Get' operation ('auto-suggestion'), which implies a read-only, non-destructive action. However, it does not disclose the response format (e.g., whether it returns a single suggestion or multiple, confidence scores, or behavior for unknown payees). The description is adequate but leaves gaps in behavioral transparency.
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 exceptionally concise, consisting of two short sentences (18 words). It is front-loaded with the core action ('Get ZenMoney's auto-suggestion') followed by the input and use case. Every word adds value, and there is 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?
The tool is simple: one string parameter, no output schema. The description adequately explains what it does, why it is useful, and identifies the key input. It does not mention error behavior or return format, but given the simplicity, it is mostly complete. The absence of annotations and output schema means the description could offer slightly more, but it still provides sufficient context for a simple read-only suggestion utility.
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% since the only parameter 'payee' is described as 'The payee/merchant name from the receipt.' The tool description adds minimal extra meaning by mentioning 'payee name' and 'receipts,' but this largely repeats the schema. No additional parameter details are provided beyond the schema, so the baseline score of 3 is appropriate.
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: 'Get ZenMoney's auto-suggestion for category and merchant based on a payee name.' The verb 'Get' and the specific resource ('auto-suggestion for category and merchant') make the purpose unambiguous. It also distinguishes from sibling tools like list_categories and create_category by focusing on the suggestion feature rather than direct category management.
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 'Useful for categorizing receipts' provides a clear context for when to use this tool. However, it does not explicitly mention alternatives or cases where this tool should not be used, despite having many sibling tools for category and transaction management. The use case alone gives sufficient guidance for an agent to decide when to invoke it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Sync data with ZenMoney. Run this first before using other tools. Use force_full=true to re-download everything.
| Name | Required | Description | Default |
|---|---|---|---|
| force_full | No | Force a full sync instead of incremental |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden for behavioral disclosure. It reveals that sync is incremental by default with an optional full re-download, and that it is a prerequisite step. However, it does not disclose whether the sync is one-way or two-way, what happens to local changes, or any authentication/rate-limit considerations.
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 just two sentences, front-loaded with 'Sync data with ZenMoney.' Each sentence earns its place: the action, the prerequisite ordering, and the parameter usage. There is no wasted or redundant text.
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 a single optional boolean parameter and no output schema, the description covers the essential points: what it does, when to run it, and how to force a full sync. It lacks detail on directionality or failure behavior, but given the tool's simplicity, it is reasonably 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 description coverage is 100%, so the baseline is 3. The description's phrase 're-download everything' adds a practical effect to the force_full parameter, but it largely restates the schema's 'Force a full sync instead of incremental' without adding significant new semantic depth.
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 the verb 'Sync' with a clear resource 'data with ZenMoney', and the instruction 'Run this first before using other tools' distinguishes it from all sibling CRUD/list tools. It clearly identifies this as a synchronization operation that prepares data for the other 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 phrase 'Run this first before using other tools' provides explicit sequencing guidance, while 'Use force_full=true to re-download everything' gives a specific use case for the parameter. It does not explicitly state when not to use it, but the sibling tools handle post-sync operations, making the intended context clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Change an existing transaction: its category, amount, date, payee, comment or account. Only the fields you pass are touched. Pass a single id or a list of ids to apply the same change to several transactions at once (handy for recategorizing). Ids come from list_transactions. Sync must be done first.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Transaction UUID, or a list of UUIDs to update together | |
| date | No | New transaction date in YYYY-MM-DD format | |
| payee | No | New payee. Pass an empty string to clear it. The linked merchant is re-matched to the new payee. | |
| amount | No | New amount for an expense or income. For transfers use outcome_amount/income_amount instead. | |
| account | No | Move the transaction to another account (name or UUID). Not valid for transfers — use from_account/to_account there. | |
| comment | No | New comment. Pass an empty string to clear it. | |
| category | No | New category name or UUID (or several). Pass an empty string or an empty array to remove the category. | |
| to_account | No | New destination account of a transfer (name or UUID) | |
| from_account | No | New source account of a transfer (name or UUID) | |
| income_amount | No | New amount credited to the destination account | |
| outcome_amount | No | New amount debited from the source account |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does disclose a key mutation semantic: "Only the fields you pass are touched" (partial update), plus bulk-apply behavior and the sync-first prerequisite. It omits permission requirements, reversibility, and error behavior, which are relevant for an 11-parameter mutation.
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, front-loaded with the core action, then partial-update semantics, bulk behavior, id source, and the prerequisite. Every clause earns its place with 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?
Given a rich 11-parameter schema but no annotations and no output schema, the description covers mutation scope, bulk mode, and the sync prerequisite, which is most of what an agent needs. It leaves permissions and failure behavior unstated, a minor gap for a tool this well-specified elsewhere.
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 every parameter including the transfer fields (from_account/to_account/outcome_amount/income_amount) is already documented in the schema. The description's bulk-id explanation largely restates the schema's id description, adding only the "same change to several" framing, 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 verb and resource ("Change an existing transaction") and enumerates the mutable fields, which cleanly separates it from the add_expense/add_income/add_transfer siblings. Referencing list_transactions as the id source further anchors it in the tool graph.
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 concrete usage context: bulk recategorization via a list of ids, the requirement that sync run first, and where ids come from. It does not state when-not-to-use or flag the transfer-specific path (from/to_account) as an alternative mode, so it stops just short of explicit alternatives.
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.4.1add_expenseadd_incomeadd_transferlist_accountslist_categorieslist_merchantslist_transactionssuggest_categorysync_dataupdate_transactionScored across 10 tools
Each tool targets a clearly distinct resource and action: sync_data, the three add_* tools map to distinct transaction types (income/expense/transfer), the four list_* tools target distinct entities, and suggest_category/update_transaction are unique operations. There is no meaningful overlap in purpose.
Every tool follows a consistent snake_case verb_noun pattern (sync_data, add_income, list_accounts, update_transaction). The convention is applied uniformly with no camelCase or stylistic deviations.
Ten tools is well-scoped for a personal-finance integration, covering sync, listing of the main entities, and transaction creation/updating without redundancy. Each tool earns its place.
The set covers sync, reading (accounts, categories, merchants, transactions), creating all transaction types, and updating transactions in batch. The main gap is deleting transactions (and managing accounts/categories/merchants), but core record-keeping and recategorization workflows are covered.
Personal finance for AI agents: accounts, budgets, goals, 9-strategy debt payoff, reports. OAuth 2.1
Read Yomio expense, income, account, budget, and spending data in an MCP-compatible AI client.
Ask your AI about your own accounts, debts, budgets and goals. OAuth sign-in, read-only by default.
Personal finance for AI agents: budgets, receipts, net worth, spend checks. Read-only OAuth.