Tusk Ledger 用の Model Context Protocol サーバー。 AIアシスタントがローカルの個人財務データに型付きでアクセスできるようにします。データはマシン外に一切送信されません。
ラップトップ上でローカルの Model Context Protocol サーバーとして動作する小さなPythonパッケージです。AIクライアント（Claude Desktop、Cursor、Cowork、Claude Codeなど、MCPに対応しているもの）の設定に追加すると、アシスタントが以下のようなツールを呼び出せるようになります：
list_accounts — 残高と同期ステータスを含む接続済み口座の一覧
query_transactions — 日付、口座、カテゴリなどでフィルタリング
search_transactions — 加盟店やメモに対するあいまい検索
get_spending_summary — 指定期間のカテゴリ別合計
get_top_merchants — 最も支出の多い加盟店
get_recurring_subscriptions — Netflixやジムなどの定期購読
get_upcoming_bills — 今後30日間の請求と残高推移
get_net_worth — 現在の純資産と12ヶ月の推移
get_holdings — すべての投資ポジション
get_investments_summary — ポートフォリオのまとめと資産配分
get_retirement_projection — 保存されたシナリオに基づくモンテカルロ法による要約
run_sync — Plaidの同期を実行
list_stale_accounts — データが古い口座の一覧
サーバーは http://127.0.0.1:8000 でローカルのTusk Ledgerバックエンドと通信します。データはインターネットを通過しません。 「MCPクラウド」のようなものは存在せず、マシン上で実行されている1つのPythonプロセスが、同じマシン上の別のPythonプロセスと通信するだけです。
Related MCP server: OpenBudget MCP Server
Tusk Ledger は、エージェントを活用するユーザーのために構築されています。5年前には一人ではできなかったことを、Claude / Cursor / Cowork に依頼できるユーザーのためのものです。このMCPサーバーは、その目標に向けた最も強力な手段です。アシスタントは、React UIをスクレイピングしたりデータベーススキーマを推測したりする必要がなく、財務データに型付きの構造化されたアクセスが可能になります。
インストール後の活用例：
「Whole Foodsでの過去6ヶ月の取引を『ショッピング』ではなく『食料品』に分類して。」 → アシスタントがクエリを実行し、あなたが確認した上でルールを作成します。
「先四半期にコーヒーにいくら使った？」 → UIをクリックすることなく、3秒で回答します。
「今朝、純資産が減ったんだけど、原因は何？」 → アシスタントが口座、残高、最近の取引を取得して診断します。
「今年、HSAの拠出限度額に到達できそう？」 → HSAの残高、年初来の拠出額、IRSの制限額を読み取り、不足分を返します。
実行中の Tusk Ledger インストール（メインアプリ）
Python 3.10以上
MCP対応クライアント（Claude Desktop、Cursor、Cowork、Claude Codeなど）
uvx（推奨、永続的なインストール不要）uv (pip install uv) がインストールされている場合：
// In your MCP client's config
{
"mcpServers": {
"tuskledger": {
"command": "uvx",
"args": ["--from", "git+https://github.com/BradMorphsters/tuskledger-mcp", "tuskledger-mcp"]
}
}
}uvx が分離されたPython環境を処理するため、グローバルなPython環境を汚染しません。サーバーは初回実行時に取得・キャッシュされます。
pip installpip install git+https://github.com/BradMorphsters/tuskledger-mcpその後、MCPクライアントでインストールされた tuskledger-mcp バイナリを指定します：
{
"mcpServers": {
"tuskledger": {
"command": "tuskledger-mcp"
}
}
}（venvを使用している場合は which tuskledger-mcp で得られるフルパスを使用してください。）
git clone https://github.com/BradMorphsters/tuskledger-mcp
cd tuskledger-mcp
python -m venv .venv && source .venv/bin/activate
pip install -e .クライアント | 設定ファイルのパス |
Claude Desktop (macOS) |
|
Claude Desktop (Windows) |
|
Cursor | 設定 → 機能 → Model Context Protocol |
Cowork | AnthropicのCoworkドキュメントを参照 |
Claude Code | プロジェクトレベルの |
設定を編集した後、クライアントを再起動してください。サーバーはクライアントの起動時に立ち上がり、終了時に停止します。
2つの環境変数が利用可能です（どちらもオプション）：
変数 | デフォルト | 備考 |
|
| Tusk Ledgerバックエンドの待ち受け先。ポートを変更した場合は上書きしてください。 |
|
| リクエストごとのタイムアウト。データベースが巨大でクエリに時間がかかる場合は増やしてください。 |
例：
{
"mcpServers": {
"tuskledger": {
"command": "uvx",
"args": ["--from", "git+https://github.com/BradMorphsters/tuskledger-mcp", "tuskledger-mcp"],
"env": {
"TUSKLEDGER_BASE_URL": "http://127.0.0.1:8000",
"TUSKLEDGER_TIMEOUT_SECONDS": "30"
}
}
}
}このv0バージョンでは、Tusk Ledgerバックエンドが DEV_BYPASS_AUTH=true で実行されていることを前提としています（メインリポジトリのREADMEに記載されている一般的なシングルマシン構成）。認証を有効にしたままにしている場合、MCPサーバーの呼び出しは401エラーで失敗し、アシスタントの応答にエラーが表示されます。
認証対応はロードマップに含まれています。それまでの間、認証とMCPの両方を使用したい場合は、アシスタントを使用している間だけ DEV_BYPASS_AUTH=true でバックエンドを実行し、終わったら元に戻してください。
設計上、v0は読み取り専用です。サーバーは以下を公開しません：
口座、取引、ルール、目標の削除
データベーススキーマの変更やマイグレーションの実行
認証の無効化や暗号化キーのローテーション
Plaidアクセストークンの操作
127.0.0.1 以外の場所へのデータ送信
その理由は、AIアシスタントはデータの理解や安全な操作（同期、クエリ）を支援すべきであり、不可逆的な変更はWeb UIで行うべきだからです。将来のバージョンで、明示的な確認フローを伴う構造化された書き込みツール（例：「ルールを作成する」）を追加する可能性がありますが、基準は高く保たれます。
Could not reach Tusk Ledger backend at http://127.0.0.1:8000 — Tusk Ledgerアプリが実行されていません。メインリポジトリから ./start.sh を実行してください。
401 Unauthorized — 認証が有効になっています。上記の「認証」セクションを参照してください。今のところは DEV_BYPASS_AUTH=true で実行してください。
404 Not Found — バックエンドにアクセスしようとしているエンドポイントが存在しません。Tusk Ledgerのバージョンが古い可能性があります。メインアプリを更新し、MCPクライアントを再起動してください。
ツールがアシスタントに表示されない — MCPサーバーの起動に失敗しています。クライアントのMCPサーバーログを確認してください（Claude Desktopには「View MCP server logs」メニュー項目があります）。一般的な原因：設定のパスが間違っている、PythonがPATHに含まれていない、uvx がインストールされていないなど。
一般的なヘルスチェック — メインのTusk Ledgerリポジトリから ./tuskledger doctor を実行してください。これがインストール全体の標準的な診断ツールです。
git clone https://github.com/BradMorphsters/tuskledger-mcp
cd tuskledger-mcp
python -m venv .venv && source .venv/bin/activate
pip install -e .
pip install pytest pytest-asyncio
pytest tests/ -vテストはMCPトランスポートを立ち上げず、モッククライアントを使用してディスパッチレイヤーを直接実行します。MCPプロトコル自体は単なるラッパーです。
CIはGitHub Actionsを通じてPython 3.10/3.11/3.12で同じスイートを実行します（.github/workflows/ci.yml を参照）。
プロジェクトサイト: https://www.tuskledger.com
外部から閲覧するエージェント向け: https://www.tuskledger.com/llms.txt
イシュー / ディスカッション: https://github.com/BradMorphsters/tuskledger-mcp/issues
ライセンス: MIT
Current investment holdings across every connected brokerage and 401(k). Returns symbol, account, quantity, current value, and unrealized gain/loss per position.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose all behavioral traits. It states it returns holdings across all accounts but does not mention performance, authentication requirements, or whether it triggers a refresh. Minimal extra context beyond obvious read operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences: first sets scope, second lists returned fields. No unnecessary words. Information is front-loaded and easy to parse.
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 parameterless tool returning a list, the description covers the key output fields adequately. Lacks mention of potential size limits or ordering, but overall sufficient given simple use case.
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?
Zero parameters, so schema coverage is 100%. Description adds value by detailing the output fields, which is necessary since no output schema exists. 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?
Description clearly states what the tool does: returns current investment holdings with specific fields (symbol, account, quantity, etc.) across all connected brokerages and 401(k)s. Distinguishes from sibling tools like get_investments_summary by emphasizing per-position detail.
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 (e.g., get_investments_summary for aggregates). Does not specify preconditions or limitations such as requiring a recent sync.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Roll-up of investment portfolio: total value, asset allocation (stocks/bonds/cash), top 5 holdings, % YTD gain. The 'how are my investments doing?' answer.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden. It discloses the tool produces a summary roll-up (read-only behavior) and lists specific output fields. No contradictions; it is transparent for a simple, read-only tool with no parameters.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with key information, and no redundant words. Every sentence serves a purpose.
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 no parameters and no output schema, the description fully explains the output: total value, asset allocation, top 5 holdings, and YTD gain. An agent can confidently determine when to call this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are no parameters (schema coverage 100%), so baseline is 4. The description adds value by explaining what the tool returns, which is sufficient for the agent to understand usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: a roll-up of investment portfolio including total value, asset allocation, top 5 holdings, and YTD gain. It also provides a usage hint ('the how are my investments doing? answer'), making it unambiguous and distinct from siblings like get_holdings or get_net_worth.
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 when to use this tool (for an overall portfolio snapshot), but does not explicitly mention when not to use or suggest alternatives. The context is clear but lacks explicit exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Current net worth (assets minus liabilities) plus a 12-month trend. Numbers are point-in-time from the last sync, not live-computed. Use list_stale_accounts to verify freshness.
| Name | Required | Description | Default |
|---|---|---|---|
| history | No | If true, return the full snapshot history instead of just latest. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description adds value by disclosing that numbers are point-in-time from last sync, not live-computed. It does not mention rate limits or auth, but for a read-only tool, this is acceptable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the main purpose, and every sentence adds value. 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?
For a low-complexity tool (one optional parameter, no output schema), the description explains the main output, data freshness, and a usage hint. It is mostly complete, though return format details are omitted.
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 fully describes the single parameter 'history' with a description. The tool description does not add additional meaning beyond that, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns 'current net worth (assets minus liabilities) plus a 12-month trend', specifying the resource (net worth) and action (get). It distinguishes from siblings by noting data is point-in-time from last sync, not live-computed.
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 tells when to use the tool to get net worth with trend and advises using list_stale_accounts to verify data freshness. It does not explicitly mention when not to use, but the sibling list provides context for alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List detected recurring subscriptions: Netflix, Spotify, gym, etc. Returns merchant, cadence (monthly/annual/etc.), last amount, next expected date, and confidence. The user often asks 'what subscriptions do I have' — this answers it.
| Name | Required | Description | Default |
|---|---|---|---|
No 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 describes what the tool returns but does not explicitly state that it is read-only or disclose any potential side effects. The name and context strongly imply safety, but the description lacks explicit disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the main action, and every sentence adds value. No redundant 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?
Given no output schema and zero parameters, the description adequately covers the tool's functionality by specifying return fields. However, it could offer more detail on detection confidence or limitations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the baseline is 4. The description adds value by listing the output fields, which helps the agent understand what data to expect, compensating for the lack of input parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it lists detected recurring subscriptions, provides concrete examples (Netflix, Spotify), and explicitly names the returned fields (merchant, cadence, etc.), making it distinct from siblings like get_upcoming_bills.
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 includes a direct cue for common user queries ('what subscriptions do I have') and clearly indicates when to use the tool. However, it does not explicitly state when not to use or mention alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run the multi-decade Monte Carlo retirement simulator. Returns probability of success, depletion age, and summary at key milestones (retirement, age 73 for RMDs, etc.).
Caveat: scenarios live in the Tusk Ledger UI's localStorage on the device the user last edited from — they aren't accessible to this tool. So the user (or their assistant) must supply at least current_age. Other params accept sensible defaults that match the standard 4% rule scenario; pass any you know to tighten the projection. To pull a saved scenario verbatim, the user can copy it out of the Retirement page in the UI and paste the values into the assistant's prompt.
| Name | Required | Description | Default |
|---|---|---|---|
| current_age | Yes | User's current age. Required. | |
| retirement_age | No | Target retirement age (default 65). | |
| spouse_age | No | Spouse's current age. Optional — enables two-phase simulation when paired with spouse_retirement_age. | |
| spouse_retirement_age | No | Age at which the spouse retires (in spouse's years). | |
| desired_annual_income | No | Target annual spending in retirement, today's dollars (default 80000). | |
| annual_contribution | No | Annual contribution. Omit to auto-detect from last 12mo of investment-account inflows. | |
| return_rate | No | Real annual return during accumulation (default 0.06 = 6%). | |
| withdrawal_rate | No | Safe withdrawal rate (default 0.04 = the 4% rule). | |
| pension_annual | No | Annual pension income, today's dollars. | |
| ss_annual | No | Annual Social Security at the user's claim age. | |
| ss_start_age | No | Age at which to claim SS (62–70, default 67). | |
| inflation_rate | No | Long-run inflation assumption (default 0.025). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, but the description discloses key behavior: it is a simulation (not a mutation), returns specific outputs, and depends on user-supplied data due to localStorage inaccessibility. It also mentions default assumptions (4% rule). No destructive or side effects indicated.
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?
Well-structured: first sentence states purpose, then details outputs and caveats. However, the third paragraph could be shortened slightly without losing clarity.
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 12 parameters and no output schema, the description adequately explains inputs, defaults, and output types (probability, depletion age, milestones). Could include more detail on milestone ages, but sufficient for an agent to invoke 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 descriptions cover all 12 parameters with defaults, but the description adds context such as the 4% rule, two-phase simulation for spouses, and the option to pass known values to tighten projections. This adds value beyond the raw 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?
Clearly states 'Run the multi-decade Monte Carlo retirement simulator' and specifies outputs (probability of success, depletion age, summary at milestones). Distinct from sibling tools like get_investments_summary or get_net_worth, as it focuses on retirement projection.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear guidance: user must supply current_age because saved scenarios are not accessible; other parameters have sensible defaults. Mentions the localStorage limitation and suggests copying values from the UI. However, lacks explicit comparison to alternatives, though siblings are clearly different.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Aggregated spending totals broken down by category for a date range. Returns totals + per-category subtotals + counts. Defaults to the current calendar month if no dates given.
| Name | Required | Description | Default |
|---|---|---|---|
| start_date | No | ISO date YYYY-MM-DD. | |
| end_date | No | ISO date YYYY-MM-DD. | |
| exclude_business | No | Drop transactions tagged as business (default false). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It mentions default date range behavior and that it returns aggregated data, implying read-only. However, it does not explicitly state safety (e.g., no side effects) or authentication needs.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences: first states the core function, second describes output format, third explains default behavior. No redundant words, front-loaded with the main purpose.
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 3 optional parameters and no output schema, the description explains return values (totals, subtotals, counts) but lacks details on structure (e.g., whether dates are inclusive) and does not mention the 'exclude_business' parameter. Could be more complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with clear parameter descriptions. The description adds value by specifying the default behavior for date range (current calendar month) when no dates are given, which is not in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool aggregates spending totals by category for a date range, returns totals, subtotals, and counts. It is distinct from siblings like 'query_transactions' but does not explicitly differentiate.
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 does not provide guidance on when to use this tool versus alternatives like 'get_investments_summary' or 'query_transactions'. No exclusions or context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Top N merchants by total spend in a date range. Returns merchant name, total amount, transaction count, and a sparkline of the monthly trend. Useful for 'who am I paying the most?'.
| Name | Required | Description | Default |
|---|---|---|---|
| start_date | No | ISO date. | |
| end_date | No | ISO date. | |
| limit | No | How many merchants to return (default 10). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. Description only lists return fields; does not disclose read-only nature, authentication requirements, rate limits, or behavior on empty results. Lacks behavioral context beyond output.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences: purpose, output details, and a use case. No redundancy; front-loaded with actionable 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?
Given low complexity and no output schema, description sufficiently covers return values. However, missing details such as sorting order (descending by spend?) and timezone handling could improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so description adds little beyond schema. Baseline 3; description's 'date range' and 'top N' mirror schema descriptions without enriching meaning.
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?
Description clearly states the tool returns top merchants by total spend in a date range, listing returned fields. It distinguishes itself from sibling tools like get_spending_summary by focusing on merchants.
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 a use case ('who am I paying the most?') but lacks explicit guidance on when not to use or alternatives. No mention of sibling tools or conditions like data availability.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Forward 30-day calendar of expected bills + paychecks with a running balance. Returns each event's date, amount, source (merchant or paycheck), and the projected account balance after that event. Useful for 'is my account going to dip before payday?'.
| Name | Required | Description | Default |
|---|---|---|---|
| days | No | How many days forward to look (default 30). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description carries the full burden. It discloses the output in detail (date, amount, source, projected balance) and implies read-only behavior. It could be improved by mentioning any prerequisites like synced accounts.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loading the main functionality and ending with a practical use case. Every sentence adds value with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter, no output schema), the description adequately covers what the tool does and returns. It addresses a common user question, leaving minimal gaps in understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a clear description for the single parameter 'days'. The description adds little beyond the schema's parameter description, so a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns a forward 30-day calendar of expected bills and paychecks with a running balance. It specifies the verb ('returns') and the resource ('calendar of expected bills + paychecks'), distinguishing it from siblings like get_recurring_subscriptions or query_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 provides a clear use case: 'is my account going to dip before payday?'. However, it does not explicitly mention when not to use this tool or suggest alternatives among the siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List every connected account in Tusk Ledger with current balance, type (checking, savings, credit, investment, loan), and last-sync timestamp. Use this first to understand what accounts exist before drilling into transactions or holdings.
| Name | Required | Description | Default |
|---|---|---|---|
No 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 the tool lists all accounts with selected fields and implies a read operation. However, it omits any mention of potential limitations (e.g., pagination, data freshness) or side effects. The description is adequate but not comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences: the first clearly states output content, the second provides usage guidance. It is front-loaded and contains no unnecessary words, making it highly efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no parameters, no output schema, and no annotations, the description is fairly complete. It states what is returned and when to use it. It does not address error conditions or scale limits, but for a simple list tool this is 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?
The input schema has no parameters and is 100% covered. The description adds no parameter-related meaning because there are none. Baseline for 0 parameters is 4, and the description appropriately focuses on output content.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses specific verb+resource ('List every connected account') and enumerates returned fields (balance, type, timestamp). It distinguishes from sibling tools by advising to use this first before drilling into transactions or holdings, clearly differentiating its purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use the tool ('Use this first to understand what accounts exist') and contrasts with drilling into transactions or holdings. It could be improved by explicitly noting when not to use it, but the guidance is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return accounts whose data is older than the freshness threshold (a week for synced accounts, a month for manual). Useful when the user asks 'why is my net worth wrong?' — stale balances are usually the cause.
| Name | Required | Description | Default |
|---|---|---|---|
No 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 the tool returns accounts based on freshness thresholds, which is the key behavioral trait. It implies a read-only operation, which is sufficient for a list 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?
Two sentences with no wasted words. The purpose is front-loaded, and the use case is given in the second sentence. Highly concise and 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?
For a parameterless tool with no output schema, the description adequately explains what the tool returns and when to use it. It is complete for the tool's complexity.
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 no parameters and schema coverage is 100%. The description does not need to add parameter info. Baseline 4 is appropriate as the description covers the tool's function without needing to detail parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: return accounts with stale data. It defines the freshness threshold (a week for synced, a month for manual) and distinguishes from siblings like list_accounts by focusing on stale 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?
The description provides a specific use case: 'when the user asks why is my net worth wrong?' It implies this is for troubleshooting, not for a general list. However, it doesn't explicitly state when not to use it or mention alternatives, though siblings exist.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List transactions matching optional filters. Returns the most recent matches first. Common filter combos: • account_id + start_date + end_date → 'all transactions in my checking account this month' • category='Coffee' + start_date='2026-01-01' → 'every coffee purchase since New Year' Defaults to no filter (returns the most recent 100 transactions across all accounts).
| Name | Required | Description | Default |
|---|---|---|---|
| account_id | No | Filter to a single account by id. | |
| category | No | Filter to a single category name (exact match). | |
| start_date | No | ISO date YYYY-MM-DD; inclusive lower bound. | |
| end_date | No | ISO date YYYY-MM-DD; inclusive upper bound. | |
| limit | No | Max rows to return (default 100, max 500). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description covers default ordering, default limit, and common use cases. It does not disclose any potential side effects, authentication needs, rate limits, or the exact structure of returned data, but the behavioral context given is adequate for basic usage.
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 front-loaded with the main purpose and uses bullet-like examples efficiently. Each sentence contributes meaning, though the examples could be slightly condensed without losing clarity.
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 5 parameters with full schema coverage, no output schema, and no annotations, the description covers ordering, filtering combos, defaults, and limits. It does not detail the return format, but for a list tool this is a minor gap; overall it is fairly 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?
Despite 100% schema coverage, the description adds significant value by providing example combos (e.g., account_id + start_date + end_date) and clarifying defaults (limit default 100, max 500). This contextualizes parameters beyond the schema's standalone descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists transactions matching optional filters and returns the most recent first. It distinguishes from siblings by focusing on filtering and ordering, though it does not explicitly contrast with the similar-sounding 'search_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 provides common filter combinations and default behavior (no filter returns 100 recent transactions across all accounts). However, it lacks explicit guidance on when not to use this tool or alternatives (e.g., search_transactions for more complex queries), leaving usage implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Trigger a Plaid sync across all connected items. Same as clicking 'Sync Now' in the UI. Returns a summary of what was fetched (accounts updated, transactions added). Safe to call freely — Plaid dedupes.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description discloses the sync trigger, output summary, and safety due to deduplication. It doesn't mention rate limits or async behavior, but provides reasonable transparency for a simple action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no wasted words. Front-loaded with the action verb and clear purpose.
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 zero parameters and no output schema, the description covers the essentials: trigger, return summary, and safety. Could mention sync duration but is 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?
No parameters exist, per instructions baseline is 4. No additional parameter info needed since schema coverage is complete.
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 it triggers a Plaid sync across all connected items, analogizes to UI Sync Now, and specifies the output summary. This distinguishes it from siblings which are all read-only query tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for syncing data but doesn't explicitly state when to prefer this over alternatives. It does convey that calling is safe and deduplication occurs, giving some usage confidence.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Free-text search across transaction names, merchant names, and notes. Use when the user asks 'find that Whole Foods charge from last week' or 'when did I last pay Verizon?'. Different from query_transactions in that this is a fuzzy text search, not a structured filter.
| Name | Required | Description | Default |
|---|---|---|---|
| q | Yes | Search string. Matches partial words, case-insensitive. | |
| limit | No | Max rows (default 50). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It mentions fuzzy matching and case-insensitivity but does not explicitly state the tool is read-only or describe result behavior beyond limit parameter. Returns a list of transactions, but no detail on ordering or that it doesn't modify 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 front-load key purpose and usage boundaries. Every sentence adds value with zero repetition.
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 search tool with 2 parameters and no output schema, the description covers purpose, usage guidance, and search scope. Missing explicit mention that search is read-only and that results may be ordered by relevance, but overall adequate.
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?
Input schema has 100% coverage of parameters (q and limit), and schema descriptions are adequate. Description adds minimal new info beyond schema (e.g., default limit 50 already in schema). No further enrichment 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?
Description clearly states it performs free-text search across transaction names, merchants, and notes. Provides specific example queries ('find that Whole Foods charge', 'when did I last pay Verizon?') and explicitly distinguishes from sibling tool query_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?
Explicitly tells when to use this tool ('free-text search') and contrasts with query_transactions ('structured filter'). Includes concrete user expressions to guide invocation.
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.1get_holdingsget_investments_summaryget_net_worthget_recurring_subscriptionsget_retirement_projectionget_spending_summaryget_top_merchantsget_upcoming_billslist_accountslist_stale_accountsquery_transactionsrun_syncsearch_transactionsScored across 13 tools
Each tool targets a distinct financial domain: holdings vs investment summary vs net worth, and query vs search transactions are clearly differentiated. Descriptions provide clear purpose for each tool.
All tools follow a consistent verb_noun pattern (e.g., get_holdings, list_accounts, run_sync) with clear and predictable naming.
13 tools cover a comprehensive range of personal finance operations without being excessive. Each tool serves a distinct and necessary function.
Covers holdings, investments, net worth, subscriptions, retirement, spending, merchants, bills, accounts, transactions, and sync. Missing budget management or transaction updating, but core data retrieval is well-covered.
Personal finance, bank account, and shared memory connector for Claude, ChatGPT, Gemini Spark & more
Personal finance ledger for AI agents — query spending, track bills, forecast cash flow.
Read-only banking and personal finance for AI agents: accounts, transactions, spending, budgets.
Connect AI agents to bank accounts, transactions, balances, and investments.
