Skip to main content
Glama

save_category_spending

Records or replaces a non-account card or cash source's monthly spending by expense category for an already closed month; send the full statement at once.

Instructions

Saves a free source's spending by category (a card or cash that is not an account; for an account use save_account_lines) for a month BEFORE the first open month of the wizard queue (an earlier, already closed month). For the first open month use preview_statement / commit_statement; this tool refuses that month and later ones with 409 advisor.use_statement_tools. Expense categories only (invalid_category_flow otherwise). It REPLACES everything that source already had for that month (other sources stay), so send the whole statement at once; an empty items list removes the source's month. month is YYYY-MM, not later than the last finished month. source names the card or the cash. Each item is the month's total for one category in one currency (one item per category and currency); categoryId comes from list_spending_categories. Confirm the numbers with the user before saving.

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": {
      "month": "<month>",
      "source": "<source>",
      "items": "<items>"
    },
    "name": "save_category_spending"
  }
}

Input Schema

NameRequiredDescriptionDefault
itemsYes
monthYesThe statement's month, YYYY-MM
sourceYesThe statement's source, e.g. a bank or a card

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?

Annotations only declare readOnlyHint=false, so the description carries the load and does: it discloses that the call REPLACES the source's entire month (other sources untouched), that an empty items list deletes that month, and the exact 409 error code plus invalid_category_flow. These are destructive and error-path semantics an agent cannot get from the structured fields.

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 purpose and scope, and every sentence carries a constraint or routing rule rather than filler. It is dense with nested parentheticals and semicolon-joined clauses, which slightly hurts scannability for a definition of this length.

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 3-parameter replace-style mutation with no output schema, the description covers scope, exclusivity, destructive replace semantics, deletion path, error codes, and validation constraints. Nothing an agent needs to invoke it safely 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?

With 67% schema coverage, the description still adds real meaning: month must not be later than the last finished month, source names the card or cash, items must be one entry per category and currency representing the month's total, and categoryId must come from list_spending_categories. The 'send the whole statement at once' instruction is behavior the schema cannot express, though the per-field currency constraints are largely duplicated.

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 and resource ('Saves a free source's spending by category') and immediately bounds the scope to a closed month, contrasting explicitly with save_account_lines for accounts and preview_statement/commit_statement for the open month. An agent can identify the tool and its domain 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?

Explicit routing rules: accounts go to save_account_lines, the first open month and later go to preview_statement/commit_statement, and this tool refuses those months with 409 advisor.use_statement_tools. It also restricts to expense categories and states the empty-list case, leaving little to inference.

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