MCP 服务器，将 Claude（桌面版、Code 或任何 MCP 客户端）连接到 Monarch Money，用于个人财务分析和轻量级编辑。
封装了非官方的 monarchmoney Python 客户端。
组 | 工具 |
交易 |
|
标签 |
|
分类 |
|
账户 |
|
净资产 |
|
现金流 |
|
预算/目标 |
|
由于上游库未实现，以下功能未公开：
标签：不支持重命名、删除。
分类：不支持重命名（支持删除）。
目标：只读（随 get_budgets 一起返回）；不支持创建/更新/删除。
Related MCP server: monarch-mcp2
需要 Python 3.10+ 以及 keyring 包可以调用的操作系统密钥环（macOS Keychain、Windows 凭据管理器、Linux 上通过 D-Bus 的 GNOME Keyring / KWallet）。
pipx 将包安装到其自己的 venv 中，并将 monarch-mcp / monarch-mcp-setup 入口点放入您的 $PATH：
pipx install .python3 -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install .如果采用此路径，Claude Desktop 将需要 venv 中 monarch-mcp 二进制文件的绝对路径（见下文）。
在无头 Linux 机器（或没有桌面会话的 WSL2）上，keyring 默认找不到后端。请执行以下任一操作：
安装 gnome-keyring 并运行 dbus-launch 以便可以访问守护进程，或者
安装 keyrings.alt (pip install keyrings.alt) 并接受密钥以明文形式存储在 ~/.local/share/python_keyring/ 下 —— 这对于个人开发机器没问题，但不适用于共享机器。
运行一次以将您的 Monarch 电子邮件、密码和（可选但推荐）MFA TOTP 密钥存储在操作系统密钥环中。这三者都位于服务名称 monarch-mcp 下。
monarch-mcp-setup set # interactive prompts (password + MFA are hidden input)
monarch-mcp-setup show # report which fields are stored (values not echoed)
monarch-mcp-setup clear # wipe all three fields不带子命令的 monarch-mcp-setup 默认为 set。
当您在 Monarch 中启用 MFA 时，设置屏幕会显示一个二维码和一个 base32 字符串（通常标记为“密钥”或“手动输入代码”）。该 base32 字符串正是 monarch-mcp-setup 所要求的 —— 而不是 6 位数的代码。
存储它允许服务器自行计算 TOTP 代码，并在会话 pickle 过期后在无人值守的情况下重新进行身份验证。如果没有它，每次会话过期都会迫使您通过清除凭据并使用新代码再次运行 set 来手动重新登录。
如果您在首次注册时没有保存该密钥，可以在 Monarch 的设置中重新注册您的身份验证器以再次查看它。
在首次成功登录后，服务器会缓存一个会话 pickle，以便后续进程启动时跳过登录往返：
默认：~/.config/monarch-mcp/session.pickle
覆盖：将 MONARCH_MCP_SESSION_DIR 环境变量设置为您选择的目录
如果 pickle 被损坏或被 Monarch 拒绝，服务器会静默回退到使用存储的凭据进行全新登录 —— 您无需手动清除它。
编辑 claude_desktop_config.json：
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json
在 mcpServers 下添加一个条目：
{
"mcpServers": {
"monarch": {
"command": "monarch-mcp"
}
}
}如果 monarch-mcp 不在 Claude Desktop 可见的 $PATH 中（在使用 venv 而非 pipx 时很常见），请提供绝对路径：
{
"mcpServers": {
"monarch": {
"command": "/Users/you/code/monarch-mcp/.venv/bin/monarch-mcp"
}
}
}要将会话 pickle 存放在非默认位置：
{
"mcpServers": {
"monarch": {
"command": "monarch-mcp",
"env": { "MONARCH_MCP_SESSION_DIR": "/Users/you/.local/share/monarch-mcp" }
}
}
}重启 Claude Desktop。工具应出现在 MCP 选择器中。
claude mcp add monarch monarch-mcp所有日期参数均为 ISO YYYY-MM-DD 字符串。
ID（分类、标签、账户）是不透明字符串 —— 在调用过滤后的端点之前，请通过相应的 list_* 工具发现它们。
set_budget 需要 category_id 或 category_group_id 中的恰好一个。
list_transactions 支持分页：传递 limit 和 offset 以遍历大于默认 100 条的结果。
测试套件是封闭的 —— 当未安装这些包时，它会存根 keyring、monarchmoney 和 mcp.server.fastmcp，因此您可以在没有网络访问或密钥环后端的情况下运行它。
python3 -m venv .venv
source .venv/bin/activate
pip install -e '.[dev]'-e .[dev] 安装可编辑的包以及 pytest 和 pytest-asyncio。
pytest # full suite (~80ms, 43 tests)
pytest tests/test_server.py # one module
pytest -k "set_budget" # one keyword
pytest -v # verbose, lists each testPytest 配置位于 pyproject.toml 的 [tool.pytest.ini_options] 下：
pythonpath = ["src"] —— 允许 from monarch_mcp import ... 在没有可编辑安装的情况下解析（在不运行 pip install 的 CI 容器中很方便）。
asyncio_mode = "auto" —— 异步测试函数不需要 @pytest.mark.asyncio 装饰器。
testpaths = ["tests"] —— 直接运行 pytest 即可找到套件。
src/monarch_mcp/
auth.py — keychain wrapper (get/set/delete + require_login_credentials)
setup.py — monarch-mcp-setup CLI (set / show / clear)
server.py — FastMCP server, lazy-login client, all tool definitions
tests/
conftest.py — third-party stubs + clean_keyring / fake_mm_client / server_with_fake_client fixtures
test_auth.py
test_setup.py
test_server.py将一个带有 @mcp.tool() 装饰的异步函数添加到 src/monarch_mcp/server.py。文档字符串将成为 Claude 看到的 MCP 工具描述，因此请为 Claude 编写它。
如果它调用了新的 MonarchMoney 方法，请将方法名称添加到 tests/conftest.py 中的 _FAKE_METHODS，以便 fake_mm_client 对其进行模拟。
使用 server_with_fake_client fixture 在 tests/test_server.py 中添加测试 —— 断言 client.<method>.await_args.kwargs 以确认调用形式。
clean_keyring —— 在每次测试前清除内存中的密钥环存根（安装真实密钥环时为空操作）。
fake_mm_client —— MagicMock，其 Monarch 方法是返回 {"called": <method_name>} 的 AsyncMock。
server_with_fake_client —— 将 server._client monkeypatch 为 fake，因此工具调用完全绕过 _get_client() 和登录流程。执行登录的测试（test_get_client_*）会将 _client 重置为 None 并直接修补 server.MonarchMoney。
Create a new category under the given group.
| Name | Required | Description | Default |
|---|---|---|---|
| group_id | Yes | ||
| name | Yes | ||
| icon | No | ❓ | |
| rollover_enabled | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, and the description fails to disclose any behavioral aspects such as side effects, permissions, idempotency, or error conditions.
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 very short (one sentence) but omits critical information about parameters and behavior, making it under-specified rather than efficiently concise.
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 an output schema, the description does not mention the return value. With 4 parameters and no parameter details, the description is insufficient for an agent to use the tool 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 description coverage is 0%, and the description does not explain any parameters. The input schema defines 4 parameters with defaults, but the description adds no value beyond the parameter names.
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 action (create) and resource (category) with context (under a given group). It is easily distinguishable from sibling tools like create_tag and delete_category.
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 is provided on when to use this tool versus alternatives like list_categories or delete_category. The description lacks any usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new tag. Color is a hex string like '#ff0000'.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| color | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Provides color format example but no annotations; lacks info on error behavior, uniqueness, or return value beyond the output schema existence.
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 are direct and contain no extraneous information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With a simple parameter set and output schema present, the description covers the main purpose and color format; could mention constraints but adequate for basic use.
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?
Adds meaning for the 'color' parameter with a hex string example, but the 'name' parameter is not elaborated beyond schema, and schema coverage is 0%.
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?
Clearly states it creates a new tag, distinguishing it from sibling tools like list_tags and create_category.
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 tool vs alternatives, such as when to create a category instead.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a category by ID.
| Name | Required | Description | Default |
|---|---|---|---|
| category_id | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description should disclose behavioral traits. It only states the action without mentioning side effects, permissions, or reversibility. For a delete operation, this is insufficient.
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 concise sentence with no fluff. However, it could be slightly expanded without losing conciseness to include more context.
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 required parameter, no nested objects), the description is minimally adequate. However, it lacks differentiation from sibling tools and doesn't address potential impacts, making it less 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 has 0% coverage (no descriptions for parameters). The description adds 'by ID' but does not explain the format, constraints, or required format of the category_id parameter. More detail is needed.
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 'Delete a category by ID.' specifies the action (delete), resource (category), and required identifier (ID), clearly distinguishing it from sibling tools like create_category or list_categories.
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 tool versus alternatives, nor any prerequisites or warnings about irreversible effects (e.g., cascading to transactions). A better description would mention potential side effects.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Historical balance snapshots for a single account.
| Name | Required | Description | Default |
|---|---|---|---|
| account_id | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavior. It only states 'Historical balance snapshots' without specifying granularity (daily, monthly?), time range, inclusion of current balance, or read-only nature. The lack of detail hinders agent understanding beyond the basic purpose.
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 clear sentence with no filler. While appropriately concise, it lacks structure (e.g., bullet points) that could improve readability for complex details. However, for a simple tool, brevity is acceptable.
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, an output schema, and no annotations, the description is minimally adequate but lacks context about output format, example usage, or how to obtain account_id. For a tool with many siblings, more completeness would improve agent decision-making.
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 0% description coverage, and the tool description does not explain the account_id parameter (e.g., format, source, constraints). The description only implies a single account but adds no semantics beyond the schema, leaving the agent without guidance on what value to provide.
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 'Historical balance snapshots for a single account,' specifying the verb (get/historical snapshots), resource (account), and scope (single account). This distinguishes it from siblings like list_accounts (which lists accounts) and get_transaction (individual transactions).
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 obtaining historical balance data for a specific account, but it does not explicitly state when to prefer this tool over siblings like get_net_worth_history, get_cash_flow, or get_transactions_summary. No alternative tools or exclusions are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Budget plan vs. actuals for the date range. Includes v2 goals when present.
| Name | Required | Description | Default |
|---|---|---|---|
| start_date | No | ||
| end_date | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
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 mentions inclusion of v2 goals when present, which adds transparency. However, it does not state that the operation is read-only, any required permissions, rate limits, or how it behaves with no data.
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 with no filler. Front-loads the core purpose and includes a valuable additional detail about v2 goals. Efficient and clear.
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 annotations and zero parameter descriptions, the description leaves many gaps. It does not explain budget periods, mandatory inputs, or what the output contains (though an output schema exists). The agent likely needs more context to use this tool reliably.
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 0% description coverage. The description hints at date range parameters but does not specify formats, constraints, or how the date range interacts with budget periods. Minimal added meaning 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 resource (budgets) and purpose (plan vs. actuals for a date range). It adds a specific detail about v2 goals, which helps distinguish from general financial reports. However, it doesn't explicitly differentiate from sibling tools like get_cash_flow_summary or set_budget.
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 tool versus siblings such as get_cash_flow or set_budget. There is no mention of prerequisites, alternatives, or when not to use. The context is implied but not explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Cash flow aggregated by category, group, and merchant for the date range.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| start_date | No | ||
| end_date | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description does not disclose behavioral traits like read-only nature, rate limits, or authentication requirements. The agent cannot infer safety or side effects.
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 sentence with no redundant words. It is front-loaded with the core action and resource.
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 an output schema (so return values are covered), the description lacks context on aggregation behavior, default date ranges, and interaction of dimensions. It is insufficient for an agent to use effectively without additional knowledge.
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 0%, and the description adds minimal meaning to parameters. It mentions 'date range' but does not clarify start_date/end_date format or how 'limit' affects results, leaving significant ambiguity.
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 aggregates cash flow by category, group, and merchant for a date range. It uses a specific verb and resource, and distinguishes from sibling tools like 'get_cash_flow_summary' which likely provides summary-level data.
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 guidelines on when to use this tool versus alternatives such as 'get_cash_flow_summary' or 'get_transactions'. The description does not mention exclusions or preferred contexts.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Top-line cash flow numbers only (income, expense, savings).
| Name | Required | Description | Default |
|---|---|---|---|
| start_date | No | ||
| end_date | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must carry the burden. It discloses return values (income, expense, savings) but does not mention any behavioral traits like aggregation method, date range dependency, or permissions. Adequate for a simple read tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no wasted words. Front-loaded with the core purpose. 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 description omits crucial parameter guidance despite having two optional parameters. With an output schema present, return values are covered, but parameter usage is left to assumption. Incomplete for a tool with optional date range.
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 0% with no parameter descriptions. The description does not mention 'start_date' or 'end_date' at all, leaving agents uninformed about how to use them. Fails to add any meaning beyond the schema itself.
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?
Clearly states it returns top-line cash flow numbers (income, expense, savings). Specific verb and resource, distinguishes from sibling 'get_cash_flow' which likely provides details.
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 'only' implies a limited scope, hinting at when to use this summary vs. a detailed alternative. Does not explicitly name alternatives but context is clear from sibling tool names.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Net worth broken down by account type. Timeframe: 'month' or 'year'.
| Name | Required | Description | Default |
|---|---|---|---|
| start_date | Yes | ||
| timeframe | No | month |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It only states the tool breaks down net worth by type and timeframe, but does not disclose whether it is read-only, what aggregation period is used, or how dates are handled. This is insufficient for safe agent invocation.
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 very concise with two short sentences and no redundancy. However, it is so brief that it sacrifices necessary detail, which slightly reduces the score.
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?
Although an output schema exists, the description leaves gaps in parameter clarity (start_date format) and does not differentiate from siblings. The tool's purpose is clear but the description is not fully complete given the lack of annotations and schema descriptions.
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 0%, so the description must compensate. It adds meaning for timeframe ('month' or 'year'), but start_date is completely unexplained (format, allowed range, etc.). This partial coverage leaves the agent guessing.
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 gets net worth broken down by account type, and mentions the timeframe parameter, distinguishing it from the sibling get_net_worth_history which likely provides a time series. However, it could be more specific about the grouping and return format.
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 no guidance on when to use this tool versus alternatives. It does not explain that it aggregates by account type, which is the key differentiator from get_net_worth_history.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Daily net-worth snapshots aggregated across all accounts.
Optional account_type filters to a single type (e.g. 'brokerage'). Dates are ISO YYYY-MM-DD.
| Name | Required | Description | Default |
|---|---|---|---|
| start_date | No | ||
| end_date | No | ||
| account_type | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries burden. It implies a read operation ('snapshots'), but does not explicitly state it is read-only, non-destructive, or describe any side effects. Lacks details on 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?
Two concise sentences, front-loaded with main purpose. No wasted words. Efficient and clear.
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 an output schema available, the description covers the tool's purpose, optional filter, and date format adequately. No missing essential information for an agent to use 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?
Adds meaning beyond input schema: explains account_type filter is optional and filters to a single type, and specifies date format (ISO YYYY-MM-DD). However, does not elaborate on start/end_date semantics beyond format.
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?
Clearly states it provides daily net-worth snapshots aggregated across all accounts. Distinguishes from sibling tools like get_net_worth_by_type (which likely gives breakdown by 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?
Mentions optional account_type filter and ISO date format, but does not explicitly guide when to use this tool versus alternatives like get_net_worth_by_type, nor does it mention prerequisites or when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return full detail for a single transaction (includes splits, tags, attachments).
| Name | Required | Description | Default |
|---|---|---|---|
| transaction_id | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description carries full burden. It indicates a read operation and lists return contents, but lacks details on permissions, rate limits, or side effects.
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?
Single sentence, front-loaded, and efficient. No unnecessary 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 tool's simplicity (one parameter, output schema exists), the description adequately covers return contents. Lacks mention that the transaction ID must exist, but overall sufficient.
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 0% schema description coverage, the description does not add meaning to the single parameter (transaction_id) beyond what the schema provides. It does not explain how to obtain the ID or format requirements.
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 'Return full detail for a single transaction' and lists included items (splits, tags, attachments). This differentiates it from sibling tools like list_transactions or get_transactions_summary.
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 explicit guidance on when to use this tool versus alternatives. While the purpose implies usage for detail retrieval, missing context about when not to use it or comparisons to siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Aggregate stats (count, sum, average, max) across all transactions.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are absent, so the description carries the full burden. It states the tool computes aggregate stats but does not disclose whether the operation is read-only, whether it uses cached data, or any potential side effects. For a read-only summary, more transparency would be expected.
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 without any wasted words. It is front-loaded and to the point.
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 (no parameters, output schema exists), the description is adequate. It explains what the tool returns. However, it could mention that the aggregation is applied to all transactions without filtering, which is implied but not explicit.
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 no parameters (100% coverage), so the description adds significant value by specifying which statistics are returned (count, sum, average, max). This clarifies what the tool computes beyond the empty 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 that the tool provides aggregate stats (count, sum, average, max) across all transactions. It uses an implicit verb 'Aggregate' and distinguishes itself from siblings like list_transactions by summarizing rather than listing. However, it could be more explicit about the scope (e.g., 'all transactions across the entire dataset').
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 is provided on when to use this tool versus alternatives like list_transactions or get_cash_flow_summary. The description does not mention any prerequisites, limitations, or scenarios where another tool would be more appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all configured accounts with current balances and metadata.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the burden. It indicates a read operation by saying 'list', but does not disclose potential behaviors such as pagination, rate limits, or required permissions. With no parameters and an output schema present, the description is minimally adequate.
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 sentence with no extraneous words. It is front-loaded and immediately conveys the tool's purpose. Every part earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (no parameters, output schema exists), the description is complete enough. It covers the action, resource, and included data. However, it could optionally mention the output format or any default sorting if relevant.
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 no parameters, and schema description coverage is 100%. The description adds value by specifying what is included (balances and metadata), which is not detailed in the schema. For a parameterless tool, this is sufficient.
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 verb 'list' and the resource 'accounts', specifying that it retrieves 'current balances and metadata'. This effectively distinguishes it from sibling tools like list_categories and list_tags, which operate on different resources.
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 retrieving all accounts, but does not provide explicit guidance on when to use this tool versus alternatives like get_account_history or get_budgets. The context suggests it is for a broad listing, but exclusions or specific scenarios are not mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all transaction categories.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description only states 'List all transaction categories' without disclosing any behavioral traits (e.g., read-only, no side effects). It fails to add transparency beyond the obvious.
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 sentence with no extraneous information, achieving maximum conciseness.
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 no parameters and an output schema exists, the description is complete enough for a simple list operation. However, it could briefly mention the nature of the output or any default ordering.
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 and the input schema is empty (100% coverage). The description adds minimal additional meaning, but for zero-parameter tools, a baseline of 4 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 'List all transaction categories' uses a clear verb ('List') and resource ('transaction categories'), distinguishing it from siblings like 'create_category' or 'delete_category'.
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 is provided on when to use this tool versus alternatives such as 'list_accounts' or 'list_tags'. There is no mention of context or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all category groups (the parent groupings for categories).
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description clearly indicates a read-only list operation, with no side effects disclosed. With no annotations, the description carries the burden, but it sufficiently conveys the trivial nature of the tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single, concise sentence that conveys the tool's purpose without redundant or unnecessary content. Efficient and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no parameters, is read-only, and has an output schema, the description provides adequate completeness. Could optionally mention expected output (list of group objects) but not required.
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?
No parameters present; schema coverage is 100% trivially. The description adds no parameter information, which is appropriate given no parameters exist. Baseline score of 4 for zero-parameter 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?
Clearly states it lists category groups and explains they are parent groupings for categories. The verb 'list' and resource 'category groups' are specific and distinct from sibling tool 'list_categories'.
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 explicit guidance on when to use this tool versus alternatives. However, as a simple list tool with no parameters, usage context is implied. Missing when-not-to-use or alternative suggestions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all transaction tags.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the burden. It states 'List all transaction tags' which implies a read-only operation, but it does not disclose any additional behavioral traits such as return format, pagination, or side effects. It is not misleading but minimal.
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 sentence that is concise and front-loaded. Every word is necessary and no extraneous information is included.
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 (no parameters, list all), the description is complete. The output schema exists to define return structure, so no further detail is needed.
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 are no parameters in the input schema, so the description does not need to add parameter information. With 0 parameters, the baseline is 4. The description is sufficient.
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 'List all transaction tags' clearly states the action (List) and the resource (transaction tags). It effectively distinguishes from sibling tools like create_tag, delete_tag, and set_transaction_tags.
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?
While no explicit when-to-use or alternatives are given, the purpose is straightforward and the context of sibling tools makes it clear this is for listing all tags. A slightly higher score would require explicit differentiation, but it's adequate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List transactions with optional filters. Dates are ISO YYYY-MM-DD.
Use list_categories / list_tags / list_accounts to discover the IDs needed for the *_ids filter arguments.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| offset | No | ||
| start_date | No | ||
| end_date | No | ||
| search | No | ||
| category_ids | No | ||
| account_ids | No | ||
| tag_ids | No | ||
| has_attachments | No | ||
| has_notes | No | ||
| hidden_from_reports | No | ||
| is_split | No | ||
| is_recurring | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It implies read-only operation but does not mention pagination, rate limits, or default behaviors beyond limit/offset schema. Dates format is a plus.
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?
Extremely concise: two sentences, front-loaded with purpose and key filter guidance. No unnecessary 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 13 parameters and no schema descriptions, the description covers only essentials. Output schema exists but is not referenced. Could mention default ordering or result structure.
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 0%, so description must compensate. It adds meaning for date format and ID discovery, but leaves limit, offset, search, and boolean parameters unexplained. Param names are fairly self-explanatory.
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 with optional filters', using a specific verb and resource. It distinguishes from siblings like get_transaction (singular) and list_accounts.
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 useful guidance: date format ISO YYYY-MM-DD, and suggests using other list tools to discover IDs for filter arguments. However, it does not explicitly compare with alternatives like get_transaction or get_transactions_summary.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Set a budget amount. Provide exactly one of category_id or category_group_id.
timeframe: 'month' or 'year'. apply_to_future propagates the change forward.
| Name | Required | Description | Default |
|---|---|---|---|
| amount | Yes | ||
| category_id | No | ||
| category_group_id | No | ||
| timeframe | No | month | |
| start_date | No | ||
| apply_to_future | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses that apply_to_future propagates changes forward, which is a key behavioral trait. However, it does not mention whether this overwrites existing budgets, if the operation is idempotent, or any side effects.
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 extremely concise with two sentences plus a line break, all front-loaded. Every word serves a purpose: stating the action, the key constraint, and explaining two parameters.
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 6 parameters, no annotations, and no output schema details, the description covers the core requirement and two parameters well. However, it leaves out start_date explanation and what happens if both or neither category IDs are provided, making it somewhat incomplete.
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 0% schema description coverage, the description adds essential meaning: timeframe values ('month' or 'year'), the mutual exclusivity of category_id and category_group_id, and the propagation behavior of apply_to_future. However, it omits details about start_date and the format of IDs.
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 sets a budget amount, which is a specific verb+resource combination. It further distinguishes by requiring exactly one of category_id or category_group_id, setting it apart from sibling tools like get_budgets.
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 gives clear usage guidelines: provide exactly one of category_id or category_group_id, and explains timeframe and apply_to_future. While it does not explicitly mention when not to use this tool or alternatives, the constraints are clearly stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Replace the set of tags on a transaction with the given tag IDs.
| Name | Required | Description | Default |
|---|---|---|---|
| transaction_id | Yes | ||
| tag_ids | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description says 'Replace', implying destruction of existing tags, which is transparent. However, since no annotations are provided, the description carries full burden and could further clarify that all existing tags are removed and replaced.
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?
Single sentence, 15 words, front-loaded with the verb. Every word earns its place; no fluff.
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 replacement operation with an output schema, the description is mostly complete. However, it omits the effect on existing tags (complete overwrite) and does not link to other tools for obtaining tag IDs.
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 0% schema description coverage, the description adds minimal value. It only restates 'tag IDs' without explaining that these come from list_tags or what format transaction_id expects. The array nature of tag_ids is not elaborated.
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 verb 'Replace' and the resource 'tags on a transaction', making the purpose specific. It distinguishes from sibling tools like create_tag or delete_category, but doesn't explain what tag IDs are or how to obtain them.
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 tool versus alternatives like create_tag or delete_category. No prerequisites or when-not-to-use conditions are mentioned.
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.1.0create_categorycreate_tagdelete_categoryget_account_historyget_budgetsget_cash_flowget_cash_flow_summaryget_net_worth_by_typeget_net_worth_historyget_transactionget_transactions_summarylist_accountslist_categorieslist_category_groupslist_tagslist_transactionsset_budgetset_transaction_tagsScored across 18 tools
Each tool targets a distinct financial entity or operation (e.g., categories, tags, budgets, transactions, cash flow, net worth). No two tools have overlapping functionality; even related tools like get_cash_flow and get_cash_flow_summary are clearly differentiated by detail level.
All tool names follow a consistent verb_noun pattern using snake_case (e.g., create_category, get_budgets, list_transactions). Verbs are uniformly chosen (create, delete, get, list, set) and nouns are plural or singular as appropriate.
18 tools cover the major areas of personal finance management (accounts, transactions, categories, tags, budgets, cash flow, net worth) without being overwhelming. The count is within the optimal 3-15 range, though slightly above, but still well-scoped for the domain.
The tool surface has significant gaps: no update or delete for transactions, no delete for tags, no update for categories or tags. While core reads and some writes exist, essential lifecycle operations (especially delete and update for transactions) are missing, limiting agent workflows.
An MCP server that provides read access to your cloud storage providers, bank accounts and more.
Personal finance for AI agents — onboard, import statements, categorize & budget over MCP.
Hosted MCP server connecting claude.ai, ChatGPT and other AI apps to your own computer
Query your real net worth, spending, transactions, budgets and portfolio from any MCP client.
