Well

Create invoice document

well_create_invoice_document

Render an existing invoice as a print-ready PDF and attach it as the invoice's source document.

The letterhead carries the issuing company's own mark when Well has one on file, and otherwise sets the issuer's name as text. Never promise a logo.

Use this tool when the user asks to generate, render, or attach a PDF for an invoice that already exists in the workspace. This does NOT email or send the invoice anywhere — it only creates and attaches the file.

REQUIRED: invoice_id (the invoice must already exist)

Refused if the invoice is already linked to a REAL ingested document (an upload, a connector import, or a provider-issued PDF) — that source of truth is never overwritten.

Returns { success: true, invoice_id, document_id, reference_number, file } on success, or { success: false, error } on failure.

file carries the rendered PDF's name and size plus the links to fetch it: download_url (saves the file), signed_url (opens it), and app_url (the document in Well). Hand the user download_url when they ask for the PDF itself. Both signed links stop working at expires_at; app_url does not.

Input Schema

TableJSON Schema

Name	Required	Description
`invoice_id`	Yes
`workspace_id`	No	Target workspace. Omit when the token authorizes one workspace. Required when it authorizes several — a write lands in exactly one workspace and this call would not say which.
`conversation_id`	No	The conversation id returned by the previous Well result, in its meta under well/conversation_id, in its structuredContent, or in its JSON text block. Pass it back on every call in the same conversation, including a call a card makes, so the chosen workspace and the earlier answers still apply. It decides the conversation on its own: nothing the host states about the session replaces it. Omit it only on the first call of a conversation.
`idempotency_key`	No	Optional client-supplied key. A retried write with the same key returns the original result instead of re-applying the operation.

Output Schema

TableJSON Schema

Name	Required	Description
`file`	No
`error`	No
`success`	Yes
`invoice_id`	No
`document_id`	No
`conversation_id`	No	The conversation this result belongs to. Pass it back as the conversation_id argument on every later Well call in the same conversation.
`reference_number`	No
`conversation_id_note`	No	Present only when the server opened a fresh lane, stating that no choice recorded earlier was read.
`conversation_id_source`	No	Where the conversation id came from: the host's own request meta, the caller's argument, or a fresh lane the server opened.

Schema Changelog

Changes observed during successful MCP inspections.

Changed4 schema fields changedSep 22, 2026

addedInput schema / properties / conversation_id

Added value: +{
+  "description": "The conversation id returned by the previous Well result, in its meta under well/conversation_id, in its structuredContent, or in its JSON text block. Pass it back on every call in the same conversation, including a call a card makes, so the chosen workspace and the earlier answers still apply. It decides the conversation on its own: nothing the host states about the session replaces it. Omit it only on the first call of a conversation.",
+  "type": "string"
+}

addedOutput schema / properties / conversation_id

Added value: +{
+  "description": "The conversation this result belongs to. Pass it back as the conversation_id argument on every later Well call in the same conversation.",
+  "type": "string"
+}

addedOutput schema / properties / conversation_id_note

Added value: +{
+  "description": "Present only when the server opened a fresh lane, stating that no choice recorded earlier was read.",
+  "type": "string"
+}

addedOutput schema / properties / conversation_id_source

Added value: +{
+  "description": "Where the conversation id came from: the host's own request meta, the caller's argument, or a fresh lane the server opened.",
+  "enum": [
+    "host_meta",
+    "argument",
+    "minted"
+  ],
+  "type": "string"
+}

Changed1 schema field changedAug 31, 2026

changedInput schema / properties / workspace_id / description

Previous value: -"Target workspace. Omit to use the only authorized workspace, or (for read tools) to query all authorized workspaces grouped by workspace. Required for write tools when the token authorizes more than one workspace."New value: +"Target workspace. Omit when the token authorizes one workspace. Required when it authorizes several — a write lands in exactly one workspace and this call would not say which."

Changed1 schema field changedAug 14, 2026

addedOutput schema / properties / file

Added value: +{
+  "additionalProperties": false,
+  "properties": {
+    "app_url": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "download_url": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "expires_at": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "name": {
+      "type": "string"
+    },
+    "signed_url": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "size_bytes": {
+      "type": "number"
+    }
+  },
+  "required": [
+    "name",
+    "size_bytes",
+    "signed_url",
+    "download_url",
+    "app_url",
+    "expires_at"
+  ],
+  "type": "object"
+}

AddedAug 12, 2026

TDQS

A4.4/5.0

Behavior5/5

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

Annotations only state readOnlyHint=false and destructiveHint=false; the description goes well beyond by disclosing that the tool refuses to overwrite a REAL ingested document, that it conditionally uses a logo or issuer name as text, and that 'Never promise a logo.' It also explains link expiry semantics for signed URLs versus app_url. This is strong behavioral transparency beyond what annotations provide.

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 but organized into clear functional blocks: the action, the letterhead caveat, usage guidance, refusal condition, and return-value explanation. It front-loads the core purpose in the first sentence, and the later detail about URLs and expiry is genuinely useful rather than filler. Minor inefficiency exists because some return-shape details overlap with the output schema.

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 moderate complexity, the output schema, and the annotations, the description covers all essential operational context: prerequisites (invoice must exist), refusal conditions (already linked to a REAL document), side-effect expectations (does not send), return shape, and link semantics. An agent has enough information to decide when to call it and what to expect.

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 75%, and the schema already thoroughly documents workspace_id, conversation_id, and idempotency_key. The description adds the key precondition that invoice_id must reference an existing invoice, but it does not add much semantic value beyond the schema for the optional parameters. This is adequate but not exceptional.

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 opens with a specific verb and resource: 'Render an existing invoice as a print-ready PDF and attach it as the invoice's source document.' This clearly distinguishes the tool from siblings like well_create_invoice_from_data (creates an invoice from data) and well_upload_document (uploads arbitrary documents), and the first sentence alone tells the agent exactly what the tool does.

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

Usage Guidelines4/5

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

The description gives an explicit usage trigger: 'Use this tool when the user asks to generate, render, or attach a PDF for an invoice that already exists in the workspace.' It also states a clear when-not behavior: 'This does NOT email or send the invoice anywhere.' It stops short of naming alternative sibling tools explicitly, so it has clear context and exclusions but not full alternative routing.

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

All Well 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?