Claude（Desktop、Code、または任意のMCPクライアント）をMonarch Moneyに接続し、個人財務の分析や簡易的な編集を行うためのMCPサーバーです。
非公式のmonarchmoney Pythonクライアントをラップしています。
グループ | ツール |
取引 |
|
タグ |
|
カテゴリ |
|
口座 |
|
純資産 |
|
キャッシュフロー |
|
予算 / 目標 |
|
上流ライブラリで実装されていないため、以下の機能は公開されていません：
タグ：名前変更、削除は不可。
カテゴリ：名前変更は不可（削除はサポートされています）。
目標：読み取り専用（get_budgetsと一緒に返されます）。作成/更新/削除は不可。
Related MCP server: monarch-mcp2
Python 3.10以上と、keyringパッケージが通信可能なOSキーチェーン（macOS Keychain、Windows Credential Manager、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シークレットをOSキーチェーンに保存します。これら3つはすべてサービス名 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を有効にすると、設定画面にQRコードとbase32文字列（「シークレットキー」や「手動入力コード」とラベル付けされていることが多い）が表示されます。monarch-mcp-setup が求めているのはそのbase32文字列であり、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 にない場合（pipxではなくvenvを使用した場合によくあります）、絶対パスを指定してください：
{
"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 はページネーションを行います。デフォルトの100件を超える結果を取得するには limit と offset を渡してください。
テストスイートは自己完結型です。パッケージがインストールされていない場合は 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.pysrc/monarch_mcp/server.py に @mcp.tool() デコレータを付けた非同期関数を追加します。docstringがClaudeに見えるMCPツールの説明になるため、Claude向けに記述してください。
新しい MonarchMoney メソッドを呼び出す場合は、tests/conftest.py の _FAKE_METHODS にメソッド名を追加し、fake_mm_client がモック化できるようにします。
tests/test_server.py に server_with_fake_client フィクスチャを使用したテストを追加し、client.<method>.await_args.kwargs をアサートして呼び出しの形式を確認します。
clean_keyring — 各テストの前にメモリ内のキーチェーンスタブをクリアします（実際のキーチェーンがインストールされている場合は何もしません）。
fake_mm_client — Monarchメソッドが {"called": <method_name>} を返す AsyncMock である MagicMock です。
server_with_fake_client — server._client をフェイクにモンキーパッチし、ツール呼び出しが _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.
