This server gives MCP-compatible assistants Carve's parser, linter, formatter, and renderers for authoring, reviewing, converting, and safely patching Carve documents.
Lint and diagnose: carve_lint returns structured warnings; carve_diagnose_and_fix previews/applies safe fixes with undo patches.
Format and render: carve_format canonicalizes Carve; carve_render outputs HTML, Markdown, plain text, or ANSI with loss reporting.
Compare publishing targets: carve_check_targets checks compatibility across HTML, Markdown, plain text, ANSI, GitHub, WordPress, and PDF-stage profiles.
Parse and inspect: carve_parse returns a position-aware interchange AST; carve_select_ast_nodes finds headings, footnotes, node types, or AST paths.
Patch ASTs: create, apply, preview, and reverse position-independent AST patches, including stale-edit fingerprints and guarded source edits.
Plan edits: carve_plan_ast_edit turns semantic matches and edit intents into explained reversible source patches.
Migrate content: carve_migrate converts HTML, Markdown, Djot, or BBCode to Carve with fidelity reports.
Index references: carve_reference_graph indexes headings, footnotes, links, and images, detects broken edges and orphaned definitions when workspace access is enabled.
Guides and rules: exposes carve://guide, carve://rules, and rule/lint-name lookup resources.
Profile tool surfaces: use --tool-profile review, convert, structure, or workspace to expose only relevant tools.
Safety defaults: no filesystem access unless a workspace root is configured; raw HTML passthrough is disabled by default.
Allows migration of Markdown documents to Carve with fidelity diagnostics and rendering of Carve documents as Markdown.
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., "@carve-mcp Lint this Carve document: ::heading[Welcome]"
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.
Give MCP-compatible assistants the same Carve parser, linter, formatter, and renderers used by the JavaScript implementation. Filesystem access is absent by default and can be enabled for explicitly configured document roots.
carve_lint checks a document and returns precise, structured warnings.
carve_diagnose_and_fix previews safe fixes, applies selected fix IDs, and returns an undo patch; ambiguous repairs remain writer-review items.
carve_format produces canonical Carve and reports rendering losses.
carve_render renders HTML, Markdown, plain text, or ANSI.
carve_check_targets compares publishing compatibility across HTML, Markdown, plain text, ANSI, GitHub, WordPress, and PDF-stage profiles.
carve_parse returns the resolved, position-aware interchange AST.
carve_create_ast_patch compares two interchange ASTs and returns a
position-independent patch.
carve_apply_ast_patch validates and previews a patch as both an AST and
canonical Carve source without changing files.
carve_select_ast_nodes finds headings, footnotes, node types, or a current
AST path without making an ambiguous selection for the caller.
carve_plan_ast_edit turns one or more exact semantic matches and small edit
intents into one explained, reversible source patch for approval.
carve_create_reversible_ast_patch adds inverse operations and semantic
stale-edit fingerprints.
carve_apply_reversible_ast_patch safely previews forward or undo operations
as a guarded UTF-8 source edit.
carve_migrate converts HTML, Markdown, Djot, or BBCode and reports version 2 migration fidelity.
carve_reference_graph indexes cross-document headings, footnotes, abbreviations, links, and images, including broken edges and orphaned definitions (when workspace access is enabled).
Tools return concise text for readers alongside schema-validated structured results for clients. Six optional prompts guide common review, conversion, and publishing workflows without replacing the writer's judgment.
Use --tool-profile review, convert, structure, or workspace to expose
only the tools needed for that job and reduce model context. The default all
profile preserves the complete tool surface.
Raw HTML passthrough is disabled by default because MCP inputs are untrusted.
The server has no filesystem access unless you explicitly give it a workspace
root. That also governs {{ path }} includes, which stay literal until a call
names a configured root. See Include expansion.
Related MCP server: document-mcp
carve://guide is a concise authoring quick start.
carve://rules explains the normative rule categories.
carve://rules/{ruleId} looks up a stable normative CARVE-* rule ID, such as
carve://rules/CARVE-P0-001.
carve://lint-rules/{ruleName} explains a stable diagnostic name returned by
carve_lint.
The resources identify the Carve version and link to the complete documentation
when a reader needs normative detail. Lint diagnostic names are a separate
namespace and are returned with their explanations directly by carve_lint.
Node.js 20 or newer is required.
npx -y @markup-carve/carve-mcpSee Connect Carve to your writing tool for copy-ready setup in Claude, VS Code, Cursor, Zed, and Codex, plus prompts to confirm it works. The compatibility page explains what CI verifies and provides the short host smoke test used for releases.
The writer workflows show practical review, conversion, preview, GitHub publishing, and documentation-folder tasks.
For local builds, workspace access, native binaries, HTTP and container deployment, and contributor checks, see Development and deployment.
This project is licensed under the MIT License.
Validate and apply structured operations to a PART 12 Carve AST, returning the patched AST and canonical Carve source.
| Name | Required | Description | Default |
|---|---|---|---|
| ast | Yes | PART 12 base AST (maximum 1000000 JSON bytes) | |
| operations | Yes | Structured patch operations (maximum 1000 operations and 1000000 JSON bytes) |
| Name | Required | Description |
|---|---|---|
| ast | Yes | |
| source | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already communicate read-only and non-destructive behavior, and the description adds useful context: the operation validates before applying, produces a patched AST, and emits canonical Carve source. This goes beyond the structured fields. readOnlyHint is consistent with an in-memory transformation, so there is no contradiction.
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 one tight, front-loaded sentence covering the action, input resource, and output. Every phrase contributes meaning, with no filler or redundant elaboration.
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, combined with the annotations and output schema, gives enough context to invoke the tool correctly. It explains validation, application, and result. The main gap is not explaining how operations are produced or when to use the reversible variant, but this is partially recoverable from sibling names.
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 both ast and operations have descriptions. The description mostly restates those concepts ('structured operations', 'PART 12 Carve AST') without adding deeper meaning about operation shapes or expected AST structure, 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 uses specific language: 'Validate and apply structured operations to a PART 12 Carve AST' and states the return value ('patched AST and canonical Carve source'). This clearly distinguishes it from sibling tools like carve_create_ast_patch, which creates patches, and carve_apply_reversible_ast_patch, which applies reversible patches.
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 the tool is used when you already have a PART 12 AST and structured operations to apply. However, it does not explicitly state when to choose this over the reversible or create-patch sibling tools, nor does it name alternatives or exclusion conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Verify a reversible AST patch against source, apply or undo it, and return a minimal stale-guarded UTF-8 source edit without writing files.
| Name | Required | Description | Default |
|---|---|---|---|
| patch | Yes | Version 1 reversible AST patch (maximum 1000000 JSON bytes and 1000 operations per direction) | |
| source | Yes | Document source (maximum 1000000 UTF-8 bytes) | |
| inverse | No | Apply inverse operations to undo the patch. |
| Name | Required | Description |
|---|---|---|
| ast | Yes | |
| source | Yes | |
| direction | Yes | |
| sourcePatch | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds meaningful behavioral details: it is stale-guarded, returns a minimal UTF-8 source edit, and does not write files. This goes beyond the structured annotations and clarifies that 'apply or undo' is non-destructive.
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 entire description is a single front-loaded sentence that packs purpose, behavior, and key constraints without wasted words. Every element ('verify', 'apply or undo', 'minimal stale-guarded UTF-8', 'without writing files') 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 tool with three parameters, nested patch schema, output schema, and strong annotations, the description is nearly complete. It covers the non-obvious behavioral contract (no file writes, stale guard, undo support). It lacks only explicit routing against siblings like carve_apply_ast_patch, which is somewhat mitigated by the reversible/non-writing language.
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 source, patch, and inverse are already fully described in the schema. The description reinforces the reversible-patch context but adds no parameter-specific meaning beyond the schema, matching the baseline of 3 for high 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 states a specific verb-resource relationship: verify or apply/undo a reversible AST patch and return a source edit. It explicitly notes that no files are written, which distinguishes it from the likely file-writing sibling carve_apply_ast_patch. The reversible nature and undo capability make its role 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 clear usage context: to verify and safely apply or undo a reversible patch without persisting changes. It implies when this tool is appropriate, but it does not explicitly name alternatives or state when not to use it. This is clear context without exclusions, so it earns a 4.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Compare one Carve document across HTML, Markdown, plain text, ANSI, GitHub, WordPress, and PDF-stage profiles, returning target-specific warnings, losses, and fallbacks.
| Name | Required | Description | Default |
|---|---|---|---|
| source | Yes | Document source (maximum 1000000 UTF-8 bytes) | |
| targets | No |
| Name | Required | Description |
|---|---|---|
| summary | Yes | |
| targets | Yes | |
| compatible | Yes | |
| targetCount | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, and the description reinforces a non-mutating behavior by saying it 'returns' warnings, losses, and fallbacks. This adds useful context about the output granularity without contradicting the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence with the operation, scope, and result type front-loaded. Every phrase earns its place, and there is no filler or duplication of schema 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?
Given two simple parameters, read-only annotations, and an existing output schema, the description gives agents enough to select and invoke the tool correctly. It specifies exactly which targets are involved and what kind of results will be returned.
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 only 50%, with `targets` lacking a description, but the description compensates partially by enumerating the profile names and saying results are target-specific. It still does not explain the source format, the default target behavior, or how errors are handled, so the extra semantic value is moderate.
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 names a specific verb ('Compare'), a specific resource ('one Carve document'), and explicit profile targets ('HTML, Markdown, plain text, ANSI, GitHub, WordPress, and PDF-stage'), and the outcome ('warnings, losses, fallbacks') is clear. It also stands apart from mutation/render siblings because it only returns assessment data rather than transforming or rendering.
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 clearly frames when to use this tool: when you need to compare a single Carve document across multiple target profiles and see target-specific issues. It gives strong context, though it does not explicitly state when not to use it or name alternatives such as carve_render or carve_lint.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Compare two PART 12 Carve ASTs and return position-independent add, replace, and remove operations.
| Name | Required | Description | Default |
|---|---|---|---|
| after | Yes | PART 12 AST after the edit (maximum 1000000 JSON bytes) | |
| before | Yes | PART 12 AST before the edit (maximum 1000000 JSON bytes) |
| Name | Required | Description |
|---|---|---|
| changes | Yes | |
| operations | Yes | |
| changeCount | Yes | |
| operationCount | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the agent knows this is a safe read operation. The description adds the key behavioral trait: the output is 'position-independent' operations, which is meaningful beyond the annotations. It also implies the tool does not modify anything, consistent with annotations. No contradiction.
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?
One sentence with zero waste. The core action, resource, and output type are all front-loaded. 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?
The tool has an output schema, so return values are documented elsewhere. The description covers the input semantics (two ASTs), the operation (compare), and the output type (add/replace/remove operations). The only minor gap is not explicitly stating the relationship to the reversible patch sibling, but the sibling list and name make that 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?
Schema description coverage is 100%, so the schema already documents both parameters ('before' and 'after' ASTs). The description adds the semantic context that these are 'PART 12 Carve ASTs' and that the comparison is between before/after states, but it doesn't add syntax or format details beyond the schema. 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 ('Compare'), a specific resource ('two PART 12 Carve ASTs'), and the output ('position-independent add, replace, and remove operations'). It clearly distinguishes this from sibling tools like carve_apply_ast_patch (which applies patches) and carve_create_reversible_ast_patch (which creates reversible patches).
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 clearly implies this tool is for diffing two ASTs to produce operations, and the sibling names provide context for alternatives (e.g., reversible patch creation, applying patches). However, it doesn't explicitly state when to choose this over carve_create_reversible_ast_patch, which is a close sibling. The 'position-independent' qualifier adds useful context but no explicit when/when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Compare two PART 12 ASTs and return forward and inverse operations with semantic stale-edit fingerprints.
| Name | Required | Description | Default |
|---|---|---|---|
| after | Yes | PART 12 AST after the edit (maximum 1000000 JSON bytes) | |
| before | Yes | PART 12 AST before the edit (maximum 1000000 JSON bytes) |
| Name | Required | Description |
|---|---|---|
| changes | Yes | |
| forward | Yes | |
| inverse | Yes | |
| version | Yes | |
| afterFingerprint | Yes | |
| beforeFingerprint | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, and the description's 'return' wording is consistent with that. It adds no major behavioral detail beyond mentioning the generated artifacts; it does not contradict the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One compact sentence carries the action, inputs, and output without repetition or filler. It is front-loaded and every clause 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?
With only two fully documented parameters and an output schema available, the description does not need to enumerate return values. The only slight gap is that 'semantic stale-edit fingerprints' is domain jargon with no expansion, but it is coherent within the tool family.
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 input schema already documents before and after. The description adds the domain constraint that they are PART 12 ASTs, which the schema properties also mention, but it contributes little meaning beyond that.
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?
Description opens with a specific verb ('Compare') and a concrete resource ('two PART 12 ASTs'), then specifies the deliverable: forward and inverse operations plus semantic stale-edit fingerprints. This clearly separates it from the non-reversible carve_create_ast_patch and the apply-family siblings.
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 wording 'Compare... and return' makes it evident this tool is for analysis/diffing rather than applying changes, which differentiates it from carve_apply_reversible_ast_patch and carve_apply_ast_patch. It does not spell out exclusions, but the context is clear enough for an agent to choose it when an inverse patch is required.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Diagnose Carve source, propose bounded fixes, and optionally apply selected safe fix IDs with forward and undo patches. Writer-review fixes are never applied automatically.
| Name | Required | Description | Default |
|---|---|---|---|
| source | Yes | Document source (maximum 1000000 UTF-8 bytes) | |
| platforms | No | ||
| applyFixIds | No |
| Name | Required | Description |
|---|---|---|
| fixes | Yes | |
| patch | Yes | |
| valid | Yes | |
| value | Yes | |
| warnings | Yes | |
| undoPatch | Yes | |
| warningCount | Yes | |
| appliedFixIds | Yes | |
| remainingValid | Yes | |
| remainingWarningCount | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description claims the tool can 'optionally apply selected safe fix IDs,' which is a mutating behavior, while annotations set readOnlyHint=true. This is an annotation contradiction, so the behavioral disclosure cannot be trusted. It also leaves ambiguous whether 'apply' means returning a modified source or persisting changes.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short, efficient sentences with the main action front-loaded and no filler. The safety clause about writer-review fixes is concise and earns its place as a behavioral guardrail.
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 multi-step diagnose-and-fix tool, but the description omits the meaning of `platforms`, does not define 'safe fix IDs,' and gives no routing guidance relative to sibling tools. The presence of an output schema helps, but the missing parameter semantics and the annotation contradiction leave the description incomplete.
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 documents only `source` (coverage ~33%), and the description adds meaning only for `applyFixIds` via 'selected safe fix IDs.' The `platforms` parameter is entirely unexplained in both the schema and description, and the description does not define what a fix ID is or how to obtain one.
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 clear action sequence—diagnose Carve source, propose bounded fixes, and optionally apply selected safe fix IDs—and names the target resource. This gives the tool an identifiable identity distinct from lower-level siblings like carve_parse, carve_lint, or carve_format.
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 a workflow: only selected safe fix IDs are applied, and writer-review fixes are never applied automatically. However, it never names alternatives or states when to prefer this tool over carve_apply_reversible_ast_patch or carve_plan_ast_edit, so the usage context is mostly implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Format Carve source canonically and report any lossy raw-format nodes.
| Name | Required | Description | Default |
|---|---|---|---|
| source | Yes | Document source (maximum 1000000 UTF-8 bytes) |
| Name | Required | Description |
|---|---|---|
| value | Yes | |
| losses | Yes | |
| truncated | Yes | |
| totalLosses | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and destructiveHint false. The description adds useful behavioral detail beyond those: it produces canonical formatting and surfaces lossy raw-format nodes as a report. No contradiction with the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one efficient, front-loaded sentence with no wasted words. It conveys both the primary action and the notable reporting behavior in minimal space.
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?
With one fully documented parameter, an output schema, and safety annotations, the description provides enough context for correct invocation. Nothing critical is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides 100% coverage for the single parameter, including its type, meaning, and size limit. The description adds no parameter detail, so the 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 states a specific action ('Format'), a specific resource ('Carve source'), and a distinctive outcome ('canonically and report any lossy raw-format nodes'). This clearly separates it from sibling tools like carve_lint, carve_render, carve_parse, and carve_migrate.
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 clearly implies use for canonical formatting of Carve source and for detecting lossy raw-format nodes. It does not explicitly name alternatives or state when not to use the tool, but the context is clear enough for an agent to select it appropriately.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check Carve source for author-facing problems and silent degradation.
| Name | Required | Description | Default |
|---|---|---|---|
| source | Yes | Document source (maximum 1000000 UTF-8 bytes) | |
| platforms | No |
| Name | Required | Description |
|---|---|---|
| valid | Yes | |
| warnings | Yes | |
| warningCount | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, and the description does not contradict them. The description adds useful semantic context by mentioning 'silent degradation' and 'author-facing problems', but it does not disclose mechanics, permissions, or behavior beyond what the annotations and output schema already imply.
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 sentence with no filler. The key verb and target resource are front-loaded, making it easy to parse quickly and accurately.
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-only lint tool with annotations and an output schema, the description covers the core call well. The main gaps are clarification of the optional platforms parameter and explicit guidance on when to choose this tool over siblings, but these are minor given the schema's enum and the visibility of sibling names.
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 only 50%; the source parameter is described in the schema, but the platforms parameter has no property-level description. The tool description does not mention either parameter or clarify what 'platforms' means, so it fails to compensate for the schema coverage gap.
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 action ('Check') on a specific resource ('Carve source') with a clear objective ('author-facing problems and silent degradation'). This clearly differentiates it from sibling tools like carve_format or carve_render, which perform transformations rather than analysis.
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 the tool should be used to validate Carve source for problems, but it does not explicitly state when to prefer carve_lint over carve_format, carve_render, carve_parse, or carve_migrate. It gives no exclusions or alternatives, leaving the agent to infer usage context from the verb and resource.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Migrate HTML, Markdown, Djot, or BBCode source to Carve with version 2 fidelity diagnostics.
| Name | Required | Description | Default |
|---|---|---|---|
| format | Yes | ||
| source | Yes | Document source (maximum 1000000 UTF-8 bytes) | |
| markdownDialect | No | Opt-in Markdown flavor constructs; valid only for Markdown input. |
| Name | Required | Description |
|---|---|---|
| value | Yes | |
| report | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the operation read-only and non-destructive. The description adds a behavioral nugget beyond that: the migration comes with 'version 2 fidelity diagnostics,' implying the output or result includes a fidelity assessment. It does not spell out how diagnostics are returned, but the output schema exists and there is no contradiction with the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One tightly written sentence front-loads the action and target, and the diagnostic qualifier is placed at the end. There is no filler or restatement of schema details.
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 nested markdownDialect option and an output schema, the description is adequate for basic invocation but leaves at least one use-case gap: it never explains the diagnostic concept or how this tool compares with carve_parse/carve_render/carve_format. An agent can call it from the schema but cannot fully contextualize 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 prose names the four format enum values but adds no meaning beyond the schema, and it is silent on the required source parameter's size constraint and the optional markdownDialect semantics. With schema coverage at 67%, the description does not compensate for the remaining gap.
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?
Description uses a specific verb ('Migrate'), names the target ('Carve'), and enumerates the accepted source formats, making the tool's job unmistakable. The operation is clearly distinct from sibling AST-patch, parse, format, and lint tools even without naming them.
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 intended use is implied: use this when converting HTML, Markdown, Djot, or BBCode into Carve. However, there is no explicit when-to-use guidance, no named alternatives, and no mention of when the markdownDialect option is appropriate, so the agent must infer boundaries.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Parse and resolve Carve into its position-aware interchange AST.
| Name | Required | Description | Default |
|---|---|---|---|
| source | Yes | Document source (maximum 1000000 UTF-8 bytes) |
| Name | Required | Description |
|---|---|---|
| type | Yes | |
| children | Yes | |
| srcByteLength | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds the 'resolve' and 'interchange AST' semantics, but does not detail any errors, limits, or side-effect-like behavior. This is adequate but not rich.
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?
A single, front-loaded sentence states the action and the result with no filler or repetition. Every word adds meaning.
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 one-parameter, read-only tool with a full input schema, complete annotations, and an output schema present. The description's mention of the AST result is sufficient for an agent to select and 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 'source' parameter is already fully described as the document source with a size limit. The description does not add further parameter-level meaning, 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 ('Parse and resolve') plus a clear target ('Carve') and a distinctive outcome ('position-aware interchange AST'). This makes it unmistakable from its siblings (carve_format, carve_lint, carve_render, carve_migrate), so an agent can tell what this tool is for.
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 intended use is implied: use this when you need to parse Carve source into an AST. However, it does not explicitly state when to prefer it over the sibling tools or mention any exclusions, leaving some routing judgment to the agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Plan one or more atomic semantic AST edits and return a human-readable, reversible, stale-guarded source patch without writing the document.
| Name | Required | Description | Default |
|---|---|---|---|
| edit | Yes | ||
| then | No | Additional atomic edits resolved against the original source (maximum 100 total steps). | |
| source | Yes | Document source (maximum 1000000 UTF-8 bytes) | |
| selector | Yes |
| Name | Required | Description |
|---|---|---|
| edit | Yes | |
| match | Yes | |
| steps | Yes | |
| notices | Yes | |
| selector | Yes | |
| editCount | Yes | |
| sourcePatch | Yes | |
| reversiblePatch | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds meaningful context by specifying the patch is 'human-readable, reversible, stale-guarded', which goes beyond the annotations. It also reiterates the non-writing behavior, reinforcing consistency. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the primary action and key constraints. It wastes no words and conveys the essential purpose immediately. It is appropriately concise for a tool with this level of complexity.
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 (nested objects, 4 parameters, multiple edit kinds, selector kinds), the description is far too sparse. It does not explain what 'atomic semantic AST edit' means, how selectors work, or what the patch format entails. Even though an output schema exists, the usage context for a tool this intricate is incomplete without parameter guidance.
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 only 50%, so the description should compensate by explaining parameters like selector, edit, and their nested structures. It does not—it is a single statement about the overall action. The schema provides enum values but no descriptions for most fields, and the description adds zero parameter-level meaning.
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 "Plan" and the resource "atomic semantic AST edits", and explicitly contrasts with siblings by saying "without writing the document". This distinguishes it from apply/create tools and clarifies its dry-run nature. The output is also specified as a reversible, stale-guarded patch, adding precise purpose.
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 a planning-only use case ('without writing the document') but does not explicitly mention when to use this tool versus alternatives like carve_apply_ast_patch or carve_create_ast_patch. There is no stated exclusion or explicit routing to sibling tools, leaving usage context implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Render Carve to HTML, Markdown, plain text, or ANSI terminal text, with loss reporting.
| Name | Required | Description | Default |
|---|---|---|---|
| preset | No | portable lowercases IDs and transliterates where possible; static-html is HTML-only. | default |
| source | Yes | Document source (maximum 1000000 UTF-8 bytes) | |
| target | Yes | ||
| extensions | No | Opt-in extensions; semantic-spans is HTML-only. | |
| allowRawHtml | No | Pass trusted raw HTML through on HTML output. Disabled by default. | |
| sanitizeUrls | No | Block dangerous authored URL schemes. Keep enabled for untrusted input. | |
| strictLosses | No | Fail instead of returning output when a raw-format node would be dropped. | |
| asciiHeadingIds | No | Heading ID policy; explicit values override the preset. | |
| maxRenderLosses | No | Maximum detailed losses to return. | |
| smartTypography | No | Render typographic glyphs or the punctuation the author typed. | |
| lowercaseHeadingIds | No | Lowercase generated heading IDs; explicit values override the preset. |
| Name | Required | Description |
|---|---|---|
| value | Yes | |
| losses | Yes | |
| truncated | Yes | |
| totalLosses | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish readOnlyHint=true and destructiveHint=false, so the non-destructive nature is covered. The description adds 'with loss reporting' as an extra behavioral hint, but it does not clarify what kinds of losses can occur or when they are triggered.
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?
One concise sentence with no filler words. It front-loads the core purpose and adds one useful qualifier ('with loss reporting') without duplicating schema details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the rich input schema, output schema, and annotations, the high-level description is mostly sufficient for an agent to understand what the tool does. The only notable gap is that it does not contextualize the loss-reporting behavior or the preset variants, though those are covered in the 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 91%, so the schema carries most of the parameter documentation. The description does not add meaningful parameter semantics beyond referencing loss reporting, which only loosely relates to maxRenderLosses and strictLosses.
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 ('Render'), a clear resource ('Carve'), and enumerates the exact output formats: HTML, Markdown, plain text, and ANSI terminal text. This immediately sets it apart from sibling tools like carve_parse or carve_format.
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 that this tool is for converting Carve documents into renderable output formats, but it does not explicitly say when to choose it over siblings or when not to use it. No exclusions or alternatives are named.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Resolve a heading ID, footnote label, node type, or current AST path to reviewable PART 12 AST paths without silently choosing among multiple matches.
| Name | Required | Description | Default |
|---|---|---|---|
| ast | Yes | PART 12 AST (maximum 1000000 JSON bytes) | |
| selector | Yes |
| Name | Required | Description |
|---|---|---|
| matches | Yes | |
| selector | Yes | |
| truncated | Yes | |
| matchCount | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover read-only and non-destructive behavior, and the description adds valuable transparency by disclosing that it does not silently choose among multiple matches, surface ambiguity instead. This goes beyond what the annotations state and helps the agent anticipate behavior when multiple nodes match.
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, well-structured sentence that is front-loaded with the action and resource. It contains no filler and efficiently communicates both the main purpose and a key behavioral guarantee.
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 that the tool has an output schema and annotations covering safety profile, the description is largely sufficient for an agent to call it correctly. It conveys the core selection behavior and the ambiguity-handling rule. Minor gaps like no-match behavior or error semantics are not critical because the output schema likely covers return structure.
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 description adds minimal semantic meaning to the parameters by naming the selector kinds ('heading ID, footnote label, node type, or current AST path'), which are already enumerated in the schema's enum. It does not clarify the expected format or syntax for the value field, and the 'ast' parameter is already described in the schema. Schema coverage is only 50%, but the description only partially compensates.
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 action ('Resolve') on a specific resource ('AST paths') with clear input types ('heading ID, footnote label, node type, or current AST path'). It also distinguishes itself from siblings by adding the constraint 'without silently choosing among multiple matches', which differentiates it from patch/apply 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 implies when to use the tool (when you have a semantic selector and need reviewable AST paths) but does not explicitly state when not to use it or mention alternative tools. No exclusions or comparison with sibling tools are provided, leaving the agent to infer usage context.
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.5carve_apply_reversible_ast_patch4 fields changedOutput schema / properties / sourcePatch / properties / edits / items / properties / end / descriptionAdded value: +"Exclusive UTF-8 byte offset"Output schema / properties / sourcePatch / properties / edits / items / properties / start / descriptionAdded value: +"Inclusive UTF-8 byte offset"Output schema / properties / sourcePatch / properties / unresolved / items / properties / end / descriptionAdded value: +"Exclusive UTF-8 byte offset"Output schema / properties / sourcePatch / properties / unresolved / items / properties / start / descriptionAdded value: +"Inclusive UTF-8 byte offset"carve_check_targetscarve_diagnose_and_fixcarve_migrate12 fields changedInput schema / properties / format / enumPrevious value: -[
- "html",
- "markdown",
- "djot"
-]New value: +[
+ "html",
+ "markdown",
+ "djot",
+ "bbcode"
+]Output schema / properties / report / properties / adapterAdded value: +{
+ "type": "string"
+}Output schema / properties / report / properties / diagnostics / items / additionalPropertiesAdded value: +{}Output schema / properties / report / properties / diagnostics / items / propertiesAdded value: +{
+ "code": {
+ "minLength": 1,
+ "type": "string"
+ },
+ "column": {
+ "exclusiveMinimum": 0,
+ "maximum": 9007199254740991,
+ "type": "integer"
+ },
+ "confidence": {
+ "enum": [
+ "exact",
+ "inferred",
+ "fallback"
+ ],
+ "type": "string"
+ },
+ "fidelity": {
+ "enum": [
+ "preserved",
+ "normalized",
+ "degraded",
+ "dropped"
+ ],
+ "type": "string"
+ },
+ "line": {
+ "exclusiveMinimum": 0,
+ "maximum": 9007199254740991,
+ "type": "integer"
+ },
+ "message": {
+ "minLength": 1,
+ "type": "string"
+ },
+ "path": {
+ "type": "string"
+ },
+ "severity": {
+ "enum": [
+ "info",
+ "warning",
+ "error"
+ ],
+ "type": "string"
+ }
+}Output schema / properties / report / properties / diagnostics / items / requiredAdded value: +[
+ "code",
+ "message",
+ "severity",
+ "fidelity",
+ "confidence"
+]Output schema / properties / report / properties / diagnostics / items / typeAdded value: +"object"Output schema / properties / report / properties / modeAdded value: +{
+ "type": "string"
+}Output schema / properties / report / properties / schemaVersion / constAdded value: +2Output schema / properties / report / properties / schemaVersion / maximumRemoved value: -9007199254740991Output schema / properties / report / properties / schemaVersion / minimumRemoved value: --9007199254740991Output schema / properties / report / properties / schemaVersion / typePrevious value: -"integer"New value: +"number"Output schema / properties / report / properties / sourceFormat / enumAdded value: +[
+ "html",
+ "markdown",
+ "djot",
+ "bbcode"
+]carve_plan_ast_editcarve_select_ast_nodes4 fields changedInput schema / properties / selector / properties / kind / enumPrevious value: -[
- "heading-id",
- "footnote-label",
- "node-type"
-]New value: +[
+ "heading-id",
+ "footnote-label",
+ "node-type",
+ "ast-path"
+]Input schema / properties / selector / properties / value / maxLengthPrevious value: -256New value: +4096Output schema / properties / selector / properties / kind / enumPrevious value: -[
- "heading-id",
- "footnote-label",
- "node-type"
-]New value: +[
+ "heading-id",
+ "footnote-label",
+ "node-type",
+ "ast-path"
+]Output schema / properties / selector / properties / value / maxLengthPrevious value: -256New value: +4096v0.1.4carve_apply_reversible_ast_patch1 field changedInput schema / properties / patch / properties / changesAdded value: +{
+ "items": {
+ "additionalProperties": {},
+ "properties": {
+ "kind": {
+ "enum": [
+ "add",
+ "remove",
+ "replace"
+ ],
+ "type": "string"
+ },
+ "path": {
+ "type": "string"
+ },
+ "summary": {
+ "type": "string"
+ },
+ "target": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "kind",
+ "path",
+ "target",
+ "summary"
+ ],
+ "type": "object"
+ },
+ "type": "array"
+}carve_create_ast_patch3 fields changedOutput schema / properties / changeCountAdded value: +{
+ "maximum": 9007199254740991,
+ "minimum": -9007199254740991,
+ "type": "integer"
+}Output schema / properties / changesAdded value: +{
+ "items": {
+ "additionalProperties": {},
+ "properties": {
+ "kind": {
+ "enum": [
+ "add",
+ "remove",
+ "replace"
+ ],
+ "type": "string"
+ },
+ "path": {
+ "type": "string"
+ },
+ "summary": {
+ "type": "string"
+ },
+ "target": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "kind",
+ "path",
+ "target",
+ "summary"
+ ],
+ "type": "object"
+ },
+ "type": "array"
+}Output schema / requiredPrevious value: -[
- "operations",
- "operationCount"
-]New value: +[
+ "operations",
+ "operationCount",
+ "changes",
+ "changeCount"
+]carve_create_reversible_ast_patch2 fields changedOutput schema / properties / changesAdded value: +{
+ "items": {
+ "additionalProperties": {},
+ "properties": {
+ "kind": {
+ "enum": [
+ "add",
+ "remove",
+ "replace"
+ ],
+ "type": "string"
+ },
+ "path": {
+ "type": "string"
+ },
+ "summary": {
+ "type": "string"
+ },
+ "target": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "kind",
+ "path",
+ "target",
+ "summary"
+ ],
+ "type": "object"
+ },
+ "type": "array"
+}Output schema / requiredPrevious value: -[
- "version",
- "forward",
- "inverse",
- "beforeFingerprint",
- "afterFingerprint"
-]New value: +[
+ "version",
+ "forward",
+ "inverse",
+ "beforeFingerprint",
+ "afterFingerprint",
+ "changes"
+]carve_select_ast_nodesv0.1.3carve_apply_ast_patchcarve_apply_reversible_ast_patchcarve_create_ast_patchcarve_create_reversible_ast_patchv0.1.2carve_format1 field changedOutput schema / (root)Previous value: -nullNew value: +{
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
+ "additionalProperties": {},
+ "properties": {
+ "losses": {
+ "items": {},
+ "type": "array"
+ },
+ "totalLosses": {
+ "maximum": 9007199254740991,
+ "minimum": -9007199254740991,
+ "type": "integer"
+ },
+ "truncated": {
+ "type": "boolean"
+ },
+ "value": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "value",
+ "losses",
+ "totalLosses",
+ "truncated"
+ ],
+ "type": "object"
+}carve_lint1 field changedOutput schema / (root)Previous value: -nullNew value: +{
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
+ "additionalProperties": {},
+ "properties": {
+ "valid": {
+ "type": "boolean"
+ },
+ "warningCount": {
+ "maximum": 9007199254740991,
+ "minimum": -9007199254740991,
+ "type": "integer"
+ },
+ "warnings": {
+ "items": {
+ "additionalProperties": {},
+ "properties": {
+ "column": {
+ "maximum": 9007199254740991,
+ "minimum": -9007199254740991,
+ "type": "integer"
+ },
+ "data": {
+ "additionalProperties": {},
+ "propertyNames": {
+ "type": "string"
+ },
+ "type": "object"
+ },
+ "end": {
+ "maximum": 9007199254740991,
+ "minimum": -9007199254740991,
+ "type": "integer"
+ },
+ "line": {
+ "maximum": 9007199254740991,
+ "minimum": -9007199254740991,
+ "type": "integer"
+ },
+ "message": {
+ "type": "string"
+ },
+ "resourceUri": {
+ "type": "string"
+ },
+ "rule": {
+ "type": "string"
+ },
+ "start": {
+ "maximum": 9007199254740991,
+ "minimum": -9007199254740991,
+ "type": "integer"
+ }
+ },
+ "required": [
+ "rule",
+ "message",
+ "line",
+ "column",
+ "start",
+ "end",
+ "resourceUri"
+ ],
+ "type": "object"
+ },
+ "type": "array"
+ }
+ },
+ "required": [
+ "valid",
+ "warningCount",
+ "warnings"
+ ],
+ "type": "object"
+}carve_migrate2 fields changedInput schema / properties / markdownDialectAdded value: +{
+ "additionalProperties": false,
+ "description": "Opt-in Markdown flavor constructs; valid only for Markdown input.",
+ "properties": {
+ "abbreviations": {
+ "type": "boolean"
+ },
+ "attributes": {
+ "type": "boolean"
+ },
+ "fencedDivs": {
+ "type": "boolean"
+ },
+ "highlight": {
+ "type": "boolean"
+ },
+ "inlineFootnotes": {
+ "type": "boolean"
+ },
+ "math": {
+ "type": "boolean"
+ },
+ "superscript": {
+ "type": "boolean"
+ }
+ },
+ "type": "object"
+}Output schema / (root)Previous value: -nullNew value: +{
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
+ "additionalProperties": {},
+ "properties": {
+ "report": {
+ "additionalProperties": {},
+ "properties": {
+ "diagnostics": {
+ "items": {},
+ "type": "array"
+ },
+ "schemaVersion": {
+ "maximum": 9007199254740991,
+ "minimum": -9007199254740991,
+ "type": "integer"
+ },
+ "sourceFormat": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "schemaVersion",
+ "sourceFormat",
+ "diagnostics"
+ ],
+ "type": "object"
+ },
+ "value": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "value",
+ "report"
+ ],
+ "type": "object"
+}carve_parse1 field changedOutput schema / (root)Previous value: -nullNew value: +{
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
+ "additionalProperties": {},
+ "properties": {
+ "children": {
+ "items": {},
+ "type": "array"
+ },
+ "srcByteLength": {
+ "maximum": 9007199254740991,
+ "minimum": -9007199254740991,
+ "type": "integer"
+ },
+ "type": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "type",
+ "children",
+ "srcByteLength"
+ ],
+ "type": "object"
+}carve_render10 fields changedInput schema / properties / allowRawHtmlAdded value: +{
+ "default": false,
+ "description": "Pass trusted raw HTML through on HTML output. Disabled by default.",
+ "type": "boolean"
+}Input schema / properties / asciiHeadingIdsAdded value: +{
+ "description": "Heading ID policy; explicit values override the preset.",
+ "enum": [
+ "off",
+ "fold",
+ "strict"
+ ],
+ "type": "string"
+}Input schema / properties / extensionsAdded value: +{
+ "default": [],
+ "description": "Opt-in extensions; semantic-spans is HTML-only.",
+ "items": {
+ "enum": [
+ "autolink",
+ "semantic-spans",
+ "wikilinks"
+ ],
+ "type": "string"
+ },
+ "maxItems": 3,
+ "type": "array"
+}Input schema / properties / lowercaseHeadingIdsAdded value: +{
+ "description": "Lowercase generated heading IDs; explicit values override the preset.",
+ "type": "boolean"
+}Input schema / properties / maxRenderLossesAdded value: +{
+ "description": "Maximum detailed losses to return.",
+ "maximum": 10000,
+ "minimum": 0,
+ "type": "integer"
+}Input schema / properties / presetAdded value: +{
+ "default": "default",
+ "description": "portable lowercases IDs and transliterates where possible; static-html is HTML-only.",
+ "enum": [
+ "default",
+ "portable",
+ "static-html"
+ ],
+ "type": "string"
+}Input schema / properties / sanitizeUrlsAdded value: +{
+ "default": true,
+ "description": "Block dangerous authored URL schemes. Keep enabled for untrusted input.",
+ "type": "boolean"
+}Input schema / properties / smartTypographyAdded value: +{
+ "description": "Render typographic glyphs or the punctuation the author typed.",
+ "enum": [
+ "glyph",
+ "source"
+ ],
+ "type": "string"
+}Input schema / properties / strictLossesAdded value: +{
+ "default": false,
+ "description": "Fail instead of returning output when a raw-format node would be dropped.",
+ "type": "boolean"
+}Output schema / (root)Previous value: -nullNew value: +{
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
+ "additionalProperties": {},
+ "properties": {
+ "losses": {
+ "items": {},
+ "type": "array"
+ },
+ "totalLosses": {
+ "maximum": 9007199254740991,
+ "minimum": -9007199254740991,
+ "type": "integer"
+ },
+ "truncated": {
+ "type": "boolean"
+ },
+ "value": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "value",
+ "losses",
+ "totalLosses",
+ "truncated"
+ ],
+ "type": "object"
+}v0.1.0carve_formatcarve_lintcarve_migratecarve_parsecarve_renderScored across 13 tools
Most tools target distinct operations, but the create_ast_patch/create_reversible_ast_patch and apply_ast_patch/apply_reversible_ast_patch pairs have heavily overlapping purposes and could cause misselection. Similarly, plan_ast_edit and diagnose_and_fix both surface proposed changes, though their intended workflows differ. Overall, descriptions help, but boundaries between the patch-related tools are not crisp.
All tools follow a consistent carve_ prefix with snake_case verb_noun naming, e.g. carve_parse, carve_render, carve_migrate, carve_create_ast_patch. The pattern is predictable and makes the purpose of each tool clear from its name alone.
With 13 tools, the server is well within the ideal 3-15 range for a domain-specific toolset. Each tool covers a distinct phase of the Carve document workflow: parsing, rendering, formatting, linting, migrating, patching, and cross-target checking. The count feels proportional to the complexity of the domain.
The toolset covers a comprehensive document lifecycle: parse, edit via AST patches, render, format, lint, migrate, check target compatibility, and diagnose/fix. Minor gaps include a lack of direct high-level document creation or deletion operations, though these can be handled through migration and AST patch operations. Overall, agents should be able to complete most Carve authoring and conversion workflows without dead ends.
Render, verify, describe, and safely edit Mermaid diagrams through MCP.
Convert files, URLs, and documents to clean, AI-ready Markdown via MCP.
Generate PDF, Word (.docx) and PowerPoint (.pptx) documents from Markdown over MCP.
Document-to-Markdown MCP server — convert PDF, Office and HTML into LLM-ready Markdown.
