Skip to main content
Glama

add_spending_category

Create a spending or income category with its flow and kind when no existing one fits. Use it to add a missing budget category before recording expenses or income.

Instructions

Adds a new category. Call it only when no existing category fits, and tell the user which category you are creating. flow: expense (the default), active income (salary, business, a bonus) or passive income (dividends, coupons, interest, rent, benefits); it cannot be changed later. An expense category needs kind: mandatory (housing, utilities, food, insurance) or optional; an income one takes no kind and may be oneOff (a bonus, a tax refund). A name that exists in any letter case is refused with 409 category_exists: use the existing category instead.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "name": "<name>"
    },
    "name": "add_spending_category"
  }
}

Input Schema

NameRequiredDescriptionDefault
flowNoThe total the category allocates; default expense
kindNoOnly for an expense category, and needed there
nameYesThe category's name
oneOffNoOnly for an income category: income not expected every month

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A4.8/5.0
Behavior5/5

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

Goes well beyond the single readOnlyHint=false annotation: it warns that flow is immutable after creation ('it cannot be changed later'), that name collisions are case-insensitive and surface as 409 category_exists, and that kind is mandatory for expenses but forbidden for income. These are exactly the failure modes and permanence consequences an agent needs before mutating state.

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-loads the action, then the gating rule, then the parameter mechanics — a sound order. It is dense and semicolon-chained in places, but no sentence is filler; the only cost is readability from packing several constraints into one paragraph.

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?

With four parameters, no output schema, and only one annotation, the description carries the full burden and meets it: conditional parameter rules, immutability, the error code, and the correct conflict resolution are all covered. Nothing needed to invoke it correctly is missing.

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 coverage is 100% so the baseline is 3, and the description earns a bump by supplying concrete examples for each flow value (salary, dividends, rent), clarifying that expense is the default, and spelling out the conditional relationship between flow, kind, and oneOff. Some of this (kind only for expense) duplicates the schema's own text, so it is not purely additive.

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?

States a specific verb+resource ('Adds a new category') and then immediately scopes it against the other categories by instructing the agent to use an existing one when it fits. The flow/kind branching further pins down exactly what kind of category object this creates, distinguishing it from the sibling list/save tools.

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?

Gives an explicit gating rule ('Call it only when no existing category fits'), a user-facing obligation ('tell the user which category you are creating'), and a resolution path on conflict ('use the existing category instead'). When-to-use, when-not-to-use, and the fallback are all present.

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