公式 Carbone MCP サーバー — AI アシスタントを文書自動化のエキスパートに変えます。自然言語を使ってプロフェッショナルな PDF、請求書、レポートなどを生成します。
Claude、ChatGPT、その他の AI アシスタントに以下の機能を提供します:
🔄 ドキュメント変換 — 100 以上の形式の組み合わせ (PDF、DOCX、XLSX、PNG、HTML、CSV など)
📄 テンプレートエンジン — {d.field} タグを使用して JSON データからドキュメントを生成
📚 テンプレートライブラリ — 再利用可能なテンプレートのアップロード、バージョン管理、カテゴリ分類、管理
🎨 PDF カスタマイズ — PDF フォームの入力、透かし、パスワード、暗号化、複数の変換エンジン (LibreOffice、OnlyOffice、Chromium、Carbone ICE)
🌍 ローカライゼーション — 多言語サポート、通貨換算、タイムゾーン処理
⚡ バッチ生成 — 1 回のリクエストで数百のドキュメントを作成 (webhook による非同期)
無料の API キーを account.carbone.io で取得してください。
すべての stdio 互換 MCP クライアントは同じ設定を使用します:
{
"mcpServers": {
"carbone": {
"command": "npx",
"args": ["-y", "carbone-mcp"],
"env": {
"CARBONE_API_KEY": "your_api_key_here"
}
}
}
}クライアント | 設定ファイル |
Claude Desktop (macOS) |
|
Claude Desktop (Windows) |
|
Cursor (グローバル) |
|
Cursor (プロジェクト) |
|
Claude Code |
|
VS Code は
{ "mcp": { "servers": { ... } } }を{ "mcpServers": { ... } }の代わりに使用します — 内部の設定ブロックは同一です。
設定を追加したら、クライアントを再起動して、「Carbone は何ができますか？」 と試してみてください。
ホストされたエンドポイントに直接接続します。VS Code、Cursor、Claude Code、およびストリーミング可能な HTTP トランスポートをサポートする他のクライアントでサポートされています。
{
"mcp": {
"servers": {
"carbone": {
"type": "streamable-http",
"url": "https://mcp.carbone.io",
"headers": {
"Authorization": "Bearer your_api_key_here"
}
}
}
}
}認証: HTTP エンドポイントは現在、
Authorizationヘッダーで Bearer トークンとして渡される Carbone API キーを必要とします。OAuth2 サポート (Claude Desktop、Mistral、ChatGPT、Gemini、および他のクライアント向け) は将来のリリースで計画されています。Cursor は
{ "mcpServers": { ... } }を{ "mcp": { "servers": { ... } } }の代わりに使用します — 内部の設定ブロックは同一です。Claude Desktop は HTTP Bearer トークン認証をサポートしていません — 代わりに上記の stdio オプションを使用してください。
docker run -d -p 3000:3000 \
-e MCP_TRANSPORT=http \
-e CARBONE_API_KEY=your_api_key_here \
carbone/carbone-mcp上記の HTTP 設定を使用して MCP クライアントを http://your-host:3000 に接続します (URL を置き換えてください)。
Docker Compose — compose.yml を参照してください:
CARBONE_API_KEY=your_key docker compose up -dClaude Desktop と Docker (stdio) — Claude Desktop は HTTP トランスポートをサポートしていません。代わりに stdio モードを使用してください:
{
"mcpServers": {
"carbone": {
"command": "docker",
"args": ["run", "-i", "--rm",
"-e", "CARBONE_API_KEY=your_api_key_here",
"-e", "MCP_TRANSPORT=stdio",
"carbone/carbone-mcp"]
}
}
}Carbone オンプレミス を実行している場合は、MCP サーバーをインスタンスに向けてください — API キーは不要です:
# Docker (HTTP)
docker run -d -p 3000:3000 \
-e CARBONE_BASE_URL=https://your-carbone-server.com \
carbone/carbone-mcp
# stdio
CARBONE_BASE_URL=https://your-carbone-server.com npx carbone-mcpRelated MCP server: doc-ops-mcp
必須 (stdio モード、クラウド API):
CARBONE_API_KEY — あなたの Carbone API キー (無料で取得 →)。CARBONE_BASE_URL が自社のオンプレミスサーバーを指している場合、または HTTP モードで実行している場合 (クライアントが Authorization: Bearer 経由で独自のキーを提供する場合) は不要です。
変数 | デフォルト | 説明 |
|
| セルフホストまたはステージング環境用の上書き。カスタム URL に設定すると、 |
|
| リクエストのタイムアウト (ミリ秒、最大: 60000) |
|
| 解決された入力ファイル (パス、URL、base64) の最大サイズ (バイト、デフォルト 100 MB) |
|
| トランスポートモード: |
|
| HTTP サーバーのポート ( |
|
| HTTP エンドポイントのパス ( |
|
| リクエストボディの最大サイズ (バイト、デフォルト 60 MB、Carbone Cloud の制限に一致) |
|
| HTTP モードのみ — すべてのリクエストで |
|
| ユーザー指定の URL (テンプレート、 |
ツール | 説明 | ドキュメント |
| テンプレートを保存せずに 100 以上の形式間でドキュメントを変換します | |
| JSON データとマージしてテンプレートからドキュメントを生成します |
ツール | 説明 | ドキュメント |
| カテゴリや検索でフィルタリングしてテンプレートライブラリを閲覧します（タグはテンプレートごとに返されますが、サーバー側でフィルタリングはできません） | |
| アカウント内のすべてのテンプレートカテゴリを一覧表示します | |
| テンプレート全体で使用されているすべてのタグを一覧表示します | |
| バージョン管理、カテゴリ分類、メタデータを備えた再利用可能なテンプレートを保存します | |
| テンプレートバージョンの名前変更、カテゴリ分類、タグ付け、デプロイ、または期限切れ設定を行います | |
| テンプレートをソフト削除します（削除対象としてマークされ、約24時間後に消去されます） | |
| 元のテンプレートファイル（DOCX、XLSX、PDFなど）をダウンロードします |
ツール | 説明 | ドキュメント |
| Carbone APIのヘルス状態と現在のバージョンを確認します | |
| サポートされているすべての形式、機能、および例を表示します |
📖 完全なAPIリファレンス → — 詳細なパラメータ、スキーマ、および例
デフォルトでは、生成または変換されたファイルは、そのタイプとトランスポートに基づいて返されます：
出力 | stdio（ローカルクライアント） | HTTP（リモート / セルフホスト） |
テキスト — HTML、TXT、CSV、MD、XML | インラインテキスト | インラインテキスト |
インライン画像 — PNG、JPG、GIF、WEBP | インライン画像 | インライン画像 |
その他すべて — PDF、Office、ZIP、SVG… | 一時ファイルに保存され、パスが返されます | ダウンロード添付ファイルとして返されます |
convert_document と render_document（および download_template の outputPath / asAttachment）の3つのオプションパラメータでこれを上書きできます：
パラメータ | 効果 |
| stdioのみ — インラインで返す代わりに、出力をこのローカルパスに保存します（HTTPモードでは拒否されます） |
| 任意の形式で、インラインではなくダウンロード可能な添付ファイルとしてバイトを返します |
| ファイルの代わりにCarboneの公開ワンタイムダウンロードURLを返します — 短命で、最初のダウンロードで消費されるため、自分で取得するのではなくユーザーに渡してください（stdioとHTTPの両方で動作します） |
Claude Desktop: インラインのバイナリ添付ファイルをレンダリングできません（画像として誤って処理されます）。PDFやOfficeファイルの場合は、デフォルトのstdio一時ファイルパスを使用するか、
returnLinkを使用してダウンロードURLを取得してください。
"Convert this Word document to PDF: /path/to/contract.docx"
"Turn my Excel spreadsheet into CSV format"
"Convert this HTML page to a PNG image"
"Convert my Markdown README to PDF"
"Convert this PPTX to PNG — use OnlyOffice for best fidelity"
"Convert this 500-page Word report to PDF — use the ICE converter, it's much faster"
"Rasterize this PDF to PNG images — one per page""Generate an invoice using template T123 with: {customer: 'Acme Corp', total: 1500, items: [...]}"
"Generate invoices from the data in /data/invoices.json"
"Create 500 invoices from my billing data and bundle them in a ZIP"
"Generate a French invoice for my Paris client — use EUR currency and fr-fr locale"
"Render this monthly report for each client in clients.json and ZIP them all"
"Generate invoice-{d.id}.pdf for each row in my sales data""Add a CONFIDENTIAL watermark to this contract before sending it"
"Convert this NDA to PDF/A format for long-term archiving"
"Generate a password-protected PDF — open password: 'secret123'"
"Create signed offer letters for each candidate using this DOCX template"
"Generate a compliance report with a DRAFT watermark, 20% opacity, rotated -45°""Create personalized onboarding documents for all 50 new employees in this JSON"
"Generate an employment contract for each person in new-hires.json"
"Build payslips for every employee in my payroll export"
"Create training certificates for everyone who passed this month"
"Fill out the performance review template with each employee's data""Generate this invoice in French, German, and Spanish from the same template"
"Render the report with timezone America/New_York so dates show in Eastern time"
"Convert all prices from EUR to USD using today's exchange rates"
"Generate the contract in fr-fr locale so numbers use European formatting""Convert this DOCX to a password-protected PDF"
"Add a semi-transparent DRAFT watermark to every page"
"Generate a PDF/A-1b compliant version of this document for archiving"
"Export only pages 1–5 of this presentation as a PDF"
"Convert each slide of this PPTX to a separate PDF page""Upload this invoice template and tag it 'sales' and 'finance'"
"What templates do I have in the 'contracts' category?"
"Show me all templates tagged 'hr'"
"Download template T456 so I can edit it locally"
"Deploy version V789 as the active version without deleting the others"
"Schedule this old template for deletion in 30 days"サーバーを対話的にテストおよびデバッグします：
npx @modelcontextprotocol/inspector npx carbone-mcpまたはローカルビルドから：
npx @modelcontextprotocol/inspector node dist/index.jshttp://localhost:5173 を開くと、すべてのツールの表示、テスト呼び出し、リクエスト/レスポンスJSONの検査ができます — AI推論は不要です。
# macOS — Claude Desktop logs
tail -f ~/Library/Logs/Claude/mcp*.log
# Windows
Get-Content "$env:APPDATA\Claude\logs\mcp*.log" -Wait -Tail 50確認する項目：
✅ Carbone MCP Server v1.x.x started (stdio)
❌ エラーメッセージやスタックトレース
HTTPモードで実行している場合、サーバーはヘルスエンドポイントを公開します：
curl http://localhost:3000/health{
"mcp": { "version": "1.2.2" },
"carbone": { "version": "5.x.x" }
}carbone フィールドはバックエンドの接続状態を示します：
{ "version": "..." } — 到達可能かつ認証済み
{ "error": "unauthorized", "message": "..." } — 到達可能だがAPIキーがない、または無効
{ "error": "unreachable", "message": "..." } — ネットワークエラー、タイムアウト、または予期しないレスポンス
⚠️ ファイルおよびURL入力（SSRF / ローカルファイル）
ツールは、file / template および参照渡しのJSONパラメータ（data、complement など）に対して、ローカルパス、HTTPS URL、またはbase64を受け入れます。2つのガードが適用されます：
URL は、ループバック、プライベート（RFC1918）、リンクローカル（クラウドメタデータ 169.254.169.254 を含む）、CGNAT、または予約済みアドレスを指す場合に解決され拒否されます — また、すべてのリダイレクトホップが再チェックされます。内部テンプレートホストを必要とする信頼できるデプロイメントでのみ CARBONE_ALLOW_PRIVATE_NETWORK=true を設定してください。
ローカルパス は stdioのみ で読み取り可能です。この場合、サーバーはすでにあなた自身として実行されています。HTTPモードでは拒否されるため、リモートの呼び出し元がサーバーに自身のファイルシステムを読み取らせることは決してできません。
⚠️ サーバーレベルのAPIキーの共有（HTTPモード）
HTTPサーバーで CARBONE_API_KEY を設定し、CARBONE_REQUIRE_CLIENT_AUTH_HEADER=false（デフォルト）のままにすると、Bearerキーなしのリクエストはそのキーにフォールバックします — ポートに到達できる人は誰でもそのCarboneアカウントを使用できます。各クライアントが独自のキーを持つことを要求するには true に設定するか、信頼できるネットワーク上でのみポートを公開してください。（サーバーキーが設定されていない場合、例えば認証なしのオンプレミスCarboneでは適用されません。）
⚠️ プロンプトインジェクション AIアシスタントを外部サービスに接続することには固有のリスクが伴います。悪意のあるドキュメントやテンプレートには、AIを意図しないアクション（データの外部送信、テンプレートの削除など）に誘導する指示が含まれている可能性があります。ツール呼び出しを確認する前に、AIクライアントが実行しようとしていることを常に確認してください。
⚠️ APIキーの保護
CARBONE_API_KEY をバージョン管理にコミットしないでください
環境変数またはシークレットマネージャーを使用してください
account.carbone.io でAPIキーを定期的にローテーションしてください
⚠️ テンプレートの安全性
信頼できるソースからのテンプレートのみをアップロードしてください
デプロイ前にテンプレートを確認してください
簡単なロールバックのためにテンプレートのバージョン管理を使用してください
⚠️ データプライバシー
Carboneはレンダリング後にドキュメントデータを保存しません
最大限の制御のために CARBONE_BASE_URL を使用してセルフホストインスタンスを指定してください
詳細はプライバシーポリシーを参照してください
Word、Excel、LibreOffice、またはHTMLで {d.field} タグを使用してテンプレートをデザインします：
Dear {d.customer.name},
Your invoice total is {d.total:formatC(EUR)}.
Items:
{d.items[i].description} {d.items[i].quantity}x {d.items[i].price:formatC(EUR)}
{d.items[i+1]}ガイドとベストプラクティス：
Carbone Skill — AIツール向けのユニバーサルCarboneテンプレート構文リファレンス（.skillをダウンロード · GitHub）
カテゴリ | 形式 |
ドキュメント | PDF、DOCX、XLSX、PPTX、ODT、ODS、ODP、ODG、RTF、EPUB |
画像 | PNG、JPG、WEBP、SVG、TIFF、BMP、GIF |
Web / テキスト | HTML、TXT、CSV、MD、XML |
完全な変換マトリックス：carbone.io/documentation
コントリビューションを歓迎します：
🐛 バグの報告 — GitHub Issues 経由
💡 機能リクエスト や改善提案
📝 ドキュメントの改善
🧪 テストの追加 でカバレッジを向上
🔧 プルリクエストの提出 でバグ修正や機能強化
ガイドラインについては CONTRIBUTING.md を参照してください。
npm run dev # Run with tsx (no build needed)
npm run build # Compile TypeScript → dist/
npm test # Run the test suite (integration tests run only with CARBONE_TEST_API_KEY)
npm run test:watch # Watch mode
npm run test:integration # Real API tests (requires CARBONE_TEST_API_KEY)
npm run test:coverage # Coverage report🤖 MCPドキュメント: carbone.io/documentation/developer/ai/mcp.html
📚 APIドキュメント: carbone.io/documentation/developer/http-api/introduction.html
📚 テンプレートドキュメント: carbone.io/documentation/design/overview/getting-started.html
🐛 バグ報告: GitHub Issues
💬 ライブチャット: carbone.io（右下のウィジェット）
📧 エンタープライズ: contact@carbone.io
📋 OpenAPI仕様: carbone.OpenAPI.yml
Apache 2.0 — LICENSE を参照してください。
Convert a document to another format without storing a template. Pure conversion: no data is sent, so Carbone tags such as {d.name} are kept as written; this is also how you proof a template in another format (DOCX template → PDF, or DOCX → ODT while it stays a template). The source file can be a local file path, an HTTPS URL, or a base64-encoded string. Use render_document instead when you need data injection ({d.field} tags resolved), translations, or batch generation. Example: { "file": "/Users/me/report.docx", "convertTo": "pdf" } (a bare file name such as "report.docx" is not a path). Common conversions: DOCX → PDF (add converter: "I" for the fastest conversion), XLSX → PDF, PPTX → PDF, HTML → PDF (converter: "C" for full CSS/JS rendering), DOCX → HTML, XLSX → CSV, PDF → PNG, PPTX → PNG (first slide as image), MD → PDF.
| Name | Required | Description | Default |
|---|---|---|---|
| file | Yes | The document to convert. Three input forms are accepted: (1) Local file path — absolute, e.g. "/Users/me/report.docx" (or "C:\Users\me\report.docx" on Windows), or under the home directory, e.g. "~/report.docx". A relative path must start with "./" or "../" and resolves against the server process's working directory, which is rarely yours: prefer an absolute path. A bare file name such as "report.docx" is NOT a path: it would be sent as base64 content. (2) HTTPS URL — the file is downloaded automatically, e.g. "https://example.com/file.pptx". (3) Base64-encoded string — the raw file content encoded as base64. Supported input formats: DOCX, XLSX, PPTX, ODT, ODS, ODP, ODG, HTML, XHTML, XML, SVG, IDML, MD, TXT, CSV, RTF, PDF. Carbone reads XML-based and text-based documents (plus PDF): the legacy binary Office formats DOC, XLS and PPT are rejected as input, although they are valid outputs. Re-save such a file as DOCX, XLSX or PPTX first. Full conversion matrix: https://carbone.io/documentation/developer/http-api/generate-reports.html#output-file-type | |
| convertTo | Yes | Target output format. Valid outputs depend on the input format (e.g. HTML converts to pdf, docx or png, but not xlsx); see the conversion matrix: https://carbone.io/documentation/developer/http-api/generate-reports.html#output-file-type. "doc", "xls" and "ppt" are output formats; as input, use DOCX, XLSX or PPTX. Simple usage: "pdf". With options: { "formatName": "pdf", "formatOptions": { ... } }. | |
| converter | No | Converter engine, used whenever the format changes (not only for PDF). If omitted, "L" is used. "L" LibreOffice: DOCX, XLSX, PPTX, ODT, ODS, ODP, ODG, MD, PDF; the only converter supporting all PDF options. "I" Carbone ICE: DOCX and ODT to PDF; Carbone's own engine, 3x to 300x faster, recommended over "O" for DOCX from v5.15.0. It converts all content except WEBP and EMF/WMF images, SmartArt and complex charts (bar, line, area, pie and doughnut charts are drawn), comments, tracked changes, form fields and equations: keep the default "L" for documents with those. A missing font is replaced by Noto Sans (https://carbone.io/documentation/developer/http-api/generate-reports.html#converters-carbone-ice-limitations). "O" OnlyOffice: DOCX, XLSX, PPTX to PDF. "C" Chromium: HTML to PDF, JPG, PNG, WEBP with full CSS/JS; 100 MB max. PDF options: "L" supports all of them; "O", "C" and "I" apply Security (passwords, permissions) and Watermarks. Docs: https://carbone.io/documentation/developer/http-api/generate-reports.html#converters | |
| outputPath | No | Optional local file path to save the converted document to (e.g. "/home/user/out.pdf" or "~/out.pdf"). When set, the file is written to disk and the tool returns the saved path + size instead of embedding the document inline — ideal for large files. The path must not exist yet: an existing file is never overwritten (the call fails and asks for a new file name). | |
| reportName | No | Name of the delivered file, WITHOUT extension (e.g. "contract", "2026-invoice"). The document is delivered as "<reportName>.<ext>", with the extension of convertTo, used as the attachment name and the default saved file name. This server names the file itself: a conversion has no templating pass, which is where Carbone resolves reportName. Used literally: Carbone tags such as {d.id} are not resolved here. Ignored with returnLink (a download URL, not a named file) and with outputPath (which sets the path itself). | |
| returnLink | No | If true, generate the document and return a public download URL instead of the file contents. The link is SHORT-LIVED and ONE-TIME — Carbone deletes the file after the first download — so it is meant for the end user to download once (do not fetch it programmatically). Works in stdio and HTTP. Mutually exclusive with outputPath and asAttachment. | |
| hardRefresh | No | If true, Carbone runs the converter even when the output format equals the input format, and recomputes pagination and the table of contents at the end of the conversion. Needed for PDF → PDF: without it Carbone returns the PDF unchanged and formatOptions (password, permissions, watermarks, PDF/A, …) are NOT applied. This server sets it automatically when the input is a PDF, convertTo is "pdf" and formatOptions are given; pass false to opt out. Example (PDF → PDF/A-4): { "hardRefresh": true, "convertTo": { "formatName": "pdf", "formatOptions": { "SelectPdfVersion": 4 } } }. | |
| asAttachment | No | If true, return the document as a downloadable file attachment (a base64 EmbeddedResource), for any format. Default delivery: text and png/jpg/gif/webp are returned inline; other binary outputs (PDF, Office, …) are saved to a temp file (path returned). Ignored when outputPath or returnLink is set. | |
| egressAuthorization | No | Value for the Authorization header Carbone adds to its OUTBOUND (egress) requests during conversion — e.g. when a Chromium HTML→PDF conversion fetches a protected external image or stylesheet. For example "Bearer abc123" makes Carbone send `authorization: Bearer abc123` to those hosts. Only the authorization header can be customised; max 511 characters. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true), so the bar is lower. The description still adds real behavioral context: no data is injected so Carbone tags are kept literal, and no template is stored. It does not itself cover delivery side effects like one-time links or non-overwriting paths, but those live in the parameter docs.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Core purpose, tag-preservation semantics, input forms, the alternative tool, an example, and common conversions are all front-loaded in a logical order. It is dense but nearly every sentence carries information; the trailing conversions list is the only borderline padding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 9-parameter tool with no output schema, the description covers purpose, alternative routing, examples, and typical conversion paths, while the rich schema documents delivery (outputPath/returnLink/asAttachment) and options. It is nearly complete, though it never states the default return/delivery behavior itself.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description goes beyond the schema by pairing conversion examples with practical converter choices ('I' for fastest DOCX→PDF, 'C' for full CSS/JS HTML→PDF) and by showing a concrete invocation example, which meaningfully aids correct parameter selection.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource ('Convert a document to another format') and immediately distinguishes scope with 'without storing a template' and 'no data is sent'. The sibling render_document is explicitly named as the tool to use for a different job, so an agent can differentiate without opening either schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives an explicit when-to-use-this ('pure conversion', proofing a template in another format) and an explicit when-to-use-something-else ('Use render_document instead when you need data injection, translations, or batch generation'). The common-conversion list further anchors the intended scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a stored Carbone template. Takes effect immediately: the template is no longer listed, downloadable or renderable (404); the file itself is purged after the retention delay (Carbone Cloud: 24 hours). You can delete by Template ID (removes all versions) or by Version ID (removes only that specific version). To schedule a deletion instead, use update_template_metadata with expireAt set to a future Unix timestamp.
| Name | Required | Description | Default |
|---|---|---|---|
| templateId | Yes | Template ID (64-bit) or Version ID (SHA-256) to delete. Template ID — deletes the template record and all its versions. Version ID — deletes only that specific version, leaving other versions intact. Both formats are returned by upload_template and list_templates. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already flag destructiveHint=true and idempotentHint=true; the description adds what is actually destroyed (listing/download/render stop immediately with 404, file purged after a 24h retention delay on Carbone Cloud) and the blast radius difference between Template ID and Version ID. That is behavioral context well beyond the annotation hints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with the action, then effect, then the ID-type distinction, then the alternative. No filler or restatement of the title.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers action, immediate and delayed effects, ID-type semantics, and the alternative scheduling tool. No output schema is needed for a deletion, and no gaps remain for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the schema description already explains the two ID formats and where they come from. The description restates the Template ID vs Version ID distinction without adding syntax or format detail beyond the schema, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Delete a stored Carbone template') and immediately qualifies scope by ID type. An agent can distinguish it from sibling read/list tools without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly routes the agent: delete by Template ID vs Version ID, and names the alternative path for deferred action ('To schedule a deletion instead, use update_template_metadata with expireAt...'). This is when-to-use and when-to-use-something-else in one place.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Download the original source file of a stored Carbone template (e.g. the DOCX, XLSX, PPTX, or HTML file that was uploaded). Use this to inspect, edit, or back up a template. Pass a Template ID to download the currently deployed version, or a Version ID to download a specific version. Set sample: true to get the JSON sample dataset stored with the template instead of the template file.
| Name | Required | Description | Default |
|---|---|---|---|
| sample | No | If true, download the JSON SAMPLE DATASET saved with the template (the "sample" array passed to upload_template) instead of the template file, returned as inline JSON text by default, of the form [{ "data": {...}, "complement": {...}, "translations": {...}, "enum": {...} }] (each key optional). Use it to recover the example data a template expects before calling render_document. Errors if the template was uploaded without a sample. | |
| outputPath | No | Optional local file path to save the template file to (e.g. "/home/user/out.pdf" or "~/out.pdf"). When set, the file is written to disk and the tool returns the saved path + size instead of embedding the document inline — ideal for large files. The path must not exist yet: an existing file is never overwritten (the call fails and asks for a new file name). | |
| templateId | Yes | Template ID (64-bit) or Version ID (SHA-256) to download. Template ID — downloads the currently deployed version of the template. Version ID — downloads that exact version regardless of deployment status. Both formats are returned by upload_template and list_templates. | |
| asAttachment | No | If true, return the template as a downloadable file attachment (base64 resource) instead of inline text/image. Useful in HTTP mode where outputPath is unavailable. Default: false. Ignored when outputPath is set. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=false while the description frames this as a passive 'download', which the disk-write behavior under outputPath justifies rather than contradicts. The description notes the no-overwrite guard and the sample error case, but both of those details are already spelled out in the schema, so genuine added behavioral context is limited.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, each doing distinct work, with the core action and file types front-loaded before the version-selection and sample-mode refinements.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a four-parameter tool with no output schema and one required parameter, the description covers the main modes (deployed vs versioned, file vs sample JSON) adequately. It could mention the attachment/inline return trade-off, though the schema handles that thoroughly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description restates the Template ID vs Version ID semantics and the sample flag, but adds no format or syntax detail beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Download the original source file of a stored Carbone template') and enumerates the file types involved, so it is immediately distinguishable from siblings like list_templates, render_document, and inspect_template.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives concrete use cases ('inspect, edit, or back up a template') and clearly routes between Template ID (deployed version) and Version ID (specific version), plus when to use sample:true. It stops short of naming an actual alternative tool for the inspect/back-up workflow.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check Carbone API health and version. Returns the current API version and a status message. Useful for verifying connectivity and confirming which Carbone version is active.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| message | Yes | Status message returned by the API. |
| version | Yes | The running Carbone API version. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and a closed-world scope, so the safety profile is fully covered by structured data. The description adds only that it returns version and status, which the output schema already carries, so it contributes little beyond the annotations without contradicting them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, front-loaded with the action, then the return values, then the use case. No filler or redundancy; each sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a trivial diagnostic tool with no parameters, full annotation coverage, and a dedicated output schema, the description supplies everything an agent needs — what it checks, what it returns, and why to call it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline of 4 applies. The empty schema is consistent with the description, which implies a no-argument call.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource combination ('Check Carbone API health and version') that is unambiguously distinct from every sibling, all of which operate on templates, categories, tags, or documents. An agent can route to it without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives concrete usage contexts — verifying connectivity and confirming the active Carbone version — which is clear guidance for when to call it. No alternatives or exclusions are named, but for a no-arg health check none are plausibly needed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns a summary of all Carbone capabilities: supported formats, features, tool usage examples, and links to full documentation. Call this first if you are unsure what Carbone can do.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, openWorldHint=false, and destructiveHint=false, so the safety profile is fully covered. The description adds the orientation role ('call first') but nothing about response size, caching, or side effects 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no filler, and the orientation cue is placed last as a directive. Every clause adds information about the return contents or the calling condition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, but the description compensates by naming the categories of content returned (formats, features, examples, doc links), which is enough for an agent to decide whether to call it. A note on response format or size would push this to a 5.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so the baseline of 4 applies; there is no parameter semantics to document or miss. The description also does not introduce any phantom arguments.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Specific verb (Returns) plus resource (Carbone capabilities) with an enumeration of what the payload contains: formats, features, usage examples, and documentation links. It is clearly a discovery tool, distinguishing it from action siblings like convert_document or render_document, though it does not name any sibling explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states the trigger: 'Call this first if you are unsure what Carbone can do.' That is a clear when-to-use condition. There is no when-not or named alternative (e.g., 'skip if you already know the format'), so it stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the Carbone tags a template uses and return a sample JSON dataset matching its structure. Call it before render_document when you do not know which data a template expects. Pass exactly one of templateId (a stored template: Template ID or Version ID) or template: a local file path, an HTTPS URL, or a base64-encoded string. It runs one render on the Carbone account and discards the document. {t()} translation tags are not listed.
| Name | Required | Description | Default |
|---|---|---|---|
| template | No | Inline template to inspect, without storing it. Three input forms are accepted: (1) Local file path — absolute, e.g. "/Users/me/report.docx" (or "C:\Users\me\report.docx" on Windows), or under the home directory, e.g. "~/report.docx". A relative path must start with "./" or "../" and resolves against the server process's working directory, which is rarely yours: prefer an absolute path. A bare file name such as "report.docx" is NOT a path: it would be sent as base64 content. (2) HTTPS URL — the file is downloaded automatically, e.g. "https://example.com/file.pptx". (3) Base64-encoded string — the raw file content encoded as base64. Supported input formats: DOCX, XLSX, PPTX, ODT, ODS, ODP, ODG, HTML, XHTML, XML, SVG, IDML, MD, TXT, CSV, RTF, PDF. Carbone reads XML-based and text-based documents (plus PDF): the legacy binary Office formats DOC, XLS and PPT are rejected as input, although they are valid outputs. Re-save such a file as DOCX, XLSX or PPTX first. Mutually exclusive with templateId — provide exactly one, never both. | |
| templateId | No | The ID of a stored template to inspect. Two ID formats are accepted: (1) Template ID (64-bit) — the deployed version is inspected. (2) Version ID (SHA-256) — that exact version is inspected. Both are returned by upload_template and list_templates. Mutually exclusive with template — provide exactly one, never both. |
| Name | Required | Description |
|---|---|---|
| tags | Yes | The Carbone tags of the template, as written, e.g. "{d.customer.name}", "{d.items[i].label}", "{c.company}". {t()} translation tags are not listed. |
| error | No | Error reported by Carbone while inspecting; only present when there is one. |
| sample | Yes | A sample dataset matching the template structure, with placeholder values: { "data": {...}, "complement": {...} }. Pass sample.data as render_document data, and sample.complement as complement. |
| signatures | No | Signature fields found in the template; only present when there are any. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuinely non-obvious context beyond that: it consumes one render on the Carbone account and discards the resulting document, and it will not list {t()} translation tags. It does not cover auth or rate-limit behavior, which keeps it out of the top band.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four sentences, front-loaded with purpose, then routing guidance, then the parameter contract, then the translation-tag caveat. Every sentence carries information an agent needs, with no filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return values need no prose explanation, and annotations carry the safety profile. Given that, the description covers what is left: what it returns conceptually, when to call it, the parameter exclusivity, the account-side side effect, and a known limitation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3 and the schema already documents path forms, supported formats, and ID types in detail. The description still earns a bump by foregrounding the exclusive-or contract ('Pass exactly one of templateId ... or template') and summarizing the three accepted input forms, which is the key selection decision at call time.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb+resource pair: list the Carbone tags a template uses and return a matching sample JSON dataset. It also distinguishes itself from the closest sibling by naming render_document, so an agent can separate inspection from rendering without opening either schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives an explicit trigger: 'Call it before render_document when you do not know which data a template expects,' naming the alternative tool and the condition that selects it. It stops short of stating the inverse (skip it when the data shape is already known), so it is clear context rather than a full when/when-not rule.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all template categories currently in use in your Carbone account. Categories act like folders for organising templates (e.g. "invoices", "legal", "hr"). Use the returned names as the category filter in list_templates or upload_template.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| categories | Yes | Template category names in use. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare this as a read-only, idempotent, non-destructive, closed-world operation, so the safety profile is covered. The description adds genuine domain context beyond that — categories behave like folders, with concrete examples ('invoices', 'legal', 'hr') — though it says nothing about auth requirements or result size.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, each earning its place: what the tool returns, what a category conceptually is, and how to consume the output. The purpose is front-loaded with no preamble.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return-value documentation is unnecessary, and the description still explains how to use the returned names. For a zero-argument list tool with full annotations, nothing an agent needs is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline for a parameterless tool is 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('List all template categories') and scopes it to the caller's Carbone account. It is clearly distinguishable from siblings like list_templates and list_tags because it names the domain object it enumerates.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly routes the agent forward: 'Use the returned names as the category filter in list_templates or upload_template,' naming the downstream tools. It lacks an explicit when-not-to-use condition, but the usage context is unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all tags currently used across templates in your Carbone account. Tags are free-form labels attached to templates (e.g. "sales", "billing", "v2"). To find the templates with a tag, call list_templates and keep the results whose tags include it.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| tags | Yes | Template tag names in use. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, non-destructive and non-open-world behavior, so the safety profile is covered. The description adds genuinely new context beyond the annotations: tags are free-form (uncontrolled vocabulary) and the result is an account-wide aggregate across templates, which tells the agent what the list represents.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, front-loaded with the action and scope, then the definition, then the follow-up routing. No filler and no repetition of the title.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return values need not be explained, and the input is parameterless. The description covers purpose, scope, the meaning of the returned data, and the next step, leaving nothing an agent needs in order to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so there are no argument semantics to explain; the baseline for a parameterless tool is 4. Nothing in the description misrepresents the (empty) input contract.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('List all tags') with an explicit scope constraint ('currently used across templates in your Carbone account'), and defines the domain concept ('free-form labels attached to templates') so the agent knows what a tag is. This is enough to separate it from the template-listing siblings 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.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives concrete follow-up guidance: to resolve a tag to templates, call list_templates and filter results whose `tags` include it. It does not state exclusions or contrast against the similar-sounding list_categories sibling, so it stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List stored Carbone templates with filtering, search, and pagination. Filter by Template ID, Version ID, category, or upload origin. Use includeVersions to see the full version history of each template. Supports cursor-based pagination for large collections. Each result carries its tags: to find templates by tag, keep the results whose tags include it (list_tags lists the tags in use). Note: templates uploaded with versioning disabled appear with id = null and are identified only by their versionId — pass that versionId where a Template ID is expected (e.g. delete_template, download_template).
| Name | Required | Description | Default |
|---|---|---|---|
| id | No | Filter by Template ID (64-bit format). Cannot be a Version ID. | |
| limit | No | Maximum number of results to return, between 1 and 100 (Carbone API limit). Default: 100. Use cursor to page beyond that. | |
| cursor | No | Pagination cursor from the previous response nextCursor field. Use to fetch the next page. | |
| origin | No | Filter by upload origin: 0 = API, 1 = Carbone Studio, 2 = Salesforce integration, 3 = Odoo integration, 4 = HubSpot integration. Templates uploaded through this MCP server are origin 0. | |
| search | No | Fuzzy search in template names, or exact match on Template ID / Version ID. | |
| category | No | Filter by category (e.g. "invoices", "legal"). | |
| versionId | No | Filter by Version ID (SHA-256 format). | |
| includeVersions | No | If true, returns all versions for each template. Default: false (only deployed version). |
| Name | Required | Description |
|---|---|---|
| hasMore | Yes | Whether more results are available via the cursor. |
| templates | Yes | The matching templates (all fields). |
| nextCursor | No | Cursor to pass to the next list_templates call. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/idempotent/non-destructive/openWorld=false, so the safety profile is covered. The description adds genuinely non-obvious behavior: cursor-based pagination and the id=null case for templates uploaded with versioning disabled. It stops short of describing result shape, but the output schema handles that.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with purpose and filtering scope in the first sentence, then edge cases. Slight redundancy between the opening phrase "with filtering, search, and pagination" and the subsequent enumeration of filter fields, but every remaining sentence carries actionable content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an 8-parameter, zero-required listing tool with full schema coverage, annotations, and an output schema, the description covers the one thing structured fields cannot: the id=null/versionId fallback and tag-based lookup workflow. Nothing needed to invoke it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3, but the description adds real semantic value beyond the schema by explaining how id and versionId relate (null id, versionId as substitute) and how tags are actually consumed from results rather than filtered on.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Opens with a specific verb+resource ("List stored Carbone templates") and enumerates the filtering dimensions, which cleanly separates it from siblings like list_tags, list_categories, and inspect_template. An agent can identify the tool's role without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly routes the agent: use includeVersions for version history, use list_tags to discover tags (since tags are not a filter parameter here), and pass versionId to delete_template/download_template when id is null. It names concrete alternatives and the conditions that select them.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate a document by merging a Carbone template with JSON data. Two modes: (1) pass templateId to use a previously uploaded template; (2) pass template (a local file path, an HTTPS URL, or a base64-encoded string) to upload and render in a single request without storing a template. Supports output format conversion, multilingual rendering, currency conversion, batch generation, and advanced PDF options (watermark, password, PDF/A). Without data, every tag resolves to empty; to keep the tags as written, pass keepTags: true (e.g. to proof a stored template), or use convert_document for a file. Async mode: pass webhookUrl. This tool then returns only Carbone's acceptance message, never the document: Carbone POSTs { "success": true, "data": { "renderId": "..." } } to the webhook, whose server downloads the document itself from GET /render/{renderId} (one-time, no auth). You cannot fetch it from here. Batch generation (batchSplitBy) is always delivered this way.
| Name | Required | Description | Default |
|---|---|---|---|
| data | No | JSON data merged into the template — an object, or a top-level array (accessed with {d[i].field}). Access fields with {d.fieldName} tags. Nested objects: {d.customer.name}. Array loops: {d.items[i].description} … {d.items[i+1]}. Conditions: {d.status:ifEQ(active):show(Yes):elseShow(No)}. Optional: if omitted, {} is sent, so every tag resolves to empty ("Hello {d.name}!" becomes "Hello !"). To keep the tags as written instead, pass keepTags: true (and no data). Instead of inlining a large dataset, you may pass a STRING reference to the JSON: a local file path (e.g. "/data/invoices.json"), an HTTPS URL, or a base64-encoded JSON string — it is read and parsed server-side. | |
| enum | No | Enumeration map used with the :convEnum(TYPE) formatter to translate code values into human-readable labels. Define one key per enum type; each value is an object mapping code → label. Example: { "STATUS": { "1": "Active", "2": "Inactive", "3": "Pending" }, "ROLE": { "A": "Admin", "U": "User" } }. Template usage: {d.status:convEnum(STATUS)}, {d.role:convEnum(ROLE)}. May instead be passed by reference as a string — a local file path (e.g. "/data/invoices.json"), an HTTPS URL, or a base64-encoded JSON string. Documentation: https://carbone.io/documentation/design/advanced-features/key-value-mapping.html#convenum-type | |
| lang | No | Locale of the generated document. Affects three things: (1) {t(key)} translation tags — selects the matching translation from the translations map. (2) :formatN number formatter — applies locale-specific thousand/decimal separators. (3) :formatC currency formatter — applies locale-specific currency symbols and formatting. Format: BCP-47 lowercase, e.g. "fr-fr", "en-us", "de-de", "es-es", "pt-br", "zh-cn", "ja-jp". Full list: https://github.com/carboneio/carbone/blob/master/formatters/_locale.js | |
| failOn | No | Conditions that stop the render and return an error (Carbone v5.15.0+). "IMAGE_URL_ERROR": an image that cannot be downloaded from its URL fails the render, instead of being replaced with the broken-image placeholder. Empty image values are skipped; base64 images, barcodes and charts are not concerned. Example: ["IMAGE_URL_ERROR"]. Docs: https://carbone.io/documentation/developer/http-api/generate-reports.html#fail-on | |
| keepTags | No | If true, SKIP templating entirely and leave every Carbone tag in the document exactly as written: {d.customer} comes out as the literal text "{d.customer}", formatters included. Use it to proof a stored template in another format (e.g. render templateId to PDF to check the tag layout), or to convert a template between formats while it stays a template. Mutually exclusive with data: passing both is rejected, because data would have nothing to fill. Not the same as omitting data: no data renders the template with an EMPTY dataset, so every tag resolves to an empty string; keepTags leaves the tags themselves in place. | |
| template | No | Inline template for one-shot render without storing a template first. Three input forms are accepted: (1) Local file path — absolute, e.g. "/Users/me/report.docx" (or "C:\Users\me\report.docx" on Windows), or under the home directory, e.g. "~/report.docx". A relative path must start with "./" or "../" and resolves against the server process's working directory, which is rarely yours: prefer an absolute path. A bare file name such as "report.docx" is NOT a path: it would be sent as base64 content. (2) HTTPS URL — the file is downloaded automatically, e.g. "https://example.com/file.pptx". (3) Base64-encoded string — the raw file content encoded as base64. The template is uploaded and rendered in a single API request — no Template ID is returned. Use this for ephemeral renders; use upload_template + templateId when you need to reuse the template. Supported input formats: DOCX, XLSX, PPTX, ODT, ODS, ODP, ODG, HTML, XHTML, XML, SVG, IDML, MD, TXT, CSV, RTF, PDF. Carbone reads XML-based and text-based documents (plus PDF): the legacy binary Office formats DOC, XLS and PPT are rejected as input, although they are valid outputs. Re-save such a file as DOCX, XLSX or PPTX first. Mutually exclusive with templateId — provide exactly one, never both. | |
| timezone | No | IANA timezone used to convert dates in the rendered document. Default: "Europe/Paris". Applied when templates use the :formatD formatter, e.g. {d.date:formatD(YYYY-MM-DD HH:mm)}. Common values: "UTC", "America/New_York", "America/Los_Angeles", "Europe/London", "Europe/Paris", "Europe/Berlin", "Asia/Tokyo", "Asia/Shanghai", "Australia/Sydney". Full list (TZ identifier column): https://en.wikipedia.org/wiki/List_of_tz_database_time_zones | |
| convertTo | No | Output format. If omitted, the output keeps the template format. Valid outputs depend on the input format (e.g. HTML converts to pdf, docx or png, but not xlsx); see the conversion matrix: https://carbone.io/documentation/developer/http-api/generate-reports.html#output-file-type. "doc", "xls" and "ppt" are output formats; as input, use DOCX, XLSX or PPTX. Simple usage: "pdf". With options: { "formatName": "pdf", "formatOptions": { ... } }. | |
| converter | No | Converter engine, used whenever the format changes (not only for PDF). If omitted, "L" is used. "L" LibreOffice: DOCX, XLSX, PPTX, ODT, ODS, ODP, ODG, MD, PDF; the only converter supporting all PDF options. "I" Carbone ICE: DOCX and ODT to PDF; Carbone's own engine, 3x to 300x faster, recommended over "O" for DOCX from v5.15.0. It converts all content except WEBP and EMF/WMF images, SmartArt and complex charts (bar, line, area, pie and doughnut charts are drawn), comments, tracked changes, form fields and equations: keep the default "L" for documents with those. A missing font is replaced by Noto Sans (https://carbone.io/documentation/developer/http-api/generate-reports.html#converters-carbone-ice-limitations). "O" OnlyOffice: DOCX, XLSX, PPTX to PDF. "C" Chromium: HTML to PDF, JPG, PNG, WEBP with full CSS/JS; 100 MB max. PDF options: "L" supports all of them; "O", "C" and "I" apply Security (passwords, permissions) and Watermarks. Docs: https://carbone.io/documentation/developer/http-api/generate-reports.html#converters | |
| complement | No | Extra data object accessible in templates with {c.field} tags (as opposed to {d.field} for main data). Useful for static or shared values that should not be mixed into the main dataset: company info, logo URLs, footer text, configuration constants. Example: { "company": "Acme Corp", "address": "123 Main St", "vatNumber": "FR12345" }. Like data, may instead be passed by reference as a string — a local file path (e.g. "/data/invoices.json"), an HTTPS URL, or a base64-encoded JSON string. | |
| outputPath | No | Optional local file path to save the generated document to (e.g. "/home/user/out.pdf" or "~/out.pdf"). When set, the file is written to disk and the tool returns the saved path + size instead of embedding the document inline — ideal for large files. The path must not exist yet: an existing file is never overwritten (the call fails and asks for a new file name). Ignored for async/webhook renders (no document is returned inline). | |
| reportName | No | Filename (WITHOUT extension) for the generated document, returned in the Content-Disposition header. Carbone automatically appends the extension that matches convertTo, so do not include one — passing "invoice.pdf" yields "invoice.pdf.pdf". Supports Carbone tags resolved against the data at render time. Examples: "invoice" (static), "{d.type}-{d.id}" (dynamic), "{d.client}-{d.date:formatD(YYYY-MM)}". With keepTags (no templating pass), this server names the file "<reportName>.<ext>" itself, literally (tags are not resolved). | |
| returnLink | No | If true, generate the document and return a public download URL instead of the file contents. The link is SHORT-LIVED and ONE-TIME — Carbone deletes the file after the first download — so it is meant for the end user to download once (do not fetch it programmatically). Works in stdio and HTTP. Mutually exclusive with outputPath and asAttachment. Ignored when webhookUrl is set (no link is returned). | |
| templateId | No | The ID of a previously uploaded template to render. Two ID formats are accepted: (1) Template ID (64-bit) — stable identifier shared across versions; Carbone automatically uses the deployed version. (2) Version ID (SHA-256) — pins rendering to a specific version regardless of deployment status. Both are returned by upload_template. Mutually exclusive with template — provide exactly one, never both. | |
| webhookUrl | No | Webhook URL that enables asynchronous rendering (render timeout raised to 5 minutes). This tool then returns only Carbone's acceptance message, never the document. When the document is ready, Carbone POSTs { "success": true, "data": { "renderId": "..." } } to this URL; the server behind it must download the document itself with GET /render/{renderId} on the Carbone API (one-time, no auth). You cannot fetch it from here. Required for batchSplitBy: batch output is always delivered this way. outputPath, asAttachment and returnLink are ignored in this mode. Example: "https://your-server.com/carbone-webhook". | |
| batchOutput | No | Batch result type, with batchSplitBy. "zip" (default): an archive of all generated documents. "pdf": the generated PDFs concatenated into one file; requires convertTo "pdf". | |
| hardRefresh | No | If true, Carbone recomputes pagination and refreshes the table of contents after rendering. Requires convertTo to be defined. Use this for DOCX/ODT templates that contain a TOC field or cross-references that need updating after data injection. | |
| variableStr | No | Carbone alias definitions applied to the whole template, as if written in it. An alias is a shortcut to a data path, not a variable: it stores no value and computes nothing (no arithmetic, no concatenation). Define with {#alias = d.path}, optionally with $parameters: {#mealOf($weekday) = d[weekday = $weekday]}. Use them in the template with {$alias}, e.g. {$mealOf(2).name}. Example: "{#buyer = d.order.customer}", then {$buyer.name} in the template renders d.order.customer.name. To store a computed value, use the :set formatter instead. Documentation: https://carbone.io/documentation/design/substitutions/aliases.html#alias | |
| asAttachment | No | If true, return the document as a downloadable file attachment (a base64 EmbeddedResource), for any format. Default delivery: text and png/jpg/gif/webp are returned inline; other binary outputs (PDF, Office, …) are saved to a temp file (path returned). Ignored when outputPath or returnLink is set. | |
| batchSplitBy | No | Batch generation: one document per object of an array. Use "d" when data itself is an array, or "d.items" for a direct child array of data. Requires webhookUrl (batch is always asynchronous: the result goes to the webhook, not to this tool). At most 100 objects on Carbone Cloud. Combine with batchOutput and batchReportName. Docs: https://carbone.io/documentation/developer/http-api/generate-reports.html#batch-processing | |
| translations | No | Translation map for multilingual documents. Requires "lang" to be set to select the active locale. Top-level keys are BCP-47 locale codes; values are key → translated-string maps. Template usage: {t(greeting)} is replaced by the matching string for the active locale. Example: { "fr-fr": { "greeting": "Bonjour", "total": "Total" }, "en-us": { "greeting": "Hello", "total": "Total" } }. These dictionaries get large, so you may instead pass a string reference — a local file path (e.g. "/data/invoices.json"), an HTTPS URL, or a base64-encoded JSON string. Documentation: https://carbone.io/documentation/design/advanced-features/translations-i18n.html | |
| currencyRates | No | Exchange rate table used by :formatC for currency conversion. Keys are ISO 4217 currency codes; values are rates relative to a common base. The base currency should have rate 1. Example: { "EUR": 1, "USD": 1.08, "GBP": 0.86, "JPY": 160.5 }. May instead be passed by reference as a string — a local file path (e.g. "/data/invoices.json"), an HTTPS URL, or a base64-encoded JSON string. | |
| currencySource | No | ISO 4217 currency code of the monetary amounts in the JSON data. Used by the :formatC formatter as the conversion source. Must be set together with currencyTarget and currencyRates. Example: "EUR" if all prices in your data are in euros. | |
| currencyTarget | No | ISO 4217 currency code of the output document. The :formatC formatter converts amounts from currencySource to this currency using currencyRates. Must be set together with currencySource and currencyRates. Example: "USD" to display prices in US dollars. Documentation: https://carbone.io/documentation/design/formatters/currency.html#formatc-precisionorformat-targetcurrency | |
| webhookHeaders | No | Custom headers Carbone will include when POSTing to your webhookUrl. Pass plain header names as keys — the prefix "carbone-webhook-header-" is added automatically before sending to Carbone, and Carbone forwards the original header names to your webhook endpoint. Example: { "authorization": "my-secret", "custom-id": "12345", "custom-name": "Jane Doe" } — Carbone will call your URL with headers: authorization: my-secret, custom-id: 12345, custom-name: Jane Doe. Requires webhookUrl to be set. | |
| batchReportName | No | Name of each file inside the batch ZIP, WITHOUT extension (Carbone appends it). Carbone tags are resolved against each batch item, e.g. "invoice-{d.id}". Ignored when batchOutput is "pdf". From v5.14, an index is appended to every file as soon as two names collide (invoice_1.pdf, invoice_2.pdf). Requires batchSplitBy. | |
| egressAuthorization | No | Value for the Authorization header Carbone adds to its OUTBOUND (egress) requests while rendering — fetching external images ({d.imageUrl}), external PDFs (:appendFile / :attachFile), and calling webhooks. For example "Bearer abc123" or "my-secret" makes Carbone send `authorization: <value>` to those hosts. Only the authorization header can be customised; max 511 characters. For webhook calls specifically, webhookHeaders.authorization (if set) overrides this value. | |
| preReleaseFeatureIn | No | Pre-release feature level for this render only: features and fixes introduced up to this tag apply, later ones stay disabled. Overrides the server default; a tag set in the template overrides it. Example: 5000000. Docs: https://carbone.io/documentation/design/overview/version-lifecycle.html#pre-release-features |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare readOnly=false, openWorld=true, idempotent=false, destructive=false. The description adds crucial non-obvious behavior: in async mode it returns only Carbone's acceptance message and never the document, the webhook server must fetch GET /render/{renderId} (one-time, no auth), and 'You cannot fetch it from here.' This is high-value disclosure beyond structured fields.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Purpose and the two modes are front-loaded, and the async caveat is called out with emphasis. The prose is dense and long but nearly every sentence (keepTags semantics, webhook delivery, batch behavior) earns its place; minor trimming is possible.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 28-parameter, no-output-schema tool, the description covers the highest-risk behaviors: async/webhook delivery, mutual exclusivity, keepTags, and batch. Remaining details (converter engine choice, currency/translation plumbing) are fully documented in the schema, so completeness is strong though not exhaustive in the description itself.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% across all 28 params, so the schema already carries full parameter semantics; baseline is 3. The description reinforces the keepTags-vs-omitted-data distinction and mode exclusivity but mostly restates what the schema documents.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Opens with a specific verb+resource ('Generate a document by merging a Carbone template with JSON data') and immediately distinguishes its two operating modes (templateId vs inline template). It also names sibling tools (convert_document, upload_template) so an agent can differentiate without opening any schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly routes between alternatives: inline template for ephemeral renders vs upload_template + templateId for reuse, convert_document when working from a file, and keepTags to proof a stored template. It states the async condition (webhookUrl) and that batch generation is always delivered that way, leaving little to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update the metadata of ONE stored template version: name, comment, category, tags, deployment (deployedAt), scheduled deletion (expireAt), or the Template ID it belongs to (moveToTemplateId). With a Template ID, Carbone patches its currently deployed version only; with a Version ID, that exact version. Use deployedAt to choose the version used when rendering by Template ID. Returns the patched versionId and the updated fields, as echoed back by Carbone. To delete a template now, use delete_template.
| Name | Required | Description | Default |
|---|---|---|---|
| id | No | DEPRECATED: the 1.6.0 name of moveToTemplateId, kept so existing callers keep working. Use moveToTemplateId; passing both with different values is rejected. | |
| name | No | New display name, max 200 characters. | |
| tags | No | New list of tags, replacing the existing ones. Duplicates are removed and the list is sorted; the whole list is limited to 100 characters (about 8 tags of 9 characters). | |
| comment | No | New free-text comment, max 200 characters. | |
| category | No | New category, max 200 characters. | |
| expireAt | No | Schedule deletion of the patched version at a UTC Unix timestamp (seconds). After that time it is no longer listed, downloadable or renderable (404), and the file is purged after the retention delay. Send 0 to cancel a scheduled deletion (permanent again); omit to leave it unchanged. To delete now, use delete_template. | |
| deployedAt | No | Unix timestamp (seconds) to set as the deployment time for this version. Carbone picks the version with the most recent deployedAt when rendering by Template ID. Use 42000000000 to deploy immediately (special "NOW" value). Future values are not allowed, and the deployed version's deployedAt cannot move back in time. | |
| templateId | Yes | Template ID (64-bit) or Version ID (SHA-256) of the version to update. A Template ID patches only its currently deployed version (not every version). A Version ID patches that exact version. | |
| moveToTemplateId | No | CAUTION, structural change: moves the patched version to this other Template ID (64-bit; a Version ID is rejected). It is NOT the template to patch (that is templateId). Pass the version's Version ID as templateId; with a Template ID, its currently deployed version is moved and that Template ID falls back to its next most recent version (or stops resolving if none is left). Fails if the move creates a deployedAt conflict at the destination. Only use it when the user asks to move a version. |
| Name | Required | Description |
|---|---|---|
| id | No | Template ID the version now belongs to (returned when moveToTemplateId was used). |
| name | No | Name, returned if updated. |
| tags | No | Tags, returned if updated. |
| comment | No | Comment, returned if updated. |
| category | No | Category, returned if updated. |
| expireAt | No | Deletion timestamp (0 = never expires), returned if updated. |
| versionId | Yes | Version ID of the patched version. |
| deployedAt | No | Deployment timestamp, returned if updated. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark this as destructive, non-read-only, and idempotent, but the description adds substantial context: expireAt causes 404 and eventual file purge, deployedAt has a special NOW value and cannot move backward, and moveToTemplateId is a structural change with fallback behavior on the source template. These details go well beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core action and then layers on the important behavioral rules without filler. Every sentence carries actionable information for a 9-parameter mutation tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The output schema exists, so the return values needn't be fully explained, but the description still notes that the patched versionId and updated fields are echoed back. Combined with annotations and full schema coverage, an agent has everything needed to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema coverage, the schema already documents each parameter in depth, so the baseline is 3. The description adds a useful consolidated semantic layer—grouping the fields and clarifying the Template ID vs Version ID patching rule—but much of this overlaps the schema, keeping it below a full 5.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource ('Update the metadata of ONE stored template version') and enumerates the updatable fields, so an agent can immediately tell what the tool touches. It also distinguishes itself from delete_template and separates Template ID vs Version ID semantics.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives explicit when-to-use rules: Template ID patches only the deployed version, Version ID patches the exact version, and deployedAt selects the version used for rendering by Template ID. It also names delete_template for immediate deletion and cautions that moveToTemplateId should be used only when the user asks to move a version.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Upload and store a reusable Carbone template. Once uploaded, use render_document with the returned Template ID to generate documents from it. Supports versioning: multiple versions can live under a single stable Template ID, and rendering by Template ID uses the version with the most recent deployedAt. A result deployedAt of 0 means the version is not explicitly deployed: if another version of the same Template ID is deployed, renders by Template ID keep using that one. Accepted formats: DOCX, XLSX, PPTX, ODT, ODS, ODP, ODG, HTML, XHTML, XML, SVG, IDML, Markdown, TXT, CSV, RTF and PDF (not the legacy binary DOC, XLS or PPT).
| Name | Required | Description | Default |
|---|---|---|---|
| id | No | Existing Template ID (64-bit format) to add this upload to its version history. If omitted, a new Template ID is generated. Providing a Version ID (SHA-256) is not allowed and will cause an error. | |
| name | No | Display name for the template, max 200 characters (e.g. "Invoice Template", "NDA Contract"). Optional but recommended: list_templates shows it and its search matches it. | |
| tags | No | Labels shown by list_tags and on each list_templates result (e.g. ["sales", "billing", "v2"]). Duplicates are removed and the list is sorted; the whole list is limited to 100 characters (about 8 tags of 9 characters). | |
| sample | No | Sample input data attached to the template for testing in Carbone Studio: an array with at most ONE object, whose keys data, complement, translations and enum are all optional. Example: [{ "data": { "name": "Acme" } }]. | |
| comment | No | Free-text comment to describe the template version or its purpose, max 200 characters. | |
| category | No | Group templates into folders/categories, max 200 characters (e.g. "invoices", "legal", "hr"). | |
| expireAt | No | Schedule deletion at a UTC Unix timestamp (seconds); 0 (default) means the template never expires. After that time it is no longer listed, downloadable or renderable (404), and the file is purged after the retention delay. To remove a template now, use delete_template. | |
| template | Yes | The template file. Three input forms are accepted: (1) Local file path — absolute, e.g. "/Users/me/report.docx" (or "C:\Users\me\report.docx" on Windows), or under the home directory, e.g. "~/report.docx". A relative path must start with "./" or "../" and resolves against the server process's working directory, which is rarely yours: prefer an absolute path. A bare file name such as "report.docx" is NOT a path: it would be sent as base64 content. (2) HTTPS URL — the file is downloaded automatically, e.g. "https://example.com/file.pptx". (3) Base64-encoded string — the raw file content encoded as base64. Supported input formats: DOCX, XLSX, PPTX, ODT, ODS, ODP, ODG, HTML, XHTML, XML, SVG, IDML, MD, TXT, CSV, RTF, PDF. Carbone reads XML-based and text-based documents (plus PDF): the legacy binary Office formats DOC, XLS and PPT are rejected as input, although they are valid outputs. Re-save such a file as DOCX, XLSX or PPTX first. | |
| deployedAt | No | UTC Unix timestamp (seconds) to set as the deployment time for this version. Carbone uses the version with the most recent deployedAt when rendering via Template ID. Use 42000000000 to deploy immediately (special "NOW" sentinel value). Future values are not allowed. | |
| versioning | No | Enable template versioning (default: true). When true, a stable Template ID is generated and multiple versions can be managed under it. When false, behaves as legacy mode and returns only a templateId (SHA-256 hash) and templateExtension. |
| Name | Required | Description |
|---|---|---|
| id | No | Stable Template ID (when versioning is enabled). |
| name | No | Template display name, when one was given. |
| size | No | Template size in bytes. |
| type | No | Detected template file type. |
| createdAt | No | UTC Unix timestamp (seconds) of the upload. |
| versionId | No | Version ID (SHA-256) of this uploaded version. |
| deployedAt | No | UTC Unix timestamp of deployment; 0 means this version is not explicitly deployed. |
| templateId | No | Template ID returned in legacy/non-versioned mode. |
| templateExtension | No | Detected file extension, e.g. "docx" (legacy/non-versioned mode). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish that this is a non-read-only, open-world, non-idempotent, non-destructive operation. The description adds substantial behavioral context beyond those annotations: versioning semantics, the deployedAt=0 behavior, expiry/purge/404 consequences, and rejection of legacy binary Office formats.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core action and follow-up usage, then proceeds to versioning and format details. It is somewhat long and repeats accepted format information that also appears in the schema, but the size is reasonable for a complex 10-parameter upload tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the rich input schema, output schema, and annotations, the description covers what an agent needs: purpose, follow-up render action, versioning behavior, accepted formats, and expiry behavior. No critical behavior appears missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds meaningful cross-parameter semantics not fully captured by individual schema fields, especially how multiple versions relate to a stable Template ID and how rendering selects the most recent deployedAt version.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: uploading and storing a reusable Carbone template. It also explains the primary follow-up action via render_document using the returned Template ID, which clearly distinguishes this tool from render_document itself.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear usage context by saying the returned Template ID should be passed to render_document, and it mentions delete_template for immediate removal. It does not explicitly compare this tool against update_template_metadata or state when not to use it, so it falls short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v2.1.4update_template_metadata3 fields changedInput schema / properties / tags / items / maxLengthAdded value: +96Input schema / properties / tags / items / minLengthAdded value: +1Input schema / properties / tags / maxItemsAdded value: +100upload_template3 fields changedInput schema / properties / tags / items / maxLengthAdded value: +96Input schema / properties / tags / items / minLengthAdded value: +1Input schema / properties / tags / maxItemsAdded value: +100v2.0.0convert_document12 fields changedInput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"Input schema / properties / asAttachment / descriptionPrevious value: -"If true, return the document as a downloadable file attachment (a base64 EmbeddedResource), for any format. Default delivery: text and png/jpg/gif/webp are returned inline; other binary outputs (PDF, Office, …) are saved to a temp file in stdio mode (path returned), or returned as an attachment in HTTP mode. Ignored when outputPath or returnLink is set."New value: +"If true, return the document as a downloadable file attachment (a base64 EmbeddedResource), for any format. Default delivery: text and png/jpg/gif/webp are returned inline; other binary outputs (PDF, Office, …) are saved to a temp file (path returned). Ignored when outputPath or returnLink is set."Input schema / properties / convertTo / anyOfPrevious value: -[
- {
- "enum": [
- "pdf",
- "docx",
- "doc",
- "xlsx",
- "xls",
- "pptx",
- "ppt",
- "odt",
- "ods",
- "odp",
- "odg",
- "html",
- "xhtml",
- "txt",
- "csv",
- "md",
- "xml",
- "rtf",
- "png",
- "jpg",
- "jpeg",
- "webp",
- "svg",
- "tiff",
- "bmp",
- "gif",
- "zip",
- "idml",
- "epub",
- "cdr"
- ],
- "type": "string"
- },
- {
- "properties": {
- "formatName": {
- "description": "Target format name.",
- "enum": [
- "pdf",
- "docx",
- "doc",
- "xlsx",
- "xls",
- "pptx",
- "ppt",
- "odt",
- "ods",
- "odp",
- "odg",
- "html",
- "xhtml",
- "txt",
- "csv",
- "md",
- "xml",
- "rtf",
- "png",
- "jpg",
- "jpeg",
- "webp",
- "svg",
- "tiff",
- "bmp",
- "gif",
- "zip",
- "idml",
- "epub",
- "cdr"
- ],
- "type": "string"
- },
- "formatOptions": {
- "additionalProperties": {},
- "description": "Advanced format options object. Examples by format: PDF — { \"EncryptFile\": true, \"DocumentOpenPassword\": \"secret\", \"DocumentPermissionPassword\": \"owner\" } password-protect; PDF — { \"Watermarks\": [{ \"text\": \"DRAFT\", \"opacity\": 0.2, \"rotation\": -45, \"fontsize\": 60 }] } up to 5 watermarks; PDF — { \"SelectPdfVersion\": 1 } PDF/A-1b compliance (use 2 for PDF/A-2, 3 for PDF/A-3); PDF — { \"PageRange\": \"1-3,5\" } export specific pages only; PDF — { \"ConvertSlideshow\": true } convert each slide to a separate PDF page; Images (PNG/JPG/WEBP) — { \"Quality\": 90 } set compression quality 0-100; Images — { \"density\": 150 } set DPI for rasterisation (default 96); CSV — { \"fieldSeparator\": \";\" } custom column separator.",
- "propertyNames": {
- "type": "string"
- },
- "type": "object"
- }
- },
- "required": [
- "formatName"
- ],
- "type": "object"
- }
-]New value: +[
+ {
+ "enum": [
+ "pdf",
+ "docx",
+ "doc",
+ "odt",
+ "ott",
+ "rtf",
+ "epub",
+ "xlsx",
+ "xls",
+ "ods",
+ "ots",
+ "csv",
+ "dbf",
+ "dif",
+ "pptx",
+ "ppt",
+ "odp",
+ "otp",
+ "odg",
+ "html",
+ "xhtml",
+ "txt",
+ "md",
+ "xml",
+ "idml",
+ "png",
+ "jpg",
+ "jpeg",
+ "webp",
+ "gif",
+ "tiff",
+ "bmp",
+ "svg",
+ "emf",
+ "wmf",
+ "eps"
+ ],
+ "type": "string"
+ },
+ {
+ "properties": {
+ "formatName": {
+ "description": "Target format name.",
+ "enum": [
+ "pdf",
+ "docx",
+ "doc",
+ "odt",
+ "ott",
+ "rtf",
+ "epub",
+ "xlsx",
+ "xls",
+ "ods",
+ "ots",
+ "csv",
+ "dbf",
+ "dif",
+ "pptx",
+ "ppt",
+ "odp",
+ "otp",
+ "odg",
+ "html",
+ "xhtml",
+ "txt",
+ "md",
+ "xml",
+ "idml",
+ "png",
+ "jpg",
+ "jpeg",
+ "webp",
+ "gif",
+ "tiff",
+ "bmp",
+ "svg",
+ "emf",
+ "wmf",
+ "eps"
+ ],
+ "type": "string"
+ },
+ "formatOptions": {
+ "additionalProperties": {},
+ "description": "Format-specific options. Examples: PDF password: { \"EncryptFile\": true, \"DocumentOpenPassword\": \"s3cr3t\" }; PDF permissions: { \"RestrictPermissions\": true, \"PermissionPassword\": \"owner\" }; PDF watermarks (max 4): { \"Watermarks\": [{ \"text\": \"DRAFT\", \"size\": 60, \"opacity\": 0.2, \"rotation\": -45 }] }; PDF/A (L only): { \"SelectPdfVersion\": 2 } (2 = PDF/A-2b, 3 = PDF/A-3b, 4 = PDF/A-4); page selection (L only): { \"PageRange\": \"1-5\" }; accessibility (L only): { \"UseTaggedPDF\": true, \"PDFUACompliance\": true }; JPG/PNG: { \"PixelWidth\": 1200, \"PixelHeight\": 630 }, JPG quality: { \"Quality\": 80 } (1-100); CSV: { \"fieldSeparator\": \";\" }. All options: https://carbone.io/documentation/developer/http-api/generate-reports.html#pdf-options",
+ "propertyNames": {
+ "type": "string"
+ },
+ "type": "object"
+ }
+ },
+ "required": [
+ "formatName"
+ ],
+ "type": "object"
+ }
+]Input schema / properties / convertTo / descriptionPrevious value: -"Target output format. Documents : \"pdf\", \"docx\", \"xlsx\", \"pptx\", \"odt\", \"ods\", \"odp\", \"odg\", \"rtf\", \"epub\", plus the legacy \"doc\", \"xls\", \"ppt\" (output only — Carbone writes them but cannot read them back). Web/text : \"html\", \"xhtml\", \"txt\", \"csv\", \"md\", \"xml\", \"idml\". Images : \"png\", \"jpg\", \"jpeg\", \"webp\", \"svg\", \"tiff\", \"bmp\", \"gif\". Archive : \"zip\" (batch output). Simple usage: \"pdf\". Advanced usage: { \"formatName\": \"pdf\", \"formatOptions\": { \"EncryptFile\": true, \"DocumentOpenPassword\": \"secret\" } }."New value: +"Target output format. Valid outputs depend on the input format (e.g. HTML converts to pdf, docx or png, but not xlsx); see the conversion matrix: https://carbone.io/documentation/developer/http-api/generate-reports.html#output-file-type. \"doc\", \"xls\" and \"ppt\" are output formats; as input, use DOCX, XLSX or PPTX. Simple usage: \"pdf\". With options: { \"formatName\": \"pdf\", \"formatOptions\": { ... } }."Input schema / properties / converter / descriptionPrevious value: -"Converter engine. Only relevant when convertTo is \"pdf\" (or an image format rasterised from a document). \"L\" — LibreOffice (default): best all-round engine for DOCX, XLSX, PPTX, ODT, ODS, ODP. \"O\" — OnlyOffice: highest fidelity rendering for Microsoft Office formats (DOCX, XLSX, PPTX). \"C\" — Chromium: best for HTML, CSS, JavaScript — full browser rendering. \"I\" — Carbone ICE (Instant Converter Engine, Carbone 5.14.0+): DOCX → PDF ONLY, no third-party converter — up to 60x faster than LibreOffice on a 1000-page DOCX (3x on a one-page document). Any other input or output format is REJECTED — use another converter for those. PDF options: only Watermarks are applied. EncryptFile, DocumentOpenPassword, RestrictPermissions and the other security options are SILENTLY IGNORED — the PDF comes back readable by anyone, with no error — so NEVER pick \"I\" when the request needs a password or restricted permissions; use \"L\" for those. Also unsupported: WEBP and EMF/WMF images, table of contents, SmartArt, complex charts, footnotes/endnotes, comments, tracked changes, form fields, equations, bookmarks and links; a missing font falls back to Noto Sans. If omitted, LibreOffice is used by default."New value: +"Converter engine, used whenever the format changes (not only for PDF). If omitted, \"L\" is used. \"L\" LibreOffice: DOCX, XLSX, PPTX, ODT, ODS, ODP, ODG, MD, PDF; the only converter supporting all PDF options. \"I\" Carbone ICE: DOCX and ODT to PDF; Carbone's own engine, 3x to 300x faster, recommended over \"O\" for DOCX from v5.15.0. It converts all content except WEBP and EMF/WMF images, SmartArt and complex charts (bar, line, area, pie and doughnut charts are drawn), comments, tracked changes, form fields and equations: keep the default \"L\" for documents with those. A missing font is replaced by Noto Sans (https://carbone.io/documentation/developer/http-api/generate-reports.html#converters-carbone-ice-limitations). \"O\" OnlyOffice: DOCX, XLSX, PPTX to PDF. \"C\" Chromium: HTML to PDF, JPG, PNG, WEBP with full CSS/JS; 100 MB max. PDF options: \"L\" supports all of them; \"O\", \"C\" and \"I\" apply Security (passwords, permissions) and Watermarks. Docs: https://carbone.io/documentation/developer/http-api/generate-reports.html#converters"Input schema / properties / converter / enumPrevious value: -[
- "L",
- "C",
- "O",
- "I"
-]New value: +[
+ "L",
+ "O",
+ "C",
+ "I"
+]Input schema / properties / egressAuthorization / descriptionPrevious value: -"Value for the Authorization header Carbone adds to its OUTBOUND (egress) requests during conversion — e.g. when a Chromium HTML→PDF conversion fetches a protected external image or stylesheet. For example \"Bearer abc123\" makes Carbone send `authorization: Bearer abc123` to those hosts. Only the authorization header can be customised; max 512 characters."New value: +"Value for the Authorization header Carbone adds to its OUTBOUND (egress) requests during conversion — e.g. when a Chromium HTML→PDF conversion fetches a protected external image or stylesheet. For example \"Bearer abc123\" makes Carbone send `authorization: Bearer abc123` to those hosts. Only the authorization header can be customised; max 511 characters."Input schema / properties / egressAuthorization / maxLengthPrevious value: -512New value: +511Input schema / properties / file / descriptionPrevious value: -"The document to convert. Three input forms are accepted: (1) Local file path — absolute or relative, e.g. \"/home/user/report.docx\" or \"./invoice.xlsx\". (2) HTTPS URL — the file is downloaded automatically, e.g. \"https://example.com/file.pptx\". (3) Base64-encoded string — the raw file content encoded as base64. Supported input formats: DOCX, XLSX, PPTX, ODT, ODS, ODP, ODG, HTML, XHTML, XML, SVG, IDML, Markdown (MD), TXT, CSV, RTF, PDF, PNG and JPG. Carbone reads XML-based and text-based documents only, so the legacy BINARY Office formats DOC, XLS and PPT are REJECTED as input — Carbone can produce them as output but cannot read them. Re-save such a file as DOCX/XLSX/PPTX first. Full conversion matrix: https://carbone.io/documentation/developer/http-api/generate-reports.md"New value: +"The document to convert. Three input forms are accepted: (1) Local file path — absolute, e.g. \"/Users/me/report.docx\" (or \"C:\\Users\\me\\report.docx\" on Windows), or under the home directory, e.g. \"~/report.docx\". A relative path must start with \"./\" or \"../\" and resolves against the server process's working directory, which is rarely yours: prefer an absolute path. A bare file name such as \"report.docx\" is NOT a path: it would be sent as base64 content. (2) HTTPS URL — the file is downloaded automatically, e.g. \"https://example.com/file.pptx\". (3) Base64-encoded string — the raw file content encoded as base64. Supported input formats: DOCX, XLSX, PPTX, ODT, ODS, ODP, ODG, HTML, XHTML, XML, SVG, IDML, MD, TXT, CSV, RTF, PDF. Carbone reads XML-based and text-based documents (plus PDF): the legacy binary Office formats DOC, XLS and PPT are rejected as input, although they are valid outputs. Re-save such a file as DOCX, XLSX or PPTX first. Full conversion matrix: https://carbone.io/documentation/developer/http-api/generate-reports.html#output-file-type"Input schema / properties / hardRefresh / descriptionPrevious value: -"Forces Carbone to run the converter even when the output format already matches the input format. Only useful for PDF: converting PDF → PDF to APPLY formatOptions (watermark, password, PDF/A, page range). Without it Carbone may pass the file straight through and none of those options take effect. Leave unset for any format-changing conversion (DOCX → PDF, XLSX → CSV, …), where the converter runs anyway."New value: +"If true, Carbone runs the converter even when the output format equals the input format, and recomputes pagination and the table of contents at the end of the conversion. Needed for PDF → PDF: without it Carbone returns the PDF unchanged and formatOptions (password, permissions, watermarks, PDF/A, …) are NOT applied. This server sets it automatically when the input is a PDF, convertTo is \"pdf\" and formatOptions are given; pass false to opt out. Example (PDF → PDF/A-4): { \"hardRefresh\": true, \"convertTo\": { \"formatName\": \"pdf\", \"formatOptions\": { \"SelectPdfVersion\": 4 } } }."Input schema / properties / outputPath / descriptionPrevious value: -"Optional local file path to save the converted document to (e.g. \"/home/user/out.pdf\" or \"~/out.pdf\"). When set, the file is written to disk and the tool returns the saved path + size instead of embedding the document inline — ideal for large files."New value: +"Optional local file path to save the converted document to (e.g. \"/home/user/out.pdf\" or \"~/out.pdf\"). When set, the file is written to disk and the tool returns the saved path + size instead of embedding the document inline — ideal for large files. The path must not exist yet: an existing file is never overwritten (the call fails and asks for a new file name)."Input schema / properties / reportName / descriptionPrevious value: -"Filename (WITHOUT extension) for the converted document, returned in the Content-Disposition header. Carbone appends the extension matching convertTo, so do not include one — \"report.pdf\" yields \"report.pdf.pdf\". Examples: \"contract\", \"2026-invoice\". Unlike render_document, Carbone tags are NOT resolved here (conversion does not run templating), so pass a literal name rather than a pattern like \"{d.id}\" — a pattern would come back verbatim. Ignored when returnLink is set, which returns a download URL rather than a named file."New value: +"Name of the delivered file, WITHOUT extension (e.g. \"contract\", \"2026-invoice\"). The document is delivered as \"<reportName>.<ext>\", with the extension of convertTo, used as the attachment name and the default saved file name. This server names the file itself: a conversion has no templating pass, which is where Carbone resolves reportName. Used literally: Carbone tags such as {d.id} are not resolved here. Ignored with returnLink (a download URL, not a named file) and with outputPath (which sets the path itself)."delete_template1 field changedInput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"download_template3 fields changedInput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"Input schema / properties / outputPath / descriptionPrevious value: -"Optional local file path to save the template file to (e.g. \"/home/user/out.pdf\" or \"~/out.pdf\"). When set, the file is written to disk and the tool returns the saved path + size instead of embedding the document inline — ideal for large files."New value: +"Optional local file path to save the template file to (e.g. \"/home/user/out.pdf\" or \"~/out.pdf\"). When set, the file is written to disk and the tool returns the saved path + size instead of embedding the document inline — ideal for large files. The path must not exist yet: an existing file is never overwritten (the call fails and asks for a new file name)."Input schema / properties / sample / descriptionPrevious value: -"If true, download the JSON SAMPLE DATASET saved with the template (the \"sample\" array passed to upload_template) instead of the template file. Returns JSON of the form [{ \"data\": {...}, \"complement\": {...}, \"translations\": {...}, \"enum\": {...} }]. Use it to recover the example data a template expects — handy before calling render_document against an unfamiliar template. Errors if the template was uploaded without a sample."New value: +"If true, download the JSON SAMPLE DATASET saved with the template (the \"sample\" array passed to upload_template) instead of the template file, returned as inline JSON text by default, of the form [{ \"data\": {...}, \"complement\": {...}, \"translations\": {...}, \"enum\": {...} }] (each key optional). Use it to recover the example data a template expects before calling render_document. Errors if the template was uploaded without a sample."get_api_status1 field changedOutput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"inspect_templatelist_categories1 field changedOutput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"list_tags1 field changedOutput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"list_templates4 fields changedInput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"Input schema / properties / limit / descriptionPrevious value: -"Maximum number of results to return, between 1 and 100. Default: 100. Use cursor to page beyond that."New value: +"Maximum number of results to return, between 1 and 100 (Carbone API limit). Default: 100. Use cursor to page beyond that."Input schema / properties / origin / descriptionPrevious value: -"Filter by upload origin. 0 = API, 1 = Carbone Studio, 2 = Salesforce, 3 = Odoo, 4 = HubSpot. Templates created through this MCP are origin 0."New value: +"Filter by upload origin: 0 = API, 1 = Carbone Studio, 2 = Salesforce integration, 3 = Odoo integration, 4 = HubSpot integration. Templates uploaded through this MCP server are origin 0."Output schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"render_document24 fields changedInput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"Input schema / properties / asAttachment / descriptionPrevious value: -"If true, return the document as a downloadable file attachment (a base64 EmbeddedResource), for any format. Default delivery: text and png/jpg/gif/webp are returned inline; other binary outputs (PDF, Office, …) are saved to a temp file in stdio mode (path returned), or returned as an attachment in HTTP mode. Ignored when outputPath or returnLink is set."New value: +"If true, return the document as a downloadable file attachment (a base64 EmbeddedResource), for any format. Default delivery: text and png/jpg/gif/webp are returned inline; other binary outputs (PDF, Office, …) are saved to a temp file (path returned). Ignored when outputPath or returnLink is set."Input schema / properties / batchOutput / descriptionPrevious value: -"How the batch result is packaged. Defaults to \"zip\". \"zip\" — every generated document is bundled into a single ZIP archive (use batchReportName to name each entry). \"pdf\" — all documents are CONCATENATED into one continuous PDF instead of being zipped; this requires convertTo to be \"pdf\" as well. Must be used together with batchSplitBy."New value: +"Batch result type, with batchSplitBy. \"zip\" (default): an archive of all generated documents. \"pdf\": the generated PDFs concatenated into one file; requires convertTo \"pdf\"."Input schema / properties / batchReportName / descriptionPrevious value: -"Filename pattern for each individual document inside the batch ZIP. Supports Carbone tags. Tags are resolved against the item's data (relative path) or the full dataset (absolute path). Examples: \"invoice-{d.id}.pdf\", \"{d.client.name}-{d.date}.docx\". Carbone sanitises the result — path separators, \"..\", Windows-forbidden and control characters each become an underscore — and appends an index to duplicates (\"report_1.pdf\", \"report_2.pdf\"), so a pattern that resolves to the same name for several items will not silently drop documents. Only meaningful with batchOutput: \"zip\"; a concatenated \"pdf\" batch is a single file. Must be used together with batchSplitBy."New value: +"Name of each file inside the batch ZIP, WITHOUT extension (Carbone appends it). Carbone tags are resolved against each batch item, e.g. \"invoice-{d.id}\". Ignored when batchOutput is \"pdf\". From v5.14, an index is appended to every file as soon as two names collide (invoice_1.pdf, invoice_2.pdf). Requires batchSplitBy."Input schema / properties / batchSplitBy / descriptionPrevious value: -"JSON path to the array in your data that drives batch generation. One document is generated per element of the array. Two forms: \"d\" when data itself IS the array (one report per top-level element), or \"d.arrayName\" to split on a child array. Example: \"d.invoices\" — produces one PDF per item in data.invoices. Example: \"d.employees\" — produces one contract per employee. Carbone Cloud allows 1 to 100 objects per batch (on-premise follows the nbReportMaxPerBatch setting). Batch is ALWAYS asynchronous — webhookUrl is required. Pair with batchOutput to choose ZIP or a single concatenated PDF, and batchReportName to name each document."New value: +"Batch generation: one document per object of an array. Use \"d\" when data itself is an array, or \"d.items\" for a direct child array of data. Requires webhookUrl (batch is always asynchronous: the result goes to the webhook, not to this tool). At most 100 objects on Carbone Cloud. Combine with batchOutput and batchReportName. Docs: https://carbone.io/documentation/developer/http-api/generate-reports.html#batch-processing"Input schema / properties / convertTo / anyOfPrevious value: -[
- {
- "enum": [
- "pdf",
- "docx",
- "doc",
- "xlsx",
- "xls",
- "pptx",
- "ppt",
- "odt",
- "ods",
- "odp",
- "odg",
- "html",
- "xhtml",
- "txt",
- "csv",
- "md",
- "xml",
- "rtf",
- "png",
- "jpg",
- "jpeg",
- "webp",
- "svg",
- "tiff",
- "bmp",
- "gif",
- "zip",
- "idml",
- "epub",
- "cdr"
- ],
- "type": "string"
- },
- {
- "properties": {
- "formatName": {
- "description": "Target format name.",
- "enum": [
- "pdf",
- "docx",
- "doc",
- "xlsx",
- "xls",
- "pptx",
- "ppt",
- "odt",
- "ods",
- "odp",
- "odg",
- "html",
- "xhtml",
- "txt",
- "csv",
- "md",
- "xml",
- "rtf",
- "png",
- "jpg",
- "jpeg",
- "webp",
- "svg",
- "tiff",
- "bmp",
- "gif",
- "zip",
- "idml",
- "epub",
- "cdr"
- ],
- "type": "string"
- },
- "formatOptions": {
- "additionalProperties": {},
- "description": "Advanced format options object. Examples by format: PDF — { \"EncryptFile\": true, \"DocumentOpenPassword\": \"secret\", \"DocumentPermissionPassword\": \"owner\" } password-protect; PDF — { \"Watermarks\": [{ \"text\": \"DRAFT\", \"opacity\": 0.2, \"rotation\": -45, \"fontsize\": 60 }] } up to 5 watermarks; PDF — { \"SelectPdfVersion\": 1 } PDF/A-1b compliance (use 2 for PDF/A-2, 3 for PDF/A-3); PDF — { \"PageRange\": \"1-3,5\" } export specific pages only; PDF — { \"ConvertSlideshow\": true } convert each slide to a separate PDF page; Images (PNG/JPG/WEBP) — { \"Quality\": 90 } compression quality 0-100; Images — { \"density\": 150 } DPI for rasterisation (default 96); CSV — { \"fieldSeparator\": \";\" } custom column separator.",
- "propertyNames": {
- "type": "string"
- },
- "type": "object"
- }
- },
- "required": [
- "formatName"
- ],
- "type": "object"
- }
-]New value: +[
+ {
+ "enum": [
+ "pdf",
+ "docx",
+ "doc",
+ "odt",
+ "ott",
+ "rtf",
+ "epub",
+ "xlsx",
+ "xls",
+ "ods",
+ "ots",
+ "csv",
+ "dbf",
+ "dif",
+ "pptx",
+ "ppt",
+ "odp",
+ "otp",
+ "odg",
+ "html",
+ "xhtml",
+ "txt",
+ "md",
+ "xml",
+ "idml",
+ "png",
+ "jpg",
+ "jpeg",
+ "webp",
+ "gif",
+ "tiff",
+ "bmp",
+ "svg",
+ "emf",
+ "wmf",
+ "eps"
+ ],
+ "type": "string"
+ },
+ {
+ "properties": {
+ "formatName": {
+ "description": "Target format name.",
+ "enum": [
+ "pdf",
+ "docx",
+ "doc",
+ "odt",
+ "ott",
+ "rtf",
+ "epub",
+ "xlsx",
+ "xls",
+ "ods",
+ "ots",
+ "csv",
+ "dbf",
+ "dif",
+ "pptx",
+ "ppt",
+ "odp",
+ "otp",
+ "odg",
+ "html",
+ "xhtml",
+ "txt",
+ "md",
+ "xml",
+ "idml",
+ "png",
+ "jpg",
+ "jpeg",
+ "webp",
+ "gif",
+ "tiff",
+ "bmp",
+ "svg",
+ "emf",
+ "wmf",
+ "eps"
+ ],
+ "type": "string"
+ },
+ "formatOptions": {
+ "additionalProperties": {},
+ "description": "Format-specific options. Examples: PDF password: { \"EncryptFile\": true, \"DocumentOpenPassword\": \"s3cr3t\" }; PDF permissions: { \"RestrictPermissions\": true, \"PermissionPassword\": \"owner\" }; PDF watermarks (max 4): { \"Watermarks\": [{ \"text\": \"DRAFT\", \"size\": 60, \"opacity\": 0.2, \"rotation\": -45 }] }; PDF/A (L only): { \"SelectPdfVersion\": 2 } (2 = PDF/A-2b, 3 = PDF/A-3b, 4 = PDF/A-4); page selection (L only): { \"PageRange\": \"1-5\" }; accessibility (L only): { \"UseTaggedPDF\": true, \"PDFUACompliance\": true }; JPG/PNG: { \"PixelWidth\": 1200, \"PixelHeight\": 630 }, JPG quality: { \"Quality\": 80 } (1-100); CSV: { \"fieldSeparator\": \";\" }. All options: https://carbone.io/documentation/developer/http-api/generate-reports.html#pdf-options",
+ "propertyNames": {
+ "type": "string"
+ },
+ "type": "object"
+ }
+ },
+ "required": [
+ "formatName"
+ ],
+ "type": "object"
+ }
+]Input schema / properties / convertTo / descriptionPrevious value: -"Output format. If omitted, the output matches the template format. Documents : \"pdf\", \"docx\", \"xlsx\", \"pptx\", \"odt\", \"ods\", \"odp\", \"odg\", \"rtf\", \"epub\". Web/text : \"html\", \"xhtml\", \"txt\", \"csv\", \"md\", \"xml\", \"idml\". Images : \"png\", \"jpg\", \"jpeg\", \"webp\", \"svg\", \"tiff\", \"bmp\", \"gif\". Archive : \"zip\" (use with batchSplitBy for batch output). Simple usage: \"pdf\". Advanced usage: { \"formatName\": \"pdf\", \"formatOptions\": { ... } } for PDF-specific options."New value: +"Output format. If omitted, the output keeps the template format. Valid outputs depend on the input format (e.g. HTML converts to pdf, docx or png, but not xlsx); see the conversion matrix: https://carbone.io/documentation/developer/http-api/generate-reports.html#output-file-type. \"doc\", \"xls\" and \"ppt\" are output formats; as input, use DOCX, XLSX or PPTX. Simple usage: \"pdf\". With options: { \"formatName\": \"pdf\", \"formatOptions\": { ... } }."Input schema / properties / converter / descriptionPrevious value: -"Converter engine. Only relevant when convertTo is \"pdf\" (or an image rasterised from a document). \"L\" — LibreOffice (default): best all-round engine for DOCX, XLSX, PPTX, ODT, ODS, ODP. \"O\" — OnlyOffice: highest fidelity for Microsoft Office formats (DOCX, XLSX, PPTX). \"C\" — Chromium: best for HTML/CSS/JS templates — full browser rendering. \"I\" — Carbone ICE (Instant Converter Engine, Carbone 5.14.0+): DOCX → PDF ONLY, no third-party converter — up to 60x faster than LibreOffice on a 1000-page DOCX (3x on a one-page document). Any other input or output format is REJECTED — use another converter for those. PDF options: only Watermarks are applied. EncryptFile, DocumentOpenPassword, RestrictPermissions and the other security options are SILENTLY IGNORED — the PDF comes back readable by anyone, with no error — so NEVER pick \"I\" when the request needs a password or restricted permissions; use \"L\" for those. Also unsupported: WEBP and EMF/WMF images, table of contents, SmartArt, complex charts, footnotes/endnotes, comments, tracked changes, form fields, equations, bookmarks and links; a missing font falls back to Noto Sans. If omitted, LibreOffice is used by default."New value: +"Converter engine, used whenever the format changes (not only for PDF). If omitted, \"L\" is used. \"L\" LibreOffice: DOCX, XLSX, PPTX, ODT, ODS, ODP, ODG, MD, PDF; the only converter supporting all PDF options. \"I\" Carbone ICE: DOCX and ODT to PDF; Carbone's own engine, 3x to 300x faster, recommended over \"O\" for DOCX from v5.15.0. It converts all content except WEBP and EMF/WMF images, SmartArt and complex charts (bar, line, area, pie and doughnut charts are drawn), comments, tracked changes, form fields and equations: keep the default \"L\" for documents with those. A missing font is replaced by Noto Sans (https://carbone.io/documentation/developer/http-api/generate-reports.html#converters-carbone-ice-limitations). \"O\" OnlyOffice: DOCX, XLSX, PPTX to PDF. \"C\" Chromium: HTML to PDF, JPG, PNG, WEBP with full CSS/JS; 100 MB max. PDF options: \"L\" supports all of them; \"O\", \"C\" and \"I\" apply Security (passwords, permissions) and Watermarks. Docs: https://carbone.io/documentation/developer/http-api/generate-reports.html#converters"Input schema / properties / converter / enumPrevious value: -[
- "L",
- "C",
- "O",
- "I"
-]New value: +[
+ "L",
+ "O",
+ "C",
+ "I"
+]Input schema / properties / currencyTarget / descriptionPrevious value: -"ISO 4217 currency code of the output document. The :formatC formatter converts amounts from currencySource to this currency using currencyRates. Must be set together with currencySource and currencyRates. Example: \"USD\" to display prices in US dollars. Documentation: https://carbone.io/documentation.html#formatc-precisionorformat-"New value: +"ISO 4217 currency code of the output document. The :formatC formatter converts amounts from currencySource to this currency using currencyRates. Must be set together with currencySource and currencyRates. Example: \"USD\" to display prices in US dollars. Documentation: https://carbone.io/documentation/design/formatters/currency.html#formatc-precisionorformat-targetcurrency"Input schema / properties / data / descriptionPrevious value: -"JSON data merged into the template — an object, or a top-level array (accessed with {d[i].field}). Access fields with {d.fieldName} tags. Nested objects: {d.customer.name}. Array loops: {d.items[i].description} … {d.items[i+1]}. Conditionals: {d.status == \"active\" ? \"Yes\" : \"No\"}. Optional — if omitted, defaults to an empty object {} so the template is simply converted (tags resolve to empty). Useful to convert a stored template by templateId without data injection. Instead of inlining a large dataset, you may pass a STRING reference to the JSON: a local file path (e.g. \"/data/invoices.json\"), an HTTPS URL, or a base64-encoded JSON string — it is read and parsed server-side."New value: +"JSON data merged into the template — an object, or a top-level array (accessed with {d[i].field}). Access fields with {d.fieldName} tags. Nested objects: {d.customer.name}. Array loops: {d.items[i].description} … {d.items[i+1]}. Conditions: {d.status:ifEQ(active):show(Yes):elseShow(No)}. Optional: if omitted, {} is sent, so every tag resolves to empty (\"Hello {d.name}!\" becomes \"Hello !\"). To keep the tags as written instead, pass keepTags: true (and no data). Instead of inlining a large dataset, you may pass a STRING reference to the JSON: a local file path (e.g. \"/data/invoices.json\"), an HTTPS URL, or a base64-encoded JSON string — it is read and parsed server-side."Input schema / properties / egressAuthorization / descriptionPrevious value: -"Value for the Authorization header Carbone adds to its OUTBOUND (egress) requests while rendering — fetching external images ({d.imageUrl}), external PDFs (:appendFile / :attachFile), and calling webhooks. For example \"Bearer abc123\" or \"my-secret\" makes Carbone send `authorization: <value>` to those hosts. Only the authorization header can be customised; max 512 characters. For webhook calls specifically, webhookHeaders.authorization (if set) overrides this value."New value: +"Value for the Authorization header Carbone adds to its OUTBOUND (egress) requests while rendering — fetching external images ({d.imageUrl}), external PDFs (:appendFile / :attachFile), and calling webhooks. For example \"Bearer abc123\" or \"my-secret\" makes Carbone send `authorization: <value>` to those hosts. Only the authorization header can be customised; max 511 characters. For webhook calls specifically, webhookHeaders.authorization (if set) overrides this value."Input schema / properties / egressAuthorization / maxLengthPrevious value: -512New value: +511Input schema / properties / enum / descriptionPrevious value: -"Enumeration map used with the :convEnum(TYPE) formatter to translate code values into human-readable labels. Define one key per enum type; each value is an object mapping code → label. Example: { \"STATUS\": { \"1\": \"Active\", \"2\": \"Inactive\", \"3\": \"Pending\" }, \"ROLE\": { \"A\": \"Admin\", \"U\": \"User\" } }. Template usage: {d.status:convEnum(STATUS)}, {d.role:convEnum(ROLE)}. May instead be passed by reference as a string — a local file path (e.g. \"/data/invoices.json\"), an HTTPS URL, or a base64-encoded JSON string. Documentation: https://carbone.io/documentation.html#convenum-type-"New value: +"Enumeration map used with the :convEnum(TYPE) formatter to translate code values into human-readable labels. Define one key per enum type; each value is an object mapping code → label. Example: { \"STATUS\": { \"1\": \"Active\", \"2\": \"Inactive\", \"3\": \"Pending\" }, \"ROLE\": { \"A\": \"Admin\", \"U\": \"User\" } }. Template usage: {d.status:convEnum(STATUS)}, {d.role:convEnum(ROLE)}. May instead be passed by reference as a string — a local file path (e.g. \"/data/invoices.json\"), an HTTPS URL, or a base64-encoded JSON string. Documentation: https://carbone.io/documentation/design/advanced-features/key-value-mapping.html#convenum-type"Input schema / properties / failOnAdded value: +{
+ "description": "Conditions that stop the render and return an error (Carbone v5.15.0+). \"IMAGE_URL_ERROR\": an image that cannot be downloaded from its URL fails the render, instead of being replaced with the broken-image placeholder. Empty image values are skipped; base64 images, barcodes and charts are not concerned. Example: [\"IMAGE_URL_ERROR\"]. Docs: https://carbone.io/documentation/developer/http-api/generate-reports.html#fail-on",
+ "items": {
+ "enum": [
+ "IMAGE_URL_ERROR"
+ ],
+ "type": "string"
+ },
+ "type": "array"
+}Input schema / properties / keepTags / descriptionPrevious value: -"If true, SKIP templating entirely and leave every Carbone tag in the document exactly as written — {d.customer} comes out as the literal text \"{d.customer}\", formatters included. Use it to proof a stored template in another format (e.g. render templateId to PDF to check the tag layout), or to convert a template between formats while it stays a template. Mutually exclusive with data — passing both is rejected, because data would have nothing to fill. Note the difference from omitting data: no data renders the template with an EMPTY dataset, so every tag resolves to an empty string; keepTags leaves the tags themselves in place. Requires Carbone 5.9.0+ (carbone-version: 5)."New value: +"If true, SKIP templating entirely and leave every Carbone tag in the document exactly as written: {d.customer} comes out as the literal text \"{d.customer}\", formatters included. Use it to proof a stored template in another format (e.g. render templateId to PDF to check the tag layout), or to convert a template between formats while it stays a template. Mutually exclusive with data: passing both is rejected, because data would have nothing to fill. Not the same as omitting data: no data renders the template with an EMPTY dataset, so every tag resolves to an empty string; keepTags leaves the tags themselves in place."Input schema / properties / outputPath / descriptionPrevious value: -"Optional local file path to save the generated document to (e.g. \"/home/user/out.pdf\" or \"~/out.pdf\"). When set, the file is written to disk and the tool returns the saved path + size instead of embedding the document inline — ideal for large files. Ignored for async/webhook renders (no document is returned inline)."New value: +"Optional local file path to save the generated document to (e.g. \"/home/user/out.pdf\" or \"~/out.pdf\"). When set, the file is written to disk and the tool returns the saved path + size instead of embedding the document inline — ideal for large files. The path must not exist yet: an existing file is never overwritten (the call fails and asks for a new file name). Ignored for async/webhook renders (no document is returned inline)."Input schema / properties / preReleaseFeatureInAdded value: +{
+ "description": "Pre-release feature level for this render only: features and fixes introduced up to this tag apply, later ones stay disabled. Overrides the server default; a tag set in the template overrides it. Example: 5000000. Docs: https://carbone.io/documentation/design/overview/version-lifecycle.html#pre-release-features",
+ "maximum": 9007199254740991,
+ "minimum": -9007199254740991,
+ "type": "integer"
+}Input schema / properties / reportName / descriptionPrevious value: -"Filename (WITHOUT extension) for the generated document, returned in the Content-Disposition header. Carbone automatically appends the extension that matches convertTo, so do not include one — passing \"invoice.pdf\" yields \"invoice.pdf.pdf\". Supports Carbone tags resolved against the data at render time. Examples: \"invoice\" (static), \"{d.type}-{d.id}\" (dynamic), \"{d.client}-{d.date:formatD(YYYY-MM)}\"."New value: +"Filename (WITHOUT extension) for the generated document, returned in the Content-Disposition header. Carbone automatically appends the extension that matches convertTo, so do not include one — passing \"invoice.pdf\" yields \"invoice.pdf.pdf\". Supports Carbone tags resolved against the data at render time. Examples: \"invoice\" (static), \"{d.type}-{d.id}\" (dynamic), \"{d.client}-{d.date:formatD(YYYY-MM)}\". With keepTags (no templating pass), this server names the file \"<reportName>.<ext>\" itself, literally (tags are not resolved)."Input schema / properties / returnLink / descriptionPrevious value: -"If true, generate the document and return a public download URL instead of the file contents. The link is SHORT-LIVED and ONE-TIME — Carbone deletes the file after the first download — so it is meant for the end user to download once (do not fetch it programmatically). Works in stdio and HTTP. Mutually exclusive with outputPath, asAttachment, and webhookUrl (async)."New value: +"If true, generate the document and return a public download URL instead of the file contents. The link is SHORT-LIVED and ONE-TIME — Carbone deletes the file after the first download — so it is meant for the end user to download once (do not fetch it programmatically). Works in stdio and HTTP. Mutually exclusive with outputPath and asAttachment. Ignored when webhookUrl is set (no link is returned)."Input schema / properties / template / descriptionPrevious value: -"Inline template for one-shot render without storing a template first. Three input forms are accepted: (1) Local file path — absolute or relative, e.g. \"/home/user/report.docx\" or \"./invoice.xlsx\". (2) HTTPS URL — the file is downloaded automatically, e.g. \"https://example.com/file.pptx\". (3) Base64-encoded string — the raw file content encoded as base64. The template is uploaded and rendered in a single API request — no Template ID is returned. Use this for ephemeral renders; use upload_template + templateId when you need to reuse the template. Supported formats: DOCX, XLSX, PPTX, ODT, ODS, ODP, ODG, HTML, XHTML, IDML, XML, Markdown (MD), PDF, and more. Mutually exclusive with templateId — provide exactly one, never both."New value: +"Inline template for one-shot render without storing a template first. Three input forms are accepted: (1) Local file path — absolute, e.g. \"/Users/me/report.docx\" (or \"C:\\Users\\me\\report.docx\" on Windows), or under the home directory, e.g. \"~/report.docx\". A relative path must start with \"./\" or \"../\" and resolves against the server process's working directory, which is rarely yours: prefer an absolute path. A bare file name such as \"report.docx\" is NOT a path: it would be sent as base64 content. (2) HTTPS URL — the file is downloaded automatically, e.g. \"https://example.com/file.pptx\". (3) Base64-encoded string — the raw file content encoded as base64. The template is uploaded and rendered in a single API request — no Template ID is returned. Use this for ephemeral renders; use upload_template + templateId when you need to reuse the template. Supported input formats: DOCX, XLSX, PPTX, ODT, ODS, ODP, ODG, HTML, XHTML, XML, SVG, IDML, MD, TXT, CSV, RTF, PDF. Carbone reads XML-based and text-based documents (plus PDF): the legacy binary Office formats DOC, XLS and PPT are rejected as input, although they are valid outputs. Re-save such a file as DOCX, XLSX or PPTX first. Mutually exclusive with templateId — provide exactly one, never both."Input schema / properties / translations / descriptionPrevious value: -"Translation map for multilingual documents. Requires \"lang\" to be set to select the active locale. Top-level keys are BCP-47 locale codes; values are key → translated-string maps. Template usage: {t(greeting)} is replaced by the matching string for the active locale. Example: { \"fr-fr\": { \"greeting\": \"Bonjour\", \"total\": \"Total\" }, \"en-us\": { \"greeting\": \"Hello\", \"total\": \"Total\" } }. These dictionaries get large, so you may instead pass a string reference — a local file path (e.g. \"/data/invoices.json\"), an HTTPS URL, or a base64-encoded JSON string. Documentation: https://carbone.io/documentation.html#translations"New value: +"Translation map for multilingual documents. Requires \"lang\" to be set to select the active locale. Top-level keys are BCP-47 locale codes; values are key → translated-string maps. Template usage: {t(greeting)} is replaced by the matching string for the active locale. Example: { \"fr-fr\": { \"greeting\": \"Bonjour\", \"total\": \"Total\" }, \"en-us\": { \"greeting\": \"Hello\", \"total\": \"Total\" } }. These dictionaries get large, so you may instead pass a string reference — a local file path (e.g. \"/data/invoices.json\"), an HTTPS URL, or a base64-encoded JSON string. Documentation: https://carbone.io/documentation/design/advanced-features/translations-i18n.html"Input schema / properties / variableStr / descriptionPrevious value: -"Carbone alias expressions evaluated once before rendering, available everywhere in the template. Used to pre-compute reusable values or shorten repetitive paths. Syntax: \"{#aliasName = expression}\". Example: \"{#fullName = d.firstName + \\\" \\\" + d.lastName}{#total = d.price * d.qty}\". Aliases are then used in the template as {#fullName}, {#total}. Documentation: https://carbone.io/documentation.html#alias"New value: +"Carbone alias definitions applied to the whole template, as if written in it. An alias is a shortcut to a data path, not a variable: it stores no value and computes nothing (no arithmetic, no concatenation). Define with {#alias = d.path}, optionally with $parameters: {#mealOf($weekday) = d[weekday = $weekday]}. Use them in the template with {$alias}, e.g. {$mealOf(2).name}. Example: \"{#buyer = d.order.customer}\", then {$buyer.name} in the template renders d.order.customer.name. To store a computed value, use the :set formatter instead. Documentation: https://carbone.io/documentation/design/substitutions/aliases.html#alias"Input schema / properties / webhookUrl / descriptionPrevious value: -"Webhook URL to enable asynchronous rendering. When provided, Carbone returns immediately and POSTs { \"success\": true, \"data\": { \"renderId\": \"...\" } } to this URL when the document is ready. The default render timeout is extended to 5 minutes on Carbone Cloud (vs 60 s for synchronous requests). Download the document with GET /render/:renderId once the webhook is received. Required when using batchSplitBy (batch generation is always asynchronous). Example: \"https://your-server.com/carbone-webhook\"."New value: +"Webhook URL that enables asynchronous rendering (render timeout raised to 5 minutes). This tool then returns only Carbone's acceptance message, never the document. When the document is ready, Carbone POSTs { \"success\": true, \"data\": { \"renderId\": \"...\" } } to this URL; the server behind it must download the document itself with GET /render/{renderId} on the Carbone API (one-time, no auth). You cannot fetch it from here. Required for batchSplitBy: batch output is always delivered this way. outputPath, asAttachment and returnLink are ignored in this mode. Example: \"https://your-server.com/carbone-webhook\"."update_template_metadata16 fields changedInput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"Input schema / properties / category / descriptionPrevious value: -"New category."New value: +"New category, max 200 characters."Input schema / properties / category / maxLengthAdded value: +200Input schema / properties / comment / descriptionPrevious value: -"New free-text comment."New value: +"New free-text comment, max 200 characters."Input schema / properties / comment / maxLengthAdded value: +200Input schema / properties / deployedAt / descriptionPrevious value: -"Unix timestamp (seconds) to set as the deployment time for this version. Carbone picks the version with the most recent deployedAt when rendering. Use 42000000000 to deploy immediately (special \"NOW\" value)."New value: +"Unix timestamp (seconds) to set as the deployment time for this version. Carbone picks the version with the most recent deployedAt when rendering by Template ID. Use 42000000000 to deploy immediately (special \"NOW\" value). Future values are not allowed, and the deployed version's deployedAt cannot move back in time."Input schema / properties / expireAt / descriptionPrevious value: -"Unix timestamp (seconds) at which this template will be automatically deleted. Use 42000000000 to delete immediately."New value: +"Schedule deletion of the patched version at a UTC Unix timestamp (seconds). After that time it is no longer listed, downloadable or renderable (404), and the file is purged after the retention delay. Send 0 to cancel a scheduled deletion (permanent again); omit to leave it unchanged. To delete now, use delete_template."Input schema / properties / expireAt / minimumPrevious value: --9007199254740991New value: +0Input schema / properties / id / descriptionPrevious value: -"Move this version under a DIFFERENT Template ID, re-parenting it so both share a version history. Pass the destination Template ID (64-bit). Leave unset to keep the version where it is — this does not rename anything, use name for that."New value: +"DEPRECATED: the 1.6.0 name of moveToTemplateId, kept so existing callers keep working. Use moveToTemplateId; passing both with different values is rejected."Input schema / properties / id / minLengthAdded value: +1Input schema / properties / moveToTemplateIdAdded value: +{
+ "description": "CAUTION, structural change: moves the patched version to this other Template ID (64-bit; a Version ID is rejected). It is NOT the template to patch (that is templateId). Pass the version's Version ID as templateId; with a Template ID, its currently deployed version is moved and that Template ID falls back to its next most recent version (or stops resolving if none is left). Fails if the move creates a deployedAt conflict at the destination. Only use it when the user asks to move a version.",
+ "minLength": 1,
+ "type": "string"
+}Input schema / properties / name / descriptionPrevious value: -"New display name."New value: +"New display name, max 200 characters."Input schema / properties / name / maxLengthAdded value: +200Input schema / properties / tags / descriptionPrevious value: -"New list of tags — replaces existing tags entirely."New value: +"New list of tags, replacing the existing ones. Duplicates are removed and the list is sorted; the whole list is limited to 100 characters (about 8 tags of 9 characters)."Input schema / properties / templateId / descriptionPrevious value: -"Template ID (64-bit) or Version ID (SHA-256) to update. Using a Template ID updates the metadata shared by all versions. Using a Version ID updates only that specific version."New value: +"Template ID (64-bit) or Version ID (SHA-256) of the version to update. A Template ID patches only its currently deployed version (not every version). A Version ID patches that exact version."Output schema / (root)Previous value: -nullNew value: +{
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
+ "additionalProperties": false,
+ "properties": {
+ "category": {
+ "description": "Category, returned if updated.",
+ "type": "string"
+ },
+ "comment": {
+ "description": "Comment, returned if updated.",
+ "type": "string"
+ },
+ "deployedAt": {
+ "description": "Deployment timestamp, returned if updated.",
+ "type": "number"
+ },
+ "expireAt": {
+ "description": "Deletion timestamp (0 = never expires), returned if updated.",
+ "type": "number"
+ },
+ "id": {
+ "description": "Template ID the version now belongs to (returned when moveToTemplateId was used).",
+ "type": "string"
+ },
+ "name": {
+ "description": "Name, returned if updated.",
+ "type": "string"
+ },
+ "tags": {
+ "description": "Tags, returned if updated.",
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+ },
+ "versionId": {
+ "description": "Version ID of the patched version.",
+ "type": "string"
+ }
+ },
+ "required": [
+ "versionId"
+ ],
+ "type": "object"
+}upload_template24 fields changedInput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"Input schema / properties / category / descriptionPrevious value: -"Group templates into folders/categories (e.g. \"invoices\", \"legal\", \"hr\")."New value: +"Group templates into folders/categories, max 200 characters (e.g. \"invoices\", \"legal\", \"hr\")."Input schema / properties / category / maxLengthAdded value: +200Input schema / properties / comment / descriptionPrevious value: -"Free-text comment to describe the template version or its purpose."New value: +"Free-text comment to describe the template version or its purpose, max 200 characters."Input schema / properties / comment / maxLengthAdded value: +200Input schema / properties / deployedAt / descriptionPrevious value: -"UTC Unix timestamp (seconds) to set as the deployment time for this version. Carbone uses the version with the most recent deployedAt when rendering via Template ID. Use 42000000000 to deploy immediately (special \"NOW\" sentinel value)."New value: +"UTC Unix timestamp (seconds) to set as the deployment time for this version. Carbone uses the version with the most recent deployedAt when rendering via Template ID. Use 42000000000 to deploy immediately (special \"NOW\" sentinel value). Future values are not allowed."Input schema / properties / expireAt / descriptionPrevious value: -"UTC Unix timestamp (seconds) at which this template will be automatically deleted. Use 42000000000 to delete immediately (special \"NOW\" sentinel value)."New value: +"Schedule deletion at a UTC Unix timestamp (seconds); 0 (default) means the template never expires. After that time it is no longer listed, downloadable or renderable (404), and the file is purged after the retention delay. To remove a template now, use delete_template."Input schema / properties / expireAt / minimumPrevious value: --9007199254740991New value: +0Input schema / properties / name / descriptionPrevious value: -"Display name for the template (e.g. \"Invoice Template\", \"NDA Contract\")."New value: +"Display name for the template, max 200 characters (e.g. \"Invoice Template\", \"NDA Contract\"). Optional but recommended: list_templates shows it and its search matches it."Input schema / properties / name / maxLengthAdded value: +200Input schema / properties / sample / descriptionPrevious value: -"Sample input data attached to the template for testing in Carbone Studio. Each item must include data, complement, translations, and enum objects."New value: +"Sample input data attached to the template for testing in Carbone Studio: an array with at most ONE object, whose keys data, complement, translations and enum are all optional. Example: [{ \"data\": { \"name\": \"Acme\" } }]."Input schema / properties / sample / items / additionalPropertiesAdded value: +falseInput schema / properties / sample / items / requiredRemoved value: -[
- "data",
- "complement",
- "translations",
- "enum"
-]Input schema / properties / sample / maxItemsAdded value: +1Input schema / properties / tags / descriptionPrevious value: -"Tags for searchability and filtering (e.g. [\"sales\", \"billing\", \"v2\"])."New value: +"Labels shown by list_tags and on each list_templates result (e.g. [\"sales\", \"billing\", \"v2\"]). Duplicates are removed and the list is sorted; the whole list is limited to 100 characters (about 8 tags of 9 characters)."Input schema / properties / template / descriptionPrevious value: -"The template file. Three input forms are accepted: (1) Local file path — absolute or relative, e.g. \"/home/user/report.docx\" or \"./invoice.xlsx\". (2) HTTPS URL — the file is downloaded automatically, e.g. \"https://example.com/file.pptx\". (3) Base64-encoded string — the raw file content encoded as base64. Supported formats: DOCX, XLSX, PPTX, ODT, ODS, ODP, ODG, HTML, XHTML, IDML, XML, Markdown (MD), PDF, and more. Full list: https://carbone.io/documentation/developer/http-api/generate-reports.md"New value: +"The template file. Three input forms are accepted: (1) Local file path — absolute, e.g. \"/Users/me/report.docx\" (or \"C:\\Users\\me\\report.docx\" on Windows), or under the home directory, e.g. \"~/report.docx\". A relative path must start with \"./\" or \"../\" and resolves against the server process's working directory, which is rarely yours: prefer an absolute path. A bare file name such as \"report.docx\" is NOT a path: it would be sent as base64 content. (2) HTTPS URL — the file is downloaded automatically, e.g. \"https://example.com/file.pptx\". (3) Base64-encoded string — the raw file content encoded as base64. Supported input formats: DOCX, XLSX, PPTX, ODT, ODS, ODP, ODG, HTML, XHTML, XML, SVG, IDML, MD, TXT, CSV, RTF, PDF. Carbone reads XML-based and text-based documents (plus PDF): the legacy binary Office formats DOC, XLS and PPT are rejected as input, although they are valid outputs. Re-save such a file as DOCX, XLSX or PPTX first."Input schema / properties / versioning / descriptionPrevious value: -"Enable template versioning (default: true). When true, a stable Template ID is generated and multiple versions can be managed under it. When false, behaves as legacy mode and returns only a templateId (SHA-256 hash)."New value: +"Enable template versioning (default: true). When true, a stable Template ID is generated and multiple versions can be managed under it. When false, behaves as legacy mode and returns only a templateId (SHA-256 hash) and templateExtension."Input schema / requiredPrevious value: -[
- "template",
- "name"
-]New value: +[
+ "template"
+]Output schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"Output schema / properties / createdAtAdded value: +{
+ "description": "UTC Unix timestamp (seconds) of the upload.",
+ "type": "number"
+}Output schema / properties / deployedAtAdded value: +{
+ "description": "UTC Unix timestamp of deployment; 0 means this version is not explicitly deployed.",
+ "type": "number"
+}Output schema / properties / name / descriptionPrevious value: -"Template display name."New value: +"Template display name, when one was given."Output schema / properties / templateExtensionAdded value: +{
+ "description": "Detected file extension, e.g. \"docx\" (legacy/non-versioned mode).",
+ "type": "string"
+}Output schema / requiredRemoved value: -[
- "name"
-]v1.6.0convert_document8 fields changedInput schema / properties / convertTo / anyOfPrevious value: -[
- {
- "enum": [
- "pdf",
- "docx",
- "xlsx",
- "pptx",
- "odt",
- "ods",
- "odp",
- "odg",
- "html",
- "xhtml",
- "txt",
- "csv",
- "md",
- "xml",
- "rtf",
- "png",
- "jpg",
- "jpeg",
- "webp",
- "svg",
- "tiff",
- "bmp",
- "gif",
- "zip",
- "idml",
- "epub",
- "cdr"
- ],
- "type": "string"
- },
- {
- "properties": {
- "formatName": {
- "description": "Target format name.",
- "enum": [
- "pdf",
- "docx",
- "xlsx",
- "pptx",
- "odt",
- "ods",
- "odp",
- "odg",
- "html",
- "xhtml",
- "txt",
- "csv",
- "md",
- "xml",
- "rtf",
- "png",
- "jpg",
- "jpeg",
- "webp",
- "svg",
- "tiff",
- "bmp",
- "gif",
- "zip",
- "idml",
- "epub",
- "cdr"
- ],
- "type": "string"
- },
- "formatOptions": {
- "additionalProperties": {},
- "description": "Advanced format options object. Examples by format: PDF — { \"EncryptFile\": true, \"DocumentOpenPassword\": \"secret\", \"DocumentPermissionPassword\": \"owner\" } password-protect; PDF — { \"Watermarks\": [{ \"text\": \"DRAFT\", \"opacity\": 0.2, \"rotation\": -45, \"fontsize\": 60 }] } up to 5 watermarks; PDF — { \"SelectPdfVersion\": 1 } PDF/A-1b compliance (use 2 for PDF/A-2, 3 for PDF/A-3); PDF — { \"PageRange\": \"1-3,5\" } export specific pages only; PDF — { \"ConvertSlideshow\": true } convert each slide to a separate PDF page; Images (PNG/JPG/WEBP) — { \"Quality\": 90 } set compression quality 0-100; Images — { \"density\": 150 } set DPI for rasterisation (default 96); CSV — { \"fieldSeparator\": \";\" } custom column separator.",
- "propertyNames": {
- "type": "string"
- },
- "type": "object"
- }
- },
- "required": [
- "formatName"
- ],
- "type": "object"
- }
-]New value: +[
+ {
+ "enum": [
+ "pdf",
+ "docx",
+ "doc",
+ "xlsx",
+ "xls",
+ "pptx",
+ "ppt",
+ "odt",
+ "ods",
+ "odp",
+ "odg",
+ "html",
+ "xhtml",
+ "txt",
+ "csv",
+ "md",
+ "xml",
+ "rtf",
+ "png",
+ "jpg",
+ "jpeg",
+ "webp",
+ "svg",
+ "tiff",
+ "bmp",
+ "gif",
+ "zip",
+ "idml",
+ "epub",
+ "cdr"
+ ],
+ "type": "string"
+ },
+ {
+ "properties": {
+ "formatName": {
+ "description": "Target format name.",
+ "enum": [
+ "pdf",
+ "docx",
+ "doc",
+ "xlsx",
+ "xls",
+ "pptx",
+ "ppt",
+ "odt",
+ "ods",
+ "odp",
+ "odg",
+ "html",
+ "xhtml",
+ "txt",
+ "csv",
+ "md",
+ "xml",
+ "rtf",
+ "png",
+ "jpg",
+ "jpeg",
+ "webp",
+ "svg",
+ "tiff",
+ "bmp",
+ "gif",
+ "zip",
+ "idml",
+ "epub",
+ "cdr"
+ ],
+ "type": "string"
+ },
+ "formatOptions": {
+ "additionalProperties": {},
+ "description": "Advanced format options object. Examples by format: PDF — { \"EncryptFile\": true, \"DocumentOpenPassword\": \"secret\", \"DocumentPermissionPassword\": \"owner\" } password-protect; PDF — { \"Watermarks\": [{ \"text\": \"DRAFT\", \"opacity\": 0.2, \"rotation\": -45, \"fontsize\": 60 }] } up to 5 watermarks; PDF — { \"SelectPdfVersion\": 1 } PDF/A-1b compliance (use 2 for PDF/A-2, 3 for PDF/A-3); PDF — { \"PageRange\": \"1-3,5\" } export specific pages only; PDF — { \"ConvertSlideshow\": true } convert each slide to a separate PDF page; Images (PNG/JPG/WEBP) — { \"Quality\": 90 } set compression quality 0-100; Images — { \"density\": 150 } set DPI for rasterisation (default 96); CSV — { \"fieldSeparator\": \";\" } custom column separator.",
+ "propertyNames": {
+ "type": "string"
+ },
+ "type": "object"
+ }
+ },
+ "required": [
+ "formatName"
+ ],
+ "type": "object"
+ }
+]Input schema / properties / convertTo / descriptionPrevious value: -"Target output format. Documents : \"pdf\", \"docx\", \"xlsx\", \"pptx\", \"odt\", \"ods\", \"odp\", \"odg\", \"rtf\", \"epub\". Web/text : \"html\", \"xhtml\", \"txt\", \"csv\", \"md\", \"xml\", \"idml\". Images : \"png\", \"jpg\", \"jpeg\", \"webp\", \"svg\", \"tiff\", \"bmp\", \"gif\". Archive : \"zip\" (batch output). Simple usage: \"pdf\". Advanced usage: { \"formatName\": \"pdf\", \"formatOptions\": { \"EncryptFile\": true, \"DocumentOpenPassword\": \"secret\" } }."New value: +"Target output format. Documents : \"pdf\", \"docx\", \"xlsx\", \"pptx\", \"odt\", \"ods\", \"odp\", \"odg\", \"rtf\", \"epub\", plus the legacy \"doc\", \"xls\", \"ppt\" (output only — Carbone writes them but cannot read them back). Web/text : \"html\", \"xhtml\", \"txt\", \"csv\", \"md\", \"xml\", \"idml\". Images : \"png\", \"jpg\", \"jpeg\", \"webp\", \"svg\", \"tiff\", \"bmp\", \"gif\". Archive : \"zip\" (batch output). Simple usage: \"pdf\". Advanced usage: { \"formatName\": \"pdf\", \"formatOptions\": { \"EncryptFile\": true, \"DocumentOpenPassword\": \"secret\" } }."Input schema / properties / converter / descriptionPrevious value: -"Converter engine. Only relevant when convertTo is \"pdf\" (or an image format rasterised from a document). \"L\" — LibreOffice (default): best all-round engine for DOCX, XLSX, PPTX, ODT, ODS, ODP. \"O\" — OnlyOffice: highest fidelity rendering for Microsoft Office formats (DOCX, XLSX, PPTX). \"C\" — Chromium: best for HTML, CSS, JavaScript — full browser rendering. If omitted, LibreOffice is used by default."New value: +"Converter engine. Only relevant when convertTo is \"pdf\" (or an image format rasterised from a document). \"L\" — LibreOffice (default): best all-round engine for DOCX, XLSX, PPTX, ODT, ODS, ODP. \"O\" — OnlyOffice: highest fidelity rendering for Microsoft Office formats (DOCX, XLSX, PPTX). \"C\" — Chromium: best for HTML, CSS, JavaScript — full browser rendering. \"I\" — Carbone ICE (Instant Converter Engine, Carbone 5.14.0+): DOCX → PDF ONLY, no third-party converter — up to 60x faster than LibreOffice on a 1000-page DOCX (3x on a one-page document). Any other input or output format is REJECTED — use another converter for those. PDF options: only Watermarks are applied. EncryptFile, DocumentOpenPassword, RestrictPermissions and the other security options are SILENTLY IGNORED — the PDF comes back readable by anyone, with no error — so NEVER pick \"I\" when the request needs a password or restricted permissions; use \"L\" for those. Also unsupported: WEBP and EMF/WMF images, table of contents, SmartArt, complex charts, footnotes/endnotes, comments, tracked changes, form fields, equations, bookmarks and links; a missing font falls back to Noto Sans. If omitted, LibreOffice is used by default."Input schema / properties / converter / enumPrevious value: -[
- "L",
- "C",
- "O"
-]New value: +[
+ "L",
+ "C",
+ "O",
+ "I"
+]Input schema / properties / file / descriptionPrevious value: -"The document to convert. Three input forms are accepted: (1) Local file path — absolute or relative, e.g. \"/home/user/report.docx\" or \"./invoice.xlsx\". (2) HTTPS URL — the file is downloaded automatically, e.g. \"https://example.com/file.pptx\". (3) Base64-encoded string — the raw file content encoded as base64. Supported input formats include: DOCX, XLSX, PPTX, ODT, ODS, ODP, ODG, HTML, XHTML, XML, IDML, Markdown (MD), PDF, TXT, CSV, PNG, JPG, SVG, and more. Full conversion matrix: https://carbone.io/documentation/developer/http-api/generate-reports.md"New value: +"The document to convert. Three input forms are accepted: (1) Local file path — absolute or relative, e.g. \"/home/user/report.docx\" or \"./invoice.xlsx\". (2) HTTPS URL — the file is downloaded automatically, e.g. \"https://example.com/file.pptx\". (3) Base64-encoded string — the raw file content encoded as base64. Supported input formats: DOCX, XLSX, PPTX, ODT, ODS, ODP, ODG, HTML, XHTML, XML, SVG, IDML, Markdown (MD), TXT, CSV, RTF, PDF, PNG and JPG. Carbone reads XML-based and text-based documents only, so the legacy BINARY Office formats DOC, XLS and PPT are REJECTED as input — Carbone can produce them as output but cannot read them. Re-save such a file as DOCX/XLSX/PPTX first. Full conversion matrix: https://carbone.io/documentation/developer/http-api/generate-reports.md"Input schema / properties / hardRefreshAdded value: +{
+ "description": "Forces Carbone to run the converter even when the output format already matches the input format. Only useful for PDF: converting PDF → PDF to APPLY formatOptions (watermark, password, PDF/A, page range). Without it Carbone may pass the file straight through and none of those options take effect. Leave unset for any format-changing conversion (DOCX → PDF, XLSX → CSV, …), where the converter runs anyway.",
+ "type": "boolean"
+}Input schema / properties / outputPath / descriptionPrevious value: -"Optional local file path to save the converted document to (e.g. \"/home/user/out.pdf\" or \"~/out.pdf\"). When set, the file is written to disk and the tool returns the saved path + size instead of embedding the document inline — ideal for large files. Local (stdio) mode only; rejected in HTTP mode."New value: +"Optional local file path to save the converted document to (e.g. \"/home/user/out.pdf\" or \"~/out.pdf\"). When set, the file is written to disk and the tool returns the saved path + size instead of embedding the document inline — ideal for large files."Input schema / properties / reportNameAdded value: +{
+ "description": "Filename (WITHOUT extension) for the converted document, returned in the Content-Disposition header. Carbone appends the extension matching convertTo, so do not include one — \"report.pdf\" yields \"report.pdf.pdf\". Examples: \"contract\", \"2026-invoice\". Unlike render_document, Carbone tags are NOT resolved here (conversion does not run templating), so pass a literal name rather than a pattern like \"{d.id}\" — a pattern would come back verbatim. Ignored when returnLink is set, which returns a download URL rather than a named file.",
+ "type": "string"
+}download_template2 fields changedInput schema / properties / outputPath / descriptionPrevious value: -"Optional local file path to save the template file to (e.g. \"/home/user/template.docx\" or \"~/template.docx\"). When set, the file is written to disk and the tool returns the saved path + size instead of embedding the file inline. Local (stdio) mode only; rejected in HTTP mode."New value: +"Optional local file path to save the template file to (e.g. \"/home/user/out.pdf\" or \"~/out.pdf\"). When set, the file is written to disk and the tool returns the saved path + size instead of embedding the document inline — ideal for large files."Input schema / properties / sampleAdded value: +{
+ "description": "If true, download the JSON SAMPLE DATASET saved with the template (the \"sample\" array passed to upload_template) instead of the template file. Returns JSON of the form [{ \"data\": {...}, \"complement\": {...}, \"translations\": {...}, \"enum\": {...} }]. Use it to recover the example data a template expects — handy before calling render_document against an unfamiliar template. Errors if the template was uploaded without a sample.",
+ "type": "boolean"
+}list_templates2 fields changedInput schema / properties / limit / descriptionPrevious value: -"Maximum number of results to return. Must be between 1 and 100 (Carbone API limit). Default: 100."New value: +"Maximum number of results to return, between 1 and 100. Default: 100. Use cursor to page beyond that."Input schema / properties / origin / descriptionPrevious value: -"Filter by upload origin. 0 = uploaded via API, 1 = uploaded via Carbone Studio."New value: +"Filter by upload origin. 0 = API, 1 = Carbone Studio, 2 = Salesforce, 3 = Odoo, 4 = HubSpot. Templates created through this MCP are origin 0."render_document15 fields changedInput schema / properties / batchOutput / descriptionPrevious value: -"Container format for the batch result. Use \"zip\" to receive all generated documents as a single ZIP archive. Must be used together with batchSplitBy."New value: +"How the batch result is packaged. Defaults to \"zip\". \"zip\" — every generated document is bundled into a single ZIP archive (use batchReportName to name each entry). \"pdf\" — all documents are CONCATENATED into one continuous PDF instead of being zipped; this requires convertTo to be \"pdf\" as well. Must be used together with batchSplitBy."Input schema / properties / batchOutput / enumAdded value: +[
+ "zip",
+ "pdf"
+]Input schema / properties / batchReportName / descriptionPrevious value: -"Filename pattern for each individual document inside the batch ZIP. Supports Carbone tags. Tags are resolved against the item's data (relative path) or the full dataset (absolute path). Examples: \"invoice-{d.id}.pdf\", \"{d.client.name}-{d.date}.docx\". Must be used together with batchSplitBy."New value: +"Filename pattern for each individual document inside the batch ZIP. Supports Carbone tags. Tags are resolved against the item's data (relative path) or the full dataset (absolute path). Examples: \"invoice-{d.id}.pdf\", \"{d.client.name}-{d.date}.docx\". Carbone sanitises the result — path separators, \"..\", Windows-forbidden and control characters each become an underscore — and appends an index to duplicates (\"report_1.pdf\", \"report_2.pdf\"), so a pattern that resolves to the same name for several items will not silently drop documents. Only meaningful with batchOutput: \"zip\"; a concatenated \"pdf\" batch is a single file. Must be used together with batchSplitBy."Input schema / properties / batchSplitBy / descriptionPrevious value: -"JSON path to the array in your data that drives batch generation. One document is generated per element of the array; all documents are bundled together. Use batchOutput: \"zip\" to receive a single ZIP archive. Use batchReportName to customise each filename inside the ZIP. Example: \"d.invoices\" — produces one PDF per item in data.invoices. Example: \"d.employees\" — produces one contract per employee."New value: +"JSON path to the array in your data that drives batch generation. One document is generated per element of the array. Two forms: \"d\" when data itself IS the array (one report per top-level element), or \"d.arrayName\" to split on a child array. Example: \"d.invoices\" — produces one PDF per item in data.invoices. Example: \"d.employees\" — produces one contract per employee. Carbone Cloud allows 1 to 100 objects per batch (on-premise follows the nbReportMaxPerBatch setting). Batch is ALWAYS asynchronous — webhookUrl is required. Pair with batchOutput to choose ZIP or a single concatenated PDF, and batchReportName to name each document."Input schema / properties / complement / descriptionPrevious value: -"Extra data object accessible in templates with {c.field} tags (as opposed to {d.field} for main data). Useful for static or shared values that should not be mixed into the main dataset: company info, logo URLs, footer text, configuration constants. Example: { \"company\": \"Acme Corp\", \"address\": \"123 Main St\", \"vatNumber\": \"FR12345\" }. Like data, may instead be passed by reference as a string — a local path, HTTPS URL, or base64 to a JSON file."New value: +"Extra data object accessible in templates with {c.field} tags (as opposed to {d.field} for main data). Useful for static or shared values that should not be mixed into the main dataset: company info, logo URLs, footer text, configuration constants. Example: { \"company\": \"Acme Corp\", \"address\": \"123 Main St\", \"vatNumber\": \"FR12345\" }. Like data, may instead be passed by reference as a string — a local file path (e.g. \"/data/invoices.json\"), an HTTPS URL, or a base64-encoded JSON string."Input schema / properties / convertTo / anyOfPrevious value: -[
- {
- "enum": [
- "pdf",
- "docx",
- "xlsx",
- "pptx",
- "odt",
- "ods",
- "odp",
- "odg",
- "html",
- "xhtml",
- "txt",
- "csv",
- "md",
- "xml",
- "rtf",
- "png",
- "jpg",
- "jpeg",
- "webp",
- "svg",
- "tiff",
- "bmp",
- "gif",
- "zip",
- "idml",
- "epub",
- "cdr"
- ],
- "type": "string"
- },
- {
- "properties": {
- "formatName": {
- "description": "Target format name.",
- "enum": [
- "pdf",
- "docx",
- "xlsx",
- "pptx",
- "odt",
- "ods",
- "odp",
- "odg",
- "html",
- "xhtml",
- "txt",
- "csv",
- "md",
- "xml",
- "rtf",
- "png",
- "jpg",
- "jpeg",
- "webp",
- "svg",
- "tiff",
- "bmp",
- "gif",
- "zip",
- "idml",
- "epub",
- "cdr"
- ],
- "type": "string"
- },
- "formatOptions": {
- "additionalProperties": {},
- "description": "Advanced format options object. Examples by format: PDF — { \"EncryptFile\": true, \"DocumentOpenPassword\": \"secret\", \"DocumentPermissionPassword\": \"owner\" } password-protect; PDF — { \"Watermarks\": [{ \"text\": \"DRAFT\", \"opacity\": 0.2, \"rotation\": -45, \"fontsize\": 60 }] } up to 5 watermarks; PDF — { \"SelectPdfVersion\": 1 } PDF/A-1b compliance (use 2 for PDF/A-2, 3 for PDF/A-3); PDF — { \"PageRange\": \"1-3,5\" } export specific pages only; PDF — { \"ConvertSlideshow\": true } convert each slide to a separate PDF page; Images (PNG/JPG/WEBP) — { \"Quality\": 90 } compression quality 0-100; Images — { \"density\": 150 } DPI for rasterisation (default 96); CSV — { \"fieldSeparator\": \";\" } custom column separator.",
- "propertyNames": {
- "type": "string"
- },
- "type": "object"
- }
- },
- "required": [
- "formatName"
- ],
- "type": "object"
- }
-]New value: +[
+ {
+ "enum": [
+ "pdf",
+ "docx",
+ "doc",
+ "xlsx",
+ "xls",
+ "pptx",
+ "ppt",
+ "odt",
+ "ods",
+ "odp",
+ "odg",
+ "html",
+ "xhtml",
+ "txt",
+ "csv",
+ "md",
+ "xml",
+ "rtf",
+ "png",
+ "jpg",
+ "jpeg",
+ "webp",
+ "svg",
+ "tiff",
+ "bmp",
+ "gif",
+ "zip",
+ "idml",
+ "epub",
+ "cdr"
+ ],
+ "type": "string"
+ },
+ {
+ "properties": {
+ "formatName": {
+ "description": "Target format name.",
+ "enum": [
+ "pdf",
+ "docx",
+ "doc",
+ "xlsx",
+ "xls",
+ "pptx",
+ "ppt",
+ "odt",
+ "ods",
+ "odp",
+ "odg",
+ "html",
+ "xhtml",
+ "txt",
+ "csv",
+ "md",
+ "xml",
+ "rtf",
+ "png",
+ "jpg",
+ "jpeg",
+ "webp",
+ "svg",
+ "tiff",
+ "bmp",
+ "gif",
+ "zip",
+ "idml",
+ "epub",
+ "cdr"
+ ],
+ "type": "string"
+ },
+ "formatOptions": {
+ "additionalProperties": {},
+ "description": "Advanced format options object. Examples by format: PDF — { \"EncryptFile\": true, \"DocumentOpenPassword\": \"secret\", \"DocumentPermissionPassword\": \"owner\" } password-protect; PDF — { \"Watermarks\": [{ \"text\": \"DRAFT\", \"opacity\": 0.2, \"rotation\": -45, \"fontsize\": 60 }] } up to 5 watermarks; PDF — { \"SelectPdfVersion\": 1 } PDF/A-1b compliance (use 2 for PDF/A-2, 3 for PDF/A-3); PDF — { \"PageRange\": \"1-3,5\" } export specific pages only; PDF — { \"ConvertSlideshow\": true } convert each slide to a separate PDF page; Images (PNG/JPG/WEBP) — { \"Quality\": 90 } compression quality 0-100; Images — { \"density\": 150 } DPI for rasterisation (default 96); CSV — { \"fieldSeparator\": \";\" } custom column separator.",
+ "propertyNames": {
+ "type": "string"
+ },
+ "type": "object"
+ }
+ },
+ "required": [
+ "formatName"
+ ],
+ "type": "object"
+ }
+]Input schema / properties / converter / descriptionPrevious value: -"Converter engine. Only relevant when convertTo is \"pdf\" (or an image rasterised from a document). \"L\" — LibreOffice (default): best all-round engine for DOCX, XLSX, PPTX, ODT, ODS, ODP. \"O\" — OnlyOffice: highest fidelity for Microsoft Office formats (DOCX, XLSX, PPTX). \"C\" — Chromium: best for HTML/CSS/JS templates — full browser rendering. If omitted, LibreOffice is used by default."New value: +"Converter engine. Only relevant when convertTo is \"pdf\" (or an image rasterised from a document). \"L\" — LibreOffice (default): best all-round engine for DOCX, XLSX, PPTX, ODT, ODS, ODP. \"O\" — OnlyOffice: highest fidelity for Microsoft Office formats (DOCX, XLSX, PPTX). \"C\" — Chromium: best for HTML/CSS/JS templates — full browser rendering. \"I\" — Carbone ICE (Instant Converter Engine, Carbone 5.14.0+): DOCX → PDF ONLY, no third-party converter — up to 60x faster than LibreOffice on a 1000-page DOCX (3x on a one-page document). Any other input or output format is REJECTED — use another converter for those. PDF options: only Watermarks are applied. EncryptFile, DocumentOpenPassword, RestrictPermissions and the other security options are SILENTLY IGNORED — the PDF comes back readable by anyone, with no error — so NEVER pick \"I\" when the request needs a password or restricted permissions; use \"L\" for those. Also unsupported: WEBP and EMF/WMF images, table of contents, SmartArt, complex charts, footnotes/endnotes, comments, tracked changes, form fields, equations, bookmarks and links; a missing font falls back to Noto Sans. If omitted, LibreOffice is used by default."Input schema / properties / converter / enumPrevious value: -[
- "L",
- "C",
- "O"
-]New value: +[
+ "L",
+ "C",
+ "O",
+ "I"
+]Input schema / properties / currencyRates / descriptionPrevious value: -"Exchange rate table used by :formatC for currency conversion. Keys are ISO 4217 currency codes; values are rates relative to a common base. The base currency should have rate 1. Example: { \"EUR\": 1, \"USD\": 1.08, \"GBP\": 0.86, \"JPY\": 160.5 }. May instead be passed by reference as a string — a local path, HTTPS URL, or base64 to a JSON file."New value: +"Exchange rate table used by :formatC for currency conversion. Keys are ISO 4217 currency codes; values are rates relative to a common base. The base currency should have rate 1. Example: { \"EUR\": 1, \"USD\": 1.08, \"GBP\": 0.86, \"JPY\": 160.5 }. May instead be passed by reference as a string — a local file path (e.g. \"/data/invoices.json\"), an HTTPS URL, or a base64-encoded JSON string."Input schema / properties / data / descriptionPrevious value: -"JSON data merged into the template — an object, or a top-level array (accessed with {d[i].field}). Access fields with {d.fieldName} tags. Nested objects: {d.customer.name}. Array loops: {d.items[i].description} … {d.items[i+1]}. Conditionals: {d.status == \"active\" ? \"Yes\" : \"No\"}. Optional — if omitted, defaults to an empty object {} so the template is simply converted (tags resolve to empty). Useful to convert a stored template by templateId without data injection. Instead of inlining a large dataset, you may pass a STRING reference to the JSON: a local file path (e.g. \"/data/invoices.json\"), an HTTPS URL, or a base64-encoded JSON string — it is read and parsed server-side. Local paths resolve in stdio (local) mode only; URLs and base64 work in both transports."New value: +"JSON data merged into the template — an object, or a top-level array (accessed with {d[i].field}). Access fields with {d.fieldName} tags. Nested objects: {d.customer.name}. Array loops: {d.items[i].description} … {d.items[i+1]}. Conditionals: {d.status == \"active\" ? \"Yes\" : \"No\"}. Optional — if omitted, defaults to an empty object {} so the template is simply converted (tags resolve to empty). Useful to convert a stored template by templateId without data injection. Instead of inlining a large dataset, you may pass a STRING reference to the JSON: a local file path (e.g. \"/data/invoices.json\"), an HTTPS URL, or a base64-encoded JSON string — it is read and parsed server-side."Input schema / properties / enum / descriptionPrevious value: -"Enumeration map used with the :convEnum(TYPE) formatter to translate code values into human-readable labels. Define one key per enum type; each value is an object mapping code → label. Example: { \"STATUS\": { \"1\": \"Active\", \"2\": \"Inactive\", \"3\": \"Pending\" }, \"ROLE\": { \"A\": \"Admin\", \"U\": \"User\" } }. Template usage: {d.status:convEnum(STATUS)}, {d.role:convEnum(ROLE)}. May instead be passed by reference as a string — a local path, HTTPS URL, or base64 to a JSON file. Documentation: https://carbone.io/documentation.html#convenum-type-"New value: +"Enumeration map used with the :convEnum(TYPE) formatter to translate code values into human-readable labels. Define one key per enum type; each value is an object mapping code → label. Example: { \"STATUS\": { \"1\": \"Active\", \"2\": \"Inactive\", \"3\": \"Pending\" }, \"ROLE\": { \"A\": \"Admin\", \"U\": \"User\" } }. Template usage: {d.status:convEnum(STATUS)}, {d.role:convEnum(ROLE)}. May instead be passed by reference as a string — a local file path (e.g. \"/data/invoices.json\"), an HTTPS URL, or a base64-encoded JSON string. Documentation: https://carbone.io/documentation.html#convenum-type-"Input schema / properties / keepTagsAdded value: +{
+ "description": "If true, SKIP templating entirely and leave every Carbone tag in the document exactly as written — {d.customer} comes out as the literal text \"{d.customer}\", formatters included. Use it to proof a stored template in another format (e.g. render templateId to PDF to check the tag layout), or to convert a template between formats while it stays a template. Mutually exclusive with data — passing both is rejected, because data would have nothing to fill. Note the difference from omitting data: no data renders the template with an EMPTY dataset, so every tag resolves to an empty string; keepTags leaves the tags themselves in place. Requires Carbone 5.9.0+ (carbone-version: 5).",
+ "type": "boolean"
+}Input schema / properties / outputPath / descriptionPrevious value: -"Optional local file path to save the generated document to (e.g. \"/home/user/out.pdf\" or \"~/out.pdf\"). When set, the file is written to disk and the tool returns the saved path + size instead of embedding the document inline — ideal for large files. Local (stdio) mode only; rejected in HTTP mode. Ignored for async/webhook renders (no document is returned inline)."New value: +"Optional local file path to save the generated document to (e.g. \"/home/user/out.pdf\" or \"~/out.pdf\"). When set, the file is written to disk and the tool returns the saved path + size instead of embedding the document inline — ideal for large files. Ignored for async/webhook renders (no document is returned inline)."Input schema / properties / template / descriptionPrevious value: -"Inline template for one-shot render without storing a template first. Accepts a local file path (e.g. /home/user/invoice.docx), a URL (https://example.com/template.docx), or a base64-encoded string. The template is uploaded and rendered in a single API request — no Template ID is returned. Use this for ephemeral renders; use upload_template + templateId when you need to reuse the template. Supported formats: DOCX, XLSX, PPTX, ODT, ODS, ODP, ODG, HTML, XHTML, IDML, XML, Markdown (MD), PDF, and more. Mutually exclusive with templateId — provide exactly one, never both."New value: +"Inline template for one-shot render without storing a template first. Three input forms are accepted: (1) Local file path — absolute or relative, e.g. \"/home/user/report.docx\" or \"./invoice.xlsx\". (2) HTTPS URL — the file is downloaded automatically, e.g. \"https://example.com/file.pptx\". (3) Base64-encoded string — the raw file content encoded as base64. The template is uploaded and rendered in a single API request — no Template ID is returned. Use this for ephemeral renders; use upload_template + templateId when you need to reuse the template. Supported formats: DOCX, XLSX, PPTX, ODT, ODS, ODP, ODG, HTML, XHTML, IDML, XML, Markdown (MD), PDF, and more. Mutually exclusive with templateId — provide exactly one, never both."Input schema / properties / translations / descriptionPrevious value: -"Translation map for multilingual documents. Requires \"lang\" to be set to select the active locale. Top-level keys are BCP-47 locale codes; values are key → translated-string maps. Template usage: {t(greeting)} is replaced by the matching string for the active locale. Example: { \"fr-fr\": { \"greeting\": \"Bonjour\", \"total\": \"Total\" }, \"en-us\": { \"greeting\": \"Hello\", \"total\": \"Total\" } }. These dictionaries get large, so you may instead pass a string reference — a local path, HTTPS URL, or base64 to a JSON file. Documentation: https://carbone.io/documentation.html#translations"New value: +"Translation map for multilingual documents. Requires \"lang\" to be set to select the active locale. Top-level keys are BCP-47 locale codes; values are key → translated-string maps. Template usage: {t(greeting)} is replaced by the matching string for the active locale. Example: { \"fr-fr\": { \"greeting\": \"Bonjour\", \"total\": \"Total\" }, \"en-us\": { \"greeting\": \"Hello\", \"total\": \"Total\" } }. These dictionaries get large, so you may instead pass a string reference — a local file path (e.g. \"/data/invoices.json\"), an HTTPS URL, or a base64-encoded JSON string. Documentation: https://carbone.io/documentation.html#translations"update_template_metadata1 field changedInput schema / properties / idAdded value: +{
+ "description": "Move this version under a DIFFERENT Template ID, re-parenting it so both share a version history. Pass the destination Template ID (64-bit). Leave unset to keep the version where it is — this does not rename anything, use name for that.",
+ "type": "string"
+}upload_template1 field changedInput schema / properties / template / descriptionPrevious value: -"The template file. Accepts a local file path (e.g. /home/user/invoice.docx), a URL (https://example.com/template.docx), or a base64-encoded string. Supported formats: DOCX, XLSX, PPTX, ODT, ODS, ODP, ODG, HTML, XHTML, IDML, XML, Markdown (MD), PDF, and more. Full list: https://carbone.io/documentation/developer/http-api/generate-reports.md"New value: +"The template file. Three input forms are accepted: (1) Local file path — absolute or relative, e.g. \"/home/user/report.docx\" or \"./invoice.xlsx\". (2) HTTPS URL — the file is downloaded automatically, e.g. \"https://example.com/file.pptx\". (3) Base64-encoded string — the raw file content encoded as base64. Supported formats: DOCX, XLSX, PPTX, ODT, ODS, ODP, ODG, HTML, XHTML, IDML, XML, Markdown (MD), PDF, and more. Full list: https://carbone.io/documentation/developer/http-api/generate-reports.md"v1.4.0convert_document1 field changedInput schema / properties / egressAuthorizationAdded value: +{
+ "description": "Value for the Authorization header Carbone adds to its OUTBOUND (egress) requests during conversion — e.g. when a Chromium HTML→PDF conversion fetches a protected external image or stylesheet. For example \"Bearer abc123\" makes Carbone send `authorization: Bearer abc123` to those hosts. Only the authorization header can be customised; max 512 characters.",
+ "maxLength": 512,
+ "type": "string"
+}render_document3 fields changedInput schema / properties / data / descriptionPrevious value: -"JSON data merged into the template — an object, or a top-level array (accessed with {d[i].field}). Access fields with {d.fieldName} tags. Nested objects: {d.customer.name}. Array loops: {d.items[i].description} … {d.items[i+1]}. Conditionals: {d.status == \"active\" ? \"Yes\" : \"No\"}. For pure document conversion without data injection, pass {}. Instead of inlining a large dataset, you may pass a STRING reference to the JSON: a local file path (e.g. \"/data/invoices.json\"), an HTTPS URL, or a base64-encoded JSON string — it is read and parsed server-side. Local paths resolve in stdio (local) mode only; URLs and base64 work in both transports."New value: +"JSON data merged into the template — an object, or a top-level array (accessed with {d[i].field}). Access fields with {d.fieldName} tags. Nested objects: {d.customer.name}. Array loops: {d.items[i].description} … {d.items[i+1]}. Conditionals: {d.status == \"active\" ? \"Yes\" : \"No\"}. Optional — if omitted, defaults to an empty object {} so the template is simply converted (tags resolve to empty). Useful to convert a stored template by templateId without data injection. Instead of inlining a large dataset, you may pass a STRING reference to the JSON: a local file path (e.g. \"/data/invoices.json\"), an HTTPS URL, or a base64-encoded JSON string — it is read and parsed server-side. Local paths resolve in stdio (local) mode only; URLs and base64 work in both transports."Input schema / properties / egressAuthorizationAdded value: +{
+ "description": "Value for the Authorization header Carbone adds to its OUTBOUND (egress) requests while rendering — fetching external images ({d.imageUrl}), external PDFs (:appendFile / :attachFile), and calling webhooks. For example \"Bearer abc123\" or \"my-secret\" makes Carbone send `authorization: <value>` to those hosts. Only the authorization header can be customised; max 512 characters. For webhook calls specifically, webhookHeaders.authorization (if set) overrides this value.",
+ "maxLength": 512,
+ "type": "string"
+}Input schema / requiredRemoved value: -[
- "data"
-]v1.2.2convert_document5 fields changedInput schema / properties / asAttachmentAdded value: +{
+ "description": "If true, return the document as a downloadable file attachment (a base64 EmbeddedResource), for any format. Default delivery: text and png/jpg/gif/webp are returned inline; other binary outputs (PDF, Office, …) are saved to a temp file in stdio mode (path returned), or returned as an attachment in HTTP mode. Ignored when outputPath or returnLink is set.",
+ "type": "boolean"
+}Input schema / properties / convertTo / anyOfPrevious value: -[
- {
- "enum": [
- "pdf",
- "docx",
- "xlsx",
- "pptx",
- "odt",
- "ods",
- "odp",
- "odg",
- "html",
- "xhtml",
- "txt",
- "csv",
- "md",
- "xml",
- "rtf",
- "png",
- "jpg",
- "jpeg",
- "webp",
- "svg",
- "tiff",
- "bmp",
- "gif",
- "zip",
- "idml",
- "epub"
- ],
- "type": "string"
- },
- {
- "properties": {
- "formatName": {
- "description": "Target format name.",
- "enum": [
- "pdf",
- "docx",
- "xlsx",
- "pptx",
- "odt",
- "ods",
- "odp",
- "odg",
- "html",
- "xhtml",
- "txt",
- "csv",
- "md",
- "xml",
- "rtf",
- "png",
- "jpg",
- "jpeg",
- "webp",
- "svg",
- "tiff",
- "bmp",
- "gif",
- "zip",
- "idml",
- "epub"
- ],
- "type": "string"
- },
- "formatOptions": {
- "additionalProperties": {},
- "description": "Advanced format options object. Examples by format: PDF — { \"EncryptFile\": true, \"DocumentOpenPassword\": \"secret\", \"DocumentPermissionPassword\": \"owner\" } password-protect; PDF — { \"Watermarks\": [{ \"text\": \"DRAFT\", \"opacity\": 0.2, \"rotation\": -45, \"fontsize\": 60 }] } up to 5 watermarks; PDF — { \"SelectPdfVersion\": 1 } PDF/A-1b compliance (use 2 for PDF/A-2, 3 for PDF/A-3); PDF — { \"PageRange\": \"1-3,5\" } export specific pages only; PDF — { \"ConvertSlideshow\": true } convert each slide to a separate PDF page; Images (PNG/JPG/WEBP) — { \"Quality\": 90 } set compression quality 0-100; Images — { \"density\": 150 } set DPI for rasterisation (default 96); CSV — { \"fieldSeparator\": \";\" } custom column separator.",
- "propertyNames": {
- "type": "string"
- },
- "type": "object"
- }
- },
- "required": [
- "formatName"
- ],
- "type": "object"
- }
-]New value: +[
+ {
+ "enum": [
+ "pdf",
+ "docx",
+ "xlsx",
+ "pptx",
+ "odt",
+ "ods",
+ "odp",
+ "odg",
+ "html",
+ "xhtml",
+ "txt",
+ "csv",
+ "md",
+ "xml",
+ "rtf",
+ "png",
+ "jpg",
+ "jpeg",
+ "webp",
+ "svg",
+ "tiff",
+ "bmp",
+ "gif",
+ "zip",
+ "idml",
+ "epub",
+ "cdr"
+ ],
+ "type": "string"
+ },
+ {
+ "properties": {
+ "formatName": {
+ "description": "Target format name.",
+ "enum": [
+ "pdf",
+ "docx",
+ "xlsx",
+ "pptx",
+ "odt",
+ "ods",
+ "odp",
+ "odg",
+ "html",
+ "xhtml",
+ "txt",
+ "csv",
+ "md",
+ "xml",
+ "rtf",
+ "png",
+ "jpg",
+ "jpeg",
+ "webp",
+ "svg",
+ "tiff",
+ "bmp",
+ "gif",
+ "zip",
+ "idml",
+ "epub",
+ "cdr"
+ ],
+ "type": "string"
+ },
+ "formatOptions": {
+ "additionalProperties": {},
+ "description": "Advanced format options object. Examples by format: PDF — { \"EncryptFile\": true, \"DocumentOpenPassword\": \"secret\", \"DocumentPermissionPassword\": \"owner\" } password-protect; PDF — { \"Watermarks\": [{ \"text\": \"DRAFT\", \"opacity\": 0.2, \"rotation\": -45, \"fontsize\": 60 }] } up to 5 watermarks; PDF — { \"SelectPdfVersion\": 1 } PDF/A-1b compliance (use 2 for PDF/A-2, 3 for PDF/A-3); PDF — { \"PageRange\": \"1-3,5\" } export specific pages only; PDF — { \"ConvertSlideshow\": true } convert each slide to a separate PDF page; Images (PNG/JPG/WEBP) — { \"Quality\": 90 } set compression quality 0-100; Images — { \"density\": 150 } set DPI for rasterisation (default 96); CSV — { \"fieldSeparator\": \";\" } custom column separator.",
+ "propertyNames": {
+ "type": "string"
+ },
+ "type": "object"
+ }
+ },
+ "required": [
+ "formatName"
+ ],
+ "type": "object"
+ }
+]Input schema / properties / file / descriptionPrevious value: -"The document to convert. Three input forms are accepted: (1) Local file path — absolute or relative, e.g. \"/home/user/report.docx\" or \"./invoice.xlsx\". (2) HTTPS URL — the file is downloaded automatically, e.g. \"https://example.com/file.pptx\". (3) Base64-encoded string — the raw file content encoded as base64. Supported input formats include: DOCX, XLSX, PPTX, ODT, ODS, ODP, ODG, HTML, XHTML, XML, IDML, Markdown (MD), PDF, TXT, CSV, PNG, JPG, SVG, and more. Full conversion matrix: https://carbone.io/documentation/developer/http-api/generate-reports.html#output-file-type"New value: +"The document to convert. Three input forms are accepted: (1) Local file path — absolute or relative, e.g. \"/home/user/report.docx\" or \"./invoice.xlsx\". (2) HTTPS URL — the file is downloaded automatically, e.g. \"https://example.com/file.pptx\". (3) Base64-encoded string — the raw file content encoded as base64. Supported input formats include: DOCX, XLSX, PPTX, ODT, ODS, ODP, ODG, HTML, XHTML, XML, IDML, Markdown (MD), PDF, TXT, CSV, PNG, JPG, SVG, and more. Full conversion matrix: https://carbone.io/documentation/developer/http-api/generate-reports.md"Input schema / properties / outputPathAdded value: +{
+ "description": "Optional local file path to save the converted document to (e.g. \"/home/user/out.pdf\" or \"~/out.pdf\"). When set, the file is written to disk and the tool returns the saved path + size instead of embedding the document inline — ideal for large files. Local (stdio) mode only; rejected in HTTP mode.",
+ "type": "string"
+}Input schema / properties / returnLinkAdded value: +{
+ "description": "If true, generate the document and return a public download URL instead of the file contents. The link is SHORT-LIVED and ONE-TIME — Carbone deletes the file after the first download — so it is meant for the end user to download once (do not fetch it programmatically). Works in stdio and HTTP. Mutually exclusive with outputPath and asAttachment.",
+ "type": "boolean"
+}download_template2 fields changedInput schema / properties / asAttachmentAdded value: +{
+ "description": "If true, return the template as a downloadable file attachment (base64 resource) instead of inline text/image. Useful in HTTP mode where outputPath is unavailable. Default: false. Ignored when outputPath is set.",
+ "type": "boolean"
+}Input schema / properties / outputPathAdded value: +{
+ "description": "Optional local file path to save the template file to (e.g. \"/home/user/template.docx\" or \"~/template.docx\"). When set, the file is written to disk and the tool returns the saved path + size instead of embedding the file inline. Local (stdio) mode only; rejected in HTTP mode.",
+ "type": "string"
+}get_api_status1 field changedOutput schema / (root)Previous value: -nullNew value: +{
+ "$schema": "http://json-schema.org/draft-07/schema#",
+ "additionalProperties": false,
+ "properties": {
+ "message": {
+ "description": "Status message returned by the API.",
+ "type": "string"
+ },
+ "version": {
+ "description": "The running Carbone API version.",
+ "type": "string"
+ }
+ },
+ "required": [
+ "version",
+ "message"
+ ],
+ "type": "object"
+}list_categories1 field changedOutput schema / (root)Previous value: -nullNew value: +{
+ "$schema": "http://json-schema.org/draft-07/schema#",
+ "additionalProperties": false,
+ "properties": {
+ "categories": {
+ "description": "Template category names in use.",
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+ }
+ },
+ "required": [
+ "categories"
+ ],
+ "type": "object"
+}list_tags1 field changedOutput schema / (root)Previous value: -nullNew value: +{
+ "$schema": "http://json-schema.org/draft-07/schema#",
+ "additionalProperties": false,
+ "properties": {
+ "tags": {
+ "description": "Template tag names in use.",
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+ }
+ },
+ "required": [
+ "tags"
+ ],
+ "type": "object"
+}list_templates5 fields changedInput schema / properties / limit / descriptionPrevious value: -"Maximum number of results to return (default: 100)."New value: +"Maximum number of results to return. Must be between 1 and 100 (Carbone API limit). Default: 100."Input schema / properties / limit / exclusiveMinimumRemoved value: -0Input schema / properties / limit / maximumPrevious value: -9007199254740991New value: +100Input schema / properties / limit / minimumAdded value: +1Output schema / (root)Previous value: -nullNew value: +{
+ "$schema": "http://json-schema.org/draft-07/schema#",
+ "additionalProperties": false,
+ "properties": {
+ "hasMore": {
+ "description": "Whether more results are available via the cursor.",
+ "type": "boolean"
+ },
+ "nextCursor": {
+ "description": "Cursor to pass to the next list_templates call.",
+ "type": "string"
+ },
+ "templates": {
+ "description": "The matching templates (all fields).",
+ "items": {
+ "additionalProperties": {},
+ "propertyNames": {
+ "type": "string"
+ },
+ "type": "object"
+ },
+ "type": "array"
+ }
+ },
+ "required": [
+ "templates",
+ "hasMore"
+ ],
+ "type": "object"
+}render_document30 fields changedInput schema / properties / asAttachmentAdded value: +{
+ "description": "If true, return the document as a downloadable file attachment (a base64 EmbeddedResource), for any format. Default delivery: text and png/jpg/gif/webp are returned inline; other binary outputs (PDF, Office, …) are saved to a temp file in stdio mode (path returned), or returned as an attachment in HTTP mode. Ignored when outputPath or returnLink is set.",
+ "type": "boolean"
+}Input schema / properties / complement / additionalPropertiesRemoved value: -{}Input schema / properties / complement / anyOfAdded value: +[
+ {
+ "additionalProperties": {},
+ "propertyNames": {
+ "type": "string"
+ },
+ "type": "object"
+ },
+ {
+ "type": "string"
+ }
+]Input schema / properties / complement / descriptionPrevious value: -"Extra data object accessible in templates with {c.field} tags (as opposed to {d.field} for main data). Useful for static or shared values that should not be mixed into the main dataset: company info, logo URLs, footer text, configuration constants. Example: { \"company\": \"Acme Corp\", \"address\": \"123 Main St\", \"vatNumber\": \"FR12345\" }"New value: +"Extra data object accessible in templates with {c.field} tags (as opposed to {d.field} for main data). Useful for static or shared values that should not be mixed into the main dataset: company info, logo URLs, footer text, configuration constants. Example: { \"company\": \"Acme Corp\", \"address\": \"123 Main St\", \"vatNumber\": \"FR12345\" }. Like data, may instead be passed by reference as a string — a local path, HTTPS URL, or base64 to a JSON file."Input schema / properties / complement / propertyNamesRemoved value: -{
- "type": "string"
-}Input schema / properties / complement / typeRemoved value: -"object"Input schema / properties / convertTo / anyOfPrevious value: -[
- {
- "enum": [
- "pdf",
- "docx",
- "xlsx",
- "pptx",
- "odt",
- "ods",
- "odp",
- "odg",
- "html",
- "xhtml",
- "txt",
- "csv",
- "md",
- "xml",
- "rtf",
- "png",
- "jpg",
- "jpeg",
- "webp",
- "svg",
- "tiff",
- "bmp",
- "gif",
- "zip",
- "idml",
- "epub"
- ],
- "type": "string"
- },
- {
- "properties": {
- "formatName": {
- "description": "Target format name.",
- "enum": [
- "pdf",
- "docx",
- "xlsx",
- "pptx",
- "odt",
- "ods",
- "odp",
- "odg",
- "html",
- "xhtml",
- "txt",
- "csv",
- "md",
- "xml",
- "rtf",
- "png",
- "jpg",
- "jpeg",
- "webp",
- "svg",
- "tiff",
- "bmp",
- "gif",
- "zip",
- "idml",
- "epub"
- ],
- "type": "string"
- },
- "formatOptions": {
- "additionalProperties": {},
- "description": "Advanced format options object. Examples by format: PDF — { \"EncryptFile\": true, \"DocumentOpenPassword\": \"secret\", \"DocumentPermissionPassword\": \"owner\" } password-protect; PDF — { \"Watermarks\": [{ \"text\": \"DRAFT\", \"opacity\": 0.2, \"rotation\": -45, \"fontsize\": 60 }] } up to 5 watermarks; PDF — { \"SelectPdfVersion\": 1 } PDF/A-1b compliance (use 2 for PDF/A-2, 3 for PDF/A-3); PDF — { \"PageRange\": \"1-3,5\" } export specific pages only; PDF — { \"ConvertSlideshow\": true } convert each slide to a separate PDF page; Images (PNG/JPG/WEBP) — { \"Quality\": 90 } compression quality 0-100; Images — { \"density\": 150 } DPI for rasterisation (default 96); CSV — { \"fieldSeparator\": \";\" } custom column separator.",
- "propertyNames": {
- "type": "string"
- },
- "type": "object"
- }
- },
- "required": [
- "formatName"
- ],
- "type": "object"
- }
-]New value: +[
+ {
+ "enum": [
+ "pdf",
+ "docx",
+ "xlsx",
+ "pptx",
+ "odt",
+ "ods",
+ "odp",
+ "odg",
+ "html",
+ "xhtml",
+ "txt",
+ "csv",
+ "md",
+ "xml",
+ "rtf",
+ "png",
+ "jpg",
+ "jpeg",
+ "webp",
+ "svg",
+ "tiff",
+ "bmp",
+ "gif",
+ "zip",
+ "idml",
+ "epub",
+ "cdr"
+ ],
+ "type": "string"
+ },
+ {
+ "properties": {
+ "formatName": {
+ "description": "Target format name.",
+ "enum": [
+ "pdf",
+ "docx",
+ "xlsx",
+ "pptx",
+ "odt",
+ "ods",
+ "odp",
+ "odg",
+ "html",
+ "xhtml",
+ "txt",
+ "csv",
+ "md",
+ "xml",
+ "rtf",
+ "png",
+ "jpg",
+ "jpeg",
+ "webp",
+ "svg",
+ "tiff",
+ "bmp",
+ "gif",
+ "zip",
+ "idml",
+ "epub",
+ "cdr"
+ ],
+ "type": "string"
+ },
+ "formatOptions": {
+ "additionalProperties": {},
+ "description": "Advanced format options object. Examples by format: PDF — { \"EncryptFile\": true, \"DocumentOpenPassword\": \"secret\", \"DocumentPermissionPassword\": \"owner\" } password-protect; PDF — { \"Watermarks\": [{ \"text\": \"DRAFT\", \"opacity\": 0.2, \"rotation\": -45, \"fontsize\": 60 }] } up to 5 watermarks; PDF — { \"SelectPdfVersion\": 1 } PDF/A-1b compliance (use 2 for PDF/A-2, 3 for PDF/A-3); PDF — { \"PageRange\": \"1-3,5\" } export specific pages only; PDF — { \"ConvertSlideshow\": true } convert each slide to a separate PDF page; Images (PNG/JPG/WEBP) — { \"Quality\": 90 } compression quality 0-100; Images — { \"density\": 150 } DPI for rasterisation (default 96); CSV — { \"fieldSeparator\": \";\" } custom column separator.",
+ "propertyNames": {
+ "type": "string"
+ },
+ "type": "object"
+ }
+ },
+ "required": [
+ "formatName"
+ ],
+ "type": "object"
+ }
+]Input schema / properties / currencyRates / additionalPropertiesRemoved value: -{
- "type": "number"
-}Input schema / properties / currencyRates / anyOfAdded value: +[
+ {
+ "additionalProperties": {
+ "type": "number"
+ },
+ "propertyNames": {
+ "type": "string"
+ },
+ "type": "object"
+ },
+ {
+ "type": "string"
+ }
+]Input schema / properties / currencyRates / descriptionPrevious value: -"Exchange rate table used by :formatC for currency conversion. Keys are ISO 4217 currency codes; values are rates relative to a common base. The base currency should have rate 1. Example: { \"EUR\": 1, \"USD\": 1.08, \"GBP\": 0.86, \"JPY\": 160.5 }."New value: +"Exchange rate table used by :formatC for currency conversion. Keys are ISO 4217 currency codes; values are rates relative to a common base. The base currency should have rate 1. Example: { \"EUR\": 1, \"USD\": 1.08, \"GBP\": 0.86, \"JPY\": 160.5 }. May instead be passed by reference as a string — a local path, HTTPS URL, or base64 to a JSON file."Input schema / properties / currencyRates / propertyNamesRemoved value: -{
- "type": "string"
-}Input schema / properties / currencyRates / typeRemoved value: -"object"Input schema / properties / data / additionalPropertiesRemoved value: -{}Input schema / properties / data / anyOfAdded value: +[
+ {
+ "additionalProperties": {},
+ "propertyNames": {
+ "type": "string"
+ },
+ "type": "object"
+ },
+ {
+ "items": {},
+ "type": "array"
+ },
+ {
+ "type": "string"
+ }
+]Input schema / properties / data / descriptionPrevious value: -"JSON data merged into the template. Access fields with {d.fieldName} tags. Nested objects: {d.customer.name}. Array loops: {d.items[i].description} … {d.items[i+1]}. Conditionals: {d.status == \"active\" ? \"Yes\" : \"No\"}. For pure document conversion without data injection, pass {}."New value: +"JSON data merged into the template — an object, or a top-level array (accessed with {d[i].field}). Access fields with {d.fieldName} tags. Nested objects: {d.customer.name}. Array loops: {d.items[i].description} … {d.items[i+1]}. Conditionals: {d.status == \"active\" ? \"Yes\" : \"No\"}. For pure document conversion without data injection, pass {}. Instead of inlining a large dataset, you may pass a STRING reference to the JSON: a local file path (e.g. \"/data/invoices.json\"), an HTTPS URL, or a base64-encoded JSON string — it is read and parsed server-side. Local paths resolve in stdio (local) mode only; URLs and base64 work in both transports."Input schema / properties / data / propertyNamesRemoved value: -{
- "type": "string"
-}Input schema / properties / data / typeRemoved value: -"object"Input schema / properties / enum / additionalPropertiesRemoved value: -{}Input schema / properties / enum / anyOfAdded value: +[
+ {
+ "additionalProperties": {},
+ "propertyNames": {
+ "type": "string"
+ },
+ "type": "object"
+ },
+ {
+ "type": "string"
+ }
+]Input schema / properties / enum / descriptionPrevious value: -"Enumeration map used with the :convEnum(TYPE) formatter to translate code values into human-readable labels. Define one key per enum type; each value is an object mapping code → label. Example: { \"STATUS\": { \"1\": \"Active\", \"2\": \"Inactive\", \"3\": \"Pending\" }, \"ROLE\": { \"A\": \"Admin\", \"U\": \"User\" } }. Template usage: {d.status:convEnum(STATUS)}, {d.role:convEnum(ROLE)}. Documentation: https://carbone.io/documentation.html#convenum-type-"New value: +"Enumeration map used with the :convEnum(TYPE) formatter to translate code values into human-readable labels. Define one key per enum type; each value is an object mapping code → label. Example: { \"STATUS\": { \"1\": \"Active\", \"2\": \"Inactive\", \"3\": \"Pending\" }, \"ROLE\": { \"A\": \"Admin\", \"U\": \"User\" } }. Template usage: {d.status:convEnum(STATUS)}, {d.role:convEnum(ROLE)}. May instead be passed by reference as a string — a local path, HTTPS URL, or base64 to a JSON file. Documentation: https://carbone.io/documentation.html#convenum-type-"Input schema / properties / enum / propertyNamesRemoved value: -{
- "type": "string"
-}Input schema / properties / enum / typeRemoved value: -"object"Input schema / properties / outputPathAdded value: +{
+ "description": "Optional local file path to save the generated document to (e.g. \"/home/user/out.pdf\" or \"~/out.pdf\"). When set, the file is written to disk and the tool returns the saved path + size instead of embedding the document inline — ideal for large files. Local (stdio) mode only; rejected in HTTP mode. Ignored for async/webhook renders (no document is returned inline).",
+ "type": "string"
+}Input schema / properties / reportName / descriptionPrevious value: -"Filename for the generated document, returned in the Content-Disposition header. Supports Carbone tags resolved against the data at render time. Examples: \"invoice.pdf\" (static), \"{d.type}-{d.id}.pdf\" (dynamic), \"{d.client}-{d.date:formatD(YYYY-MM)}.docx\"."New value: +"Filename (WITHOUT extension) for the generated document, returned in the Content-Disposition header. Carbone automatically appends the extension that matches convertTo, so do not include one — passing \"invoice.pdf\" yields \"invoice.pdf.pdf\". Supports Carbone tags resolved against the data at render time. Examples: \"invoice\" (static), \"{d.type}-{d.id}\" (dynamic), \"{d.client}-{d.date:formatD(YYYY-MM)}\"."Input schema / properties / returnLinkAdded value: +{
+ "description": "If true, generate the document and return a public download URL instead of the file contents. The link is SHORT-LIVED and ONE-TIME — Carbone deletes the file after the first download — so it is meant for the end user to download once (do not fetch it programmatically). Works in stdio and HTTP. Mutually exclusive with outputPath, asAttachment, and webhookUrl (async).",
+ "type": "boolean"
+}Input schema / properties / translations / additionalPropertiesRemoved value: -{
- "additionalProperties": {
- "type": "string"
- },
- "propertyNames": {
- "type": "string"
- },
- "type": "object"
-}Input schema / properties / translations / anyOfAdded value: +[
+ {
+ "additionalProperties": {
+ "additionalProperties": {
+ "type": "string"
+ },
+ "propertyNames": {
+ "type": "string"
+ },
+ "type": "object"
+ },
+ "propertyNames": {
+ "type": "string"
+ },
+ "type": "object"
+ },
+ {
+ "type": "string"
+ }
+]Input schema / properties / translations / descriptionPrevious value: -"Translation map for multilingual documents. Requires \"lang\" to be set to select the active locale. Top-level keys are BCP-47 locale codes; values are key → translated-string maps. Template usage: {t(greeting)} is replaced by the matching string for the active locale. Example: { \"fr-fr\": { \"greeting\": \"Bonjour\", \"total\": \"Total\" }, \"en-us\": { \"greeting\": \"Hello\", \"total\": \"Total\" } }. Documentation: https://carbone.io/documentation.html#translations"New value: +"Translation map for multilingual documents. Requires \"lang\" to be set to select the active locale. Top-level keys are BCP-47 locale codes; values are key → translated-string maps. Template usage: {t(greeting)} is replaced by the matching string for the active locale. Example: { \"fr-fr\": { \"greeting\": \"Bonjour\", \"total\": \"Total\" }, \"en-us\": { \"greeting\": \"Hello\", \"total\": \"Total\" } }. These dictionaries get large, so you may instead pass a string reference — a local path, HTTPS URL, or base64 to a JSON file. Documentation: https://carbone.io/documentation.html#translations"Input schema / properties / translations / propertyNamesRemoved value: -{
- "type": "string"
-}Input schema / properties / translations / typeRemoved value: -"object"upload_template2 fields changedInput schema / properties / template / descriptionPrevious value: -"The template file. Accepts a local file path (e.g. /home/user/invoice.docx), a URL (https://example.com/template.docx), or a base64-encoded string. Supported formats: DOCX, XLSX, PPTX, ODT, ODS, ODP, ODG, HTML, XHTML, IDML, XML, Markdown (MD), PDF, and more. Full list: https://carbone.io/documentation/developer/http-api/generate-reports.html#output-file-type"New value: +"The template file. Accepts a local file path (e.g. /home/user/invoice.docx), a URL (https://example.com/template.docx), or a base64-encoded string. Supported formats: DOCX, XLSX, PPTX, ODT, ODS, ODP, ODG, HTML, XHTML, IDML, XML, Markdown (MD), PDF, and more. Full list: https://carbone.io/documentation/developer/http-api/generate-reports.md"Output schema / (root)Previous value: -nullNew value: +{
+ "$schema": "http://json-schema.org/draft-07/schema#",
+ "additionalProperties": false,
+ "properties": {
+ "id": {
+ "description": "Stable Template ID (when versioning is enabled).",
+ "type": "string"
+ },
+ "name": {
+ "description": "Template display name.",
+ "type": "string"
+ },
+ "size": {
+ "description": "Template size in bytes.",
+ "type": "number"
+ },
+ "templateId": {
+ "description": "Template ID returned in legacy/non-versioned mode.",
+ "type": "string"
+ },
+ "type": {
+ "description": "Detected template file type.",
+ "type": "string"
+ },
+ "versionId": {
+ "description": "Version ID (SHA-256) of this uploaded version.",
+ "type": "string"
+ }
+ },
+ "required": [
+ "name"
+ ],
+ "type": "object"
+}v1.1.2convert_documentdelete_templatedownload_templateget_api_statusget_capabilitieslist_categorieslist_tagslist_templatesrender_documentupdate_template_metadataupload_templateScored across 12 tools
Each tool targets a distinct action on a distinct resource (upload, list, download, update, delete, render, convert, inspect), and the descriptions explicitly cross-reference each other to steer selection. The only mild overlap is render_document vs convert_document (both can output a converted/proofed file, and render with keepTags:true approaches conversion), but the descriptions call this distinction out clearly.
All twelve tools use a uniform snake_case verb_noun pattern (upload_template, list_tags, update_template_metadata, delete_template, get_api_status, etc.). No mixed casing or inconsistent verb styles; list/get/update/delete/upload/convert/render forms are predictable.
Twelve tools is well within the ideal 3-15 range and each one covers a distinct capability (lifecycle CRUD, rendering, conversion, inspection, discovery helpers). No obvious filler or redundant tool.
Template lifecycle is fully covered: upload (create), list/download (read), update_template_metadata (update), delete, plus render, convert, inspect, and discovery helpers for tags/categories/capabilities/status. Minor gaps exist around async render jobs—there is no tool to poll render status or fetch a renderId result, since async output only goes to a webhook—and tags/categories can only be listed, not managed directly.
Generate PDF, Word (.docx) and PowerPoint (.pptx) documents from Markdown over MCP.
MCP server for Api2Pdf — generate PDFs & images from HTML, URLs or office files; merge, barcodes.
Design, publish and render PDF templates with Typst. Full template lifecycle over MCP.
Document conversion MCP server: PDF to Markdown, image OCR, spreadsheet parsing.