Skip to main content
Glama

QuBe Sync: QuickBooks Desktop API for developers

Execute list merge

execute_list_merge
Read-onlyIdempotent

This request merges one list object into another list object of the same type. Currently you can merge customers/jobs, or vendors, or accounts. The consequence of the merge is that only the merge-to object remains. The merge-from object goes away and all transactions that reference that merge-from object now reference only the merge-to object.

Returns the v2 request to send, and the webhook payload QuickBooks' answer arrives in (this operation's response_json: its data shape and the status codes to handle).

Possible errors (error.code / error.type; the call result explains each): 1030 unsupported_request, 3150 missing_element, 3210 invalid_value, 3220 not_authorized, 3231 request_not_processed, 3250 feature_not_enabled, 3260 insufficient_permission, 3261 personal_data_access_denied, 3262 payroll_subscription_required, 3264 merchant_services_subscription_required

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": {
      "list_merge_type": "<list_merge_type>",
      "merge_from": "<merge_from>",
      "merge_to": "<merge_to>"
    },
    "name": "execute_list_merge"
  }
}

Input Schema

NameRequiredDescriptionDefault
merge_toYesThe object into which you are merging another object.
merge_fromYesThe object to be merged into another object.
request_idNoYour own label for the request, sent to QuickBooks as its qbXML `requestID` and echoed in the raw answer (`response_xml`); optional, since the answer's webhook already carries the request's `id`.
include_qbxmlNoAlso return the qbXML this compiles to, for debugging. Not part of the v2 request.
list_merge_typeYesThe type of the objects to be merged. Both of the objects must be the same type, for example both must be customers, because you can’t merge a vendor with a customer.
same_ship_addr_okNoA new tag (SameshipAddressOk) is added to ListMerge request. If true is supplied in this tag then the merge will go through even if elements have same default shipto address.

Output Schema

NameRequiredDescriptionDefault
urlYesReplace {connection_id} with the customer's connection.
bodyYesThe JSON body: the arguments you passed.
qbxmlNoThe qbXML it compiles to. Only with include_qbxml.
methodYes
headersYesSend with the request. Resent unchanged when no 201 came back, it answers with the request already queued.
webhookYesJSON Schema of the payload POSTed to webhook_url once QuickBooks answers, with this operation's response_json (data shape and status codes).

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A3.7/5.0
Behavior3/5

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

The description adds real behavioral context beyond the annotations: it discloses the irreversibility (merge-from disappears, all referencing transactions are re-pointed), describes the two-part return (v2 request plus the webhook payload the QuickBooks answer arrives in), and enumerates nine error codes with their meanings. That said, the disclosed destructive consequence sits in tension with destructiveHint=false and readOnlyHint=true; the description partly resolves this by framing the tool as a request compiler, but the conflict is never reconciled explicitly.

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 the merge semantics and the consequence of calling it, then the return shape, then a compact error table. The nine-code error list is dense but each entry earns its place by mapping a code to a condition the caller must handle.

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 nested-object, six-parameter mutation-adjacent call, the description covers scope, consequence, return contract, and failure modes. With an output schema present and full schema coverage, nothing critical is left for the agent to guess, apart from the supported-type mismatch noted above.

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

Parameters2/5

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

Schema description coverage is 100%, so the parameter-level bar is low, but the description actively adds misleading information: it says "Currently you can merge customers/jobs, or vendors, or accounts" while the list_merge_type enum exposes fourteen values including class and the item_* family. An agent that trusts the prose over the enum may wrongly conclude item or class merges are unsupported.

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?

"This request merges one list object into another list object of the same type" gives a specific verb plus resource, and the follow-up sentence spells out the outcome (merge-to survives, merge-from is removed, transactions are re-pointed). That is enough for an agent to distinguish this from delete_list or update_list_display without opening a schema.

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?

Usage is implied rather than stated: the tool is for consolidating duplicate list objects, and the same-type constraint is called out explicitly. There is no explicit when-not guidance, no mention of prerequisites, and no pointer to an alternative when the objects are not of the same type. The claim about supported types also conflicts with the schema (see parameter semantics).

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources