ynab-mcpb

by dizzlkheinz

Overview Schema Source Related Servers Discussions Admin

TypeScript

Local

ynab_update_category

Idempotent

Update the budgeted amount for a category in the current month, with a preview option before saving changes to YNAB.

Instructions

Update the budgeted amount for a category in the current month.

Args:

budget_id (string, optional): Budget UUID. Omit to use the default budget.
category_id (string, required): Category UUID.
budgeted_decimal (number, preferred): New funding amount in decimal currency units.
budgeted_milliunits (int, alternative): Explicit raw YNAB milliunits.
budgeted (int, deprecated): Backward-compatible alias for budgeted_milliunits.
dry_run (boolean, optional): Preview without saving. Default: false.

Returns: updated category with new budgeted, activity, balance.

Examples:

Budget $100: set budgeted_decimal=100.00
Already-converted data: set budgeted_milliunits=100000
Dry run: set dry_run=true

Errors:

"No default budget set" → run ynab_set_default_budget first

Write safety: call without confirmation_token to preview. The preview returns confirmation_token and confirmation_expires_at in its structured output (and in its text). Execute the identical validated request with that short-lived confirmation_token.

Input Schema

Name	Required	Description
`dry_run`	No
`budgeted`	No	Deprecated legacy alias for budgeted_milliunits. Use budgeted_decimal or budgeted_milliunits.
`budget_id`	No
`category_id`	Yes
`budgeted_decimal`	No	Preferred: category funding amount in decimal currency units (for example, 100.00).
`confirmation_token`	No	Short-lived, single-use token returned by the immediately preceding preview of this exact validated request. Omit, or pass null or an empty string, to preview.
`budgeted_milliunits`	No	Raw YNAB category funding amount in milliunits.

Output Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv0.32.0Nov 7, 2026

changedOutput schema / anyOf

