Caribooks (QuickBooks Online)

Attach a file to a transaction

attach_file

Destructive

Attach an original PDF, image, spreadsheet, CSV or Word file to an existing QuickBooks transaction. upload_id identifies a file in the Caribooks document box, populated through portal uploads or the account's receiving email address. For ChatGPT native attachments, file accepts the original file descriptor supplied by ChatGPT. content_base64 accepts the actual bytes of a file up to 3 MB, since the request carrying them is capped; larger files go through upload_id or file. Maximum file size: 20 MB. Requires full access on the connection. Does not create a transaction or render a transcription.

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": {
      "txn_type": "<txn_type>",
      "txn_id": "<txn_id>"
    },
    "name": "attach_file"
  }
}

Input Schema

Name	Required	Description
`file`	No	A file the user attached in this conversation, passed by the assistant's app. Use this or upload_id or content_base64, not two.
`txn_id`	Yes	QuickBooks Id of that transaction.
`company`	No	Which connected QuickBooks company to use (name, realm id, or connection id). Optional when only one company is connected.
`filename`	No	File name with its extension, e.g. 'facture-2026-08.xlsx'. Shown in QuickBooks. Required with content_base64; with upload_id it defaults to the uploaded file's name.
`txn_type`	Yes	QuickBooks transaction type the file documents.
`upload_id`	No	The document id from list_receipt_inbox. Use this or content_base64, not both.
`content_type`	No	Media type of the file, e.g. application/pdf, image/jpeg, text/csv, application/vnd.openxmlformats-officedocument.spreadsheetml.sheet. With content_base64 only; optional when it is a data URL that names it.
`content_base64`	No	The file's bytes encoded as base64 (a data URL is accepted too), for a small file you hold.
`allow_duplicate`	No	The call fails if the transaction already has an attachment. Only set true after the user explicitly confirms they want an additional document attached.

Schema Changelog

Changes observed during successful MCP inspections.

First observedSep 21, 2026

TDQS

A3.8/5.0

Behavior4/5

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

With annotations already declaring a non-read-only, open-world, destructive operation, the description adds important context: full access is required, content_base64 is capped at 3 MB due to request size, and the overall file limit is 20 MB. It also clarifies that the tool does not create a transaction or render a transcription. It leaves the duplicate-attachment failure behavior to the schema rather than explaining it in the description.

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 front-loaded with the core action and then moves efficiently through input modes, size limits, and access requirements. It is dense but appropriate for a tool with nine parameters and multiple upload paths. Each sentence contributes useful operational context.

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 complex, nested attachment tool, the description covers purpose, upload-path selection, size constraints, access requirements, and scope limitations. It does not explicitly differentiate from sibling attachment tools or describe duplicate-handling behavior, but the latter is covered in the schema. Overall it gives enough context to call the tool correctly.

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 baseline would be 3, but the description adds real meaning for the key input modes: upload_id refers to a Caribooks document-box file, file is for ChatGPT-supplied descriptors, and content_base64 carries actual bytes up to 3 MB. It does not add much about txn_type or allow_duplicate, though those are already documented in the schema.

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 states a specific verb and resource: attaching an original PDF, image, spreadsheet, CSV, or Word file to an existing QuickBooks transaction. It also scopes the tool by saying it does not create a transaction or render a transcription. It does not explicitly contrast itself with sibling tools such as attach_receipt or create_attachable.

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 gives useful input-source guidance: upload_id for Caribooks document-box files, file for ChatGPT native attachments, and content_base64 for small in-hand bytes. However, it does not say when to choose this tool over sibling attachment tools like attach_receipt or create_attachable. Usage is therefore implied rather than explicitly routed.

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

All Caribooks (QuickBooks Online) 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?