Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@YNAB MCP Server Show my budget summary"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
An MCP server for YNAB with batch operations, deterministic analysis tools, and robust undo support.
AI Disclosure: This project was built with Claude Code and Cursor. It works and is tested, but the code is largely clanker-made.
26 tools covering budgets, accounts, transactions, categories, targets, scheduled transactions, and spending analysis
Deterministic analysis — spending aggregation, trends, income vs expense, recurring-charge and anomaly detection, and a one-call budget health snapshot. Judgment calls (forecasting, reallocation, prioritization) are deliberately left to the calling agent, which has the exact data and more context
Batch operations — create, update, and delete multiple transactions in a single call, with per-item API costs documented where the YNAB API has no bulk endpoint
Undo support — every write operation is recorded and reversible
Smart categorization — transaction category suggestions from payee history and scheduled-transaction matching, with confidence gating so only high-confidence suggestions land in the ready-to-apply actions
Built-in knowledge base — YNAB methodology docs (credit cards, targets, overspending, reconciliation) served as MCP resources
5 workflow prompts — monthly reviews, spending reports, unapproved triage, budget optimization, and subscription audits
Read-only mode — write tools are not even registered, so clients only see tools they can use
Efficient caching — delta sync with YNAB's server knowledge system, configurable TTLs, and client-side rate-limit tracking
Related MCP server: YNAB Assistant
Node.js >= 20
A YNAB personal access token
Run directly with npx:
YNAB_API_TOKEN=your-token npx @maro-org/ynab-mcpOr install globally:
npm install -g @maro-org/ynab-mcp
YNAB_API_TOKEN=your-token ynab-mcpAdd the server to your MCP client config. For example, in Claude Desktop (claude_desktop_config.json):
{
"mcpServers": {
"ynab": {
"command": "npx",
"args": ["-y", "@maro-org/ynab-mcp"],
"env": {
"YNAB_API_TOKEN": "your-token"
}
}
}
}For Cursor, add the same structure to .cursor/mcp.json in your project or ~/.cursor/mcp.json globally.
All configuration is done through environment variables.
Variable | Description | Default |
| YNAB personal access token | required |
| Override the YNAB API base URL | YNAB default |
| Directory for undo history storage |
|
| Hide and disable all write operations ( |
|
| Cache TTL in seconds for live data |
|
| Cache TTL in seconds for completed past months |
|
| Undo entries kept per budget (oldest are dropped beyond this) |
|
Tool | Description |
| List all budgets with metadata |
| Force-refresh cached data from YNAB |
Tool | Description |
| List accounts with balances, filterable by type and on/off budget |
Tool | Description |
| Search with filters (dates, amounts, accounts, categories, payees, flags, cleared status) — supports multiple queries in one call |
| Batch create transactions with optional splits (one bulk API call) |
| Batch update existing transactions (one bulk API call; split changes are replaced via delete+recreate) |
| Batch delete transactions (one API call per transaction) |
Tool | Description |
| Category group hierarchy with IDs and names |
| Target details: type, amounts, underfunded, percent complete, cadence, and deadlines |
| Month-level budgeted/activity/balance per category |
| Batch set budgeted amounts (up to two API calls per category/month pair, max 50) |
| Set or clear a category's target amount and date (the API does not expose target type) |
Tool | Description |
| Spending aggregates by category/payee with top-N ranking; optional |
| Multi-month time series by category, payee, or group; the partial current month is marked and excluded from trends |
| Income vs expense totals with savings rate; partial current month excluded from averages |
| Single-call snapshot: net worth, month totals, overspending, target gaps, credit card payment gaps, RTA, issues |
| Subscription and recurring charge detection from transaction history |
| Flag unusual transactions with leave-one-out statistical baselines |
| Audit feed of budget moves between categories or Ready to Assign, including moves made in the YNAB apps |
All analysis tools are deterministic — no LLM sampling involved. They report facts and clearly-labeled statistical estimates; forecasting and reallocation decisions are left to the calling agent (the workflow prompts walk it through that reasoning using get_targets, get_monthly_budget, and get_scheduled_transactions).
Tool | Description |
| List scheduled transactions with optional filters |
| Batch create with any of the 13 YNAB frequencies (one API call per item) |
| Batch update scheduled transactions (one API call per item) |
| Batch delete scheduled transactions (one API call per item) |
Tool | Description |
| Suggest categories for uncategorized transactions based on payee history and patterns |
Suggestions carry confidence levels; only those at or above action_confidence (default high) are included in the ready-to-apply update_actions, and approval is opt-in.
Tool | Description |
| List recorded undo entries |
| Undo one or more previous write operations by ID |
Knowledge base resources for YNAB methodology. Workflow prompts reference these automatically.
URI | Topic |
| Core YNAB concepts and terminology |
| Credit card handling |
| Target types and behavior |
| Overspending mechanics |
| Reconciliation workflow |
| API quirks and limitations |
Prompt | Description |
| Guided monthly budget review |
| Spending report for a date range |
| Batch review and approve unapproved transactions |
| Analyze budget for optimization opportunities |
| Review recurring charges and manage subscriptions |
Currency units — All monetary amounts in tool inputs and outputs use standard currency units (e.g., 12.50), not YNAB's native milliunits. Most tools also echo a top-level currency ISO code; get_spending_analysis additionally reports raw *_milliunits totals alongside them.
budget_id — Most tools accept an optional budget_id. Omit it or pass "last-used" to target the most recently accessed budget.
Undo — Every write operation records an undo entry. Use list_undo_history and undo_operations to review or revert changes. The most recent 2000 entries per budget are kept (tunable via YNAB_UNDO_HISTORY_LIMIT).
Read-only mode — Set YNAB_READ_ONLY=true to hide and block all write operations. Useful for exploring your budget safely or restricting an MCP client to read-only access.
Rate limiting — The YNAB API allows 200 requests per rolling hour. The server tracks usage locally and reports when capacity frees up if the limit is reached. (The API used to expose an X-Rate-Limit header the tracker reconciled against; the live API no longer sends it, so the local tracker is the sole signal until a 429 confirms exhaustion.) Tools that cost one API call per item say so in their descriptions.
npm install
npm run dev # run with tsx watch
npm run build # compile TypeScript
npm test # run tests (vitest)
npm run typecheck # type-check without emitting
npm run lint # lint with Biome
npm run ci # typecheck + lint + testCreate one or more scheduled transactions. Each successful creation is undoable and costs one YNAB API call (no bulk endpoint exists).
| Name | Required | Description | Default |
|---|---|---|---|
| budget_id | No | Budget ID. Omit to use the last-used budget. | |
| transactions | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=false (write) and destructiveHint=false (not destructive). The description adds significant behavioral details: creations are undoable, each costs one API call, and there is no batching. This goes well beyond the annotations and helps the agent understand side effects and constraints.
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, each earning its place: first sentence states the core action, second adds key behavioral constraints. No unnecessary words or 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?
Given the tool's moderate complexity (array of required fields, multiple frequencies), the description covers the most critical behavioral aspects (undoability, API cost, bulk limitation). Missing details like error handling or response format are not essential for a creation tool but would slightly improve completeness. Still, it is largely 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?
Schema description coverage is 50% (budget_id has a description, transactions array does not). The description does not elaborate on parameter meanings beyond what the schema provides. Baseline 3 is appropriate because the schema itself is fairly detailed for the nested items, but the description adds no extra semantic value for 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 creates one or more scheduled transactions. This verb+resource combination is specific and distinguishes it from sibling tools like 'create_transactions' (non-scheduled) and 'update_scheduled_transactions'. The purpose is unambiguous.
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 useful context: each creation is undoable, costs one API call, and there is no bulk endpoint. It implicitly advises that to create multiple scheduled transactions, separate calls are needed. However, it does not explicitly compare to alternatives or state when not to use this tool (e.g., for non-recurring transactions).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create one or more transactions in a single call. Each successful creation is undoable.
| Name | Required | Description | Default |
|---|---|---|---|
| budget_id | No | Budget ID. Omit to use the last-used budget. | |
| transactions | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations, the description adds 'Each successful creation is undoable,' providing important behavioral context for agent decisions. However, it does not detail idempotency, error handling, or atomicity of batch operations.
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, front-loaded with purpose and key behavioral info. Every word is necessary; no fluff or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite complexity (batch creation, nested subtransactions), the description omits constraints like max/min items, subtransaction sum rule, and optionality of budget_id. Agents lack context for safe invocation, especially without an output schema.
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 50%, but the description adds no parameter-specific information. It does not compensate for missing schema descriptions, leaving agents without further guidance on parameters like budget_id or transaction fields.
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 'Create one or more transactions' specifying the verb (create) and resource (transactions). It also mentions batching and undo capability, distinguishing it from sibling tools like update_transactions or delete_transactions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for adding transactions but does not explicitly state when to use this tool versus alternatives like create_scheduled_transactions. No guidance on prerequisites or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete one or more scheduled transactions. Each deletion is undoable and costs one YNAB API call (no bulk endpoint exists).
| Name | Required | Description | Default |
|---|---|---|---|
| budget_id | No | Budget ID. Omit to use the last-used budget. | |
| scheduled_transaction_ids | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveness and idempotency. The description adds value by disclosing that each deletion is undoable and costs one API call, with no bulk endpoint, providing behavioral context beyond annotations.
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?
A single sentence that efficiently conveys purpose and key behavioral notes 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?
For a simple destructive operation, the description covers undoability and cost. It could mention that the scheduled transactions must exist or reference permissions, but overall it is sufficient given the lack of an output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With only 50% schema description coverage, the description should add meaning for parameters. It reiterates that transactions are multiple ('one or more') but provides no additional detail for 'scheduled_transaction_ids' (e.g., format, source). The budget_id parameter is already well-described 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 action ('Delete') and the resource ('scheduled transactions'), and it distinguishes from sibling tools like 'delete_transactions' (regular transactions) and 'create_scheduled_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 context on cost (one API call per deletion) and undoability, which helps the agent decide when to use this tool. However, it does not explicitly state when not to use it or mention alternatives like bulk operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete one or more transactions. Each deletion is undoable by re-creating the transaction. Costs one YNAB API call per transaction against the 200/hour rate limit.
| Name | Required | Description | Default |
|---|---|---|---|
| budget_id | No | Budget ID. Omit to use the last-used budget. | |
| transaction_ids | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds significant behavioral context beyond annotations: it clarifies that deletions are undoable (by re-creating) and that each deletion costs one API call against the rate limit. This complements the destructiveHint and idempotentHint annotations.
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 exceptionally concise: three short sentences with no fluff. It front-loads the core purpose and immediately adds useful context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a deletion tool, the description covers undoability and rate limits, which addresses key usage concerns. However, it does not discuss error handling or what happens on failure, but given the simple nature and rich annotations, it is largely complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description does not explain any parameter details. With only 50% schema description coverage (budget_id described, transaction_ids not), the description should compensate but fails to do so, leaving transaction_ids semantics unclear.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Delete') and the resource ('one or more transactions'), with additional context about undoability. It effectively distinguishes itself from sibling tools like update_transactions and create_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 explicit guidance on when to use (to delete transactions) and notes that deletions are undoable, implying an alternative (re-creating). It also mentions rate limits. However, it does not explicitly contrast with other deletion or undo tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find unusual transactions: abnormal amounts for known payees, large charges from new payees, and potential duplicates. Compares each transaction against a baseline built from that payee's other transactions (the transaction itself is excluded). For payees whose history is near-constant the comparison scale is floored, in which case scale_basis is "floor" and scale_multiple is a multiple of that floor rather than a standard deviation.
| Name | Required | Description | Default |
|---|---|---|---|
| budget_id | No | Budget ID. Omit to use the last-used budget. | |
| since_date | No | Start of detection window in YYYY-MM-DD format. Defaults to 30 days ago. | |
| sensitivity | No | Detection sensitivity: low (3-sigma), medium (2-sigma), high (1.5-sigma). | medium |
| history_months | No | Months of history to build baseline statistics from. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark the tool as read-only and idempotent. Description adds critical behavioral details: baseline comparison with self-exclusion, floor scaling when history is near-constant, and explains scale_basis/scale_multiple. No contradictions with annotations.
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, front-loaded with actionable purpose. Every sentence adds unique information with zero redundancy or filler.
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?
No output schema, but tool complexity is moderate. Description covers detection mechanics well, though missing details on return format (e.g., how anomalies are reported). Still sufficiently complete for agent decision-making.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. Description adds value by explaining the algorithmic context (floor scaling, sigma use) that enriches parameter meaning beyond schema descriptions, especially for sensitivity and history_months.
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 explicitly states 'Find unusual transactions' and enumerates specific anomaly types (abnormal amounts, large charges from new payees, potential duplicates). Clearly distinguishes from sibling tools like search_transactions or detect_recurring_charges.
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?
Implied usage for detecting transaction anomalies but lacks explicit when-to-use or when-not-to-use guidance. No mention of alternatives or exclusions, leaving the agent to infer context from sibling list.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Identify subscriptions and recurring charges from transaction patterns. Analyzes transaction history to detect regular outflows, estimates frequency, flags price changes, and cross-references with scheduled transactions. Returns create_scheduled_actions for unmatched recurring charges (suggestions only).
| Name | Required | Description | Default |
|---|---|---|---|
| budget_id | No | Budget ID. Omit to use the last-used budget. | |
| history_months | No | How many months of history to analyze. | |
| include_matched | No | Include recurring charges that already have a matching scheduled transaction. | |
| min_occurrences | No | Minimum number of transactions to qualify as recurring. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds meaningful behavioral context: it cross-references with scheduled transactions, returns suggestions only ('create_scheduled_actions for unmatched recurring charges (suggestions only)'), and flags price changes. This extra detail helps the agent understand the tool's behavior beyond annotations.
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 concise: two sentences, front-loaded with the main purpose, and the second sentence adds key details (cross-references, suggestions). No superfluous words, every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only analysis tool with no output schema, the description covers core functionality (analysis, frequency, price changes, cross-referencing, suggestions). It could mention the return structure more explicitly, but overall it provides sufficient context given the tool's complexity and the rich parameter descriptions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for all 4 parameters. The description adds marginal value by implying the role of history_months and min_occurrences in analysis, but does not provide additional specifics beyond what the schema already offers. Baseline 3 is appropriate given full schema coverage.
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: 'Identify subscriptions and recurring charges from transaction patterns.' It details specific actions: analyzing history, estimating frequency, flagging price changes, and cross-referencing with scheduled transactions. This distinguishes it from siblings like detect_anomalies (which detects anomalies) and search_transactions (which searches for transactions).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for detecting regular outflows and subscriptions but does not explicitly state when to use this tool versus alternatives like search_transactions or detect_anomalies. No 'when not to use' guidance is provided, making it somewhat vague for an agent deciding between sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get accounts with optional filtering by type, on-budget flag, and closed state.
| Name | Required | Description | Default |
|---|---|---|---|
| type | No | Filter by account type. | |
| budget_id | No | Budget ID. Omit to use the last-used budget. | |
| on_budget | No | ||
| include_closed | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, which cover behavioral traits. The description adds only the filtering behavior, which is expected. No additional behavioral context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence of 13 words, front-loaded with the verb and resource. No wasted words; every part earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the low complexity (4 non-required parameters, no output schema, no nested objects), the description adequately specifies the tool's purpose and filters. The lack of output format is acceptable for a straightforward list tool, but could optionally mention return type.
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 50% (2 of 4 parameters described). The description mentions the filtering parameters but does not add significant meaning beyond the schema. For undocumented parameters (on_budget, include_closed), it merely names them without explaining their values or effects.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get' and the resource 'accounts', and lists the filtering options (type, on-budget flag, closed state). It distinguishes itself from sibling tools like list_budgets or search_transactions by focusing on 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?
There is no explicit guidance on when to use this tool versus alternatives. The usage is implied by the tool name and description, but no when-not or alternative tool references are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Single-call budget snapshot and diagnostic. Surfaces net worth, account totals by type, month totals, overspent categories, underfunded targets, credit card payment gaps, uncategorized/unapproved transaction counts, and Ready to Assign status with severity-rated issues. Note: the YNAB API does not expose whether overspending happened on cash or credit; judge that from the credit card payment gaps and the transactions themselves.
| Name | Required | Description | Default |
|---|---|---|---|
| month | No | Month in YYYY-MM-DD format (use first day of month). Defaults to current month. | |
| budget_id | No | Budget ID. Omit to use the last-used budget. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds valuable behavioral context by noting a YNAB API limitation about distinguishing cash vs credit overspending, which helps the agent interpret results correctly.
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 with zero wasted words. The first sentence immediately states what the tool does, and the second adds an important caveat. Perfectly front-loaded and concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Without an output schema, the description compensates by listing key result components (net worth, account totals, month totals, etc.). It also addresses a data limitation, but could be slightly more explicit about the return format or scope.
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?
Both parameters have descriptions in the schema (100% coverage). The description adds specifics like 'use first day of month' for month and 'use last-used budget' for budget_id, enhancing understanding beyond the schema's generic 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 starts with 'Single-call budget snapshot and diagnostic,' clearly stating the tool's purpose as a comprehensive read-only overview. It lists specific outputs like net worth, account totals, and overspent categories, making it distinct from sibling tools like get_accounts or get_spending_analysis.
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 the tool is for a broad budget health check but does not explicitly state when to use it versus alternatives like get_spending_analysis or get_monthly_budget. There are no exclusion criteria or 'when not to use' guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Monthly income vs expense breakdown with savings rate calculation and trend detection across months. The in-progress current month is listed marked partial, and months predating the budget are listed marked no_data; both are excluded from averages and the trend. trend is null when fewer than two complete months are available (e.g. months=2 mid-month, or a budget younger than the window) rather than reporting a fabricated flat rate.
| Name | Required | Description | Default |
|---|---|---|---|
| months | No | Number of months to analyze (2-12). | |
| budget_id | No | Budget ID. Omit to use the last-used budget. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds significant behavioral context beyond annotations, including how partial months are marked, exclusions from averages and trend, and conditions for null trend. No contradiction with annotations.
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, front-loaded with purpose, followed by important behavioral details. 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?
The description adequately explains the output's key aspects (breakdown, savings rate, trend) but does not detail the response structure (e.g., array of month objects). Given no output schema, it is mostly 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% and the description does not add meaning beyond the schema's parameter descriptions (months range, budget_id optional).
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 provides a monthly income vs expense breakdown with savings rate and trend detection, which is specific and distinct from sibling tools like get_spending_trends or get_budget_health.
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 explains edge cases (partial months, no_data, null trend) but does not explicitly guide when to use this tool versus alternatives like get_spending_analysis or get_spending_trends.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Audit feed of money moved between categories or to/from Ready to Assign, including moves made in the YNAB apps — the only place the history behind each category's budgeted amount is visible. Use it to explain why a budgeted amount changed, or to see which moves were already made this month before proposing new ones. Movements performed together as one action share a group with its own note.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum movements to return, newest first. Defaults to 50. | |
| month | No | Restrict to one month, YYYY-MM-DD format (use first day of month). Omit for all months. | |
| budget_id | No | Budget ID. Omit to use the last-used budget. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, which tell the agent this tool is safe and idempotent. The description adds that movements performed together share a group with its own note, which is a useful behavioral detail but does not fundamentally change the risk profile. With annotations covering the main behavioral transparency needs, the description's extra value is moderate.
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 three sentences long, each serving a distinct purpose: first introduces what the tool is, second explains when to use it, third notes a grouping behavior. There is no redundancy or waste. It is front-loaded with the core 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 that the tool has only optional parameters, rich annotations (read-only, idempotent), and no output schema, the description provides sufficient context for an agent to understand what the tool returns and how to use it. It explains the nature of the data (audit feed of moves) and the grouping behavior, which is enough for correct invocation.
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 100% coverage, meaning all parameters (limit, month, budget_id) are described with sufficient detail in the schema itself. The description does not add new semantics for parameters beyond what the schema provides. Thus, the baseline 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 it is an 'audit feed of money moved between categories or to/from Ready to Assign.' It explains the specific purpose: showing the history behind each category's budgeted amount, which distinguishes it from sibling tools like search_transactions (which searches individual transactions) and get_monthly_budget (which shows budget amounts, not movements).
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 provides use cases: 'Use it to explain why a budgeted amount changed, or to see which moves were already made this month before proposing new ones.' This gives clear context for when to invoke the tool. While it does not explicitly state when not to use it, the purpose is sufficiently distinct from siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a month overview with income/budgeted/activity totals and per-category budget figures (budgeted, activity, balance) with overspending flags. Returns all visible categories by default — set include_hidden=true to include hidden ones. Categories with no activity show zeroes. No target data.
| Name | Required | Description | Default |
|---|---|---|---|
| month | No | Month in YYYY-MM-DD format (use first day of month). Defaults to current month. | |
| budget_id | No | Budget ID. Omit to use the last-used budget. | |
| include_hidden | No | Include hidden categories in the monthly budget output. Defaults to false for a cleaner review surface. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, openWorld, idempotent, and non-destructive hints. The description adds value by disclosing overspending flags, zeroes for inactive categories, and the absence of target data, going beyond annotations.
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 sentences, front-loaded with core purpose, then details on hidden categories and zeroes, then a note about no targets. Every sentence adds value; no redundancy.
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 3 parameters, no output schema, and moderate complexity, the description covers return values (income/budgeted/activity totals, per-category budget figures with overspending flags), behavior for hidden categories and zeroes, and what is excluded (target data). It is nearly complete but could specify top-level totals more explicitly.
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 parameter descriptions. The description adds context: month defaults to current month, budget_id defaults to last-used, include_hidden defaults to false for cleaner review. This enhances understanding beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get a month overview with income/budgeted/activity totals and per-category budget figures', specifying the verb and resource. It distinguishes from sibling tools like list_budgets (list budgets) and get_targets (target data) by noting 'No target data'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides context like 'Returns all visible categories by default' and 'set include_hidden=true to include hidden ones', and explicitly states 'No target data', implying use get_targets for that. However, it does not explicitly name alternatives or state when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get scheduled transactions with optional account/category filtering.
| Name | Required | Description | Default |
|---|---|---|---|
| budget_id | No | Budget ID. Omit to use the last-used budget. | |
| due_after | No | Only include transactions with next due date on or after this date (YYYY-MM-DD). | |
| account_id | No | ||
| due_before | No | Only include transactions with next due date on or before this date (YYYY-MM-DD). | |
| category_id | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, ensuring the agent knows it's safe. The description adds that filters are optional but does not disclose return format, pagination, or ordering, providing only marginal additional transparency.
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 concise, consisting of a single sentence with no redundant information. However, it could be slightly more informative without adding length, e.g., mentioning that results are returned in a list format.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no output schema, and the description does not explain the structure of the response or any limitations like pagination. For a retrieval tool with multiple optional filters, this leaves significant gaps in understanding the tool's behavior.
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 60% with three of five parameters described. The description adds meaning to account_id and category_id by labeling them as filter options, but does not cover the date range parameters (due_after, due_before) or budget_id in detail. It thus provides some semantic value beyond the schema but not fully comprehensive.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get' and resource 'scheduled transactions', indicating retrieval. It mentions optional filtering, but does not explicitly differentiate from sibling tool 'search_transactions' which might also list scheduled transactions. However, the name and context are sufficient for basic understanding.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool over alternatives such as 'search_transactions' or 'list_undo_history'. The description lacks any contextual cues for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Aggregate spending over a date range and rank by category/payee for quick insights. Optionally set time_granularity to also bucket the same spending over time (daily, weekly, day-of-week, week-of-month) to see when money is spent.
| Name | Required | Description | Default |
|---|---|---|---|
| top_n | No | ||
| group_by | No | category | |
| budget_id | No | Budget ID. Omit to use the last-used budget. | |
| since_date | Yes | Date in YYYY-MM-DD format. | |
| until_date | No | Date in YYYY-MM-DD format. | |
| account_ids | No | ||
| category_ids | No | ||
| time_granularity | No | Also bucket the same spending over time (daily, weekly starting Monday, day-of-week, or week-of-month) and include it as by_time in the result. | |
| include_transfers | No | Include internal account transfers in results. Defaults to false since transfers inflate spending totals. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, so the safety profile is clear. The description adds that the tool provides aggregated ranking and optional time bucketing. It does not disclose pagination, performance implications of large date ranges, or how the 'top_n' parameter affects results beyond what is in the schema.
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 core purpose, and adds the key optional feature in the second sentence. 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?
With 9 parameters, no output schema, and no discussion of filtering or result structure, the description is incomplete. It explains the main ranking and time bucketing but omits important filtering capabilities (accounts, categories, transfers, top_n limit). The annotations provide safety context but not operational 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 56%, with some parameters (budget_id, date formats, time_granularity, include_transfers) documented in the schema. The tool description adds meaning for time_granularity and implies group_by via 'rank by category/payee', but does not explain top_n (ranking limit) or filtering parameters like account_ids and category_ids. Thus, it partially compensates for the schema gaps.
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 clear verbs ('aggregate', 'rank') and specifies the resource ('spending') and scope ('over a date range'). It mentions optional time granularity. However, it does not explicitly distinguish from sibling tools like search_transactions or get_spending_trends, which also deal with spending data.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. The phrase 'for quick insights' implies a summary use case, but there is no explicit when-to-use/when-not-to-use or mention of alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Multi-month spending time series with trend detection. Groups spending by category, payee, or category group and identifies increasing/decreasing patterns. The in-progress current month is included in the series marked partial, but excluded from trend labels, monthly averages, and moving averages. Trend fields are null when fewer than two complete months are available rather than reporting a fabricated flat trend.
| Name | Required | Description | Default |
|---|---|---|---|
| top_n | No | Number of top entities to include in results. | |
| months | No | Number of months to analyze (2-12). | |
| group_by | No | How to group spending data. | category |
| budget_id | No | Budget ID. Omit to use the last-used budget. | |
| category_ids | No | Limit analysis to specific category IDs. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate read-only, idempotent, and non-destructive behavior. The description adds substantial value by disclosing that the in-progress month is included as partial but excluded from trends, and that trend fields are null when fewer than two complete months exist. This goes beyond annotations and prevents misinterpretation.
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 efficiently states the tool's purpose and functionality, and the second clarifies important edge-case behaviors. Every sentence adds value without redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 5 optional parameters and no output schema, the description covers time series behavior, grouping, trend detection, handling of the current month, and null-trend conditions. It provides sufficient context for an agent to understand what the tool does and its data requirements.
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 the schema already documents all parameters. The description mentions grouping by category, payee, or category_group, which overlaps with the schema's enum for group_by. It adds minimal new semantic information beyond what the schema provides, meriting the baseline score of 3.
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 provides 'multi-month spending time series with trend detection' and specifies grouping options, distinguishing it from siblings like get_spending_analysis. The verb 'get' and resource 'spending trends' are specific and unambiguous.
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 trend analysis over time but does not explicitly state when to use this tool versus siblings like get_spending_analysis. It lacks when-not-to-use guidance and does not mention alternatives, though it does provide important context about the current month and data requirements.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get categories with target progress details only: target type, amount, date, underfunded amount, months remaining, and percentage complete. Use this when you need target-specific guidance rather than monthly budget balances. Categories without targets return null target fields rather than being omitted.
| Name | Required | Description | Default |
|---|---|---|---|
| month | No | Month in YYYY-MM-DD format (use first day of month). Scopes target percentage_complete calculation. Defaults to current month. | |
| group_id | No | ||
| budget_id | No | Budget ID. Omit to use the last-used budget. | |
| include_hidden | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only, open-world, idempotent, non-destructive. The description adds value by specifying that categories without targets return null fields rather than being omitted, and that month scopes percentage calculation.
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: first lists outputs, second gives usage guidance. No fluff, front-loaded with key 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?
The description lists target fields and handling of categories without targets. No output schema exists, so the description adequately covers return structure. Missing details like pagination are acceptable for this read-only 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?
Schema description coverage is 50%, with month and budget_id described. The description adds context for month (scopes percentage) but not for group_id or include_hidden. Partial compensation for low coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves categories with target progress details, listing specific fields. It distinguishes from sibling tools like get_monthly_budget by focusing on target-specific guidance.
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 says when to use (target-specific guidance) and contrasts with monthly budget balances. It also clarifies behavior for categories without targets, providing clear context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List available YNAB budgets with key metadata.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds no additional behavioral context beyond the obvious listing behavior, so it does not enhance transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no wasted words, front-loaded with the action and resource. Perfectly concise for a zero-parameter tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description does not specify the return format or what 'key metadata' includes. With no output schema, more detail about the listing contents would 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?
No parameters exist, so baseline is 4. The description does not need to add parameter detail, and it correctly omits any unnecessary information.
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 YNAB budgets with key metadata, specifying verb and resource. However, it does not fully distinguish from sibling tools like get_budget_health, and 'key metadata' is vague.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like get_budget_health or sync_budget_data. The description provides no context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get all categories with their group hierarchy, IDs, and names. No budget figures or target data — lightweight and fast. Use this to resolve category names to IDs before write operations.
| Name | Required | Description | Default |
|---|---|---|---|
| group_id | No | ||
| budget_id | No | Budget ID. Omit to use the last-used budget. | |
| include_hidden | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description adds context beyond annotations: lightweight, fast, and returns specific fields. No contradiction with readOnly, idempotent, or openWorld hints.
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, front-loaded with the core purpose, no extraneous 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?
Covers return structure and performance, but omits detail on default behavior for budget_id and impact of include_hidden.
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 low (33%), and description does not explain parameters like group_id or include_hidden, leaving ambiguity for those fields.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves categories with group hierarchy, IDs, and names, distinguishing it from siblings that include budget figures or target data.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states use case 'resolve category names to IDs before write operations', and implies alternatives for financial data, but doesn't list alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List undoable operations for a budget.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum entries to return. Defaults to 20. | |
| offset | No | Entries to skip before returning results, for paging. | |
| budget_id | No | Budget ID. Omit to use the last-used budget. | |
| include_undone | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds no additional behavioral context (e.g., data freshness, sorting, or what qualifies as 'undoable'), so it meets the baseline without enrichment.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that clearly states the tool's purpose. Every word earns its place with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no output schema and moderate parameter count, the description is overly brief. It does not explain the return format, pagination behavior, or the meaning of 'undoable operations,' leaving gaps for the agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 75% schema coverage, the schema already describes most parameters. The description adds no parameter details, so it does not improve semantic understanding beyond what the schema provides. Baseline score 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 states 'List undoable operations for a budget,' which clearly identifies the action and resource. It implicitly distinguishes from the sibling tool 'undo_operations' by focusing on listing rather than performing actions, but does not explicitly contrast them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like 'undo_operations.' There is no mention of prerequisites, context, or exclusions, leaving the agent to infer usage from context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run one or more transaction searches in a single call with rich filters and sorted results.
| Name | Required | Description | Default |
|---|---|---|---|
| queries | Yes | ||
| budget_id | No | Budget ID. Omit to use the last-used budget. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description does not need to repeat safety traits. It adds minimal behavioral context beyond 'rich filters' and sorting, but does not contradict annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is efficient and front-loaded, containing no fluff. Every word contributes to the 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 the complexity of the tool (multiple queries, many filter options, no output schema), the description is too brief. It omits details like default budget, pagination, and output format, leaving the agent underinformed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 50% schema coverage, the description does not add detail about parameters; it only says 'rich filters'. The schema carries most of the burden, but the high-level description fails to compensate for the missing parameter documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool runs transaction searches with rich filters and sorting, and can handle multiple searches in a single call. It distinguishes well from sibling tools like list_budgets or get_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 mentions 'in a single call' which hints at batching, but does not explicitly guide when to use this tool over alternatives like get_accounts or create_transactions. No exclusions or when-not-to-use are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Set budgeted amounts for one or more category/month pairs in a single request. Costs up to two YNAB API calls per pair against the 200/hour rate limit (the prior amount is read before it is written, and the read may be served from cache) — keep batches small.
| Name | Required | Description | Default |
|---|---|---|---|
| budget_id | No | Budget ID. Omit to use the last-used budget. | |
| assignments | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false), the description reveals that the prior amount is read before writing and the read may be cached. This adds valuable internal behavior context, such as the read-before-write pattern and cache usage, which annotations do not cover.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence with a parenthetical that packs the key behavioral detail. Every word contributes meaning, and the critical usage warning is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers purpose, rate limiting, batch size advice, and internal behavior. It lacks mention of the optional budget_id parameter or return values, but given no output schema and moderate complexity, it is reasonably complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 50% (budget_id has a description, but assignments as a whole does not, and category_id within assignments lacks a description). The tool description does not elaborate on parameters beyond mentioning 'category/month pairs' in passing, failing to compensate for the incomplete schema. It does not add new semantic information for any parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool sets budgeted amounts for category/month pairs in a single request, using a specific verb ('set') and resource ('budgeted amounts'). This distinguishes it from sibling tools like set_category_targets, which set targets instead of budgets.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly warns about the cost of two API calls per pair and the 200/hour rate limit, advising to keep batches small. This provides clear usage guidance, though it does not explicitly contrast with alternatives or state when not to use the tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create or update targets on one or more categories. Returns previous state for each category.
| Name | Required | Description | Default |
|---|---|---|---|
| targets | Yes | ||
| budget_id | No | Budget ID. Omit to use the last-used budget. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide idempotentHint=true, destructiveHint=false, readOnlyHint=false. The description adds that it returns previous state, which is useful. However, it does not disclose any side effects beyond mutation, permissions, or rate limits. Since annotations cover the safety profile, the description adds modest value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two sentences, no wasted words, front-loaded with the core action. It efficiently conveys the primary purpose and return value.
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 complexity (modifies targets, has nested objects in schema) and absence of output schema, the description mentions returning previous state but not its format. It also does not note the budget_id default behavior (though schema does). Still, it is largely complete for a moderately complex tool with good annotations.
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 50% (the schema itself describes nested properties well). The description does not elaborate on parameters ('targets', 'budget_id') beyond the schema. It adds no extra meaning about parameter usage or formats, so it does not compensate for the coverage gap. Baseline 3 is appropriate as schema carries the burden.
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 creates or updates targets on categories and returns previous state. It uses specific verbs ('Create or update') and resource ('targets on... categories'), distinguishing it from siblings like get_targets (read-only) and set_category_budgets (different operation).
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 explicitly specify when to use this tool versus alternatives. Context from sibling names implies it is for setting category targets, but no 'when-not' or preconditions are provided. The purpose is clear enough to infer usage, but guidance is lacking.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Analyze uncategorized (and optionally unapproved) transactions using payee history, amount patterns, and scheduled transaction matching. Returns categorization suggestions with confidence levels — does NOT apply changes. update_actions (for update_transactions) contains only suggestions at or above action_confidence (default high); review lower-confidence suggestions manually before applying them.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum transactions to analyze. Defaults to 50. | |
| approve | No | When true, update_actions will include approved: true so categorization and approval happen in one pass. Defaults to false so applying suggestions never silently approves transactions. | |
| budget_id | No | Budget ID. Omit to use the last-used budget. | |
| since_date | No | Date in YYYY-MM-DD format. | |
| history_months | No | ||
| action_confidence | No | Minimum confidence for a suggestion to be included in update_actions. Defaults to high. Lower-confidence suggestions still appear in suggestions for manual review. | |
| include_transfers | No | Include internal account transfers in results. Defaults to false since transfers cannot be categorized. | |
| include_unapproved | No | ||
| include_approved_uncategorized | No | Include approved transactions that have no category. Defaults to true — set to false to only see unapproved transactions. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, and the description explicitly states 'does NOT apply changes', consistent with a read-only operation. It adds valuable behavioral details such as how confidence thresholds affect which suggestions appear in update_actions, and that transfers are excluded since they cannot be categorized.
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 consists of three well-structured sentences with no fluff. The first sentence states the core purpose, the second clarifies what does not happen, and the third provides actionable guidance on confidence levels and manual review.
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 complexity (9 parameters, no output schema), the description adequately covers the core behavior, confidence mechanism, relationship with update_transactions, and key caveats (transfers cannot be categorized). It could be more explicit about the full output format, but it is sufficiently complete for an AI agent.
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 78% (7 of 9 parameters have descriptions), so baseline is 3. The description does not add any parameter-level detail beyond what the schema already provides.
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 analyses uncategorized transactions using payee history, amount patterns, and scheduled transaction matching, returning suggestions with confidence levels. It distinguishes itself from sibling tools like update_transactions by noting it does NOT apply changes.
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 explains when to use the tool (to get categorization suggestions) and what it does not do (does not apply changes). It also hints at using update_transactions with the update_actions output, but does not explicitly list alternatives or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Force a fresh sync of all cached budget data (accounts, categories, payees, transactions, scheduled transactions) from the YNAB API. Use this when you suspect external changes (e.g., bank imports, mobile app edits) that may not be reflected yet. Costs up to 6 API requests against the 200/hour rate limit.
| Name | Required | Description | Default |
|---|---|---|---|
| budget_id | No | Budget ID. Omit to use the last-used budget. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnly, openWorld, idempotent, and non-destructive. The description adds critical behavioral details: it forces a sync, costs API requests, and respects a rate limit. No contradiction with annotations.
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 three sentences, each adding value. The first sentence states the core purpose, the second provides usage context, and the third discloses cost and rate limits. 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 optional param, no output schema) and the rich annotations, the description covers purpose, usage, and behavioral constraints completely. No gaps remain.
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. The description does not repeat parameter info, but the schema already handles it. No additional meaning is needed beyond what the schema provides.
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 forces a fresh sync of all cached budget data, listing specific types of data. It distinguishes itself from sibling tools that list or modify data, as this is a sync/refresh operation.
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 says to use this tool when external changes are suspected. It does not state when not to use it, but the context is clear. It also mentions the cost (up to 6 API requests) and rate limit, providing useful usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Undo one or more prior operations with conflict detection. Use force=true to override conflicts.
| Name | Required | Description | Default |
|---|---|---|---|
| force | No | ||
| undo_history_ids | Yes | The undo entry IDs to undo (returned as undo_history_ids by write tools). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds conflict detection detail over annotations. But lacks explanation of conflict behavior, side effects, or reversibility. Annotations already indicate destructiveHint.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences, front-loaded with main purpose.
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?
No output schema, missing return value description. Adequate for simple undo but not fully detailing conflict resolution or failure modes.
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?
Description adds meaning to 'force' parameter (override conflicts). Schema already documents undo_history_ids. With 50% coverage, description provides useful supplement.
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 the tool undoes prior operations and mentions conflict detection. Distinguishes from list_undo_history which lists operations.
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?
Lacks explicit when-to-use guidance. Mentions force=true usage but does not advise on prerequisites or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update one or more scheduled transactions. Each successful update is undoable and costs one YNAB API call (no bulk endpoint exists).
| Name | Required | Description | Default |
|---|---|---|---|
| budget_id | No | Budget ID. Omit to use the last-used budget. | |
| transactions | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate a write operation with idempotency and no destruction. The description adds that updates are undoable and reveals per-update API cost, providing context beyond annotations.
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 the purpose and add critical behavior/cost info without redundancy. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers purpose and key behaviors but omits return values, error conditions, and the 50-item array limit from schema. For a write operation with nested parameters, more completeness would help.
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 50%, but the tool description adds no parameter details. It fails to explain the transactions array structure or individual fields, leaving the agent underinformed.
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 'Update one or more scheduled transactions,' specifying the verb and resource. It distinguishes from siblings like create and delete, but could better differentiate from update_transactions for regular 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 notes that each update is undoable and costs one API call, and mentions no bulk endpoint exists. However, it does not explicitly guide when to use this tool versus create or delete alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update one or more existing transactions in a single call. Each successful update is undoable.
| Name | Required | Description | Default |
|---|---|---|---|
| budget_id | No | Budget ID. Omit to use the last-used budget. | |
| transactions | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate idempotency (idempotentHint: true) and non-destructiveness (destructiveHint: false). The description adds the fact that updates are undoable, which is valuable beyond annotations. However, it does not disclose other behavioral traits like permissions, rate limits, or partial failure handling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with two sentences, no wasted words, and all information is relevant to tool usage. It is easily parseable by an AI agent.
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 complexity of the input schema (many optional fields, subtransactions) and the lack of an output schema, the description is minimal. It does not explain return values, error behavior, or how partial updates are handled. While annotations provide some safety cues, the description could be more informative for a mutation 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?
The input schema has 50% description coverage, meaning many parameters already have meaningful descriptions. The tool description itself does not add any additional parameter semantics beyond what the schema provides. Thus, it meets the baseline but does not exceed it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'update' and the resource 'transactions', with the scope 'one or more existing transactions in a single call'. It effectively distinguishes this tool from sibling tools like create_transactions and delete_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 mentions that each successful update is undoable, hinting at rollback capabilities, but it does not explicitly state when to use this tool versus alternatives (e.g., batch updates via other tools) or when not to use it. No prerequisites or exclusions are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Each tool targets a distinct area (budgets, accounts, transactions, categories, scheduled transactions, analysis, etc.). Even similar-sounding tools like get_spending_analysis, get_spending_trends, and get_income_expense_summary are clearly differentiated by their descriptions and scope.
Most tools follow a verb_noun pattern (list_, get_, create_, update_, delete_, set_, etc.). However, there are minor inconsistencies: 'list_categories' vs 'get_targets', 'search_transactions' deviates, and 'undo_operations' vs 'list_undo_history' use different prefixes.
With 26 tools, the count is above the typical 3-15 range, but given the complexity of the YNAB domain (budgets, accounts, transactions, scheduled transactions, categories, targets, analysis, anomaly detection), each tool earns its place. It is slightly heavy but not excessive.
The tool surface covers most core YNAB operations: budgets, accounts, transactions, scheduled transactions, categories, targets, undo, sync, and multiple analysis tools. Minor gaps exist (e.g., no create_category or delete_category), but these are likely API limitations, and the set is comprehensive for typical usage.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Track expenses, budgets, balances, transfers, and multi-currency reports with OAuth-secured tools.
Personal finance for AI agents: accounts, budgets, goals, 9-strategy debt payoff, reports. OAuth 2.1
Search, query, and update budgets, transactions, contacts, and purchase orders in Saturation.
Personal-finance workspace for AI agents: accounts, spending, budgets, goals, and investments.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/Maronato/ynab-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
