This server provides MCP tools to manage Wraft documents, templates, and approval flows via the Wraft REST API. Key capabilities:
Documents: Create from templates (preferred) or raw markdown, update, list/filter, retrieve, build PDFs, and transition approval states.
Templates & Content Types: Create data templates from markdown with placeholders, list/retrieve templates, list content types (e.g., NDA, Offer Letter) to inspect fields.
Approval Flows: List flows, get flow details, list flow states, and move documents through workflows.
Identity: Verify API key via whoami to get user, email, organization, roles.
Operational: Pagination on all list tools; field machine names are lowercased with spaces to underscores and stripped special chars. Write operations are not idempotent: check before retrying timed-out calls. Supports stdio and Streamable HTTP.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@wraft-mcp Create a document from the 'Project Proposal' template."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
The mcp server for Wraft, the open-source document lifecycle platform. It gives Cursor, Claude Code, Claude Desktop, and any other MCP client a curated tool set for running the document lifecycle end to end:
Scaffold the pipeline — create themes, layouts, approval flows, and content types (variants) with their fillable fields
Author templates — write a document body in markdown; [Field Name] placeholders become fillable fields
Produce documents — fill a template with values, build the PDF, and move the document through its approval flow
Automate — wire adaptor steps (build document, email, HTTP, conditions) into workflow DAGs with conditional edges
One shared tool set, two ways to run it:
stdio (wraft-mcp) — your MCP client spawns the server locally; auth via env vars
Streamable HTTP (wraft-mcp-http) — a hosted, stateless service at /mcp; auth via per-request x-api-key header
Local (stdio) — recommended for individuals. Add to your MCP client config:
{
"mcpServers": {
"wraft": {
"command": "npx",
"args": ["-y", "wraft-mcp@0"],
"env": {
"WRAFT_BASE_URL": "https://app.your-wraft.example",
"WRAFT_API_KEY": "wraft_..."
}
}
}
}Remote (hosted HTTP):
{
"mcpServers": {
"wraft": {
"url": "https://mcp.your-domain.example/mcp",
"headers": { "x-api-key": "wraft_..." }
}
}
}Client timeouts: build_document can run up to 120 s. Raise your MCP client's tool-call timeout accordingly (Cursor: "timeout" per server entry) or builds will appear to fail while still completing server-side.
During development (before npm publish): "command": "node", "args": ["/ABS/PATH/wraft-mcp/dist/index.cjs"].
Related MCP server: fallengineer-us-mcp
Tool | What it does |
| Documents in the organisation |
| Preferred create path: fills a template's placeholders from a field-values map and creates the document |
| Raw-payload create (escape hatch) |
| Update content (creates a version) |
| Generate the PDF (synchronous, up to ~2 min) |
| Move a document through its approval flow |
| Pre-authored templates with fillable fields |
| Author a template from markdown — |
Tool | What it does |
| Content types (document variants) with their fields |
| Create a variant with fields, wired to a layout, flow, and theme |
| Field types (String, Text, Date, …) for |
| Approval flows and their states |
| Create a flow (default Draft → Publish states; custom states/approvers need the Wraft UI) |
| Themes: font + colors (font-file assets must pre-exist; pass ids) |
| Layouts: engine, page-template slug ( |
| Uploaded assets by type (theme fonts, layout letterheads) — source of ids for |
| Automation workflows (DAGs of adaptor steps) and their full structure |
| Create a workflow: steps (adaptor + config, referenced by key) connected by edges; triggers need the Wraft UI |
| Run a workflow with trigger data and get per-step results (synchronous) |
| Run history and per-step results of a run |
| Verify the key: user, email, organisation, roles |
Pagination: list_* tools accept page and return page_number / total_pages / total_entries — paginate before concluding something doesn't exist. Exceptions: list_flow_states and list_field_types return plain arrays.
Field machine names: create_document_from_template takes fields keyed by machine name — the field's name lowercased, apostrophes stripped, spaces → _, other characters removed ("Client Name" → client_name). Get field names from get_data_template (under content_type.fields).
Writes are not idempotent: a timed-out create_* or build_document call may still have completed. List or fetch before retrying — a blind retry creates a duplicate.
No update/delete for scaffolding: themes, layouts, flows, content types, and workflows can be created but not modified or removed via MCP — clean up mistakes in the Wraft web UI. Workflow triggers also need the UI (execution is available via execute_workflow).
Keys are unscoped. A Wraft API key carries its owner's full role permissions — the curated tool list limits what the agent can reach, not what the credential could do elsewhere. Create a dedicated least-privilege user for MCP keys.
IP-whitelisted keys don't work via the hosted server. Wraft sees the MCP server's IP, not yours, so whitelisted keys get 403 ip_not_whitelisted. Use a key without an IP whitelist for hosted access, or run stdio from an allowed machine. Do not whitelist the MCP server's egress IP — that nullifies the control for everyone behind the proxy.
Keys are never logged by this server; redaction of x-api-key / authorization must also be configured in any logging/APM middleware added around it.
See deploy/README.md — Docker image, env reference, ready-made compose + nginx edge, and the hosting checklist.
npm install
npm test # unit tests
npm run typecheck
npm run build # dist/index.cjs (stdio) + dist/http.cjs (HTTP)
# live smoke against a running Wraft (runs whoami by default; exits non-zero on tool errors):
WRAFT_BASE_URL=http://localhost:4000 WRAFT_API_KEY=wraft_... npm run smoke
# or pass tool calls:
node scripts/smoke.mjs dist/index.cjs '{"name":"list_flows","arguments":{}}'
# optional pre-push gate (typecheck + tests + build before every push):
git config core.hooksPath .githooksAGPL-3.0-only — see LICENSE.md.
Generate the document's PDF. Runs synchronously and can take up to two minutes — do not retry a timed-out build without checking get_document first (the build may have completed; retrying creates another build version). Fails with 422 if the document is locked (approval flow complete).
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Document id (UUID) | |
| naration | No | Optional name for the build version |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It discloses synchronous execution, two-minute runtime, the side effect of creating another build version on retry, and a specific error scenario (422 when locked). This is rich, non-obvious behavioral information.
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 concise sentences front-load the core purpose, then pack crucial operational warnings (retry behavior, error condition) without fluff. 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?
Given the tool's complexity (long-running, possible timeouts, side effects) and lack of output schema, the description covers all critical aspects: synchronous nature, duration, retry policy, side effect of duplicate builds, and failure mode. It is exceptionally complete for a build operation.
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 has 100% coverage for both parameters (id and naration). The description does not add any parameter-specific semantics beyond what is in the schema, so 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?
The description opens with 'Generate the document's PDF' – a specific verb and object that immediately conveys the tool's function. This clearly distinguishes it from siblings like get_document (retrieval) and update_document (modification).
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?
Provides explicit guidance on when NOT to retry (after timeout) and tells the agent to check get_document first. Also mentions the 422 failure condition related to locked documents, giving actionable context for choosing this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Author a new data template for a content type from markdown. Write [Field Name] placeholders in the body and title_template — they become fillable holder fields, and MUST match the content type's field names (see list_content_types). Supported markdown: #-###### headings, paragraphs, - bullets, 1. numbered lists, > quotes, ---, bold, italic. The result reports any placeholders that didn't match a field (left as plain text) — fix and recreate if needed. NOT idempotent.
| Name | Required | Description | Default |
|---|---|---|---|
| title | Yes | Template display title | |
| body_markdown | Yes | Template body as markdown with [Field Name] placeholders | |
| title_template | No | Document title pattern with [Field] placeholders, e.g. "Letter of Intent — [Company Name]". Defaults to title. | |
| content_type_id | Yes | Content type id (UUID) whose fields the placeholders map to |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully bears the transparency burden. It discloses that placeholders become fillable fields, must match content type fields, supported markdown syntax, reports unmatched placeholders, and explicitly states 'NOT idempotent.' This goes beyond basic purpose and informs the agent of validation and side effects.
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 sentences, each serving a distinct purpose: stating the tool's function, explaining placeholder usage, listing supported markdown, and warning about non-idempotency. It is front-loaded and contains no fluff, making it efficiently structured despite its length.
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 create operation with no output schema and no annotations, the description covers prerequisites (field name matching), input format (markdown), behavior (validation and reporting), and side effects (non-idempotency). This is sufficient for an agent to invoke the tool correctly and reason about outcomes.
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 input schema already covers all parameters with descriptions (100% coverage), so baseline is 3. The description adds semantic meaning by explaining how [Field Name] placeholders work in both body and title_template, and that they must match content type fields, which enhances understanding beyond the schema.
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 starts with 'Author a new data template for a content type from markdown,' which uses a specific verb and resource, clearly distinguishing it from sibling tools like create_document or create_document_from_template. The focus on authoring a template rather than a document is explicit.
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 instructs users to see list_content_types for field name matching, which implies a prerequisite and workflow. It also warns about non-idempotency and the need to fix and recreate if placeholders don't match. However, it does not explicitly name alternative tools or state when not to use it, leaving some ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a document from a raw payload (escape hatch — prefer create_document_from_template). serialized must be an object: {title, body (markdown), serialized (JSON-encoded ProseMirror doc), fields (JSON-encoded field-values map)}. NOT idempotent: if the call times out, the document may still have been created — list_documents before retrying.
| Name | Required | Description | Default |
|---|---|---|---|
| raw | Yes | Document body as markdown | |
| meta | No | Optional document metadata | |
| vendor_id | No | Optional vendor id (UUID) | |
| serialized | Yes | Serialized content: {title, body, serialized: '<ProseMirror JSON string>', fields: '<field-values JSON string>'} | |
| content_type_id | Yes | Content type id (UUID) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It explicitly states 'NOT idempotent' and explains the timeout scenario, which is critical behavioral information for a create operation. However, it does not mention return values, error handling, or permissions, which would enhance transparency further.
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: a single sentence establishes purpose and alternative, followed by a compact payload specification and a crucial idempotency warning. Every sentence serves a distinct purpose with no 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?
Despite having no output schema, the description covers the complex nested payload format and the non-idempotency caveat, which are the most contextually important aspects for safe usage. It doesn't explain return values or other parameters, but the schema covers those, and the description focuses on what the agent must know to avoid mistakes.
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 input schema already covers all parameters with 100% description coverage, earning a baseline of 3. The description adds value by detailing the required structure of the 'serialized' parameter as an object with nested fields, and clarifying that 'raw' is markdown. This goes beyond the schema's generic 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?
The description clearly states the tool creates a document from a raw payload, using a specific verb ('Create') and resource ('document'). It distinguishes itself from the sibling tool by explicitly labeling itself an 'escape hatch' and preferring create_document_from_template, making the tool's 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 provides explicit usage guidance: 'prefer create_document_from_template' indicates when this tool should not be used, and the warning about non-idempotency with a suggestion to list_documents before retrying gives clear operational instructions. This is exemplary guidance for an alternative tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
PREFERRED way to create a document: fills a data template's placeholder fields and creates the document in one step. Get field machine names from get_data_template (content_type.fields → lowercase name, spaces to underscores, e.g. "Client Name" → client_name). NOT idempotent: if the call times out, the document may still have been created — list_documents before retrying.
| Name | Required | Description | Default |
|---|---|---|---|
| meta | No | Optional document metadata (contract content types: start_date, expiry_date, contract_value) | |
| title | No | Optional title override; defaults to the template's title_template with [Field] placeholders filled | |
| fields | Yes | Field values keyed by machine name, e.g. {"client_name": "Acme Corp", "effective_date": "2026-08-02"} | |
| data_template_id | Yes | Data template id (UUID) — see list_data_templates |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and discloses a critical behavioral trait: the tool is NOT idempotent and may have created the document even if the call times out, advising to list_documents before retrying. This is valuable and goes beyond a generic description, but it does not cover other potential behaviors like auth requirements, rate limits, or return format, so it is not a 5.
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 three sentences, each earning its place: the first states the core purpose, the second gives essential field-naming instructions, and the third provides a critical idempotency warning. It is front-loaded with the main purpose and contains no fluff 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 creation tool with 4 parameters, nested objects, and no output schema, the description covers the core workflow: filling placeholders, getting machine names, and cautioning about non-idempotency. It lacks an explicit statement about return values, but given the absence of an output schema and the tool's complexity, it is reasonably complete. It does not fully anticipate all edge cases but is strong overall.
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 meaningful semantics by explaining how to derive field machine names (lowercase, underscores, from get_data_template) and gives a concrete example for fields. This exceeds the schema's generic example, but it does not explain meta or title properties beyond what the schema already provides, so not a 5.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool creates a document by filling a data template's placeholder fields, naming a specific verb and resource. It positions itself as the 'PREFERRED way' to create a document, which implies distinction from siblings, but it does not explicitly name alternatives like create_document or build_document, so it stops short of a 5.
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 usage context: it is the preferred one-step template-based creation method, and it gives explicit instructions to obtain field machine names from get_data_template. It also warns about non-idempotency and suggests listing documents before retrying. However, it does not explicitly state when not to use this tool or name alternative tools, missing the 'when-not/alternatives' bar for a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get one data template with its content type and fields. The content_type.fields list gives each field's name; the machine name for create_document_from_template is the lowercased name with spaces as underscores and other characters stripped (e.g. "Client Name" → client_name).
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Data template id (UUID) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden. It discloses that the response includes content_type.fields, and adds the machine-name transformation rule—useful behavior. It doesn't mention retrievability or permissions, but for a read tool it gives meaningful context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no filler. The first states the purpose, the second adds a valuable transformation detail. Every word 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 simple read with one parameter and no output schema, the description is complete enough: it describes the return contents and offers a naming rule relevant to a sibling tool. It lacks edge-case warnings, but those aren't critical here.
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 id parameter is fully described in the schema ('Data template id (UUID)'), and the description doesn't add parameter-specific detail. Schema coverage is 100%, so 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?
The description states a specific verb ('Get') and resource ('one data template') and specifies what's included ('content type and fields'). It clearly distinguishes from sibling list_data_templates by indicating 'one' vs. a list.
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 use when you need details of a single template and provides a transformation tip relevant for create_document_from_template. It doesn't explicitly state alternatives or exclusions, but the context is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get one document with its content, content type, state, versions, and approval systems.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Document id (UUID) |
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 discloses the returned fields but does not explicitly state read-only behavior, permission requirements, or error handling. The 'get' verb implies read-only, but the description does not elaborate beyond that.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that efficiently captures the tool's purpose and key return values with no 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?
For a simple get-by-id tool with one parameter and no output schema, the description covers the main return data (content, content type, state, versions, approval systems). It does not mention error conditions or pagination, but these are less critical for a single-document fetch, making it largely complete.
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% for the single parameter 'id', which is already described as a UUID. The description adds no additional parameter guidance, so the baseline 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 it retrieves a single document by ID and specifies the key returned attributes (content, content type, state, versions, approval systems). This distinguishes it from siblings like list_documents and update_document.
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 fetching one specific document, contrasting with list_documents. However, it does not explicitly name alternatives or state when not to use it, though the context is clear for a get-by-id operation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get one flow with its states.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Flow id (UUID) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of disclosing behavior. It indicates a read operation ('get') but does not specify what happens if the id is not found, the structure of the response, or whether states are nested or referenced. This is a significant gap for a tool with no output schema.
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 a single, concise sentence that directly conveys the tool's function. It is not bloated, but it is also terse. It earns its place without unnecessary 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?
This is a simple single-id retrieval tool, but the description is incomplete. There is no output schema and no info about error handling, response format, or how 'states' are presented. Given the sibling tools, explicitly mentioning that states are bundled and that this is for a single flow would enhance completeness, but it does not.
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%: the only parameter 'id' is documented with 'Flow id (UUID)'. The description adds no extra meaning about how the id is used or formatted, 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?
The description 'Get one flow with its states' clearly identifies the action (get) and resource (one flow) while adding that states are included. This distinguishes it from sibling tools like list_flows (which lists flows) and list_flow_states (which likely lists states separately), though it does not explicitly name alternatives.
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 guidance is provided on when to use this tool versus alternatives like list_flows or list_flow_states. The description implies it is for retrieving a single flow with states, but there is no explicit when-to-use or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List Wraft content types (document variants such as NDA, Offer Letter). Each includes its fields (name, type, required) — field names determine the machine names used by create_document_from_template. Paginated.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | Filter by content type name | |
| page | No | Page number (responses are paginated; check page_number/total_pages/total_entries in the result and paginate past page one when searching) | |
| sort | No | Sort: name | name_desc | inserted_at | inserted_at_desc |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses pagination behavior ('Paginated.'), describes the response shape ('Each includes its fields (name, type, required)'), and highlights a downstream implication (field names feed create_document_from_template). This is valuable context beyond a simple 'list' statement, though it omits details like default page size or rate limits.
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 extremely concise, using two sentences plus a one-word fragment. It front-loads the purpose, then adds response details and a practical note, with no fluff or redundant information.
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 list tool with no output schema, the description covers the essential aspects: what it lists, what each item contains, how the output is used elsewhere, and pagination. It is sufficiently complete, though it could mention the output format's page fields, but those are already documented in the schema parameter description.
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 parameters are fully documented there. The tool description adds no additional meaning about parameters, only restating the pagination behavior already captured in the schema's 'page' parameter description. This meets the baseline of 3 but does not exceed it.
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's action ('List Wraft content types') and gives concrete examples ('NDA, Offer Letter'). It provides a specific verb+resource but does not explicitly differentiate from the sibling tool 'list_data_templates', relying on the parenthetical 'document variants' to hint at distinction.
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 when to use the tool by noting that field names 'determine the machine names used by create_document_from_template', which suggests using it when preparing to create documents. However, it does not explicitly state 'use this instead of X' or provide exclusions, making the guidance indirect rather than direct.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List Wraft data templates (pre-authored document bodies with fillable placeholder fields). Use a template id with get_data_template or create_document_from_template. Paginated.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number (responses are paginated; check page_number/total_pages/total_entries in the result and paginate past page one when searching) | |
| title | No | Filter by template title |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description is the only source of behavioral context. It discloses pagination and that templates are reusable pre-authored bodies. However, it does not describe ordering, filter matching behavior, authentication requirements, or what fields will be present in the response beyond what the schema already mentions.
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 a compact two-sentence structure that front-loads the action, defines the resource, gives downstream guidance, and notes pagination. Every clause earns its place and there is no redundant or filler content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a straightforward list tool with optional pagination and title filter, the description covers purpose, template semantics, downstream use, and pagination. It does not describe the return shape (no output schema) or filter matching semantics in detail, but the schema provides pagination response fields, and the tool's simplicity makes the description reasonably complete.
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%: both `page` and `title` are already described with useful detail. The description adds only the 'Paginated' note, which is already echoed in the `page` parameter description. Since the schema carries the parameter explanation, the description adds no additional semantic value.
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 the specific verb 'List' with a clear resource, 'Wraft data templates', and adds a parenthetical definition ('pre-authored document bodies with fillable placeholder fields') that clarifies what is being listed. It also distinguishes this from related get/create tools by mentioning how template ids are used downstream, making the purpose unmistakable.
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 downstream usage: 'Use a template id with get_data_template or create_document_from_template.' This implies this tool is for discovering template ids. It does not explicitly exclude alternatives like list_content_types or say 'use this when you need a template', but the guidance is helpful enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List documents (content instances) in the organisation. Paginated — check total_pages and paginate before concluding a document doesn't exist.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number (responses are paginated; check page_number/total_pages/total_entries in the result and paginate past page one when searching) | |
| sort | No | Sort: instance_id | instance_id_desc | inserted_at | inserted_at_desc | expiry_date | expiry_date_desc | |
| state | No | Filter by state name | |
| instance_id | No | Filter by human-readable instance id (e.g. NDA0001) | |
| content_type_name | No | Filter by content type name | |
| document_instance_title | No | Filter by title |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of behavioral disclosure. It discloses the critical pagination requirement, which goes beyond a simple 'list' statement. However, it does not mention side effects, return format, or permissions, though the read-only nature is implicit.
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 concise sentences, front-loaded with the primary purpose and followed by a precise pagination warning. No filler or redundant text.
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's simplicity and full schema parameter coverage, the description is mostly complete. It supplements the schema with a key pagination warning and hints at the response structure (total_pages). Lack of an explicit output schema is mitigated by the page parameter description, though return fields are not fully specified.
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 input schema provides 100% coverage with descriptive parameter docs. The description adds the pagination context which partially overlaps with the page parameter description, but does not add new meaning for other parameters. Baseline 3 applies due to full schema coverage.
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 'List documents (content instances) in the organisation', using a specific verb and resource. This distinguishes it from sibling tools like get_document, which fetches a single document, and other list 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 advises paginating via total_pages before concluding a document doesn't exist, providing important usage context. However, it does not explicitly state when to use this tool versus alternatives like get_document or list_content_types, leaving the selection partially implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List Wraft approval flows. Paginated.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | Filter by flow name | |
| page | No | Page number (responses are paginated; check page_number/total_pages/total_entries in the result and paginate past page one when searching) | |
| sort | No | Sort: name | name_desc | inserted_at | inserted_at_desc | updated_at | updated_at_desc |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of disclosing behavior. It mentions pagination, a useful behavioral trait, but does not disclose additional traits such as read-only nature, authentication requirements, or return structure. For a simple list tool, this is modest but acceptable disclosure.
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 two short sentences with no redundancy. 'List Wraft approval flows. Paginated.' is clear, front-loaded, and every word 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 simple list tool with well-documented parameters, the description is nearly complete. It states the core action and pagination. The schema covers pagination mechanics. Without an output schema, a bit more detail about the return payload could improve completeness, but it is not necessary 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?
Schema description coverage is 100%, so the parameter descriptions already fully document each parameter. The tool description adds no additional semantic value beyond what the schema provides, warranting the baseline score of 3.
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 'List Wraft approval flows' uses a specific verb and resource, clearly identifying the tool as listing flows. It distinguishes from siblings like list_flow_states (which lists states) and get_flow (which fetches a single flow).
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: if you need to list approval flows, use this tool. However, it provides no explicit guidance on when not to use it, no alternatives are mentioned, and there is no differentiation from sibling list tools beyond the resource name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the states of a flow in order (returns a plain array, not paginated). Use a state's id with transition_document_state. Note: states can carry approver requirements — a transition may be rejected if the API key's user is not an eligible approver.
| Name | Required | Description | Default |
|---|---|---|---|
| flow_id | Yes | Flow id (UUID) |
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 discloses that the result is a plain array (not paginated), that states are returned in order, and that approver requirements may cause transitions to be rejected. This goes beyond the schema, though it doesn't cover error handling or authentication.
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 two sentences, front-loaded with the core action, and the approver note adds valuable context. Every sentence serves a purpose, with no 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?
For a one-parameter tool without an output schema, the description covers purpose, return shape (array, not paginated), ordering, and a relevant downstream limitation. It does not enumerate the state object's fields, but the mention of a state's id implies the necessary structure. Overall sufficiently complete.
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% because flow_id is documented as 'Flow id (UUID)'. The description adds no further parameter semantics, so the baseline score 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?
The description uses a specific verb ('List'), resource ('states of a flow'), and scoping ('in order'). It clearly distinguishes from sibling tools like list_flows and transition_document_state by focusing on flow states and hinting at a downstream use for the state IDs.
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 by noting the return format (plain array, not paginated) and directing the agent to use a state's id with transition_document_state. It does not explicitly exclude alternatives, but this guidance is enough for appropriate selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Move a document to another state in its flow. Get valid state ids from list_flow_states (the document's flow is on its content type). Transitions may be rejected if the flow requires an approver the API key's user is not.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Document id (UUID) | |
| state_id | Yes | Target state id (UUID) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It discloses a key rejection condition ('Transitions may be rejected if the flow requires an approver the API key's user is not'), which is valuable. However, it does not describe success behavior, return values, or validation details, leaving some ambiguity.
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 three sentences, each earning its place: the primary action, where to get valid inputs, and a critical failure condition. It is front-loaded with the core purpose and contains 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 tool with two parameters and no output schema, the description covers purpose, input sourcing, and a key error condition. It is sufficiently complete for an agent to select and invoke the tool correctly, though it omits any details about the success response or the exact transition rules.
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 both parameters with descriptions and 100% coverage. The description adds meaningful context for state_id by instructing where to obtain valid values (list_flow_states), which goes beyond the schema's generic 'Target state id' and directly aids correct invocation.
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's function with a specific verb and resource: 'Move a document to another state in its flow.' This distinguishes it from sibling tools like get_document (read) and update_document (content update), and it explicitly relates to flow states.
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 usage context by directing the user to list_flow_states for valid state IDs and linking the flow to the content type. It does not explicitly exclude alternative tools, but the instruction to get states from the sibling tool implies the proper workflow. The mention of potential rejection due to approver permissions also gives situational awareness.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update a document's content. serialized has the same object shape as create_document. Fails if the document is no longer editable (approval flow complete). Metadata is NOT updated here. NOT idempotent: if the call times out, the document may still have been created — list_documents before retrying.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Document id (UUID) | |
| raw | Yes | Document body as markdown | |
| naration | No | Optional version note stored with the saved revision | |
| vendor_id | No | Optional vendor id (UUID) | |
| serialized | Yes | Serialized content object |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and excels: discloses failure condition (approval flow complete), non-idempotency, timeout behavior, and a safe retry strategy. This goes beyond typical mutation descriptions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four sentences, all dense with relevant information. Front-loaded with purpose, followed by critical caveats. No 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?
For a mutation tool with no output schema and 5 parameters, the description covers failure modes, idempotency, scope, and references a sibling for complex parameter shape. It does not mention return value, but this is a minor gap given the strong behavioral coverage.
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 value by noting that 'serialized has the same object shape as create_document', giving cross-tool semantic context not present in the schema itself, which justifies one point above 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 opens with 'Update a document's content' – a specific verb and resource with clear scope. It distinguishes from siblings like create_document by stating 'Metadata is NOT updated here' and referencing the serialized shape relative to create_document, making the tool's 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?
Provides clear context: for content updates only, not metadata. Warns about non-idempotency and advises listing documents before retrying. Does not explicitly name alternative tools for metadata updates, but the exclusion is clear enough given sibling names like transition_document_state.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the current user for the configured API key (name, email, organisation, roles). Use to verify connectivity and see which organisation the key operates on.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must convey behavioral traits. The word 'Get' implies a read-only operation, but the description does not explicitly confirm lack of side effects, error behavior, or response structure. This is acceptable for a simple tool but leaves room for ambiguity.
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 two sentences, front-loaded with the action, and contains no redundant or extraneous information. Every word adds value.
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, parameterless tool with no output schema, the description covers the essential purpose and use cases. It could mention the return format more explicitly, but the information provided is sufficient for basic understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and schema coverage is 100% (empty object). The description has no parameters to explain, so the baseline of 4 applies. It does not add param-specific details, but none are needed.
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's function with a specific verb ('Get') and resource ('current user for the configured API key'), including the exact data returned (name, email, organisation, roles). It distinguishes itself from sibling tools that focus on document and content 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?
The description gives explicit use cases: 'verify connectivity and see which organisation the key operates on.' While it doesn't mention alternatives, there are no close siblings for user identity, so the guidance is adequate.
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.
v0.1.0build_documentcreate_data_templatecreate_documentcreate_document_from_templateget_data_templateget_documentget_flowlist_content_typeslist_data_templateslist_documentslist_flow_stateslist_flowstransition_document_stateupdate_documentwhoamiScored across 15 tools
Most tools target distinct resources and actions (documents, templates, flows, content types), with clear verb-prefixed names. The main potential confusion is between create_document_from_template and create_document, and between get_flow and list_flow_states, but the descriptions clarify their respective purposes well.
The majority follow a consistent verb_noun pattern: get_, list_, create_, update_, build_, transition_. The only outlier is 'whoami', a common utility convention, so it doesn't disrupt overall readability.
With 15 tools, the server sits at the upper end of the ideal range but every tool serves a distinct necessary function for document management, template authoring, and approval flows. No redundant or superfluous tools are present.
Core document lifecycle is covered: create (two ways), read, update, build PDF, and transition states. Missing delete operations for documents/templates and an update for data templates are minor gaps that agents can work around, but they don't prevent primary workflows.
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
MCP server for AI agents to plan, verify, and deploy Cloudflare-native apps.
MCP server for secureFlows: token-free URL builders and integration-linting tools for AI agents.
DocBase MCP server for AI agents
