Tusk Ledger 的模型上下文协议 (Model Context Protocol) 服务器。 让你的 AI 助手能够以类型化的方式访问你的本地个人财务数据 —— 且无需将任何内容发送到你的机器之外。
这是一个小型 Python 包，作为本地 模型上下文协议 (Model Context Protocol) 服务器在你的笔记本电脑上运行。一旦你将其添加到 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 云”——整个过程就是一个在你机器上运行的 Python 进程，与同一台机器上的另一个 Python 进程进行通信。
Related MCP server: OpenBudget MCP Server
Tusk Ledger 是为“代理辅助”用户构建的——即那些可以要求 Claude / Cursor / Cowork 完成五年前无法独自完成的任务的用户。MCP 服务器是实现这一目标最高效的举措：你的助手可以获得类型化、结构化的财务数据访问权限，而无需去抓取 React UI 或猜测数据库架构。
安装后的实际应用示例：
“将过去 6 个月在 Whole Foods 的交易分类为‘杂货’而不是‘购物’。” → 助手查询这些交易，你确认后，它会创建一条规则。
“我上个季度在咖啡上花了多少钱？” → 3 秒钟，无需点击 UI。
“我的净资产今天早上下降了——是什么原因？” → 助手拉取账户、余额和近期交易并进行诊断。
“我今年能存满 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"
}
}
}（如果你使用的是虚拟环境，请使用 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 | 设置 → 功能 → 模型上下文协议 |
Cowork | 参阅 Anthropic 的 Cowork 文档 |
Claude Code | 项目级 |
编辑配置后，请重启客户端。服务器会在客户端启动时引导，并在客户端关闭时停止。
两个环境变量，均为可选：
变量 | 默认值 | 说明 |
|
| 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 有一个“查看 MCP 服务器日志”菜单项）。常见原因：配置中的路径错误、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）。
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.
