ExpenseBot

group_expenses

Destructive

Group an exact set of recorded expenses for a client, project, trip, job, or other user-named purpose. Examples: 'group my Mexico meals for client Rob', 'put these Vegas expenses under the Vegas project', or 'group these for client Rob and create a report'. The user does not need to know about tags: ExpenseBot resolves the requested name against existing groups and proposes creating one only when needed. Use exact expenseId values returned by search_expenses. A grounded preview is automatic for every bulk request; the user does not need to ask for one. First call with confirm omitted/false, show the returned exact rows, count, totals, proposed group, exclusions, and conflicts, then ask for approval. Only after explicit user approval, repeat the same operationId and selection with confirm:true. A premature confirm:true is converted to preview. When the request includes a report, set createReport:true on that confirmed group_expenses call and use its report result; do not run a separate broader create_report query. For 'without personal expenses', set excludePersonal:true; ExpenseBot removes Personal-tagged and Personal-category rows before preview so their Personal marker is never overwritten. The confirmed operation returns exact report and Bill Client links. Expenses already assigned to another ordinary report are excluded; if none remain, no duplicate report is created and the result links to Reports instead. Keep the user-facing response concise and do not add unsolicited tax or substantiation advice. Do not call check_compliance, get_report_details, or tax/deductibility tools before or after this workflow unless the user explicitly asks for that separate analysis. In user-facing prose call the destination a group, not a tag. Treat preview totals as provisional; after confirmation use only the terminal result's exact count, total, and currency without reconciling it against the preview. A returned Bill Client URL opens the reviewed billing handoff and does not mean an invoice was created, sent, or confirmed. Sharing remains a separate share_report action with recipient confirmation.

Input Schema

TableJSON Schema

Name	Required	Description
`undo`	No	Undo a completed grouping within its undo window.
`group`	No	The user-named destination group to apply to every eligible selected expense.
`status`	No	Read operation status using operationId.
`confirm`	No	Omit/false for preview; true only after explicit approval.
`selection`	No	Exact expenses returned by search_expenses and approved for this bounded operation.
`operationId`	Yes	Stable idempotency key generated once for the preview and reused unchanged.
`reportTitle`	No	Optional title when createReport is true; otherwise ExpenseBot derives one from the group.
`createReport`	No	Create a report from the exact eligible grouped expenses.
`excludedTags`	No	Existing groups to exclude before preview and grouping.
`approveNewGroup`	No	True only when the preview says a new group is required.
`excludePersonal`	No	Exclude Personal-tagged and Personal-category expenses from both grouping and the exact report.
`excludedCategories`	No	Expense categories to exclude before preview and grouping.

Output Schema

TableJSON Schema

