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., "@GraphViz MCP Render docs/architecture.dot to SVG and update the Markdown reference."
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.
GraphViz MCP is a local, Windows-friendly Model Context Protocol server for creating maintainable technical diagrams. It exposes GraphViz over STDIO, so Claude Code and Codex launch a short-lived server process automatically for each client session. No terminal process, HTTP daemon, Windows service, or open GraphViz_MCP workspace is required.
Claude Code / Codex VS Code extension
| STDIO MCP
v
.venv\Scripts\python.exe server.py
|
v
GraphViz -> .dot source + bounded parent/inner .svg/.png/.pdf artifactsThe target repository is always supplied as project_dir; it does not have to be this server repository. A .dot file is the editable source of truth. SVG is the default documentation artifact, PNG is available for compatibility, and PDF is available for publication workflows.
Related MCP server: Vizdown-MCP
GraphViz must be installed and available on PATH. This environment was verified with:
Get-Command dot
where.exe dot
dot -VThe verified executable is C:\Program Files\Graphviz\bin\dot.exe, GraphViz 10.0.1 (20240210.2158). The graphviz_environment tool performs the same discovery at runtime and reports the absolute executable path and version. The server never installs or selects another GraphViz distribution. An optional GRAPHVIZ_DOT environment variable can point to a specific absolute executable when a client needs an explicit override.
The isolated environment uses Python 3.12 and is located at C:\MyRepos\Python\GraphViz_MCP\.venv. To recreate it:
py -3.12 -m venv .venv
.venv\Scripts\python.exe -m pip install -e ".[test]"The MCP clients launch:
C:\MyRepos\Python\GraphViz_MCP\.venv\Scripts\python.exe
C:\MyRepos\Python\GraphViz_MCP\server.pySTDOUT is reserved for MCP protocol traffic. GraphViz output is written to requested files and bounded diagnostics are returned in tool results; the server does not print debugging text to STDOUT.
Installing the package (pip install -e .) exposes three console scripts under
[project.scripts]. They reconcile every configuration change in place: existing unrelated
settings, servers, comments, and formatting are preserved; the graphviz entry is upserted
so repeated runs never create duplicates; and a timestamped .bak backup is written before
any file changes.
graphviz-mcpRuns the stdio MCP server (equivalent to launching server.py). MCP clients normally invoke
the interpreter and server.py directly, but this script is a stable, PATH-resolvable entry
point.
# Run the server over stdio (a client normally launches this for you).
.venv\Scripts\graphviz-mcp.exegraphviz-mcp-vscode [project_dir]Writes the repository-local artifacts a local VS Code repository needs (defaults to the current directory):
.mcp.json — Claude Code project-scoped mcpServers.graphviz stdio entry.
.codex/config.toml — Codex project-scoped [mcp_servers.graphviz] table with command,
args, cwd, startup_timeout_sec, tool_timeout_sec, and enabled.
.claude/rules/graphviz.md — concise Claude Code rule.
AGENTS.md — a marker-delimited GraphViz guidance section (created or upserted).
README.md — a marker-delimited GraphViz usage section documenting the typical workflows
and available tools (created or upserted).
The generated stdio command targets the adjacent .venv interpreter when present, otherwise
the interpreter running the script; args points at this repository's server.py.
# Configure the repository in the current directory.
.venv\Scripts\graphviz-mcp-vscode.exe
# Or point at a specific repository.
.venv\Scripts\graphviz-mcp-vscode.exe C:\MyRepos\SomeProjectgraphviz-mcp-installRegisters the server in the global user configuration:
~/.claude.json — top-level mcpServers.graphviz.
~/.claude/rules/graphviz.md — concise global rule.
~/.codex/config.toml — [mcp_servers.graphviz] table.
~/.codex/AGENTS.md — marker-delimited GraphViz guidance section.
Before writing configuration it detects the GraphViz dot executable via PATH,
GRAPHVIZ_DOT, and common install locations (enumerated drive letters and Program Files
layouts on Windows; standard prefixes on POSIX). It also reads dot -V and compares it
against the minimum verified GraphViz version. If dot is missing, or present but older than
that minimum, it prints the exact platform command (winget/brew/apt/dnf/pacman) — an install
command when missing, an upgrade command when out of date — and only executes it when re-run
with --install-graphviz. Use --skip-graphviz-check to write configuration without touching
GraphViz detection.
# Register globally; report (but do not run) any needed GraphViz install/upgrade.
.venv\Scripts\graphviz-mcp-install.exe
# Register globally and install GraphViz if missing, or upgrade it if it is too old.
.venv\Scripts\graphviz-mcp-install.exe --install-graphviz
# Register globally and skip GraphViz detection entirely.
.venv\Scripts\graphviz-mcp-install.exe --skip-graphviz-checkOn POSIX shells the scripts are on PATH after pip install -e . (or use
.venv/bin/graphviz-mcp-install):
graphviz-mcp-vscode ./my-project
graphviz-mcp-install --install-graphvizThe initialization instructions tell agents to use GraphViz for state machines, state transitions, flowcharts, directed dependency graphs, architecture/data-flow diagrams, decision flows, and similar graph-structured technical documentation. They also emphasize version-controlled .dot sources, SVG by default, managed Markdown references, repository conventions, and avoiding decorative or unrelated edits.
Every graph image is limited to at most five visual rows, five visual columns, and therefore 25 nodes. The server inspects the coordinates computed by the selected GraphViz engine. If either dimension or the node capacity is exceeded, it spatially partitions the source into bounded inner views and renders a parent overview with one encapsulation node per inner view. SVG overview nodes link to their inner SVG images. If an overview would itself exceed 5x5, the server recursively adds bounded intermediate overview images. The original .dot remains the source of truth, and generated .parent.dot, .inner-NNN.dot, and, when needed, .group-L-NNN.dot files make the rendered hierarchy reviewable.
graphviz_environmentRead-only; no arguments. Reports the actual dot.exe path, GraphViz version, supported formats, available engine paths, server working directory, server repository path, enforced row/column/node limits, and oversized-layout behavior.
graphviz_validateRead-only validation with no persistent rendered output:
project_dir: string
dot_path: stringReturns success, dot_path, errors, warnings, bounded stderr, and a layout object containing the computed row/column counts, limits, layout_compliant, and requires_encapsulation. The source must be an existing .dot file inside project_dir. An oversized but valid source still validates successfully because rendering can safely encapsulate it.
graphviz_renderValidates and renders an existing source:
project_dir: string
dot_path: string
output_path: optional string
format: svg | png | pdf (default svg)
engine: dot | neato | fdp | sfdp | circo | twopi (default dot)If output_path is omitted, the root artifact is placed next to the source with the selected extension. A layout within 5x5 renders normally. An oversized layout automatically produces the bounded parent/inner hierarchy described above. The requested path always identifies the root parent image; related inner images use deterministic names beside it. The result includes encapsulated, the original and root layout summaries, and an artifacts manifest with every generated source/image pair and its row, column, and node counts. Encapsulated views use fixed positions through neato so GraphViz cannot expand them beyond the enforced grid.
graphviz_render_sourceWrites or updates a repository-local .dot, validates it, and renders it:
project_dir: string
dot_source: string
dot_path: optional string (default diagram.dot)
output_path: optional string
format: svg | png | pdf (default svg)
engine: allowed engine (default dot)The caller-provided .dot source remains in the project after rendering. When encapsulation is required, the derived parent/inner .dot sources also remain in the project.
graphviz_publish_markdownValidates, renders, and creates or updates one idempotent managed Markdown block:
project_dir: string
dot_path: string
markdown_path: string
output_path: optional string
format: svg | png (default svg)
alt_text: optional string
anchor: optional exact text or headingThe managed block identifies the source and uses a correct relative image link:
<!-- graphviz:docs/diagrams/controller-state.dot -->
<!-- /graphviz:docs/diagrams/controller-state.dot -->Repeated calls update the block rather than duplicating it. An anchor inserts the block after the matching line. Without an anchor, the block is appended only when the Markdown location is unambiguous. For an encapsulated diagram, the managed block references the root parent image; its encapsulation nodes lead to the separately rendered inner images when the output format supports links.
graphviz_syncConvenience operation. With markdown_path, it refreshes the managed Markdown block; without it, it validates and renders the source. The same 5x5 enforcement and automatic hierarchy apply in both cases.
All caller-provided paths are resolved and must remain inside the explicit project_dir. Existing symlinks that resolve outside the project are rejected. Output cannot overwrite the .dot source. Generated hierarchy sources remain beside the original source, while hierarchy images remain beside the requested root image; all remain inside the project. Only the six known GraphViz engines and three expected output formats are accepted. Subprocesses use argument arrays, shell=False, stdin=DEVNULL, bounded timeouts, and bounded diagnostics. No caller-supplied executable, shell argument, recursive delete, or arbitrary command execution is available.
Write tools are marked with MCP write/idempotent annotations where supported; validation and environment inspection are marked read-only.
The fixtures include a labeled controller state machine (Idle, Connecting, Connected, Fault, Retrying), a decision flowchart with a diamond and branches, and a Markdown publish fixture. The suite covers executable/version detection, valid and invalid DOT, SVG/PNG rendering, the exact 5-column boundary, automatic encapsulation of over-wide and over-tall layouts, parent-to-inner SVG links, per-artifact limits, missing and unsafe paths, invalid formats/engines, cross-project operations, relative links, managed-block creation/idempotence, and an actual MCP client/server STDIO session.
Run the complete suite:
.venv\Scripts\python.exe -m pytest -qThe user-scoped Claude configuration is %USERPROFILE%\.claude.json, specifically its top-level mcpServers object. The setup registers both latex and graphviz with absolute Python and server paths. Existing unrelated settings and servers are preserved. A timestamped backup is created before each configuration change. The GraphViz server entry is equivalent to:
"graphviz": {
"type": "stdio",
"command": "C:\\MyRepos\\Python\\GraphViz_MCP\\.venv\\Scripts\\python.exe",
"args": ["C:\\MyRepos\\Python\\GraphViz_MCP\\server.py"]
}The concise global rule is %USERPROFILE%\.claude\rules\graphviz.md. Claude Code or its VS Code extension must be reloaded before a new user-scoped MCP entry is visible; this repository cannot verify extension UI connectivity itself.
The user-scoped Codex configuration is %USERPROFILE%\.codex\config.toml. The setup preserves its existing TOML and adds [mcp_servers.graphviz] with absolute command, args, cwd, startup_timeout_sec = 15, tool_timeout_sec = 120, and enabled = true. The existing latex entry is preserved when present or restored from the verified LaTeX_MCP path if the audit finds it absent. %USERPROFILE%\.codex\AGENTS.md contains the concise ## GraphViz diagrams guidance section and is not duplicated on repeated runs.
Codex must be restarted or its MCP settings reloaded before the new server appears in the extension UI. No Codex CLI is required.
1. Choose the target repository and its existing docs/figure convention.
2. Create or update docs/diagrams/controller-state.dot without manually cramming more than 5x5 nodes into one view.
3. Call graphviz_validate with the target project_dir and inspect `layout.requires_encapsulation`.
4. Call graphviz_publish_markdown with the relevant Markdown file; it creates parent/inner views when required.
5. Review the source, generated hierarchy `.dot` files, and SVG artifacts in version control.Example request:
Document this controller state machine. Use the GraphViz MCP tools, keep the DOT source under
docs/diagrams, render it to SVG, and link the diagram from the relevant Markdown documentation.
graphviz_publish_markdown(
project_dir="C:\\MyRepos\\SomeProject",
dot_path="docs\\diagrams\\state-flow.dot",
markdown_path="README.md",
format="svg",
anchor="## State flow"
)Individual repositories do not need copies of GraphViz_MCP. They only need their own .dot source and generated artifact if project policy versions artifacts.
If graphviz_environment fails, confirm Get-Command dot, where.exe dot, and dot -V; use GRAPHVIZ_DOT only with a verified absolute executable.
If a path is rejected, use an explicit absolute project_dir and ensure every source, output, and Markdown path is inside it.
If Markdown insertion fails, supply an exact heading or anchor so the tool has an unambiguous insertion point.
If a client does not list the server, validate the JSON/TOML, then reload the Claude Code or Codex VS Code extension/session. This implementation does not claim extension-level connectivity without that UI check.
The server process is intentionally client-managed; do not start a persistent terminal or HTTP process.
This repo has the handoff MCP server configured (see .mcp.json /
.codex/config.toml). It is a durable, project-scoped place to leave
breadcrumbs between sessions. Use it instead of re-deriving context.
At the start of a session, call handoff_list to reload where prior work
stopped and what to do next, and todo_list for outstanding next steps. This is
cheaper and more reliable than re-reading the whole transcript.
While working, when you find something that must be done but is not the
current focus, call todo_add rather than holding it in the conversation.
When context gets heavy (stale greps, large logs, finished sub-tasks pile
up), call context_report, then context_compact — it returns a
summarise-then-handoff procedure and can persist the summary as a handoff in one
call.
At the end of a work chunk, call handoff_add with a summary, next steps,
and the few key facts (file paths, decisions, gotchas) the next worker needs. A
fresh session can then resume from handoff_list alone.
Close the loop with todo_update (done/dropped) and handoff_resolve so
the open lists stay a true worklist.
Tool | Use it to |
| Reload breadcrumbs at session start. |
| Record where you stopped and what is next. |
| Mark a handoff done. |
| Track next-step TODOs. |
| Counts of open todos and handoffs. |
| Notice and shrink a bloated context window. |
Every tool is scoped to this project only; there is no way to reach another
project's data. Full reference: docs/TOOL_GUIDE.md.
Report GraphViz capabilities, server paths, and enforced 5x5 layout limits.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate a safe read-only operation. The description adds meaningful context beyond the annotations by disclosing that it reports capabilities, server paths, and an enforced layout constraint, giving the agent a clear picture of what the call reveals without contradicting the read-only hint.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that enumerates three concrete items with no filler. Every word adds meaning and the structure makes the tool's purpose immediately clear.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple, parameterless, read-only environment probe with an output schema, the description fully covers what the agent needs to know. It identifies the tool's purpose and the categories of information returned, and the output schema handles the rest.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and the input schema is empty with 100% coverage, so there is nothing for the description to document. The baseline of 4 applies because no additional parameter clarification is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description uses a specific verb ('Report') and clearly specifies the resource (GraphViz environment) and the exact information returned: capabilities, server paths, and layout limits. This distinguishes it from siblings that validate, render, publish, or sync.
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 for inspecting the environment before layout operations, especially mention of enforced 5x5 limits, but it does not explicitly state when to prefer this over alternatives. No when-not-to-use guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Render a bounded diagram hierarchy and update its root Markdown reference.
| Name | Required | Description | Default |
|---|---|---|---|
| anchor | No | ||
| format | No | svg | |
| alt_text | No | GraphViz diagram | |
| dot_path | Yes | ||
| output_path | No | ||
| project_dir | Yes | ||
| markdown_path | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, idempotentHint=true, and destructiveHint=false. The description adds that it updates a Markdown reference, which is consistent with the annotations but doesn't disclose the exact side effects or whether existing content is overwritten.
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 redundant words. It is concise and to the point, though its brevity sacrifices clarity.
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 7 parameters, no parameter descriptions, and several sibling tools, the one-sentence description is insufficient. It does not explain the overall workflow, error conditions, or relationship to the output schema, leaving the agent to guess too much.
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 0% and the description provides no clarification for any of the 7 parameters. It doesn't explain that dot_path is the source diagram, markdown_path is the file to update, or how anchor/format/alt_text/output_path are used.
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 clear verb ('Render' and 'update') but the phrase 'bounded diagram hierarchy' is jargon and not self-explanatory. It doesn't clearly distinguish from sibling tools like graphviz_render or graphviz_sync.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. It doesn't mention that graphviz_render should be used when no Markdown update is needed, or that graphviz_sync handles bulk synchronization.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Render DOT, automatically creating parent/inner images above the 5x5 limit.
| Name | Required | Description | Default |
|---|---|---|---|
| engine | No | dot | |
| format | No | svg | |
| dot_path | Yes | ||
| output_path | No | ||
| project_dir | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide idempotentHint=true and destructiveHint=false, and the description adds a concrete side effect: it creates parent and inner images above the 5x5 limit. This is useful behavioral context beyond the annotations, although it does not explain where files are written or what gets overwritten.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single front-loaded sentence with no filler, which is efficient. However, '5x5 limit' and 'parent/inner images' are unexplained jargon that undercut the clarity, so brevity comes at the cost of usefulness.
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 five-parameter tool with no schema descriptions, this is too thin. It lacks the meaning of project_dir and output_path, the role of engine/format, and the behavior around the 5x5 limit. The output schema may cover return values, but invocation-level knowledge is 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?
Schema description coverage is 0%, and the description explains none of the five parameters. project_dir, dot_path, engine, format, and output_path are all left uninterpreted, so the agent cannot infer valid values or required relationships from the description.
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 clear verb/resource pair: 'Render DOT'. The mention of automatically creating parent/inner images adds specificity, but it does not clearly distinguish this tool from graphviz_render_source or explain the '5x5 limit' enough for a confident 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given for when to use graphviz_render versus siblings like graphviz_render_source, graphviz_validate, graphviz_sync, or graphviz_publish_markdown. The '5x5 limit' implies a special scenario, but it is not framed as a selection criterion or contrasted with alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Write DOT and render it with automatic parent/inner 5x5 encapsulation.
| Name | Required | Description | Default |
|---|---|---|---|
| engine | No | dot | |
| format | No | svg | |
| dot_path | No | diagram.dot | |
| dot_source | Yes | ||
| output_path | No | ||
| project_dir | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, idempotentHint=true, and destructiveHint=false. The description adds the unexplained 'automatic parent/inner 5x5 encapsulation' behavior, but does not clarify file creation, output path handling, or side effects beyond the annotation profile. It provides some extra behavioral context without 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 a single focused sentence with no filler or repeated title information. It is concise and front-loaded, though the '5x5 encapsulation' terminology is cryptic and would benefit from a brief explanation.
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 six parameters and a non-obvious '5x5 encapsulation' feature, the description is too sparse to provide complete context. It does not explain what encapsulation means, where files are written, or how the required project_dir and dot_source relate to the output. The presence of an output schema helps, but the description alone leaves important behavioral and operational details ambiguous.
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 0%, and the description names none of the six parameters. Though parameter names and defaults are somewhat self-explanatory, dot_path, output_path, engine, and format are left entirely undocumented, so the description does not compensate for the schema 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 identifies the action as writing and rendering DOT source, and adds a distinguishing 'automatic parent/inner 5x5 encapsuation' behavior. It does not explicitly name the sibling tools it differs from, but the mention of write-plus-render from DOT source communicates the tool's primary role clearly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given about when to choose this tool over graphviz_render or other siblings, nor are any exclusions or prerequisites mentioned. The agent must infer usage solely from the verb phrase, which is not enough for confident tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Render a bounded diagram hierarchy and optionally refresh its root Markdown block.
| Name | Required | Description | Default |
|---|---|---|---|
| dot_path | Yes | ||
| project_dir | Yes | ||
| markdown_path | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare idempotentHint=true and destructiveHint=false, so the description's additional mention of refreshing a Markdown block adds context about a possible side effect. However, it does not explain what 'refresh' entails, whether files are written, or how the hierarchy is bounded, leaving behavioral details under-specified.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single front-loaded sentence with no filler. Every phrase adds meaning, and the primary action is stated first, followed by the optional secondary behavior.
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, no schema descriptions, and a non-trivial 'sync' action, the description is too terse. It leaves unresolved what 'bounded diagram hierarchy' means, how parameters map to the operation, and when the Markdown refresh occurs. The output schema exists but does not compensate for missing invocation 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 0%, so the description must compensate, but it only loosely suggests the optional markdown_path via 'optionally refresh its root Markdown block.' It does not clarify the distinct roles of project_dir and dot_path or their relationship, leaving agents to guess parameter semantics.
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 identifies a specific verb ('Render') and resource ('a bounded diagram hierarchy'), and adds the distinguishing behavior of optionally refreshing a root Markdown block. This separates it from generic render tools, though it does not explicitly name sibling 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 description gives no explicit guidance on when to use this tool versus graphviz_render, graphviz_render_source, or graphviz_publish_markdown. The phrase 'optionally refresh' hints at a use case, but there is no clear context, prerequisite, or exclusion.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Validate DOT and report whether its computed layout needs 5x5 encapsulation.
| Name | Required | Description | Default |
|---|---|---|---|
| dot_path | Yes | ||
| project_dir | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the read-only safety profile, and the description adds behavioral context by specifying that it computes a layout and reports an encapsulation requirement. This goes beyond the schema and annotations without contradicting them.
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 that conveys the tool's core behavior with no filler. 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 is simple, has annotations, and an output schema exists, so the missing return-value documentation is not a major gap. However, parameter meanings are undocumented and relative usage versus siblings is absent, leaving clear gaps for an agent deciding how and when to invoke it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the description does not explain either parameter (dot_path, project_dir). The parameter names hint at their meaning, but there is no added semantic clarity about what each path refers to or how they relate to validation.
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 and resource ('Validate DOT') and identifies a distinct output ('whether its computed layout needs 5x5 encapsulation'). It is distinguishable from sibling render/environment tools, though the '5x5 encapsulation' jargon may be opaque without domain knowledge.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool versus its siblings like graphviz_render or graphviz_environment. The verb 'Validate' implies the use case, but there are no explicit conditions, prerequisites, or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.2.1graphviz_environmentgraphviz_publish_markdowngraphviz_rendergraphviz_render_sourcegraphviz_syncgraphviz_validateScored across 6 tools
The set has clear distinct tools like graphviz_environment and graphviz_validate, but graphviz_render and graphviz_render_source are easily confused, and graphviz_publish_markdown and graphviz_sync appear to overlap heavily in purpose. An agent would struggle to reliably pick between these pairs without deeper context.
Most tools follow a consistent graphviz_<verb> pattern, such as validate, render, and sync. The exception is graphviz_environment, which uses a noun instead of a verb, creating a minor inconsistency.
Six tools is a reasonable, focused scope for a GraphViz-specific server. Each tool addresses a core part of the workflow: environment discovery, validation, rendering, source rendering, and Markdown publishing/sync.
The server covers environment reporting, validation, rendering, and Markdown integration, which appears to be the core domain. The overlap between publish_markdown and sync leaves some ambiguity about the intended lifecycle, but there are no obvious critical gaps for rendering and embedding diagrams.
Render, verify, describe, and safely edit Mermaid diagrams through MCP.
Create, validate, edit, export (markdown/svg/png/mermaid), and search JSON Canvas files.
Publish markdown documents as public share links with mermaid diagram support. Built by AutEng.ai
Publish markdown documents as public share links with mermaid diagrams. Built by AutEng.ai