Carbone MCP

Official

by carboneio

Overview Schema Source Related Servers Discussions Admin

TypeScript

Hybrid

Inspect Template

inspect_template

Read-onlyIdempotent

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.

Instructions

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.

Input Schema

TableJSON Schema

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.

Output Schema

TableJSON Schema

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.

Schema Changelog

Changes observed during successful MCP inspections.

Addedv2.0.0Oct 14, 2026

TDQS

A4.5/5.0

Behavior5/5

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

Annotations already declare readOnlyHint/idempotent/destructive=false, but the description adds behavior the annotations cannot express: it consumes one render on the Carbone account and discards the resulting document, and it excludes {t()} translation tags from the output. Those are exactly the non-obvious side effects and limitations an agent needs before calling.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Four sentences, front-loaded with what the tool returns, then when to call it, then the argument contract, then a caveat. No filler and nothing repeated for padding.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present, the description need not explain return values, and it covers the remaining agent-critical facts: usage timing, the one-of argument rule, the render consumption side effect, and the translation-tag exclusion. Nothing material is missing for a two-parameter read tool.

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

Parameters3/5

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

Schema description coverage is 100%, so the schema already documents input forms, supported file types, and the mutual-exclusivity rule in far more depth than the description. The description restates the same one-of constraint and the three input forms, adding no meaning beyond the schema — the baseline 3 applies.

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

Purpose5/5

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

States a specific verb and resource (lists the Carbone tags a template uses) plus a second concrete output (a sample JSON dataset matching its structure). This is clearly distinguishable from sibling tools like list_tags and render_document, since it names its relationship to render_document explicitly.

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

Usage Guidelines4/5

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

Gives an explicit trigger: 'Call it before render_document when you do not know which data a template expects,' which routes the agent correctly. It does not state a when-not condition (e.g., when you already know the schema, skip it), 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.

Deploy Server