Servidor del Protocolo de Contexto de Modelo (MCP) para Tusk Ledger. Proporciona a tu asistente de IA acceso tipado a tus datos financieros personales locales, sin enviar nada fuera de tu máquina.
Un pequeño paquete de Python que se ejecuta como un servidor local de Protocolo de Contexto de Modelo en tu portátil. Una vez que lo hayas añadido a la configuración de tu cliente de IA (Claude Desktop, Cursor, Cowork, Claude Code, cualquier cosa que hable MCP), tu asistente podrá llamar a herramientas como:
list_accounts — cada cuenta conectada con saldo + estado de sincronización
query_transactions — filtrar por fecha, cuenta, categoría, etc.
search_transactions — búsqueda de texto difusa en comercios y notas
get_spending_summary — totales por categoría para un rango de fechas
get_top_merchants — a quién le pagas más
get_recurring_subscriptions — Netflix, gimnasio, etc.
get_upcoming_bills — próximos 30 días con saldo acumulado
get_net_worth — valor actual + tendencia de 12 meses
get_holdings — cada posición de inversión
get_investments_summary — resumen de cartera + asignación de activos
get_retirement_projection — resumen de Monte Carlo para tu escenario guardado
run_sync — activar una extracción de Plaid
list_stale_accounts — cuentas con datos obsoletos
El servidor se comunica con tu backend local de Tusk Ledger en http://127.0.0.1:8000. Ningún dato cruza Internet. La "nube MCP" no existe; todo esto es un proceso de Python ejecutándose en tu máquina, hablando con otro proceso de Python en la misma máquina.
Related MCP server: OpenBudget MCP Server
Tusk Ledger está diseñado para el usuario asistido por agentes: alguien que puede pedirle a Claude / Cursor / Cowork que haga cosas que no podía hacer solo hace cinco años. El servidor MCP es el movimiento de mayor apalancamiento hacia ese objetivo: tu asistente obtiene acceso tipado y estructurado a tus datos financieros en lugar de tener que analizar la interfaz de usuario de React o adivinar el esquema de la base de datos.
Ejemplos del mundo real una vez instalado:
"Categoriza los últimos 6 meses de transacciones de Whole Foods como Comestibles en lugar de Compras." → El asistente las consulta, tú confirmas y luego crea una regla.
"¿Cuánto gasté en café el trimestre pasado?" → 3 segundos, sin clics en la interfaz.
"Mi patrimonio neto cayó esta mañana, ¿qué lo está causando?" → El asistente extrae cuentas, saldos y transacciones recientes y diagnostica.
"¿Estoy en camino de maximizar mi HSA este año?" → Lee el fondo HSA + contribuciones hasta la fecha + límite del IRS, y devuelve la diferencia.
Una instalación en ejecución de Tusk Ledger (la aplicación principal)
Python 3.10+
Un cliente compatible con MCP (Claude Desktop, Cursor, Cowork, Claude Code, …)
uvx (recomendado; sin instalación permanente)Si tienes 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 maneja el entorno de Python aislado; nada contamina tu Python global. El servidor se descarga y se almacena en caché en la primera invocación.
pip install desde GitHubpip install git+https://github.com/BradMorphsters/tuskledger-mcpLuego apunta tu cliente MCP al binario instalado tuskledger-mcp:
{
"mcpServers": {
"tuskledger": {
"command": "tuskledger-mcp"
}
}
}(Usa la ruta completa de which tuskledger-mcp si estás usando un venv.)
git clone https://github.com/BradMorphsters/tuskledger-mcp
cd tuskledger-mcp
python -m venv .venv && source .venv/bin/activate
pip install -e .Cliente | Ruta de configuración |
Claude Desktop (macOS) |
|
Claude Desktop (Windows) |
|
Cursor | Configuración → Características → Protocolo de Contexto de Modelo |
Cowork | Ver la documentación de Cowork de Anthropic |
Claude Code |
|
Después de editar la configuración, reinicia el cliente. El servidor arranca cuando el cliente se inicia y se apaga cuando se cierra.
Dos variables de entorno, ambas opcionales:
Var | Predeterminado | Notas |
|
| Donde escucha tu backend de Tusk Ledger. Sobrescribe si has cambiado el puerto. |
|
| Tiempo de espera por solicitud. Aumenta si tu base de datos es enorme y una consulta tarda un tiempo. |
Ejemplo:
{
"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"
}
}
}
}Esta v0 asume que tu backend de Tusk Ledger se está ejecutando con DEV_BYPASS_AUTH=true (el patrón común de una sola máquina documentado en el README del repositorio principal). Si has mantenido la autenticación habilitada, las llamadas del servidor MCP fallarán con errores 401 y verás el error en la respuesta de tu asistente.
El soporte con autenticación está en la hoja de ruta. Hasta entonces, si deseas tanto autenticación como MCP, ejecuta el backend con DEV_BYPASS_AUTH=true solo cuando estés usando el asistente, y vuelve a cambiarlo cuando hayas terminado.
Por diseño, la v0 es principalmente de lectura. El servidor no expone:
Eliminar cuentas, transacciones, reglas o metas
Modificar el esquema de la base de datos o ejecutar migraciones
Deshabilitar la autenticación o rotar la clave de cifrado
Tocar tokens de acceso de Plaid
Enviar datos a cualquier lugar fuera de 127.0.0.1
La razón: un asistente de IA debería poder ayudarte a entender tus datos y ejecutar operaciones seguras (sincronización, consultas), pero los cambios irreversibles pertenecen a la interfaz web donde puedes ver lo que está a punto de suceder. Podemos añadir herramientas de escritura estructuradas (por ejemplo, "crear una regla") en versiones posteriores con flujos de confirmación explícitos, pero el estándar seguirá siendo alto.
Could not reach Tusk Ledger backend at http://127.0.0.1:8000 — Tu aplicación Tusk Ledger no se está ejecutando. Desde el repositorio principal: ./start.sh.
401 Unauthorized desde cualquier herramienta — La autenticación está activada. Consulta la sección de Autenticación anterior. Ejecuta con DEV_BYPASS_AUTH=true por ahora.
404 Not Found — El backend no tiene el endpoint al que intentamos acceder. Probablemente significa que estás en una versión anterior de Tusk Ledger. Actualiza la aplicación principal, reinicia tu cliente MCP.
Las herramientas no aparecen en tu asistente — El servidor MCP no pudo arrancar. Revisa los registros del servidor MCP de tu cliente (Claude Desktop tiene un elemento de menú "Ver registros del servidor MCP"). Causas comunes: ruta incorrecta en la configuración, Python no está en el PATH, uvx no está instalado.
Verificación de salud general — Desde el repositorio principal de Tusk Ledger: ./tuskledger doctor. Este es el diagnóstico canónico para toda la instalación.
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/ -vLas pruebas no inician un transporte MCP; ejercitan la capa de despacho directamente con un cliente simulado. El protocolo MCP en sí es solo un envoltorio.
CI ejecuta el mismo conjunto de pruebas en Python 3.10/3.11/3.12 a través de GitHub Actions (ver .github/workflows/ci.yml).
Aplicación principal: https://github.com/BradMorphsters/tuskledger
Sitio del proyecto: https://www.tuskledger.com
Para agentes que navegan externamente: https://www.tuskledger.com/llms.txt
Problemas / discusiones: https://github.com/BradMorphsters/tuskledger-mcp/issues
Licencia: 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.
