Compliant PDFs (PDF/A-2A + PDF/UA-1) from markdown or a compact DSL - fast, no headless browser.
Scored across 11 tools
Each tool has a distinct input/action: template CRUD (delete/get/list/save/update), validation (validate_dsl/validate_markdown), and rendering (render_dsl_preview for inline DSL, render_template for saved IDs, render_markdown for markdown). The free-vs-billed preview/render boundary is explicitly documented, preventing misselection between the render tools. report_feedback is a clearly separate meta-tool.
Every tool follows a consistent snake_case verb_noun or verb_noun_modifier pattern (delete_template, list_templates, render_markdown, validate_dsl). No camelCase or mixed conventions. The render_* and validate_* prefixes group related tools predictably.
11 tools is well-scoped for a PDF/template rendering service with CRUD, rendering, validation, and feedback. Each tool earns its place and none appear redundant; the count sits comfortably in the ideal 3-15 range.
Full template lifecycle (create/read/list/update/delete) plus render, preview, and validation for both DSL and markdown are covered. Minor gaps: no tool to retrieve or list previously generated artifacts by artifactId, and no render history, though PDFs are returned inline so impact is limited.
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. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses the billed nature, credit consumption rate, watermark on free plans, PDF output format, JSON metadata return, base64 PDF resource, and API endpoint mirror. This is comprehensive and leaves no critical behavior unstated.
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 information-dense and well structured, leading with the core function, then billing, then output, then validation guidance. It is slightly repetitive in places (mentions credits and validation more than once) but every sentence adds useful information for an agent deciding whether and how to call the 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 tool has a nested options object, no output schema, and no annotations, the description provides all essential context: what it produces, how it bills, how to validate first, what metadata is returned, and how it relates to sibling tools. An agent has enough information to call it correctly and interpret the result.
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 covers markdown and options with descriptions, and the description adds valuable context such as the 200-character limit, optional metadata usage, and fallback to YAML frontmatter for omitted options. It does not need to repeat every field because the input schema is already well-described, but the added context raises it above the baseline.
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 tool renders GitHub-flavored markdown to a tagged PDF/A-2A + PDF/UA-1, and explicitly distinguishes itself from preview/template tools by noting there is no free preview and that it is the only markdown render tool. This gives an agent a precise understanding of when to use it.
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 direct usage guidance: run validate_markdown first to catch issues before paying, notes the billing/credit model, explains watermark behavior on free plans, and contrasts with render_dsl_preview/render_template. The agent knows exactly how to proceed and when to avoid this tool.
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. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. The term 'Validate' and the phrase 'Cheap — no rendering' strongly imply a read-only analysis with no side effects, though it does not explicitly state that no data is modified. This is sufficient for a validation tool.
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 and well-structured, covering the action, target, specific checks, a cost/behavior hint, and an API mirror reference in two sentences. No redundant information is present.
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 validation tool with a single parameter and no output schema, the description is complete. It mentions the API endpoint for traceability and gives a hint about performance, which is sufficient context for an agent to decide 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 schema description coverage is 100% for the single parameter, and it already specifies 'GitHub-flavored markdown source.' The tool description does not need to add further parameter details, so a baseline score of 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?
The description clearly states the verb (Validate), the resource (a markdown document), and the specific checks performed (PDF/UA-1 accessibility issues: heading hierarchy, missing alt text). It also distinguishes the tool by noting it is cheap and does not render, which helps differentiate from sibling template-management tools.
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 usage guidance by explicitly stating it is cheap and does no rendering, implying it should be used for quick validation without rendering overhead. While it does not name alternative tools for when not to use it, the context of siblings (template operations) makes the intended use clear.
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.
report_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.