Name	Required	Description	Default
`undo`	No
`group`	No
`report`	No
`status`	Yes
`message`	No
`preview`	No
`success`	Yes
`manifest`	No
`candidates`	No
`exclusions`	No
`reportsUrl`	No
`finalAnswer`	No
`operationId`	No
`confirmation`	No
`suggestedTag`	No
`creationStatus`	No
`responseGuidance`	No
`reviewExpensesUrl`	No
`requiresConfirmation`	No
`requiresNewGroupApproval`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedSep 9, 2026

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "additionalProperties": true,
+  "properties": {
+    "candidates": {
+      "items": {
+        "additionalProperties": true,
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "confirmation": {
+      "additionalProperties": true,
+      "type": "object"
+    },
+    "creationStatus": {
+      "type": "string"
+    },
+    "exclusions": {
+      "additionalProperties": true,
+      "type": "object"
+    },
+    "finalAnswer": {
+      "type": "string"
+    },
+    "group": {
+      "additionalProperties": true,
+      "type": "object"
+    },
+    "manifest": {
+      "additionalProperties": true,
+      "type": "object"
+    },
+    "message": {
+      "type": "string"
+    },
+    "operationId": {
+      "type": "string"
+    },
+    "preview": {
+      "additionalProperties": true,
+      "type": "object"
+    },
+    "report": {
+      "additionalProperties": true,
+      "type": "object"
+    },
+    "reportsUrl": {
+      "type": "string"
+    },
+    "requiresConfirmation": {
+      "type": "boolean"
+    },
+    "requiresNewGroupApproval": {
+      "type": "boolean"
+    },
+    "responseGuidance": {
+      "type": "string"
+    },
+    "reviewExpensesUrl": {
+      "type": "string"
+    },
+    "status": {
+      "type": "string"
+    },
+    "success": {
+      "type": "boolean"
+    },
+    "suggestedTag": {
+      "type": "string"
+    },
+    "undo": {
+      "additionalProperties": true,
+      "type": "object"
+    }
+  },
+  "required": [
+    "success",
+    "status"
+  ],
+  "type": "object"
+}

Changed1 schema field changedAug 25, 2026

changedOutput schema / (root)

Previous value: -{
-  "additionalProperties": true,
-  "description": "Standard ExpenseBot tool result envelope. `message` is the human-readable summary the AI cites; `data` is the structured payload (totals, breakdowns, ids, etc.). On failure, `success` is false and `error` carries a code/message/hint triple.",
-  "properties": {
-    "data": {
-      "additionalProperties": true,
-      "description": "Structured payload. Shape varies per tool — common keys: total, breakdown, comparison, sampleMeta, ids, expenseId, reportId, signupUrl, results.",
-      "type": "object"
-    },
-    "error": {
-      "additionalProperties": true,
-      "description": "Present only when success === false.",
-      "properties": {
-        "code": {
-          "type": "string"
-        },
-        "hint": {
-          "type": "string"
-        },
-        "message": {
-          "type": "string"
-        }
-      },
-      "type": "object"
-    },
-    "message": {
-      "description": "Human-readable result text. Always present on success; prefer rendering this verbatim before any further reasoning.",
-      "type": "string"
-    },
-    "sampleMeta": {
-      "additionalProperties": true,
-      "description": "Set when the underlying dataset was truncated. isTruncated=true means the agent saw a sample of `sampleCount` of `totalCount` rows; aggregate totals are still accurate.",
-      "properties": {
-        "isTruncated": {
-          "type": "boolean"
-        },
-        "sampleCount": {
-          "type": "integer"
-        },
-        "totalCount": {
-          "type": "integer"
-        }
-      },
-      "type": "object"
-    },
-    "success": {
-      "description": "False on tool errors; check before reading `data`.",
-      "type": "boolean"
-    }
-  },
-  "type": "object"
-}New value: +null

Changed7 schema fields changedAug 22, 2026

addedInput schema / properties / group / description

Added value: +"The user-named destination group to apply to every eligible selected expense."

addedInput schema / properties / group / properties / kind / description

Added value: +"How to label the destination in user-facing confirmation text."

addedInput schema / properties / reportTitle / description

Added value: +"Optional title when createReport is true; otherwise ExpenseBot derives one from the group."

addedInput schema / properties / selection / description

Added value: +"Exact expenses returned by search_expenses and approved for this bounded operation."

addedInput schema / properties / selection / properties / items / description

Added value: +"One exact receipt identity per selected expense; never broaden this list after preview."

addedInput schema / properties / selection / properties / items / items / properties / expected / description
```
Added value: +"Optional current state copied from search results for conflict detection."
```
addedInput schema / properties / selection / properties / items / items / properties / expected / properties / tag / description
```
Added value: +"Current group/tag value observed before preview; an empty string means ungrouped."
```

First observedAug 10, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Annotations already declare destructiveHint=true, openWorldHint=true, and readOnlyHint=false, but the description adds substantial behavioral context beyond them: automatic grounded preview, premature confirm conversion, operationId idempotency reuse, personal-marker protection, conflict/exclusion behavior, duplicate-report avoidance, and the meaning of returned Bill Client links.

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?

The description is long and dense, but it front-loads the purpose and examples before moving into workflow constraints. Almost every sentence serves to prevent a specific failure mode in a complex destructive bulk operation, though the single-paragraph format and volume keep it from being maximally concise.

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?

Given the tool's complexity, 12 parameters, nested objects, destructive annotation, and the presence of an output schema, the description is complete enough to guide correct invocation. It covers preview/confirmation, report creation, exclusions, idempotency, conflicts, and post-confirmation reporting behavior without needing to explain return values.

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 schema already carries the basic parameter definitions. The description adds meaningful workflow semantics for confirm, createReport, excludePersonal, approveNewGroup, and selection stability, though it does not add equally clear guidance for undo, status, reportTitle, excludedTags, or excludedCategories.

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 description states a specific verb and resource: grouping an exact set of recorded expenses for a client, project, trip, job, or other user-named purpose. It is clearly differentiated from siblings by naming search_expenses as the source of exact IDs and explicitly steering report creation into this call rather than a separate create_report query.

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?

Usage is highly prescriptive: first call with confirm omitted/false to preview, then only after explicit approval repeat with confirm:true. It names alternatives and exclusions, including when to use createReport:true and excludePersonal:true, and explicitly says not to call check_compliance, get_report_details, or tax tools unless separately asked.

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

All ExpenseBot tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.