YNAB MCP Server

Create category

create_category

Creates a YNAB category within a specified category group and can set an optional savings target, helping organize budget categories and goals.

Instructions

Create a category in a category group, optionally with a target.

Input Schema

Name	Required	Description
`name`	Yes	Category name (required)
`note`	No	Category note (optional)
`target_date`	No	Date the target amount should be reached, for a balance by a date. Cannot be combined with target_frequency (optional)
`target_amount`	No	Target amount in currency units. Setting it on a category with no target creates a monthly NEED target (optional)
`target_frequency`	No	Make a repeating NEED target of target_amount every "weekly", "monthly", or "yearly". Requires target_amount (optional)
`category_group_id`	Yes	Group to create the category in (required)
`target_needs_whole_amount`	No	For NEED targets, whether the whole target is needed every period (true) or the rollover counts toward it (false) (optional)

Output Schema

Name	Required	Description
`id`	Yes	Unique category identifier
`name`	Yes	Category name
`note`	No	Category notes
`activity`	No	Activity this month (negative = spending)
`assigned`	No	Amount assigned this month
`internal`	No	Whether YNAB manages this category itself. 'Inflow: Ready to Assign' is internal: categorize income to it.
`available`	No	Amount available to spend, including rollover
`target_date`	No	Date the target should be met, for targets with a date
`target_type`	No	Target type: NEED (needed for spending, refills each period), TB (have a balance), TBD (have a balance by a date), MF (fund monthly), DEBT (pay down a debt)
`target_amount`	No	Target amount
`category_group_id`	Yes	Category group ID
`target_underfunded`	No	Amount still needed this month to stay on track
`category_group_name`	No	Category group name
`target_overall_left`	No	Amount still needed to meet the target this period
`target_percentage_complete`	No	How much of the target is funded, as a percentage

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Oct 26, 2026

TDQS

C2.9/5.0

Behavior2/5

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

Annotations already declare it is a non-read-only, non-idempotent, non-destructive, closed-world write, so the safety profile is covered. The description adds nothing beyond that: no mention of uniqueness constraints on name, what happens if the group id is invalid, or the default behavior when target_amount is supplied without frequency (the schema notes a monthly NEED target is created).

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

Conciseness3/5

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

A single short sentence with no redundancy, but it is terse to the point of under-specification — the 'optionally with a target' clause is the only non-obvious content and it is left unexplored.

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

Completeness3/5

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

An output schema exists and the input schema is fully described, so most information is available elsewhere. However, for a 7-parameter creation tool with no annotations covering validation or defaults, the description should do more than one sentence to be considered complete.

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

Parameters3/5

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

Schema description coverage is 100%, so all seven parameters are already documented in the schema, including the target_* interaction rules. The description only gestures at the optional target without adding format or interaction detail beyond the schema; baseline 3 applies.

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?

States a specific verb and resource ('Create a category') plus its containment ('in a category group') and the optional target aspect. It is distinguishable from list_categories, update_category, and create_category_group at a glance, though it doesn't explicitly name those siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

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

No guidance on when to use this versus update_category (e.g. category must not already exist) or create_category_group. Nothing about prerequisites such as needing a valid existing category_group_id, and no exclusions are stated.

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