Tokenbooks - crypto and fiat accounting and payments

Merge Portfolio Transactions

merge_transactions

Destructive

Destructively combine wallet movements from several accounting transactions into one target transaction and reclassify it; preview the grouping first, then track the queued requestId.

Input Schema

TableJSON Schema

Name	Required	Description
`reason`	No	Optional immutable root reason. Nonempty bytes are preserved exactly; use ptx:<uuid> for transaction references.
`subType`	No	Optional operation sub-type
`operations`	Yes	Operations to merge into the target
`portfolioRef`	Yes	Portfolio exact name or slug
`workspaceRef`	Yes	Workspace exact name or slug
`operationType`	Yes	Accounting operation type for the merged transaction
`transactionId`	Yes	Target transaction the operations are merged into

Output Schema

TableJSON Schema

Name	Required	Description	Default
`error`	No
`status`	Yes
`success`	No
`requestId`	No
`transactionId`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedSep 20, 2026

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "additionalProperties": false,
+  "oneOf": [
+    {
+      "additionalProperties": false,
+      "properties": {
+        "requestId": {
+          "type": "string"
+        },
+        "status": {
+          "const": "queued",
+          "type": "string"
+        },
+        "transactionId": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "status",
+        "requestId",
+        "transactionId"
+      ],
+      "type": "object"
+    },
+    {
+      "additionalProperties": false,
+      "properties": {
+        "error": {
+          "additionalProperties": false,
+          "properties": {
+            "message": {
+              "type": "string"
+            },
+            "name": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "name",
+            "message"
+          ],
+          "type": "object"
+        },
+        "status": {
+          "const": "completed",
+          "type": "string"
+        },
+        "success": {
+          "type": "boolean"
+        },
+        "transactionId": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "status",
+        "success",
+        "transactionId"
+      ],
+      "type": "object"
+    }
+  ],
+  "properties": {
+    "error": {
+      "additionalProperties": false,
+      "properties": {
+        "message": {
+          "type": "string"
+        },
+        "name": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "name",
+        "message"
+      ],
+      "type": "object"
+    },
+    "requestId": {
+      "type": "string"
+    },
+    "status": {
+      "enum": [
+        "queued",
+        "completed"
+      ],
+      "type": "string"
+    },
+    "success": {
+      "type": "boolean"
+    },
+    "transactionId": {
+      "type": "string"
+    }
+  },
+  "required": [
+    "status",
+    "transactionId"
+  ],
+  "type": "object"
+}

First observedSep 14, 2026

TDQS

A4/5.0

Behavior4/5

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

The description discloses destructive behavior ('Destructively combine') which aligns with the destructiveHint annotation. It also adds valuable context beyond annotations: the need to preview before the operation and the async nature via 'queued requestId'. This informs the agent about the non-idempotent, asynchronous behavior that annotations alone don't convey.

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?

The description is a single, compact sentence that front-loads the core action, then adds essential usage notes (preview, requestId). There is no redundancy or filler; every phrase earns its place. It is perfectly concise and well-structured.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a destructive, asynchronous operation with an output schema, the description covers the key workflow: preview, execute, track. It mentions the requestId which links to sibling get_request_status. While it omits details like error handling or prerequisites, the presence of an output schema and annotations covers much of the remaining context. It is sufficiently complete for an agent to proceed correctly.

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

Parameters3/5

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

Schema description coverage is 100%, so all parameters are documented in the schema itself. The description does not add further meaning to parameters beyond what the schema provides; it only restates the overall purpose. Since the schema already covers parameter semantics, a baseline score of 3 is appropriate.

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 clearly states the verb 'combine' (merge) with a specific resource (portfolio transactions) and the effect (destructive reclassification). It also mentions the preview step and requestId tracking, which differentiates it from siblings like split_transactions and edit_transaction. The purpose is unambiguous and distinct.

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

Usage Guidelines3/5

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

The description instructs to 'preview the grouping first' and 'track the queued requestId', giving a clear workflow. However, it does not explicitly state when to use this tool vs alternatives (e.g., split_transactions or edit_transaction) or mention conditions where it should not be used. The guidance is implicit rather than explicit about alternative selection.

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

All Tokenbooks - crypto and fiat accounting and payments 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.

Resources

Need Help?