Previous value: -[
-  {
-    "additionalProperties": false,
-    "properties": {
-      "action": {
-        "const": "ynab_update_category",
-        "type": "string"
-      },
-      "dry_run": {
-        "const": true,
-        "type": "boolean"
-      },
-      "request": {
-        "additionalProperties": false,
-        "properties": {
-          "budget_id": {
-            "type": "string"
-          },
-          "budgeted": {
-            "type": "number"
-          },
-          "category_id": {
-            "type": "string"
-          },
-          "month": {
-            "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
-            "type": "string"
-          }
-        },
-        "required": [
-          "budget_id",
-          "category_id",
-          "budgeted",
-          "month"
-        ],
-        "type": "object"
-      }
-    },
-    "required": [
-      "dry_run",
-      "action",
-      "request"
-    ],
-    "type": "object"
-  },
-  {
-    "additionalProperties": false,
-    "properties": {
-      "category": {
-        "additionalProperties": false,
-        "properties": {
-          "activity": {
-            "description": "Activity in dollars",
-            "type": "number"
-          },
-          "balance": {
-            "description": "Balance in dollars",
-            "type": "number"
-          },
-          "budgeted": {
-            "description": "Budgeted amount in dollars",
-            "type": "number"
-          },
-          "category_group_id": {
-            "description": "Category group ID",
-            "type": "string"
-          },
-          "category_group_name": {
-            "description": "Category group name",
-            "type": "string"
-          },
-          "deleted": {
-            "description": "Deleted flag",
-            "type": "boolean"
-          },
-          "goal_creation_month": {
-            "description": "Goal creation month",
-            "type": "string"
-          },
-          "goal_months_to_budget": {
-            "description": "Goal months to budget",
-            "type": "number"
-          },
-          "goal_overall_funded": {
-            "description": "Goal overall funded amount in dollars",
-            "type": "number"
-          },
-          "goal_overall_left": {
-            "description": "Goal overall left amount in dollars",
-            "type": "number"
-          },
-          "goal_percentage_complete": {
-            "description": "Goal percentage complete",
-            "type": "number"
-          },
-          "goal_target": {
-            "description": "Goal target amount in dollars",
-            "type": "number"
-          },
-          "goal_target_month": {
-            "description": "Goal target month",
-            "type": "string"
-          },
-          "goal_type": {
-            "description": "Goal type",
-            "type": "string"
-          },
-          "goal_under_funded": {
-            "description": "Goal underfunded amount in dollars",
-            "type": "number"
-          },
-          "hidden": {
-            "description": "Hidden flag",
-            "type": "boolean"
-          },
-          "id": {
-            "description": "Category ID",
-            "type": "string"
-          },
-          "name": {
-            "description": "Category name",
-            "type": "string"
-          },
-          "note": {
-            "description": "Category note",
-            "type": "string"
-          },
-          "original_category_group_id": {
-            "description": "Original category group ID",
-            "type": "string"
-          }
-        },
-        "required": [
-          "id",
-          "category_group_id",
-          "name",
-          "hidden",
-          "budgeted",
-          "activity",
-          "balance"
-        ],
-        "type": "object"
-      },
-      "updated_month": {
-        "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
-        "type": "string"
-      }
-    },
-    "required": [
-      "category",
-      "updated_month"
-    ],
-    "type": "object"
-  }
-]New value: +[
+  {
+    "additionalProperties": false,
+    "properties": {
+      "action": {
+        "const": "ynab_update_category",
+        "type": "string"
+      },
+      "confirmation_expires_at": {
+        "description": "Preview only: when confirmation_token expires (ISO 8601).",
+        "format": "date-time",
+        "type": "string"
+      },
+      "confirmation_token": {
+        "description": "Preview only: single-use token that executes this exact request when passed back as confirmation_token.",
+        "type": "string"
+      },
+      "dry_run": {
+        "const": true,
+        "type": "boolean"
+      },
+      "request": {
+        "additionalProperties": false,
+        "properties": {
+          "budget_id": {
+            "type": "string"
+          },
+          "budgeted": {
+            "type": "number"
+          },
+          "category_id": {
+            "type": "string"
+          },
+          "month": {
+            "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
+            "type": "string"
+          }
+        },
+        "required": [
+          "budget_id",
+          "category_id",
+          "budgeted",
+          "month"
+        ],
+        "type": "object"
+      }
+    },
+    "required": [
+      "dry_run",
+      "action",
+      "request"
+    ],
+    "type": "object"
+  },
+  {
+    "additionalProperties": false,
+    "properties": {
+      "category": {
+        "additionalProperties": false,
+        "properties": {
+          "activity": {
+            "description": "Activity in dollars",
+            "type": "number"
+          },
+          "balance": {
+            "description": "Balance in dollars",
+            "type": "number"
+          },
+          "budgeted": {
+            "description": "Budgeted amount in dollars",
+            "type": "number"
+          },
+          "category_group_id": {
+            "description": "Category group ID",
+            "type": "string"
+          },
+          "category_group_name": {
+            "description": "Category group name",
+            "type": "string"
+          },
+          "deleted": {
+            "description": "Deleted flag",
+            "type": "boolean"
+          },
+          "goal_creation_month": {
+            "description": "Goal creation month",
+            "type": "string"
+          },
+          "goal_months_to_budget": {
+            "description": "Goal months to budget",
+            "type": "number"
+          },
+          "goal_overall_funded": {
+            "description": "Goal overall funded amount in dollars",
+            "type": "number"
+          },
+          "goal_overall_left": {
+            "description": "Goal overall left amount in dollars",
+            "type": "number"
+          },
+          "goal_percentage_complete": {
+            "description": "Goal percentage complete",
+            "type": "number"
+          },
+          "goal_target": {
+            "description": "Goal target amount in dollars",
+            "type": "number"
+          },
+          "goal_target_month": {
+            "description": "Goal target month",
+            "type": "string"
+          },
+          "goal_type": {
+            "description": "Goal type",
+            "type": "string"
+          },
+          "goal_under_funded": {
+            "description": "Goal underfunded amount in dollars",
+            "type": "number"
+          },
+          "hidden": {
+            "description": "Hidden flag",
+            "type": "boolean"
+          },
+          "id": {
+            "description": "Category ID",
+            "type": "string"
+          },
+          "name": {
+            "description": "Category name",
+            "type": "string"
+          },
+          "note": {
+            "description": "Category note",
+            "type": "string"
+          },
+          "original_category_group_id": {
+            "description": "Original category group ID",
+            "type": "string"
+          }
+        },
+        "required": [
+          "id",
+          "category_group_id",
+          "name",
+          "hidden",
+          "budgeted",
+          "activity",
+          "balance"
+        ],
+        "type": "object"
+      },
+      "confirmation_expires_at": {
+        "description": "Preview only: when confirmation_token expires (ISO 8601).",
+        "format": "date-time",
+        "type": "string"
+      },
+      "confirmation_token": {
+        "description": "Preview only: single-use token that executes this exact request when passed back as confirmation_token.",
+        "type": "string"
+      },
+      "updated_month": {
+        "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
+        "type": "string"
+      }
+    },
+    "required": [
+      "category",
+      "updated_month"
+    ],
+    "type": "object"
+  }
+]

