This server exposes a focused Cartograph MCP interface for agents to search, install, create, validate, and manage reusable widgets and workflow defaults without mirroring the full CLI.
Search, inspect, install, and rate widgets/blueprints from the registry
Upgrade or uninstall already-installed widgets in the current project
Check widget health/status, sync state, and available updates
Scaffold new widgets or blueprints with domain/language/name
Validate widgets as a dry run before check-in
Check widgets into the library with reason, version bump, and optional publishing
Manage blueprint dependencies (add/remove/create)
Read and update Cartograph workflow defaults (auto-publish, visibility, governance, etc.)
List, initialize, or reset custom validation rules
Get recovery guidance for common Cartograph error states
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., "@cartograph-mcp search the registry for a retry widget"
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.
mcp-name: io.github.benteigland11/cartograph
Tired of vibe coding the same solutions over and over? Time to stop spending money on redundant tokens and start spending it on innovative solutions.
This MCP server is for Cartograph that exposes the daily widget workflow for agents without mirroring the entire CLI. It targets the MCP 2.0 SDK contract and returns the standard ListToolsResult envelope from tools/list. On installation of the MCP the CLI will be installed automatically. Once you have it, Search, inspect, install, create, validate, check in, custom rules, and configure Cartograph defaults through a compact agent-facing surface, then fall back to the CLI for the full administrative and recovery surface.
It is highly recommended to use the plugins for the skills that go with this MCP. It will give your agent what it needs to explain a lot of the configuration and give you a very powerful workflow tool.
I personally have spent hours and hours working on solutions I'm proud of, only to hit a wall trying to get the same one done. The reality was prompting was never good enough, I needed a way to know my llama.cpp server client integration was going to be the same everytime I used it. I also needed to know that when I found an improvement, that improvement would stick.
If you are sick and tired of wasting money and time on redoing things you've done before, like a mouse on a wheel then get your agents to start using Cartograph.
The Cartograph CLI is the source of truth, but agents do better when the common path is small and explicit.
This MCP keeps the top-level tool surface focused on daily driving:
finding reusable widgets
inspecting and installing them
managing installed widget copies
creating new widgets
validating and checking them back in
adjusting the core Cartograph defaults that affect normal workflow
Everything else stays in the CLI. That keeps the MCP easier to teach, easier to test, and less likely to drift into a second full interface.
Related MCP server: codex-subagents-mcp
pip install cartograph-mcpClaude Desktop example:
{
"mcpServers": {
"cartograph": {
"command": "cartograph-mcp"
}
}
}The package depends on cartograph-cli and shells out to it as the source of truth for the full command surface.
Common CLI setup commands:
# Claude Code
claude mcp add cartograph --scope user -- cartograph-mcp
# Codex
codex mcp add cartograph -- cartograph-mcp
# Gemini CLI
gemini mcp add cartograph cartograph-mcp
# Cursor
cursor --add-mcp '{"name":"cartograph","command":"cartograph-mcp"}'Claude Code expects an explicit scope flag such as --scope user.
The MCP intentionally exposes a small workflow-oriented surface:
registry_widget
Actions: search, inspect, install, rate
installed_widget
Actions: upgrade, uninstall
widget_status
create_widget
validate_widget
checkin_widget
cartograph_config
cartograph_rules
These are not a 1:1 mirror of the CLI. They are grouped around agent intent:
registry-facing work
installed-widget mutation
project health/status
widget authoring
workflow configuration
custom validation rules
1. Search the registry before writing logic.
2. Inspect the widget you want to reuse.
3. Install it into the project.
4. If no existing widget fits, create one.
5. Validate it with the full dry-run pipeline.
6. Check it in with a reason once it is ready.In Cartograph terms:
registry_widget handles discovery and install
installed_widget handles already-installed widget paths like cg/backend_retry_python
validate_widget is the dry run for checkin_widget
cartograph_config manages the defaults that change how your day-to-day loop behaves
cartograph_rules manages custom rules that run during validate and checkin
This MCP is deliberately not the whole CLI.
The common path belongs in MCP. The official full surface belongs in cartograph.
For uncommon, administrative, or recovery operations, use:
cartograph --help
cartograph <command> --helpThat includes things like rollback/delete, cloud operations, auth, setup, rules, doctor, export/import, and other non-daily commands.
cartograph_config exposes the workflow defaults that matter most to agents:
auto-publish
visibility
governance
cloud
show-unavailable
publish-registry
Reading and writing config is done through the CLI's --json path so MCP can consume it safely.
This package is tested in two layers:
command-contract tests that mock the CLI runner and assert the exact commands the MCP builds
isolated integration tests that run the real Cartograph CLI in a temporary environment
The integration suite isolates:
HOME
XDG_CONFIG_HOME
XDG_DATA_HOME
XDG_CACHE_HOME
WIDGET_LIBRARY_PATH
project working directory
That means validate/checkin/install flows are exercised without touching the real widget library or user config on the machine running tests.
pip install -e .
pytest -qThe repo includes:
ci.yml for normal test/build validation on pushes and pull requests
pypi-publish.yml for automated release publishing after a successful version-bump CI run
For the full product story and complete CLI surface, see Cartograph.
Blueprint-specific composition management. Blueprints are higher-order widgets that compose other widgets as dependencies. Use this to add or remove dependencies.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | Blueprint name (for create action). | |
| action | Yes | Blueprint action to perform. | |
| target | No | Target root for create. | |
| widget_id | No | Widget ID to add or remove as a dependency. | |
| no_validate | No | Skip validation when adding dependency. | |
| blueprint_path | No | Path to the blueprint directory (default: .). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must disclose behavioral traits. It does not mention that blueprints can be created (action 'create'), or any side effects like file modifications, validation behavior, or destructive potential of removing dependencies. Significantly incomplete for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, concise but incomplete. It front-loads the purpose but misses covering the 'create' action and is not well-structured to list operations clearly.
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 6 parameters and no annotations or output schema, the description fails to explain the 'create' operation, validation behavior, or return values. Does not provide enough context for an agent to use the tool correctly in a workflow.
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 descriptions cover all 6 parameters fully (100% coverage). The tool description adds no additional meaning beyond what the schema already provides. With full schema coverage, baseline is 3; description does not elevate it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly identifies the tool manages blueprints as higher-order widgets with dependencies. Uses verb 'add or remove' but omits the 'create' action present in schema, creating a slight gap in coverage. Differentiates from sibling tools by specifying blueprint composition but lacks explicit sibling distinction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a high-level use case ('add or remove dependencies') but does not give explicit guidance on when to use this tool versus alternatives like cg_create or cg_registry. No context on prerequisites, when not to use, or fallback options.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run the full validation / smoke pipeline and then check the module into the library. Use this only for changes that should become reusable logic. Requires reason. Supports either path or widget_dir for compatibility.
| Name | Required | Description | Default |
|---|---|---|---|
| bump | No | Version bump type. | |
| path | No | Directory (default: .). | |
| reason | Yes | What changed and why. | |
| publish | No | Publish to cloud after checkin. | |
| widget_dir | No | Alias for path. | |
| override_reason | No | Why warnings should be overridden. | |
| override_warnings | No | Proceed despite validation warnings. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must fully disclose behavior. It states it runs a full validation/smoke pipeline and checks in, but lacks details on side effects (e.g., overwriting, reversibility, permissions) or what 'check in' entails. Incomplete for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences only: first states primary action, second gives usage constraint and parameter hint. No redundancy, front-loaded with key purpose. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite 7 parameters and no output schema or annotations, the description omits behavior for validation outcomes, side effects of publish/bump, and return value (e.g., success confirmation). Incomplete for a complex checkin tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, baseline 3. Description adds value by noting that 'widget_dir' is an alias for 'path' for compatibility, clarifying their relationship beyond schema. Also highlights that 'reason' is required, aligning with schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool runs validation/smoke pipeline and checks module into library, with specific purpose for changes that should become reusable logic. Differentiates from siblings like cg_validate or cg_create.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states 'Use this only for changes that should become reusable logic' and 'Requires reason.' Provides clear context for when to use, but does not mention when not to use or suggest alternative tools among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read or update Cartograph workflow defaults. Provide key to read the current value; provide both key and value to update it.
| Name | Required | Description | Default |
|---|---|---|---|
| key | No | Configuration key to read or update. Omit to list all settings. | |
| value | No | Optional new value to set. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses behavioral traits: reading vs updating based on parameter presence, and the ability to list all settings by omitting key. No annotations are provided, so the description carries the full burden, which it fulfills well.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, direct and front-loaded with the purpose. Every sentence provides essential information without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description does not detail return values, but the behavior is sufficiently explained for an agent to use correctly. The sibling tools are distinct, so no further disambiguation is needed.
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% with descriptions for both parameters. The description adds value by explaining the conditional behavior: key is used to read, both key and value to update, and omitting key lists all. This goes beyond the schema's static descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb and resource: 'Read or update Cartograph workflow defaults.' It distinguishes from sibling tools like cg_blueprint or cg_create by specifying the unique action on configuration defaults.
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 explains when to read (provide key) and when to update (provide both key and value). It does not explicitly mention when not to use or compare to siblings, but the context is clear given the sibling tool names.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Scaffold a new Cartograph widget or blueprint. Use name for the slug only, not the full widget_id; Cartograph combines domain + name + language for widgets. For blueprints, just use the name.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Slug, for example retry-backoff. | |
| domain | No | Domain (required for widgets). | |
| target | No | Project root to create the module under. | |
| language | No | Language (required for widgets). | |
| display_name | No | Optional display name for manifest. | |
| is_blueprint | No | Whether to scaffold a blueprint instead of a widget. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, so the description carries the behavioral burden. It discloses an important naming behavior: Cartograph combines domain + name + language for widgets, and blueprints use only the name. It does not, however, mention what actually gets created on disk, whether the operation is destructive, or what success/output looks like, so behavioral transparency is only partial.
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 very concise and front-loaded, with the core action stated in the first sentence. The second sentence earns its place by resolving a potential misapprehension about slug vs full widget_id and blueprint naming. No filler or repetition.
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 six parameters and no output schema, the description could do more. It covers the main naming behavior and widget vs blueprint distinction, but does not mention that domain/language are required for widgets, what default target behavior is, or what the tool returns/creates. The essentials are present, but some contextual guidance is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds meaningful semantic nuance beyond the schema by clarifying that 'name' is a slug only, not a full widget_id, and explaining how domain, name, and language combine for widgets. This prevents a real misuse that the schema alone would not protect against.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Scaffold') and clear resources ('a new Cartograph widget or blueprint'), making the tool's purpose immediately obvious. It does not explicitly distinguish itself from the sibling cg_blueprint, which may cause mild ambiguity, but the core purpose is specific enough.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context for when to use: when scaffolding a new Cartograph widget or blueprint. It also adds practical guidance about how to specify the name and how blueprints differ. However, it does not mention exclusions or explicitly route to alternatives such as cg_blueprint.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recovery guidance for common Cartograph trouble states (e.g. local out of sync with cloud, checkin blocked, validation contamination, publish rejected). Use action=list to browse topics with one-line summaries, then action=get with a topic to read the full resolution. Reach for this before guessing when an agent is stuck on a Cartograph error state.
| Name | Required | Description | Default |
|---|---|---|---|
| topic | No | Topic slug for action=get (from the list output). | |
| action | Yes | list returns available topics; get returns the full entry for one topic. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Describes non-destructive guidance retrieval, but lacks explicit statement about idempotency or side effects; however, no annotations exist so description carries burden.
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, front-loaded with purpose, no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Complete for a help tool with only two parameters and no output schema; mentions return types for list and get actions.
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 covers 100% with descriptions; description adds context by explaining the list/get workflow and relation to topic output.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it provides recovery guidance for Cartograph trouble states with specific examples and distinguishes actions list and get.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly advises to use this tool before guessing on error states, and explains when to use list versus get.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Mutate widgets already installed in the current project. Use this for installed copies only; use cg_registry install for adding a new widget. Actions: upgrade requires widget_dir and optionally version; uninstall requires widget_dir. Pass the widget directory path (e.g. cg/backend-retry-python).
| Name | Required | Description | Default |
|---|---|---|---|
| action | Yes | Installed-widget action to perform. | |
| version | No | Target version for upgrade. | |
| widget_dir | No | The local widget directory path (e.g. cg/backend-retry-python). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It states 'mutate' but doesn't disclose side effects, reversibility, error handling, or authorization needs for actions like upgrade/uninstall. Adequate but not thorough.
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 and a short instruction. Front-loaded with purpose. Somewhat mixed content (usage guidelines and parameter mappings in same sentence) but still efficient and 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 mutation tool with 3 params and no output schema, description covers purpose, usage context, and action-specific requirements. However, lacks information on return values, error states, or operation results. Slight gaps given complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but description adds value by linking parameters to actions (e.g., upgrade requires widget_dir and optionally version). This clarifies usage beyond the schema's static descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Mutate' and resource 'widgets already installed in the current project', distinguishing it from sibling tool cg_registry install for adding new widgets.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says when to use this tool (installed copies only) vs cg_registry install for adding new widgets, and details action-specific requirements: upgrade needs widget_dir/version, uninstall needs widget_dir.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Registry-facing daily workflow for Cartograph widgets and blueprints. Use search before writing reusable logic, inspect before installing or editing, install to add a widget to the current project, and rate to leave registry feedback. When installing or inspecting, use the exact value from the 'id' field returned by search.
| Name | Required | Description | Default |
|---|---|---|---|
| owner | No | Filter search to widgets owned by @handle. Requires registry (owner is scoped per-registry). | |
| query | No | Search query for action=search. | |
| score | No | Rating score from 1.0 to 5.0. | |
| top_k | No | Maximum search results to return. | |
| action | Yes | Registry action to perform. | |
| domain | No | Optional search domain filter. | |
| source | No | Include source files for inspect. | |
| target | No | Install target project root. | |
| comment | No | Optional rating comment. | |
| reviews | No | Include reviews for inspect. | |
| version | No | Version for inspect or install. | |
| language | No | Optional search language filter. | |
| registry | No | Restrict search fan-out to the given registry prefixes (e.g. ['cg'], ['myorg', 'cg']). Without this, all configured registries are searched. | |
| widget_id | No | Widget ID. Use the exact value from the 'id' field returned by search. | |
| local_only | No | Search only the local library; skip all registry calls. Cannot combine with registry/owner. | |
| widget_ref | No | Widget dir path or @handle/widget-id for rate. | |
| all_versions | No | Include all historical versions for inspect. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden of behavioral disclosure. It implies registry interactions (search, install, rate) and gives a precautionary instruction to search before writing reusable logic, though it does not detail side effects like what installing modifies or whether rating is idempotent. That said, it provides a good deal of operational context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a compact paragraph of three sentences that front-loads the tool's purpose and action workflow, then adds the critical instruction about using the exact 'id' value. Every sentence earns its place and no redundant wording exists.
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 this is a multi-action orchestrator with 17 parameters and no output schema, the description could be even more complete. It covers the major workflow rules and parameter linkage but does not mention output shape or error conditions, which would be needed for full self-sufficiency. However, it is strong for an overview-level tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers all parameter descriptions at 100%, so the baseline is 3. The description adds value by linking the 'id' field semantics to widget_id, and clarifying the overall role of each action. However, most parameter meaning is already well captured in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool as a registry-facing daily workflow for Cartograph widgets and blueprints, and enumerates the primary actions (search, inspect, install, rate). It distinguishes itself from siblings by focusing on the registry workflow rather than creation, validation, or status operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit instructions on when to use the tool: use search before writing reusable logic, inspect before installing or editing, install to add a widget, and rate to leave feedback. It also tells the agent to use the exact 'id' value returned by search when installing or inspecting, which is actionable guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List or manage custom validation rules that run during Cartograph validate and checkin.
| Name | Required | Description | Default |
|---|---|---|---|
| scope | No | Whether to target project rules or global rules. Defaults to project. | |
| action | Yes | Rules action to perform. | |
| confirm | No | Required as true for reset. | |
| language | No | Language filter or target. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description alone must disclose behavioral traits. It only states the general purpose but fails to mention side effects (e.g., 'reset' might delete rules), authentication needs, or what happens during 'init'. The schema indicates a 'confirm' boolean for reset, but the description does not reinforce this.
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 that efficiently conveys the core purpose without unnecessary words. It is front-loaded and every part earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has four parameters, no output schema, and no annotations, the description is too sparse. It does not explain what 'init' or 'reset' do, the format of returned data, or how to interpret results. More context is needed for an agent to use this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides full coverage (100%) with descriptions for all four parameters, including enums for 'action' and 'scope'. The description adds no additional meaning beyond 'List or manage', so it meets the baseline but does not exceed it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'List or manage custom validation rules that run during Cartograph validate and checkin.' It specifies both the action (list/manage) and the resource (custom validation rules), and implicitly distinguishes from sibling tools like cg_validate which perform the validation itself.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, nor does it mention prerequisites, limitations, or context-specific usage. For example, it doesn't clarify when to use 'list' vs 'init' vs 'reset' or when to prefer a sibling tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check health/status for installed widgets in the current project. Use this to see if widgets are out of sync with the library, have local modifications, or have updates available. Omit widget_dir to scan all installed widgets; provide a specific directory (e.g. cg/backend-retry-python) to inspect one.
| Name | Required | Description | Default |
|---|---|---|---|
| all | No | Return every widget without pagination. | |
| page | No | 1-indexed page for aggregate listing. | |
| size | No | Page size for aggregate listing. | |
| widget_dir | No | Installed widget directory (e.g. cg-infra-agent-cli-python) or path; omit to scan all. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It implies read-only behavior (check health/status) but does not explicitly state no side effects, permissions needed, or other behavioral traits. Adequate but not comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with purpose, and contains no unnecessary words. It efficiently conveys the key 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?
Given no output schema and moderate complexity, the description sufficiently covers the tool's use (scan all or specific). It does not elaborate on return format or pagination, but the schema handles those. Overall complete for practical use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already describes all parameters. The description adds minimal context for widget_dir (example path) but does not enhance understanding of page, size, or all beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool checks health/status of installed widgets, specifying details like out-of-sync, local modifications, or updates. It distinguishes from sibling tools which perform other operations like architect, blueprint, etc.
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 explicitly advises when to use the tool (to check widget status) and how to use it (omit or provide widget_dir). It does not mention when not to use or alternative tools, but the guidance is clear and practical.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run the full preflight / smoke pipeline without checking the module into the library. Use this as the dry run for checkin before recording reusable changes.
| Name | Required | Description | Default |
|---|---|---|---|
| lib | No | Treat path as a library widget ID. | |
| path | No | Module directory (e.g. cg/backend-retry-python) or ID with lib=true. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries full burden. It states the tool runs a pipeline without checking in, but does not describe failure modes, timeouts, or what happens on success/failure. Adequate but could be more detailed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no wasted words. Front-loaded with action and purpose, then usage guidance. Highly concise.
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 (2 optional params, no output schema). The description covers purpose and usage but doesn't mention what the tool returns or outputs. For a dry run, the return might be important to know, so it's slightly 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 coverage is 100%, so baseline is 3. The description adds no additional meaning to the parameters beyond what the schema already provides for 'path' and 'lib'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool runs a preflight/smoke pipeline as a dry run for checkin. The verb 'validate' combined with 'run the full preflight / smoke pipeline' and context of 'without checking in' distinguishes it from siblings like cg_checkin.
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 explicitly says 'Use this as the dry run for checkin before recording reusable changes,' providing clear when-to-use guidance. It implies not to use instead of cg_checkin, but does not fully list alternatives or when not to use.
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.3.1cg_create2 fields changedInput schema / properties / domain / enumPrevious value: -[
- "analog",
- "backend",
- "data",
- "devops",
- "frontend",
- "infra",
- "ml",
- "modeling",
- "rtl",
- "security",
- "universal"
-]New value: +[
+ "analog",
+ "backend",
+ "data",
+ "devops",
+ "formal",
+ "frontend",
+ "gamedev",
+ "infra",
+ "ml",
+ "modeling",
+ "rtl",
+ "security",
+ "universal"
+]Input schema / properties / language / enumPrevious value: -[
- "angular",
- "go",
- "javascript",
- "nim",
- "openscad",
- "php",
- "python",
- "systemverilog",
- "terraform",
- "typescript"
-]New value: +[
+ "angular",
+ "csharp",
+ "flutter",
+ "gdscript",
+ "go",
+ "java",
+ "javascript",
+ "lean",
+ "nim",
+ "openscad",
+ "php",
+ "python",
+ "rust",
+ "spice",
+ "systemverilog",
+ "terraform",
+ "typescript"
+]cg_registry2 fields changedInput schema / properties / domain / enumPrevious value: -[
- "analog",
- "backend",
- "data",
- "devops",
- "frontend",
- "infra",
- "ml",
- "modeling",
- "rtl",
- "security",
- "universal"
-]New value: +[
+ "analog",
+ "backend",
+ "data",
+ "devops",
+ "formal",
+ "frontend",
+ "gamedev",
+ "infra",
+ "ml",
+ "modeling",
+ "rtl",
+ "security",
+ "universal"
+]Input schema / properties / language / enumPrevious value: -[
- "angular",
- "go",
- "javascript",
- "nim",
- "openscad",
- "php",
- "python",
- "systemverilog",
- "terraform",
- "typescript"
-]New value: +[
+ "angular",
+ "csharp",
+ "flutter",
+ "gdscript",
+ "go",
+ "java",
+ "javascript",
+ "lean",
+ "nim",
+ "openscad",
+ "php",
+ "python",
+ "rust",
+ "spice",
+ "systemverilog",
+ "terraform",
+ "typescript"
+]v0.2.2cg_create2 fields changedInput schema / properties / domain / enumPrevious value: -[
- "backend",
- "data",
- "devops",
- "frontend",
- "infra",
- "ml",
- "modeling",
- "rtl",
- "security",
- "universal"
-]New value: +[
+ "analog",
+ "backend",
+ "data",
+ "devops",
+ "frontend",
+ "infra",
+ "ml",
+ "modeling",
+ "rtl",
+ "security",
+ "universal"
+]Input schema / properties / language / enumPrevious value: -[
- "angular",
- "javascript",
- "nim",
- "php",
- "python",
- "systemverilog",
- "terraform",
- "typescript"
-]New value: +[
+ "angular",
+ "go",
+ "javascript",
+ "nim",
+ "openscad",
+ "php",
+ "python",
+ "systemverilog",
+ "terraform",
+ "typescript"
+]cg_registry2 fields changedInput schema / properties / domain / enumPrevious value: -[
- "backend",
- "data",
- "devops",
- "frontend",
- "infra",
- "ml",
- "modeling",
- "rtl",
- "security",
- "universal"
-]New value: +[
+ "analog",
+ "backend",
+ "data",
+ "devops",
+ "frontend",
+ "infra",
+ "ml",
+ "modeling",
+ "rtl",
+ "security",
+ "universal"
+]Input schema / properties / language / enumPrevious value: -[
- "angular",
- "javascript",
- "nim",
- "php",
- "python",
- "systemverilog",
- "terraform",
- "typescript"
-]New value: +[
+ "angular",
+ "go",
+ "javascript",
+ "nim",
+ "openscad",
+ "php",
+ "python",
+ "systemverilog",
+ "terraform",
+ "typescript"
+]v0.2.1cg_architectcg_config1 field changedInput schema / properties / key / enumPrevious value: -[
- "auto-publish",
- "visibility",
- "governance",
- "cloud",
- "show-unavailable",
- "publish-registry"
-]New value: +[
+ "auto-publish",
+ "auto-update",
+ "cloud",
+ "governance",
+ "publish-registry",
+ "search-priority",
+ "show-unavailable",
+ "visibility"
+]cg_create2 fields changedInput schema / properties / domain / enumPrevious value: -[
- "backend",
- "data",
- "frontend",
- "infra",
- "ml",
- "modeling",
- "rtl",
- "security",
- "universal",
- "devops"
-]New value: +[
+ "backend",
+ "data",
+ "devops",
+ "frontend",
+ "infra",
+ "ml",
+ "modeling",
+ "rtl",
+ "security",
+ "universal"
+]Input schema / properties / language / enumPrevious value: -[
- "angular",
- "javascript",
- "nim",
- "openscad",
- "php",
- "python",
- "systemverilog",
- "typescript"
-]New value: +[
+ "angular",
+ "javascript",
+ "nim",
+ "php",
+ "python",
+ "systemverilog",
+ "terraform",
+ "typescript"
+]cg_helpcg_registry5 fields changedInput schema / properties / domain / enumPrevious value: -[
- "backend",
- "data",
- "frontend",
- "infra",
- "ml",
- "modeling",
- "rtl",
- "security",
- "universal",
- "devops"
-]New value: +[
+ "backend",
+ "data",
+ "devops",
+ "frontend",
+ "infra",
+ "ml",
+ "modeling",
+ "rtl",
+ "security",
+ "universal"
+]Input schema / properties / language / enumPrevious value: -[
- "angular",
- "javascript",
- "nim",
- "openscad",
- "php",
- "python",
- "systemverilog",
- "typescript"
-]New value: +[
+ "angular",
+ "javascript",
+ "nim",
+ "php",
+ "python",
+ "systemverilog",
+ "terraform",
+ "typescript"
+]Input schema / properties / local_onlyAdded value: +{
+ "description": "Search only the local library; skip all registry calls. Cannot combine with registry/owner.",
+ "type": "boolean"
+}Input schema / properties / ownerAdded value: +{
+ "description": "Filter search to widgets owned by @handle. Requires registry (owner is scoped per-registry).",
+ "type": "string"
+}Input schema / properties / registryAdded value: +{
+ "description": "Restrict search fan-out to the given registry prefixes (e.g. ['cg'], ['myorg', 'cg']). Without this, all configured registries are searched.",
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+}v0.1.9cg_architectcg_blueprintcg_checkincg_configcg_createcg_installedcg_registrycg_rulescg_statuscg_validateScored across 10 tools
Tool boundaries are mostly clear: registry, installed widgets, status, creation, validation/checkin, blueprint, config, rules, and help each target a distinct area. The only mild ambiguities are between cg_registry and cg_installed, and cg_validate vs cg_checkin, but the descriptions draw useful separation lines.
All tools share the cg_ prefix and lowercase style, which is good, but the semantic pattern is mixed: some are actions (create, validate, checkin), while others are nouns or states (registry, status, blueprint, config, rules). It is readable and predictable, but not a consistent verb_noun convention.
Ten tools is well-scoped for a widget registry/workflow server. Each tool covers a meaningful slice of the lifecycle, and the count is neither bloated nor too thin for the stated purpose.
The surface covers the main workflow: scaffold, validate, check in, install, uninstall, upgrade, inspect status, manage dependencies, configure defaults, and resolve errors. Minor gaps exist around explicit registry removal or metadata editing, but agents can likely work around those with existing tools.
Embed an AI chat widget on your website from your coding agent: provision, configure, get snippet.
Develop, manage, and debug Railway projects, services, and deployments from within agents.
Set up and run an in-product AI assistant: widgets, knowledge, MCP connections, usage.
Search, fetch, lint, and install Agent Skills (SKILL.md) from the SkillMD registry.
