Tusk Ledger를 위한 모델 컨텍스트 프로토콜(MCP) 서버. AI 어시스턴트가 로컬 개인 금융 데이터에 타입이 지정된 방식으로 접근할 수 있게 해주며, 데이터를 기기 외부로 전혀 전송하지 않습니다.
노트북에서 로컬 모델 컨텍스트 프로토콜(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 — 넷플릭스, 헬스장 등 구독 서비스 확인
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 클라우드" 같은 것은 존재하지 않으며, 이 모든 것은 사용자의 기기에서 실행되는 하나의 파이썬 프로세스가 같은 기기의 다른 파이썬 프로세스와 통신하는 방식입니다.
Related MCP server: OpenBudget MCP Server
Tusk Ledger는 에이전트 보조 사용자를 위해 구축되었습니다. 5년 전에는 혼자서 할 수 없었던 일들을 Claude / Cursor / Cowork에게 요청할 수 있는 사용자를 위한 것입니다. MCP 서버는 이 목표를 달성하기 위한 가장 강력한 수단입니다. 어시스턴트가 React UI를 긁어오거나 데이터베이스 스키마를 추측할 필요 없이, 금융 데이터에 타입이 지정된 구조화된 방식으로 접근할 수 있게 됩니다.
설치 후 활용 예시:
"지난 6개월간 Whole Foods에서 결제한 거래를 '쇼핑' 대신 '식료품'으로 분류해줘." → 어시스턴트가 거래를 조회하고, 사용자가 확인하면 규칙을 생성합니다.
"지난 분기에 커피에 얼마를 썼지?" → 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는 격리된 파이썬 환경을 처리하므로 전역 파이썬 환경을 오염시키지 않습니다. 서버는 첫 실행 시 가져와서 캐시됩니다.
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 | 설정 → 기능 → 모델 컨텍스트 프로토콜 |
Cowork | Anthropic의 Cowork 문서 참조 |
Claude Code | 프로젝트 수준의 |
설정을 편집한 후 클라이언트를 다시 시작하세요. 서버는 클라이언트가 시작될 때 부팅되고 종료될 때 함께 종료됩니다.
두 가지 환경 변수를 사용할 수 있으며, 모두 선택 사항입니다:
변수 | 기본값 | 참고 |
|
| Tusk Ledger 백엔드가 실행되는 주소. 포트를 변경한 경우 수정하세요. |
|
| 요청당 타임아웃 시간. DB가 크고 쿼리 시간이 오래 걸리면 늘리세요. |
예시:
{
"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 어시스턴트는 데이터를 이해하고 안전한 작업(동기화, 쿼리)을 수행하는 데 도움을 주어야 하지만, 되돌릴 수 없는 변경 사항은 웹 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" 메뉴 항목이 있습니다). 일반적인 원인: 설정의 잘못된 경로, 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.
