You can use Carve MCP to lint, fix, format, render, check publishing targets, parse, inspect, edit, and migrate Carve documents, with optional workspace access.
Lint Carve source and get structured warnings.
Diagnose problems, propose bounded fixes, apply selected safe fixes, and receive forward/undo patches.
Format canonically and report rendering losses.
Render to HTML, Markdown, plain text, or ANSI with presets, extensions, and security controls.
Check compatibility across HTML, Markdown, plain, ANSI, GitHub, WordPress, and PDF-stage profiles.
Parse into a position-aware interchange AST.
Create and apply AST patches, including reversible patches with semantic stale-edit fingerprints.
Select AST nodes by ID, heading ID, footnote label, node type, or AST path.
Get exact source text for matched nodes or heading sections with byte offsets and sha256.
Replace a selected node/section's source safely, preview lint changes, and return patches; optional hash-guarded write when a workspace root is configured.
Plan semantic AST edits and preview them as guarded source edits.
Migrate HTML, Markdown, Djot, or BBCode to Carve with fidelity diagnostics.
Use resources for authoring guidance, rules, and lint-rule explanations, and tool profiles to reduce exposed tools.
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; positions: false leaves out source positions.
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 any block or inline node by its {#id},
headings, footnotes, node types, or a current AST path without making an
ambiguous selection for the caller.
carve_get_block returns the exact source text of the nodes a selector
matches, or a heading's whole section, with UTF-8 byte offsets and the
source sha256. It reads a workspace file by path when a root is configured.
carve_replace_source splices new Carve text over the exact bytes of one
selected node or heading section and leaves every other byte alone. It
refuses edits that change the node's kind, change how the rest of the
document parses, or add lint findings, returns forward and undo patches, and
can write the result through the hash-guarded workspace write.
carve_reviewed_edit adds a workspace check to that edit. It previews the
exact patch and undo patch, then checks local links and includes in the
proposed document. A write needs expectedSha256 and is refused when the
scan is truncated, a file is unreadable, include warnings are suppressed, or
the edit introduces a project error. Existing unresolved includes appear in
the receipt so they can be repaired separately.
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. The patched AST is returned only with
includeAst: true.
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).
carve_review_workspace accepts strict: true to check include targets and
line ranges. Its receipt lists files read and include dependencies. For CI,
use carve-mcp-review --root docs --strict as described in
development and deployment.
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.
carve_check_targets reports render losses and table-preservation
diagnostics separately. A target is lossy if either assessment finds a change.
Merged cells and caption associations can therefore require review even when
the pinned engine returns zero render losses. Table diagnostics name the AST
node path and affected field.
The response is a version 1 receipt. source.sha256 identifies the UTF-8
Carve input, and versions names the installed engine and MCP packages. Each
target retains its status, render losses, preservation findings, and assessment
scope. Keep this receipt with the converted output when reviewing a decision.
Each result includes assessmentScope and a preservation report with
complete: false, checked fields, and unchecked boundaries. A compatible
result means the declared checks found no issue. It does not certify every
semantic property, host behavior, or source spelling. The PDF profile assesses
the HTML stage only; it does not check the final PDF.
The server bundles the table-structure-v1 assessment so these checks work
with its published, pinned engine. Keep its contract aligned with the
JavaScript engine's preservation API when extending the checked fields.
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.
Table alignment checks treat an unset alignment as left alignment. Host CSS and default header styling are outside the assessment.
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. | |
| includeAst | No | Also return the patched AST. |
| Name | Required | Description |
|---|---|---|
| ast | No | |
| sha256 | No | |
| 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 is consistent with them (it explicitly does not write files). It adds meaningful value beyond the annotations: stale-guarding, verification against source before application, and minimal resulting edits. It stops short of describing failure modes for a stale fingerprint.
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 dense sentence that front-loads the operations (verify, apply, undo) and the key differentiator (no file writes). No filler; every clause carries 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?
With an output schema present, return values needn't be explained, and annotations cover the safety profile. For a nested-patch tool the description is largely sufficient, though it could clarify what 'stale-guarded' means operationally and how a failed verification surfaces.
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 all four parameters are documented in the schema, including the inverse toggle and includeAst. The description adds only the notion of stale-guarding/fingerprints, not new per-parameter semantics. Baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states specific verbs (verify, apply, undo) and a clear resource (reversible AST patch), plus a distinguishing scope clause: 'return a minimal stale-guarded UTF-8 source edit without writing files.' It doesn't explicitly name the sibling apply tool it differs from, but the 'without writing files' framing does separate it from a write-performing apply.
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?
Usage is only implied through the 'without writing files' phrasing and the verify-then-apply flow. There is no explicit when/when-not guidance and no named alternative among siblings like carve_apply_ast_patch or carve_apply_reversible... helpers, leaving the routing inference to the agent.
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.
Return the exact source text of the nodes a selector matches, or a heading's section, with UTF-8 byte offsets and the source sha256. No AST unless includeAst.
| Name | Required | Description | Default |
|---|---|---|---|
| scope | No | section: a heading through its content, up to the next heading of the same or higher level. | node |
| source | Yes | Document source (maximum 1000000 UTF-8 bytes) | |
| selector | Yes | ||
| includeAst | No |
| Name | Required | Description |
|---|---|---|
| blocks | Yes | |
| sha256 | Yes | |
| truncated | Yes | |
| matchCount | Yes | |
| sourceBytes | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish this is a safe, read-only, closed-world operation, and the description usefully adds that it returns byte offsets and a source sha256 and that AST is opt-in via includeAst. It says nothing about failure modes for non-matching selectors or the 1MB source limit beyond what the schema states.
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, tightly front-loaded with the return payload first and the AST caveat last; nothing is padded. Slightly clipped phrasing ('No AST unless includeAst') trades a little clarity for brevity.
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 an output schema present, return-value detail is largely covered elsewhere, and annotations cover the safety profile. The remaining holes are the meaning of the selector kinds and behavior on no-match, which an agent needs to invoke the tool reliably.
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 50%: 'scope' and 'source' are documented in the schema, and the description reinforces both. However, the five selector kinds (id, heading-id, footnote-label, node-type, ast-path) and includeAst have no descriptions anywhere, so the description leaves a key disambiguation gap unfilled.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('return the exact source text of the nodes a selector matches') plus the two scoping modes (node vs heading section). The clause 'No AST unless includeAst' cleanly distinguishes it from AST-returning siblings like carve_parse and carve_select_ast_nodes.
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?
Usage is only implied: an agent can infer it should call this when raw source text plus offsets/checksum is wanted, and the 'No AST' clause hints that AST retrieval belongs to another tool. But no alternative is named and there is no explicit when-to-use or when-not-to-use guidance.
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) | |
| positions | No | Include source positions. |
| 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, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered by structured data. The description adds only that resolution occurs and the AST is position-aware, which is modest extra context; it does not discuss determinism, error behavior on invalid source, or size limits (the schema's 1 MB cap).
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 with no filler; the verb and output type come first and nothing is repeated. Appropriately sized for a two-parameter parse operation.
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 an output schema present, the description need not explain return values, and the two parameters are fully covered by the schema. Given the tool's low complexity it is nearly complete; only ordering guidance relative to siblings and failure behavior are absent.
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 both 'source' (with its byte limit) and 'positions' (with its default) are already documented in the schema. The phrase 'position-aware' loosely corresponds to the positions flag but adds no format, syntax, or edge-case detail beyond it. Baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb-resource pair ('Parse and resolve Carve') plus the output artifact ('position-aware interchange AST'), so the agent knows exactly what the tool produces. However, it does not differentiate from siblings that likely parse internally (carve_lint, carve_format, carve_migrate), which weakens selection against a crowded namespace.
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?
There is no when-to-use guidance, no mention of alternatives, and no stated prerequisites or ordering relative to siblings like carve_check_targets or carve_lint. The agent must infer that this is the low-level entry point for producing an AST before patching tools run.
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 | |
| sha256 | No | |
| 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, so 'without writing the document' is largely redundant. The description still earns credit by disclosing traits annotations cannot express: the plan is 'reversible', 'stale-guarded', and 'human-readable', which tells the agent how the output behaves on concurrent modification.
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 dense sentence with no filler, and the key outcome (return a patch without writing) is front-loaded. It is appropriately sized for the tool, though the adjective stack ('human-readable, reversible, stale-guarded') slightly crowds the core claim.
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?
An output schema exists, so return-value explanation is unnecessary and correctly absent. The description covers the non-mutating, reversible, stale-guarded character of the operation, which is sufficient for a 4-parameter planning tool; only the sequencing behavior of the optional 'then' array is unaddressed.
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 50% and the schema itself carries the selector and edit 'kind' enums, so most semantics come from structured data. The description contributes only the notion of 'one or more atomic' edits, hinting at the top-level 'edit' plus the 'then' array, but says nothing about selector resolution or edit kinds.
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 ('Plan'), a resource ('atomic semantic AST edits'), and the artifact produced ('a human-readable, reversible, stale-guarded source patch'). It implicitly distinguishes itself from the apply/patch siblings by saying 'without writing the document', though it does not name the 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?
The phrase 'without writing the document' implies this is the non-mutating planning step, which an agent can infer precedes the apply siblings. However there is no explicit when-to-use statement and no routing against carve_create_ast_patch, carve_create_reversible_ast_patch, or carve_apply_reversible_ast_patch.
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 | Report blocked authored URL schemes as render losses. A dangerous scheme is always blanked; this server never emits one. | |
| 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 | false is source; { quotes: false } keeps typed quotes only. | |
| 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 declare the safe read-only profile (readOnlyHint=true, destructiveHint=false), so safety is covered. The description adds the non-obvious 'loss reporting' trait, but does not explain what a loss is or that strictLosses can turn one into a failure, leaving meaningful behavior to the 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?
A single tight sentence that names the operation, the source resource, the four output targets, and the loss-reporting trait up front. 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?
With an output schema present and 91% schema coverage plus safety annotations, most burden is carried by structured fields, and the description covers the output modes adequately. The gap is routing: for an 11-parameter tool amid many carve_* siblings, no indication of when to use this over carve_parse or carve_format is given.
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 already documents nearly every parameter (preset, extensions, sanitizeUrls, strictLosses, etc.). The description adds nothing parameter-specific, so the baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (Render) and resource (Carve) plus the concrete output formats it produces, which is more precise than a bare 'render'. It does not, however, distinguish itself from siblings like carve_parse or carve_format, leaving the agent to infer the boundary.
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 names output formats but gives no when-to-use guidance, no prerequisites, and no comparison against the crowded sibling set (carve_parse, carve_format, carve_lint). An agent must guess when rendering is the right call versus parsing or formatting.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Splice Carve text over the exact source bytes of one selected node or heading section, leaving every other byte untouched. Refuses if the node kind changes, the rest of the document parses differently, or new lint findings appear. Returns forward and undo patches.
| Name | Required | Description | Default |
|---|---|---|---|
| text | Yes | Carve source that replaces the selected range. | |
| scope | No | section: a heading through its content, up to the next heading of the same or higher level. | node |
| source | Yes | Document source (maximum 1000000 UTF-8 bytes) | |
| selector | Yes | ||
| includeSource | No | Also return the whole edited source. | |
| expectedSha256 | No | Source sha256 from carve_get_block; a mismatch refuses the edit. |
| Name | Required | Description |
|---|---|---|
| end | Yes | |
| lint | Yes | |
| match | Yes | |
| patch | Yes | |
| start | Yes | |
| write | No | |
| sha256 | Yes | |
| source | No | |
| undoPatch | Yes | |
| resultSha256 | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses traits nothing in the annotations or schema covers: the atomicity guarantee ("leaving every other byte untouched") and three concrete refusal conditions (node kind change, re-parse divergence, new lint findings), plus the forward/undo patch return. This also resolves the apparent tension with readOnlyHint=true – the tool computes and returns patches rather than mutating state directly, consistent with the create/apply sibling split.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, each earning its place: scope of edit, failure conditions, return value. The most decision-relevant information (exact-bytes splice) is front-loaded with zero 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?
With an output schema present, return values need not be detailed, and the failure semantics and scope are covered. It stops short of explaining how a caller produces a valid selector or the expectedSha256 precondition flow (deferred to carve_get_block / carve_select_ast_nodes), which a mutation-adjacent tool could reasonably spell out.
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 83%, so the schema already documents text, source, scope, includeSource and expectedSha256; the description adds only the mapping of "node or heading section" onto the scope enum. The selector's five kind values are left entirely to the schema, and no extra semantics are contributed beyond
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 precise verb ("Splice Carve text over the exact source bytes") and a bounded resource ("one selected node or heading section"), and the byte-exact framing distinguishes it from the AST-patch siblings. An agent can tell this is a surgical, range-scoped replacement rather than a document-wide edit.
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?
Usage is implied by "one selected node or heading section" (i.e. requires a selector target), but there is no explicit when-to-use versus carve_create_ast_patch / carve_create_reversible_ast_patch, and no stated prerequisite such as obtaining the selector or sha256 first. Adequate but leaves routing to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Resolve an element ID on any node, 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 declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds a genuine behavioral trait beyond that: it resolves 'without silently choosing among multiple matches,' telling the agent ambiguous selectors are surfaced rather than arbitrarily resolved. It does not discuss the returned path shape or 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?
A single dense sentence that front-loads the resolution verb and the accepted selector types, with the ambiguity caveat as the closing clause. Nothing is wasted, though the phrasing is somewhat run-on and could be split for scanability.
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?
An output schema exists so return values need no explanation, and the description covers the selector taxonomy plus the key ambiguity behavior. Remaining gaps (selector value formats, what happens on zero matches) are minor for a two-parameter read-only lookup.
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 50% – the 'ast' param is documented (with its 1,000,000-byte cap) but the nested selector object's kind/value are undocumented in the schema. The description compensates by spelling out the five selector kinds in prose, matching the enum, but adds no syntax or format detail for values or the ast-path form. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (Resolve) and resource (reviewable PART 12 AST paths) and enumerates the five accepted selector kinds, so an agent knows exactly what this tool consumes and produces. It does not explicitly name a sibling it differs from, but the resolution role is clear enough to separate it from parse/format/render.
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?
Usage is only implied: by listing selector kinds the description hints that this is the resolution step before an edit, but it never states when to prefer it over siblings like carve_check_targets or carve_get_block, nor any prerequisites. No exclusions or alternative routing is given.
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.8carve_parse1 field changedInput schema / properties / positionsAdded value: +{
+ "default": true,
+ "description": "Include source positions.",
+ "type": "boolean"
+}carve_render5 fields changedInput schema / properties / sanitizeUrls / descriptionPrevious value: -"Block dangerous authored URL schemes. Keep enabled for untrusted input."New value: +"Report blocked authored URL schemes as render losses. A dangerous scheme is always blanked; this server never emits one."Input schema / properties / smartTypography / anyOfAdded value: +[
+ {
+ "enum": [
+ "glyph",
+ "source"
+ ],
+ "type": "string"
+ },
+ {
+ "type": "boolean"
+ },
+ {
+ "additionalProperties": false,
+ "properties": {
+ "quotes": {
+ "type": "boolean"
+ }
+ },
+ "type": "object"
+ }
+]Input schema / properties / smartTypography / descriptionPrevious value: -"Render typographic glyphs or the punctuation the author typed."New value: +"false is source; { quotes: false } keeps typed quotes only."Input schema / properties / smartTypography / enumRemoved value: -[
- "glyph",
- "source"
-]Input schema / properties / smartTypography / typeRemoved value: -"string"v0.1.6carve_apply_reversible_ast_patch3 fields changedInput schema / properties / includeAstAdded value: +{
+ "default": false,
+ "description": "Also return the patched AST.",
+ "type": "boolean"
+}Output schema / properties / sha256Added value: +{
+ "type": "string"
+}Output schema / requiredPrevious value: -[
- "direction",
- "ast",
- "source",
- "sourcePatch"
-]New value: +[
+ "direction",
+ "source",
+ "sourcePatch"
+]carve_get_blockcarve_plan_ast_edit5 fields changedInput schema / properties / selector / properties / kind / enumPrevious value: -[
- "heading-id",
- "footnote-label",
- "node-type",
- "ast-path"
-]New value: +[
+ "id",
+ "heading-id",
+ "footnote-label",
+ "node-type",
+ "ast-path"
+]Input schema / properties / then / items / properties / selector / properties / kind / enumPrevious value: -[
- "heading-id",
- "footnote-label",
- "node-type",
- "ast-path"
-]New value: +[
+ "id",
+ "heading-id",
+ "footnote-label",
+ "node-type",
+ "ast-path"
+]Output schema / properties / selector / properties / kind / enumPrevious value: -[
- "heading-id",
- "footnote-label",
- "node-type",
- "ast-path"
-]New value: +[
+ "id",
+ "heading-id",
+ "footnote-label",
+ "node-type",
+ "ast-path"
+]Output schema / properties / sha256Added value: +{
+ "type": "string"
+}Output schema / properties / steps / items / properties / selector / properties / kind / enumPrevious value: -[
- "heading-id",
- "footnote-label",
- "node-type",
- "ast-path"
-]New value: +[
+ "id",
+ "heading-id",
+ "footnote-label",
+ "node-type",
+ "ast-path"
+]carve_replace_sourcecarve_select_ast_nodes2 fields changedInput schema / properties / selector / properties / kind / enumPrevious value: -[
- "heading-id",
- "footnote-label",
- "node-type",
- "ast-path"
-]New value: +[
+ "id",
+ "heading-id",
+ "footnote-label",
+ "node-type",
+ "ast-path"
+]Output schema / properties / selector / properties / kind / enumPrevious value: -[
- "heading-id",
- "footnote-label",
- "node-type",
- "ast-path"
-]New value: +[
+ "id",
+ "heading-id",
+ "footnote-label",
+ "node-type",
+ "ast-path"
+]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 15 tools
The editing surface contains overlapping clusters: carve_create_ast_patch vs carve_create_reversible_ast_patch both diff two ASTs, and carve_apply_ast_patch vs carve_apply_reversible_ast_patch both apply ops. carve_plan_ast_edit, carve_replace_source, and the reversible-patch tools all perform source edits, so boundaries rely on descriptions (fingerprints, inverse ops, stale-guards) rather than being self-evident.
Every tool uses the uniform carve_<verb>_<noun> snake_case pattern, with a stable carve_ prefix across all 15 tools. Verb choices (parse, render, lint, format, apply, create, migrate) map predictably to their actions.
15 tools is at the upper edge for this domain but each has a defensible role (parse, render, lint, format, migrate, target-check, and AST/source editing). The redundant reversible vs non-reversible patch pairs suggest a couple of tools could be consolidated.
The surface covers the full markup lifecycle: parse, render across targets, lint, format, migrate, plus segmented AST selection, source splicing, and reversible patches. Minor gaps remain around higher-level document validation/round-trip verification, but core workflows are present.
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 conversion MCP server: PDF to Markdown, image OCR, spreadsheet parsing.
