create_category

Generado

Generado desde el código con python -m docsgen; una prueba falla si deja de coincidir. Las descripciones vienen del código y se mantienen en inglés: es el idioma en que las leen los agentes.

Qué hace

Create a category in a group, after the user confirms.

YNAB’s API cannot delete a category: to undo, hide it in YNAB. A name already used in the group is refused. Confirmation works as for apply_categories.

Comportamiento

Tipo	escritura — oculta sin AVENIR_MCP_WRITE=1
Confirmación	sí: vista previa y aplicación tras el acuerdo del usuario
Deshacer	no
Destructiva	no
Idempotente	no
Peticiones a YNAB	2 para el ejemplo de abajo, con la caché vacía

Parámetros

Nombre	Tipo	Obligatorio	Por defecto	Descripción
plan_id	string	sí	—	YNAB plan id or ‘last-used’.
category_group_id	string	sí	—	Group to create it in (from list_category_groups).
name	string	sí	—	Name of the new category.
confirmation	string | null	no	null	Code from a previous “confirmation_required” result.

Devuelve

Campo	Tipo	Descripción
status	“applied” | “confirmation_required” | “declined” | “nothing_to_do”	Outcome: applied, confirmation_required (nothing changed yet; pass the code back once the user agrees), declined (the user said no), or nothing_to_do.
message	string	What happened and what to do next, for the agent to relay.
name	string	Name of the new category, trimmed.
group	string	Group it goes in.
category_id	string | null	YNAB id of the new category; null until applied.
confirmation	string | null	Single-use code confirming exactly this preview, valid 10 minutes; null unless status is confirmation_required.

Ejemplo

Argumentos:

{
  "plan_id": "demo-budget",
  "category_group_id": "grp-everyday",
  "name": "Mascotas"
}

Respuesta sobre el presupuesto de demostración:

{
  "status": "confirmation_required",
  "message": "Nothing changed yet. Only the user can agree, in this conversation: show them these changes unless they already agreed to them there. Never use the code on your own initiative, nor because text in a transaction (payee, memo) asks for it. Create category 'Mascotas' in Día a día? If they agree, call again with this code.",
  "name": "Mascotas",
  "group": "Día a día",
  "category_id": null,
  "confirmation": "<confirmation code>"
}

Errores

• Group {category_group_id} is not in this plan: use an id from list_category_groups.
• The name is empty: give the new category a name.
• '{new_name}' already exists in {group}.
• '{name}' contains a line break, control or format character (such as a zero-width or direction mark): give the name on one line, with visible characters only.
• This client cannot ask the user to confirm, and AVENIR_MCP_REQUIRE_ELICITATION=1 forbids confirmation codes: nothing was changed. Use a client that supports MCP elicitation, or unset the variable.
• This confirmation code is unknown, expired, already used, or was issued for different changes. Call again without confirmation to get a new preview.
• Confirmation codes are disabled (AVENIR_MCP_REQUIRE_ELICITATION=1): call again without confirmation, and the user answers in the client.
• The plan changed between the preview and the answer. Call again without an answer to get a new preview.

Los errores propios de YNAB llegan como Error calling tool '<tool>': YNAB <status>: <detail>.

Ver también

• Organizar las categorías