Changed4 schema fields changedv0.31.0Oct 29, 2026

addedInput schema / properties / confirmation_token / anyOf

Added value: +[
+  {
+    "minLength": 16,
+    "type": "string"
+  },
+  {
+    "const": ""
+  },
+  {
+    "type": "null"
+  }
+]

changedInput schema / properties / confirmation_token / description

Previous value: -"Short-lived, single-use token returned by the immediately preceding preview of this exact validated request."New value: +"Short-lived, single-use token returned by the immediately preceding preview of this exact validated request. Omit, or pass null or an empty string, to preview."

removedInput schema / properties / confirmation_token / minLength
```
Removed value: -16
```
removedInput schema / properties / confirmation_token / type
```
Removed value: -"string"
```

Changed5 schema fields changedv0.27.1Jul 12, 2026

addedInput schema / properties / budgeted / description

Added value: +"Deprecated legacy alias for budgeted_milliunits. Use budgeted_decimal or budgeted_milliunits."

addedInput schema / properties / budgeted_decimal

Added value: +{
+  "description": "Preferred: category funding amount in decimal currency units (for example, 100.00).",
+  "type": "number"
+}

addedInput schema / properties / budgeted_milliunits

Added value: +{
+  "description": "Raw YNAB category funding amount in milliunits.",
+  "maximum": 9007199254740991,
+  "minimum": -9007199254740991,
+  "type": "integer"
+}

addedInput schema / properties / confirmation_token

Added value: +{
+  "description": "Short-lived, single-use token returned by the immediately preceding preview of this exact validated request.",
+  "minLength": 16,
+  "type": "string"
+}

changedInput schema / required

Previous value: -[
-  "category_id",
-  "budgeted"
-]New value: +[
+  "category_id"
+]

Addedv0.26.9May 11, 2026

TDQS

A4.5/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare non-readOnly, idempotent, non-destructive, but the description goes much further: a two-step preview/confirm protocol, token single-use and expiry, a dry_run flag, the exact return shape, and a concrete error-to-remedy mapping. Nothing here contradicts idempotentHint or destructiveHint=false, since re-setting the same absolute amount is idempotent and reversible by setting another value.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the purpose, then Args/Examples/Errors/Write safety in a predictable order; the examples and the write-safety paragraph both earn their space. The Args block largely restates schema descriptions, which is mild redundancy, but the decimal-vs-milliunits guidance justifies it.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 7-parameter mutation tool with a confirmation flow, the description covers prerequisites (default budget), argument choice rules, error recovery, and the confirm step; an output schema exists so detailed return documentation is not required, and the brief returns line is sufficient. No material gaps remain for an agent to call this correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

At 57% schema coverage the description carries the load well, explaining budget_id defaults to the default budget, that budgeted_decimal is preferred over raw milliunits, that budgeted is a deprecated alias, and dry_run defaults to false. It also explains the confirmation_token semantics (omit/null/empty to preview), which the schema's one-liner alone would leave ambiguous in the execution flow.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The opening sentence gives a specific verb, resource, and scope: 'Update the budgeted amount for a category in the current month', which is distinct from any read-only category tool. It never explicitly contrasts itself with siblings such as ynab_get_category or ynab_list_categories, but those are obvious reads and there is no other budget-mutation sibling, so 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.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides concrete operational guidance: call without confirmation_token to preview, then re-execute the identical request with the returned short-lived token, and it routes to ynab_set_default_budget when the 'No default budget set' error occurs. It does not state when to prefer this over listing/reading categories first, but the when-to-use for the confirmation workflow is explicit.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server