YNAB MCP Server

Search Categories

search_categories

Read-onlyIdempotent

Search YNAB categories by name or group with case-insensitive, tokenized matching. Returns ranked results with matched terms, or falls back to listing all categories when no matches found.

Instructions

Search categories by name and category-group name (case-insensitive; multi-word queries are tokenized and OR-matched, ranked with whole-phrase and name hits first). Results report matched_on and matched_terms. No synonym expansion; if a search is empty, fall back to list_categories.

Input Schema

TableJSON Schema

Name	Required	Description
`query`	Yes	Category or group name to search for. Multi-word queries are OR-matched per word (e.g. 'work expenses' matches '💻 Work Expenses (Oliver LLC)' and anything in a 'Business Expenses' group).
`budgetId`	No	Budget ID (uses default if not provided)
`includeHidden`	No	If true, also search hidden categories and hidden category groups (default false).

Output Schema

TableJSON Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv5.4.0Sep 15, 2026
- removedOutput schema / properties / result / description
```
Removed value: -"Structured result returned by Search Categories."
```

Changed2 schema fields changedv5.2.0Aug 29, 2026

addedInput schema / properties / includeHidden

Added value: +{
+  "description": "If true, also search hidden categories and hidden category groups (default false).",
+  "type": "boolean"
+}

changedInput schema / properties / query / description

Previous value: -"Partial category name to search for (e.g. 'work' matches '💻 Work Expenses (Oliver LLC)')"New value: +"Category or group name to search for. Multi-word queries are OR-matched per word (e.g. 'work expenses' matches '💻 Work Expenses (Oliver LLC)' and anything in a 'Business Expenses' group)."

Changed1 schema field changedv5.1.1Jul 21, 2026

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": false,
+  "properties": {
+    "result": {
+      "description": "Structured result returned by Search Categories."
+    }
+  },
+  "required": [
+    "result"
+  ],
+  "type": "object"
+}

First observedv2.0.0May 28, 2026

TDQS

A4.9/5.0

Behavior5/5

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

Annotations already declare read-only, idempotent, non-destructive behavior, and the description adds valuable context beyond that: case-insensitive matching, tokenized OR semantics, ranking order, matched_on/matched_terms reporting, and no synonym expansion. This gives an agent clear expectations about how results are produced and labeled. No contradiction with annotations exists.

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

Conciseness5/5

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

Two sentences deliver the core matching behavior, ranking rules, result reporting, and a fallback instruction. Every clause earns its place, and the most important information is front-loaded.

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 search tool with a full output schema and annotations covering safety and idempotency, the description is complete. Required query behavior, matching edge cases, hidden-category handling in the schema, and fallback routing are all present, leaving no material gap for a correct invocation.

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

Parameters4/5

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

Schema description coverage is 100%, so the baseline is 3, but the description enriches the query parameter with important semantics: case-insensitivity, tokenization, OR matching, and ranking behavior. budgetId and includeHidden remain adequately documented in the schema itself.

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

Purpose5/5

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

The first sentence names a precise verb-resource pair, "search categories", and narrows scope to name plus category-group name. It also names list_categories as the fallback, making the tool's role distinct from that sibling without opening the schema.

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

Usage Guidelines5/5

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

The description explicitly gives an alternative and a condition: "if a search is empty, fall back to list_categories". It frames search as the lookup entry point, and the resource-specific wording naturally distinguishes it from search_transactions and search_payees.

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