Skip to main content
Glama

QuBe Sync: QuickBooks Desktop API for developers

Match records

match_records
Read-onlyIdempotent

Finds the record in a customer's QuickBooks company file that a name means, even written differently -- QuickBooks itself only matches a name exactly, or by 'contains' on one list. Checks the arguments and returns the v2 request to send (POST /api/v2/connections/{connection_id}/matches); it never touches a connection. Matching needs a realtime or simulated connection: a standard one answers 422 matching_requires_realtime (switching a sandbox connection to realtime is free). The first match on a connection starts building its name index and answers 409 name_index_building until it's ready, a few Web Connector sessions later; POST /api/v2/connections/{connection_id}/name-index with a webhook_url to start it ahead and be sent name_index.ready. The answer's match is a tier: exact (the full name, as QuickBooks compares names: use record), strong (exactly one record is the same once punctuation, accents, company suffixes such as Inc/LLC, spacing or word order are set aside, has the same number in its name (Subway #1234 for Subway Store 1234), has the account number sent, or shares the email, phone or postal code: likely, so confirm record before using it), candidates (up to 10 ranked records with a score and reasons: ask which, if any) or none. Numbers in names must agree: Subway #1235 is never offered for Subway #1234. When candidates_total is more than a person can choose from (a file of numbered locations), ask for what tells them apart -- the number, city, postal_code or account_number -- and match again with it. exact_only: true answers exact or none; min_score moves the candidate threshold for one call. Match a record once: when it's confirmed, store its list_id and refer to it by that (customer_ref: {list_id}); match again only when a stored list_id stops working.

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": {
      "kind": "<kind>",
      "name": "<name>"
    },
    "name": "match_records"
  }
}

Input Schema

NameRequiredDescriptionDefault
kindYesWhich lists to look in. entity is customers, vendors, employees and other names together (one name space in QuickBooks); item is every item type.
nameYesThe name the app has for the record: its own name, without its parent's when parent is given.
fieldsNoFor customer, vendor, employee, other_name, entity only: what else the app knows. The same account_number makes a strong match whatever the name. The same email, phone or postal_code, with a name at least 0.4 alike, makes a strong match. company_name and city only rank a candidate higher. city and postal_code are the record's billing (or main) address's. company_name isn't taken for employee.
parentNoFor a job, sub-item, subaccount and the like: the parent's full name or ListID, so only its children match. Taken for customer, entity, item, account, class, customer_type, vendor_type, job_type.
min_scoreNoThis call's candidate threshold, in place of 0.44: raise it to list only close names, lower it to list more. Not with exact_only.
exact_onlyNotrue answers only exact or none, never a fuzzy match, so the answer can be used without asking.

Output Schema

NameRequiredDescriptionDefault
urlYes
bodyYes
answerYesThe JSON Schema of the 200 answer.
methodYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.5/5.0
Behavior5/5

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

Annotations already declare readOnlyHint/idempotentHint, and the description adds substantial behavior beyond them: the realtime-or-simulated connection requirement with 422 matching_requires_realtime, the first-call 409 name_index_building state, the POST /name-index endpoint with webhook_url and the name_index.ready event. It also discloses the tier semantics of the answer (exact/strong/candidates/none) and the hard constraint that numbers in names must agree. No contradiction with the read-only annotations exists, since it explicitly says it never touches a connection.

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 purpose and the request-builder caveat are front-loaded, which is the right ordering. The body is one dense block covering connection requirements, index building, tier semantics, and disambiguation, and a few clauses are run-on (the long strong-match sentence), but nearly every sentence carries actionable information with little filler.

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 complex tool with nested parameters, an output schema, and async index-building behavior, the description covers the prerequisites (connection type), the failure modes (422, 409), the interpretation of the returned match tiers, and the follow-up workflow (store list_id, use customer_ref). Return shape details are partly left to the output schema, which is appropriate.

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 would be 3, but the description adds real meaning: min_score "moves the candidate threshold for one call," exact_only suppresses fuzzy results so "the answer can be used without asking," and it explains which extra fields (number, city, postal_code, account_number) to supply to disambiguate large candidate sets. The strong-match rules (account_number, email/phone/postal_code with a 0.4-similar name) are restated from the schema but reinforce how parameters drive tiers.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific verb and resource ("Finds the record in a customer's QuickBooks company file that a name means") and contrasts it with QuickBooks' own exact/contains matching. It also immediately clarifies the unusual mechanics: it "returns the v2 request to send... it never touches a connection," so the agent learns this is a request-builder rather than an executor. It doesn't explicitly name sibling alternatives, but the purpose is unambiguous once the first two sentences are read.

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?

The definition gives explicit when-to-use guidance (fuzzy name resolution where QuickBooks would fail), when to probe further ("When candidates_total is more than a person can choose from... ask for what tells them apart -- the number, city, postal_code or account_number -- and match again"), and when NOT to re-run the tool ("Match a record once: when it's confirmed, store its list_id... match again only when a stored list_id stops working"). It also states the exact_only and min_score conditions for narrowing results, so alternatives are covered within the tool's own surface.

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