Compliant PDFs (PDF/A-2A + PDF/UA-1) from markdown or a compact DSL - fast, no headless browser.
Scored across 11 tools
Template CRUD tools (delete/get/list/save/update_template) are cleanly distinct, and validation tools split neatly by input type (validate_dsl vs validate_markdown). The three render tools (render_dsl_preview, render_template, render_markdown) all produce PDFs and could momentarily overlap, but the descriptions sharply distinguish free-preview, billed-template, and markdown paths.
Every tool follows a consistent snake_case verb_noun pattern (delete_template, get_template, list_templates, render_markdown, validate_dsl, report_feedback, etc.). Verbs are precise and uniform across the whole set.
11 tools is well-scoped for a PDF rendering/validation service, with each tool earning its place. No redundant or filler tools are present.
Covers full template lifecycle (save/list/get/update/delete), rendering (preview + billed, DSL + markdown), and validation for both input types, plus feedback. The only notable gap is that artifactId is returned but there is no tool to list, fetch, or manage previously-rendered artifacts.
Delete a caller-owned template by ID. Library rows cannot be deleted. Mirrors DELETE /api/v1/templates/:id.
| Name | Required | Description | Default |
|---|---|---|---|
| templateId | Yes | Template ID — slug for library rows (e.g. 'invoice-classic') or UUID for user rows. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden, and it does disclose the destructive nature and the ownership restriction. However, it omits the safety profile that matters for a delete: whether deletion is reversible, what permissions are required, and how errors surface for nonexistent or non-owned IDs.
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, front-loaded sentences with no filler: action, constraint, and API correspondence in that order. Every 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 single-parameter tool with a fully covered schema and no output schema, the description is nearly complete: it defines scope and the key restriction. A brief note on irreversibility or failure behavior would close the remaining gap, but nothing essential 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 coverage is 100% and the schema itself explains the slug-vs-UUID distinction, so the description need not add parameter detail. It adds nothing beyond the schema, which is the expected baseline for a fully documented single parameter.
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 + resource ('Delete a caller-owned template by ID') with an added scope constraint ('Library rows cannot be deleted') that no sibling covers — none of the nine siblings performs deletion, so the tool is unambiguous. The API-endpoint mapping further pins the 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?
The description gives one exclusion ('library rows cannot be deleted'), which is a useful when-not rule, but offers no positive when-to-use guidance or comparison against alternatives such as update_template or save_template. Usage is implied rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch a single template (library or caller-owned) by ID, including its full DSL source and sampleData. Mirrors GET /api/v1/templates/:id.
| Name | Required | Description | Default |
|---|---|---|---|
| templateId | Yes | Template ID — slug for library rows (e.g. 'invoice-classic') or UUID for user rows. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description uses 'Fetch' and 'Mirrors GET', which strongly implies a read-only operation with no side effects. However, since no annotations are provided, the description carries the burden, and it does not explicitly mention error behavior, permissions, or lack of mutation. Overall it is fairly transparent but not exhaustive.
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 concise—two sentences—and front-loads the core action. Every word adds value: the resource, the scope, the return payload, and a useful API reference. No filler or redundancy.
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 simple fetch tool with a single parameter, the description covers the essential context: what is fetched, what is included in the response, and how the parameter is interpreted. It does not need to explain return schemas or error codes for this level of complexity.
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 parameter description goes beyond the schema's type string by explaining the two possible formats (slug for library rows, UUID for user rows) and provides a concrete example. This gives the agent clear, actionable guidance for constructing valid calls.
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 clearly states the action ('Fetch') and the resource ('a single template'), and specifies that it returns the full DSL source and sampleData. The phrase 'library or caller-owned' and the focal 'by ID' effectively distinguish it from list_templates, making the purpose unambiguous.
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 implies usage for retrieving a specific template by ID, but it does not explicitly state when to prefer this over alternatives. It references the REST endpoint but provides no direct guidance on when not to use it or when to use list_templates instead. This leaves some room for interpretation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List templates visible to the caller — both curated library templates (no owner) and the caller's own saved templates. Metadata only (no DSL bodies). Paginated. Use owner: 'mine' to restrict to your own; owner: 'library' for the curated catalog only; default 'all' returns both. Optional category, tags (comma-separated, ANDed), and q (free-text over name + description) filters apply across both. Mirrors GET /api/v1/templates.
| Name | Required | Description | Default |
|---|---|---|---|
| q | No | ||
| tags | No | ||
| limit | No | ||
| owner | No | all | |
| offset | No | ||
| category | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and does so well. It discloses that the operation is a read-only list, returns metadata only, is paginated, and has specific owner-filter semantics including the default 'all' behavior. The note 'Mirrors GET /api/v1/templates' reinforces the non-mutating, list-oriented behavior.
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 compact but information-dense: three sentences cover purpose, scope, return nature, pagination, owner modes, filters, and the equivalent API endpoint. Every clause contributes useful guidance, with the most important behavioral constraint ('Metadata only') placed early.
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 read-only list tool with no annotations and no output schema, the description covers what an agent needs to invoke it correctly: what is listed, who can see it, what is returned, how filtering works, the default owner mode, and pagination. The only minor omission is explicit guidance about when to switch to get_template for full DSL bodies, but the metadata-only statement and sibling list make this reasonably inferable.
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?
Since schema description coverage is 0%, the description must compensate for missing parameter semantics. It adds meaning for q (free-text over name and description), tags (comma-separated and ANDed), owner (all three enum values with default behavior), and category. It mentions pagination but does not explicitly describe how limit and offset behave beyond what the schema already shows via defaults and constraints.
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 clearly states a specific verb and resource: 'List templates visible to the caller', and further defines the two included scopes (library templates and the caller's saved templates). It distinguishes itself from siblings by explicitly noting 'Metadata only (no DSL bodies)', so an agent can tell it apart from get_template, delete_template, and render tools without needing to open their schemas.
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 provides clear context on how to use the tool: listing visible templates, filtering by owner, category, tags, and free-text q, with pagination. It does not explicitly name an alternative like 'use get_template when you need the DSL body,' but the 'Metadata only (no DSL bodies)' note implicitly communicates when this tool is not appropriate, and sibling names help fill the gap.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Render a DSL template + data to a preview PDF. Free (no credits), always watermarked 'PREVIEW — NOT FOR USE'. Returns JSON metadata plus the PDF bytes as an embedded base64 resource. Mirrors POST /api/v1/preview.
| Name | Required | Description | Default |
|---|---|---|---|
| dsl | Yes | The builder DSL script. | |
| data | No | Optional binding data. Falls back to the script's sampleData when omitted. | |
| title | No | Optional document title (shown in PDF metadata). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It discloses the cost model (free/no credits), the always-on watermark, and the return format (JSON metadata plus PDF bytes as base64). It stops short of stating side-effect behavior or error conditions, but 'preview' and the endpoint reference imply a non-destructive render.
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: the action, the constraints/cost, and the output format/endpoint. There is no filler, repetition, or unnecessary detail, and the key preview semantics are front-loaded.
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 description covers the essential context: what the tool does, cost, watermarking, and return value shape. Since there is no output schema, the explicit statement of 'JSON metadata plus the PDF bytes as an embedded base64 resource' is important and present. It does not address error cases or prerequisites, but those are minor for a simple preview endpoint.
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 mentions 'DSL template + data' in prose but adds no parameter-specific meaning beyond what the schema already documents; the schema itself covers dsl, the data fallback to sampleData, and title metadata.
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 opens with a specific verb ('Render') and resource ('a DSL template + data to a preview PDF'), making the core action unambiguous. It also distinguishes itself from the sibling render_template by emphasizing 'preview', the watermark, and the explicit endpoint reference 'POST /api/v1/preview'.
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: it is free, consumes no credits, always watermarked, and explicitly marked 'PREVIEW — NOT FOR USE', which implies it should not be used for production output. However, it does not explicitly name the alternative render_template or state the condition that should select the production render, so the guidance is contextual rather than fully explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Render GitHub-flavored markdown to a real PDF (PDF/A-2A + PDF/UA-1 dual-compliant, tagged). BILLED - consumes credits at the rate of 1 credit per 10 pages. Returns JSON metadata (pageCount, creditsDeducted, creditsRemaining, artifactId) plus the PDF bytes as an embedded base64 resource. On the free plan the PDF is watermarked; paid plans render clean. Mirrors POST /api/v1/md. Run validate_markdown first - it is free and catches heading-hierarchy and alt-text problems before you pay to render them. There is no free markdown preview: markdown needs no layout iteration, so this is the only markdown render tool.
| Name | Required | Description | Default |
|---|---|---|---|
| options | No | Optional render settings. Anything omitted falls back to YAML frontmatter in the markdown, then to the runtime default. | |
| markdown | Yes | GitHub-flavored markdown source. Max 200KB of text; inline data: image payloads are excluded from that budget. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden and does so: it discloses the billing model (1 credit per 10 pages), plan-dependent watermarking, output composition (JSON metadata plus base64 PDF resource), and the API endpoint it mirrors. This is well beyond what the schema conveys.
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?
Five tight sentences with no filler; each carries a distinct fact (compliance, cost, return shape, plan behavior, prerequisite). The billing warning is set off typographically so the cost signal is not buried.
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 nested-schema tool with no output schema and no annotations, the description supplies everything an agent needs: cost, prerequisite, plan-dependent output, and an explicit account of the return payload. Nothing material is left to inference.
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 already 100%, including the fallback chain ('Anything omitted falls back to YAML frontmatter..., then to the runtime default'), so the schema does the heavy lifting. The description adds no per-parameter meaning for `options` fields such as theme, splitMode, or margins, 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 ('Render GitHub-flavored markdown to a real PDF') plus differentiating qualities (PDF/A-2A + PDF/UA-1, tagged). It explicitly distinguishes itself from the sibling preview/render tools by noting this is the only markdown render tool and that no free markdown preview exists.
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 explicit when-to-use sequencing: 'Run `validate_markdown` first - it is free and catches heading-hierarchy and alt-text problems before you pay to render them.' It also rules out an alternative an agent might otherwise hunt for ('There is no free markdown preview'), which is exactly the routing guidance needed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Render any readable template (curated library row or caller-owned) to a real PDF. BILLED — consumes credits at the rate of 1 credit per 10 pages. Returns JSON metadata (pageCount, creditsDeducted, creditsRemaining, artifactId) plus the PDF bytes as an embedded base64 resource. On the free plan the PDF is watermarked; paid plans render clean. Mirrors POST /api/v1/render with the { templateId, data } body shape. Use render_dsl_preview first to confirm the layout — that's free and watermarked. Only call this once you're confident the template is right.
| Name | Required | Description | Default |
|---|---|---|---|
| data | No | Binding data substituted into {{var}} expressions. Falls back to the template's sampleData when omitted. | |
| title | No | Optional document title (shown in PDF metadata). | |
| templateId | Yes | Template ID — slug for library rows (e.g. 'invoice-classic') or UUID for user rows. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full behavioral disclosure. It flags that this tool is 'BILLED', explains the credit rate, mentions free-plan watermarks, describes the JSON metadata returned, and notes the PDF bytes are embedded as base64. This is unusually transparent for a mutation/billing operation.
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 dense but every sentence earns its place. It front-loads the core purpose and the critical billing warning, then covers return format, watermarking, API shape, and the recommended alternative workflow without wasted words.
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?
There is no output schema, yet the description explicitly lists the return metadata fields (pageCount, creditsDeducted, creditsRemaining, artifactId) and the embedded base64 PDF. It also covers billing consequences, free-plan behavior, and the recommended preview workflow, making this fully complete for an agent deciding whether and how to invoke the tool.
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 schema already documents all three parameters at 100% coverage, so the high-coverage baseline of 3 applies. The description adds little beyond the schema for parameters, aside from noting the API body shape mirrors '{ templateId, data }', which is marginal. It does not introduce missing parameter details, but it also doesn't need to given the schema's completeness.
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 uses a specific verb ('Render') and resource ('any readable template — curated library row or caller-owned') and clearly states the output: 'a real PDF'. It distinguishes this from sibling tools by emphasizing the paid rendering path versus the free 'render_dsl_preview', so an agent can immediately tell what this tool does.
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 explicitly instructs the agent to use 'render_dsl_preview' first for free, watermarked layout confirmation, and says to call this tool only 'once you're confident the template is right.' It also names the alternative directly and provides a clear selection criterion between paid rendering and free preview.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Report feedback about this MCP server to the makesPDF team — where you got stuck, a tool error or description that misled you, a capability you needed but could not find, or a concrete suggestion for the server. Call it after a tool failed and you could not work out why, when an error message or tool description contradicted the skill file, when something you needed is missing, or when you have a specific improvement in mind. Write the problem in your own words: what you were trying to do, what you tried, and what you expected to happen. Do not include the user's document text, markdown, DSL source or data values. Describe the problem instead; if it concerns a specific render, pass its artifactId. This is not a support channel — nobody replies in real time. Calling it is free: it does not consume credits and does not affect the user's renders.
| Name | Required | Description | Default |
|---|---|---|---|
| kind | Yes | `stuck` — a tool failed and you could not work out why; `bug` — something behaved incorrectly (a misleading error/description counts); `suggestion` — a missing capability or a concrete improvement. | |
| summary | Yes | The problem in your own words: what you tried and what you expected. Do not include document content (see the content rule above). | |
| toolName | No | Optional name of the tool this concerns (e.g. `render_template`). | |
| artifactId | No | Optional UUID of the render artifact this concerns (the `artifactId` returned by a render call or the `X-Artifact-Id` response header). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does so well: it discloses the privacy constraint (do not include document text, markdown, DSL source or data values), the cost profile (free, no credits, does not affect renders), and the no-realtime-reply limit. These are exactly the behavioral traits an agent cannot infer elsewhere.
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 the purpose and the trigger conditions, then the content rule, then the cost note. It is on the long side for a feedback tool and the four trigger clauses slightly overlap, but every sentence carries actionable information and none is filler.
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 annotations and no output schema, so the description must be self-sufficient — and it is. It covers when to call, what to write, what not to include, how to reference a specific render, and what happens after submission. An agent has everything needed to invoke 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?
Schema coverage is 100%, so the baseline is 3; the description adds genuine value by prescribing what `summary` should contain ('what you were trying to do, what you tried, and what you expected') and clarifying how `artifactId` is obtained (from a render call or the X-Artifact-Id header). It does not meaningfully extend the `kind` enum beyond what the schema already defines.
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: report feedback about this MCP server to the makesPDF team, with concrete examples of what counts as feedback. This is trivially distinguishable from every sibling (render_*, validate_*, *_template), which are all document/template operations.
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 enumerates the trigger conditions (a tool failed and you cannot work out why, an error or description contradicted the skill file, a missing capability, a concrete improvement) and adds an exclusion: 'This is not a support channel — nobody replies in real time.' Both when-to-use and when-not-to-use are stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Save a user-owned DSL template for later reuse via /api/v1/render. Validates the DSL with the catalog before persisting. Free (no credits). Pass sampleData (any JSON value) so the template's binding shape is preserved — the modify-template flow on /ai/chat round-trips this back into the Render data panel when the user returns. Optional description is a one-sentence summary surfaced on /templates. Returns { templateId, name, createdAt }.
| Name | Required | Description | Default |
|---|---|---|---|
| dsl | Yes | The builder DSL script (<=512KB). | |
| name | Yes | Human-readable template name. | |
| sampleData | No | Optional JSON binding data to persist alongside the template. Round-tripped on get_template / modify-template flow. | |
| description | No | Optional one-sentence summary (max 280 chars). Surfaced on /templates list rows. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It discloses validation-before-persist, free (no credits), and the return shape { templateId, name, createdAt }. It also explains the sampleData round-trip behavior. Does not mention permissions or reversibility, but these are less critical for a save operation.
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 with no filler. Purpose is front-loaded, and each sentence adds value: what it does, validation+free, and return shape. Efficient and well-structured.
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 no output schema, it explains the return object. It covers validation, cost, and the sampleData purpose. It does not mention error handling (e.g., what happens if validation fails) or idempotency, but those are minor for a save tool. Overall complete enough for an agent 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?
Schema coverage is 100%, so baseline is 3. The description adds meaningful context beyond the schema: it explains sampleData's role in preserving binding shape and its round-trip on /ai/chat, and it clarifies that description is surfaced on /templates. These go beyond the schema descriptions.
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 ('save a user-owned DSL template') and its purpose (reuse via /api/v1/render), clearly distinguishing it from siblings like get_template, update_template, and delete_template. The mention of validation and free usage adds specific scope.
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?
Implies when to use (saving a new template for later render) and provides context about the modify-template flow on /ai/chat that uses sampleData, but does not explicitly name alternatives or state when not to use it (e.g., vs update_template). Lacks explicit exclusions, so not a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update a saved template's DSL, name, description, and/or sampleData. Revalidates the DSL when provided. For description and sampleData: pass null to clear; omit to leave unchanged. Mirrors PUT /api/v1/templates/:id.
| Name | Required | Description | Default |
|---|---|---|---|
| dsl | No | Replacement builder DSL script (<=512KB). | |
| name | No | ||
| sampleData | No | Optional JSON binding data. `null` clears the stored value; omit to leave unchanged. | |
| templateId | Yes | Template ID — slug for library rows (e.g. 'invoice-classic') or UUID for user rows. | |
| description | No | Optional one-sentence summary (max 280 chars). Pass `null` (instead of a string) to clear the stored value; omit the key entirely to leave it unchanged. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden, and it does disclose two real behaviors: the DSL is revalidated when provided, and the null-vs-omit contract for clearing vs. preserving fields. It omits auth/permission requirements, what happens if revalidation fails, and whether the update is atomic.
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 tightly written sentences; the core update action leads, followed by the revalidation note and the null/omit contract. The trailing endpoint mapping is compact and useful, though it could be dropped without loss.
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 mutation tool with no annotations and no output schema, the description covers field semantics and revalidation but says nothing about the response, error behavior, or the maxLength/512KB constraints that constrain a successful call. Adequate but with visible gaps.
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 80%, so the schema already documents templateId slug/UUID handling and the null-clearing semantics for description and sampleData. The description repeats rather than extends that, so the baseline 3 is appropriate.
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 (Update) and resource (a saved template) and enumerates the mutable fields (DSL, name, description, sampleData). It implicitly contrasts with the create-oriented save_template sibling, but never names it or any other 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?
No when-to-use guidance and no routing to alternatives: it doesn't say how this differs from save_template or when to prefer it over delete_template/get_template. The caller must infer that 'update' applies only to existing templates.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Validate a PDF template DSL script for structure, tag/style correctness, and accessibility issues. Runs catalog validation plus alt-text checks. Cheap — no rendering. Mirrors POST /api/v1/preview/validate.
| Name | Required | Description | Default |
|---|---|---|---|
| dsl | Yes | The builder DSL script to validate. Must define a template (see skills/pdf-template-author.md). | |
| data | No | Optional binding data. Falls back to the script's sampleData when omitted. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the behavioral disclosure burden. It usefully discloses that the tool runs catalog validation plus alt-text checks and that it performs no rendering, which is a meaningful behavioral trait. It does not explicitly state side effects or return behavior, but validation implies a non-mutating, read-only operation.
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 four tight sentences with no filler. The main purpose is front-loaded, and each sentence adds value: validation scope, checks performed, cost/rendering behavior, and API mirror. This is an efficient, well-structured description.
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 description covers the tool's purpose, validation scope, performance characteristics, and API relation. With complete parameter schema and one required parameter, an agent can likely invoke it correctly. However, the description does not state what the validation result looks like (e.g., issues list, pass/fail), which is a minor gap given there is no output schema.
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%, with clear descriptions for dsl and data. The tool description adds general context about validation categories but does not add parameter-specific meaning beyond the schema's own descriptions. Baseline 3 is appropriate because the schema already documents the parameters.
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 opens with a specific verb and resource: 'Validate a PDF template DSL script.' It names exact validation dimensions (structure, tag/style correctness, accessibility) and distinguishes itself from preview/rendering tools with 'Cheap — no rendering.' This clearly differentiates it from sibling tools like render_dsl_preview and validate_markdown.
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 stating 'Cheap — no rendering,' which implies this is the lightweight validation path versus render_dsl_preview. It also signals API parity with 'Mirrors POST /api/v1/preview/validate.' However, it does not explicitly mention when to prefer this over validate_markdown or name alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Validate a markdown document for PDF/UA-1 accessibility issues (heading hierarchy, missing alt text). Cheap — no rendering. Mirrors POST /api/v1/md/validate.
| Name | Required | Description | Default |
|---|---|---|---|
| markdown | Yes | GitHub-flavored markdown source. Max 200KB of text; inline data: image payloads are excluded from that budget. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It usefully discloses that no rendering occurs (implying a lightweight, likely read-only pass), but says nothing about required permissions, whether validation is exhaustive, or what the result shape is. Partial disclosure only.
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 short sentences, front-loaded with the purpose before the cost/endpoint note. No filler and nothing repeated from the schema.
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 simple single-input validation tool this covers the essentials, but with no output schema and no annotations nothing tells the agent what comes back (a boolean, a list of issues, severity levels) or whether the call is side-effect free. A sentence on the result would close the remaining gap.
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?
Only one parameter, and the schema already documents it fully (GitHub-flavored source, 200KB budget, inline data: images excluded) at 100% coverage. The description adds no syntax or format detail beyond the schema, so the baseline of 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?
Specific verb (Validate) plus resource (markdown document) plus the standard targeted (PDF/UA-1) and the concrete issue classes checked (heading hierarchy, missing alt text). It is clearly distinct from siblings like render_markdown and validate_dsl.
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?
"Cheap — no rendering" signals the context in which this tool is preferred over a render-then-inspect approach, and the API mirror gives an integration cue. It stops short of explicitly naming render_markdown or stating when-not to use it, so it is clear context without exclusions.
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.
render_markdown2 fields changedInput schema / properties / options / properties / pageNumberPositionAdded value: +{
+ "description": "Footer alignment when pageNumbers is set. Default 'right'. Ignored without pageNumbers.",
+ "enum": [
+ "left",
+ "center",
+ "right"
+ ],
+ "type": "string"
+}Input schema / properties / options / properties / pageNumbersAdded value: +{
+ "description": "Footer page-number format: 'page-n-of-total' (Page 3 of 12), 'n-of-total' (3 / 12), or 'n' (3). Omit for no page numbers.",
+ "enum": [
+ "page-n-of-total",
+ "n-of-total",
+ "n"
+ ],
+ "type": "string"
+}render_markdown2 fields changedInput schema / properties / markdown / descriptionPrevious value: -"GitHub-flavored markdown source."New value: +"GitHub-flavored markdown source. Max 200KB of text; inline data: image payloads are excluded from that budget."Input schema / properties / markdown / maxLengthRemoved value: -200000validate_markdown2 fields changedInput schema / properties / markdown / descriptionPrevious value: -"GitHub-flavored markdown source."New value: +"GitHub-flavored markdown source. Max 200KB of text; inline data: image payloads are excluded from that budget."Input schema / properties / markdown / maxLengthRemoved value: -200000report_feedbackdelete_template1 field changedInput schema / properties / templateId / descriptionAdded value: +"Template ID — slug for library rows (e.g. 'invoice-classic') or UUID for user rows."update_template3 fields changedInput schema / properties / description / typePrevious value: -"string"New value: +[
+ "string",
+ "null"
+]Input schema / properties / dsl / descriptionAdded value: +"Replacement builder DSL script (<=512KB)."Input schema / properties / templateId / descriptionAdded value: +"Template ID — slug for library rows (e.g. 'invoice-classic') or UUID for user rows."render_markdowndelete_templateget_templatelist_templatesrender_dsl_previewrender_templatesave_templateupdate_templatevalidate_dslvalidate_markdownRender Markdown and LLM output into accessible PDF/UA-1 PDFs. No headless Chromium.
Cloud PDF generation from HTML, CSS and XSL-FO, with PDF/A and PDF/UA support.
I create PDF documents from markdown, preview, then generate a downloadable file
Markdown in, any format out. PDFs merged, split, watermarked. Runs on our own doc engines.
Add one secure layer between your agents and this server.
