This server provides a Model Context Protocol (MCP) interface to a drevo knowledge graph (Neo4j-compatible), enabling AI clients to perform comprehensive read and write operations within project-scoped graphs.
Entity Management: Create or merge entities with name, type, project, observations, and properties (create_entity); append observations (add_observations); delete entities and all relationships (delete_entity).
Relationship Management: Create typed, directed relationships with optional properties (create_relationship); delete specific relationships (delete_relationship).
Querying & Search: Retrieve a single entity with its relationships (get_entity); text search by name or observations (search_knowledge); get the full project graph (get_project_graph); list all projects (list_projects).
Scored Search: Perform BM25 full-text search (fts_search), vector ANN search (vector_search), and semantic search with automatic FTS fallback (semantic_search).
Schema Migrations: Record, view, and apply versioned Cypher migrations (add_migration, get_migrations, apply_migration).
Raw Cypher Execution: Run arbitrary Cypher queries for read/write access beyond predefined tools (run_cypher).
Provides tools for interacting with a Neo4j-compatible graph database (drevo) with full read and write access, enabling AI agents to manage entities, relationships, and execute Cypher queries.
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., "@drevo-mcp show me all nodes of type Person"
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.
A self-contained knowledge-graph MCP server that exposes a running drevo graph database to AI clients (Claude Code, Claude Desktop, OpenCode, Cline, …) as Model Context Protocol tools — with full read and write access.
It is a Bolt drop-in of the Neo4j knowledge-graph MCP: the same tools and the
same Cypher, but pointed at drevo's Neo4j-compatible Bolt endpoint instead of
Neo4j. drevo-server speaks Bolt (the official neo4j driver accepts it) and the
Cypher subset these tools use (MERGE / datetime() / SET += / map projection
/ labels() / type() / properties() / OPTIONAL MATCH / collect), so it is
a genuine copy-and-swap.
MCP client ──stdio(MCP)──▶ drevo-mcp-bolt (this repo) ──Bolt (neo4j driver)──▶ drevo-server :7687 ──▶ drevo.redbUnlike a plain HTTP wrapper, this MCP mutates the graph: it can create and delete entities and relationships, append observations, record and apply schema migrations, and run arbitrary Cypher. One process owns the redb file (the container); this MCP is just a Bolt client.
This repo is self-contained: it ships the Python MCP, a docker-compose.yml
and a scripts/run-drevo.sh helper that pull and start the published
ice1x/drevo image with Bolt enabled,
and the client configuration snippets below.
The one drevo difference from real Neo4j: CREATE INDEX schema DDL is unsupported
(drevo auto-indexes), so index creation is best-effort and a no-op on drevo.
Related MCP server: kg-mcp
Docker (to run the drevo-server container), and
Python ≥ 3.13 (to run this MCP server).
The MCP server is a normal Python process that an AI client spawns over stdio; the database is a separate container it reaches over Bolt (port 7687).
The MCP server needs a running drevo-server with its Bolt listener open. The
Bolt listener is opt-in: the server only opens 7687 when DREVO_BOLT_PORT is set.
The compose file and helper script in this repo set it for you. The image lives on
Docker Hub: https://hub.docker.com/r/ice1x/drevo. Pick any one way below.
./scripts/run-drevo.sh # pulls ice1x/drevo:latest, enables Bolt, waits for /healthIt pulls the image, bind-mounts ./data for the redb file, runs the container as
your host user, sets DREVO_BOLT_PORT=7687, and blocks until GET /health is
green. Other sub-commands:
./scripts/run-drevo.sh logs # follow container logs
./scripts/run-drevo.sh stop # stop & remove the container (host data kept)Override defaults with env vars, e.g.:
DREVO_TAG=0.1.0 DREVO_PORT=9090 DREVO_BOLT_PORT=7687 DREVO_DATA_DIR=~/drevo_data ./scripts/run-drevo.shmkdir -p ./data
DREVO_UID=$(id -u) DREVO_GID=$(id -g) docker compose up -d
docker compose logs -f # watch it boot
docker compose down # stop later (host data dir is left untouched)The compose file sets DREVO_BOLT_PORT=7687 and publishes it. docker compose pull refreshes to the newest latest.
docker runmkdir -p ./data
docker run -d --name drevo \
-p 8080:8080 -p 7687:7687 \
--user "$(id -u):$(id -g)" \
-e DREVO_HOST=0.0.0.0 -e DREVO_PORT=8080 -e DREVO_BOLT_PORT=7687 -e DREVO_DATA_DIR=/data \
-v "$(pwd)/data:/data" \
ice1x/drevo:latestcurl localhost:8080/health # {"status":"ok"}
nc -z localhost 7687 && echo "bolt open" # the Bolt listener must be open
open http://localhost:8080/ui # interactive graph Web UI (macOS; use your browser elsewhere)What the container exposes:
Port | Purpose |
8080 | HTTP API and the embedded Web UI ( |
7687 | Bolt (Neo4j-compatible) — what this MCP uses |
The redb database file is persisted on the host at ./data/drevo.redb (or
wherever DREVO_DATA_DIR points), so it survives down/stop.
Install the package into a Python environment. A virtualenv is recommended so the AI client can launch a known interpreter:
python -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install -e . # from this repo rootNote the absolute path to that interpreter — you will point the MCP client at
it so it does not depend on PATH:
python -c "import sys; print(sys.executable)"
# e.g. /Users/you/repo/drevo-mcp/.venv/bin/pythonSmoke-test the MCP protocol without any client — pipe three JSON-RPC lines in and watch the tool list come back:
export DREVO_BOLT_URL=bolt://localhost:7687 # default; override if elsewhere
printf '%s\n' \
'{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"probe","version":"0"}}}' \
'{"jsonrpc":"2.0","method":"notifications/initialized"}' \
'{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' \
| python -m drevo_mcp_boltYou should see a JSON-RPC response listing create_entity, search_knowledge,
run_cypher, etc. If you do, the server and the container are talking over Bolt.
drevo's Bolt runs without authentication, so the username / password are accepted and ignored — they only matter against a real Neo4j.
All clients launch the same command — python -m drevo_mcp_bolt — and pass the
target server via the DREVO_BOLT_URL environment variable. Use the absolute
path to your venv's python (from Step 2) as the command to avoid PATH
surprises; below it is written as /abs/path/to/.venv/bin/python.
Easiest is the CLI (run it from anywhere):
claude mcp add drevo \
--env DREVO_BOLT_URL=bolt://localhost:7687 \
-- /abs/path/to/.venv/bin/python -m drevo_mcp_boltAdd --scope project to write a shareable .mcp.json into the current repo
instead of your user config. That file looks like:
{
"mcpServers": {
"drevo": {
"command": "/abs/path/to/.venv/bin/python",
"args": ["-m", "drevo_mcp_bolt"],
"env": { "DREVO_BOLT_URL": "bolt://localhost:7687" }
}
}
}Verify inside Claude Code with /mcp — drevo should be listed as connected.
OpenCode reads opencode.json (project root) or ~/.config/opencode/opencode.json.
MCP servers go under the mcp key as a local (stdio) server:
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"drevo": {
"type": "local",
"command": ["/abs/path/to/.venv/bin/python", "-m", "drevo_mcp_bolt"],
"enabled": true,
"environment": { "DREVO_BOLT_URL": "bolt://localhost:7687" }
}
}
}Note OpenCode's spelling: the program + args are a single command array, and the
env block is environment (not env).
Open Cline → MCP Servers → Configure MCP Servers, which opens
cline_mcp_settings.json. Add:
{
"mcpServers": {
"drevo": {
"command": "/abs/path/to/.venv/bin/python",
"args": ["-m", "drevo_mcp_bolt"],
"env": { "DREVO_BOLT_URL": "bolt://localhost:7687" },
"disabled": false,
"autoApprove": ["get_entity", "search_knowledge", "get_project_graph",
"list_projects", "get_migrations"]
}
}
}Unlike the read-only HTTP MCP, these tools mutate the graph — create_entity,
delete_entity, create_relationship, delete_relationship, apply_migration
and run_cypher can change or remove data. Keep those out of autoApprove
(as above, only the read tools are listed) so each write asks for a confirmation.
Edit claude_desktop_config.json (macOS:
~/Library/Application Support/Claude/claude_desktop_config.json) and add the same
mcpServers block shown for Claude Code, then restart the app.
The server exposes fourteen tools — read, write, and migration. The JSON
Schema for each is generated automatically by FastMCP from the function
signatures, so clients discover arguments via tools/list.
Tool | Arguments | Effect |
|
| Create or merge an entity ( |
|
| Append observations to an existing entity. |
|
| Delete an entity and all its relationships ( |
Tool | Arguments | Effect |
|
| Create a typed relationship between two entities. |
|
| Delete a specific relationship. |
Tool | Arguments | Returns |
|
| The entity with its incoming and outgoing relationships. |
|
| Entities matching |
|
| The full entity/relationship graph for a project. |
| — | All distinct project namespaces. |
Ranked retrieval over drevo's CALL fts.search (BM25 full-text) and
CALL drevo.vector.query (vector ANN) procedures. Each row is
{"node": {...}, "score": <float>}, ordered best-first. Entities written
through this MCP are searchable because create_entity / add_observations
mirror name + observations into the drevo-indexed body field.
Tool | Arguments | Returns |
|
| Top- |
|
| Top- |
|
| Embed the |
|
| Run |
hybrid_search combines the two retrievers over a shared pool of candidates
(at least k) and merges them by Reciprocal Rank Fusion — fusing on rank,
not score, so BM25's and cosine's incomparable scales need no calibration. rrf_k
(default 60) damps how strongly the top ranks dominate. Lexical catches exact
terms/names/codes, vectors catch meaning, so the fused ranking usually beats
either alone. Like semantic_search, it degrades to lexical BM25 (top-k,
unfused) when embeddings are unavailable, unless fallback_to_fts=false.
semantic_search is the self-contained-RAG path: one drevo instance embeds the
query and searches the graph, so no external embedder is needed. It calls
drevo's OpenAI-compatible POST {DREVO_HTTP_URL}/v1/embeddings (drevo issue
#217). It requires drevo built with the embeddings-proxy feature and an
upstream configured (DREVO_EMBEDDINGS_UPSTREAM). Set DREVO_HTTP_URL
(default http://localhost:8080) to drevo's HTTP base.
Works without an LLM: when embeddings are not configured (drevo answers
503) or the upstream errors, semantic_search transparently degrades to
fts_search (lexical BM25 over the query text) so you still get relevant nodes
— the fallback searches indexed node text graph-wide rather than
label.prop embeddings. Pass fallback_to_fts=false to get an
embedding_error envelope instead.
Tool | Arguments | Effect |
|
| Record a schema/data migration (not yet applied). |
|
| The migration history for a project. |
|
| Execute a pending migration's |
Tool | Arguments | Effect |
|
| Execute an arbitrary Cypher query — can read or mutate. |
Once connected, just ask the assistant in natural language — it picks the tools:
"Add a service entity called billing to project erp." → create_entity(name="billing", entity_type="service", project="erp")
"Note that billing now depends on payments." → create_relationship("billing", "payments", "DEPENDS_ON", "erp")
"What do we know about billing in erp?" → get_entity("billing", "erp")
"Search the erp graph for anything about invoices." → search_knowledge("invoice", "erp")
"Show me the whole erp project graph." → get_project_graph("erp")
"Remove the billing→payments dependency." → delete_relationship("billing", "payments", "DEPENDS_ON", "erp")
A reliable pattern: create_entity for the nodes → create_relationship to
link them → get_project_graph / search_knowledge to read back.
This MCP models a project-scoped knowledge graph (the Neo4j knowledge-graph shape), which is a thin layer over drevo's property graph:
An entity is a node labelled Entity with a name, a type, a list of
observations (free-text facts), arbitrary properties, and a project
namespace. Entities are unique per (name, project).
A relationship is a typed, directed edge between two entities in the same
project (e.g. DEPENDS_ON, KNOWS, PART_OF). Relationship types are
sanitised to upper-snake-case.
A project is just the project property — every tool takes it so multiple
knowledge graphs can live in one drevo instance without colliding. Discover the
ones that exist with list_projects.
A migration is a Migration node recording a cypher_up / cypher_down
pair, sequenced per project, that apply_migration executes on demand.
You generally pick your own entity/relationship types per scenario, for example:
Scenario | Example entity types | Example relationship types |
IT task manager |
|
|
Bug tracker |
|
|
Story / book editor |
|
|
CBT journal |
|
|
ERP |
|
|
For anything the tool surface doesn't cover directly, run_cypher runs arbitrary
Cypher against the same graph.
This MCP server reads these environment variables:
Variable | Default | Meaning |
|
| Bolt URI of the running |
|
| Username (accepted and ignored by drevo). |
|
| Password (accepted and ignored by drevo). |
|
| Bolt database name. |
The container (Step 1) reads these, mirrored by the compose file and the helper script:
Variable | Default | Meaning |
|
| Image tag to pull ( |
|
| Host port mapped to the container's HTTP API. |
|
| Host port mapped to the Bolt endpoint and the env var that opens the listener. |
|
| Host folder bind-mounted to |
|
| UID/GID the container runs as (set to |
pip install -e ".[dev]"
pytest # unit tests run offline (no live server needed)
mypy --strict drevo_mcp_bolt/
ruff check . && black --check .The unit tests run offline. The end-to-end test in tests/test_integration.py is
opt-in: it drives a real Bolt server and is skipped unless DREVO_BOLT_URL
is set and the port is open. To run it against the container from Step 1:
DREVO_BOLT_URL=bolt://localhost:7687 pytest -q tests/test_integration.pyIt writes only into a throwaway it-… project namespace and deletes everything
it creates.
Tool calls fail with a connection error — the container isn't up, Bolt isn't
enabled, or DREVO_BOLT_URL is wrong. Check nc -z localhost 7687; if it is
closed, the server was started without DREVO_BOLT_PORT (use the compose file /
helper script in this repo, which set it).
Client shows the server as "failed to start" — the command likely isn't
the interpreter where this package is installed. Use the absolute path to your
venv's python (Step 2).
CREATE INDEX errors in logs — harmless: drevo auto-indexes and rejects
schema DDL, so index creation is best-effort and ignored.
Permission denied writing drevo.redb — the container user can't write the
bind-mounted folder. Start it as your host user (--user $(id -u):$(id -g),
which the script and compose file already do).
Dual-licensed under MIT or Apache-2.0. See LICENSE.
Record a graph schema/data migration for a project.
| Name | Required | Description | Default |
|---|---|---|---|
| project | Yes | ||
| version | No | ||
| cypher_up | Yes | ||
| cypher_down | No | ||
| description | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description carries the full burden but only says 'Record', which implies creation, without disclosing idempotency, side effects, permissions, or return behavior. The output schema exists but is not described.
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, but it is under-specified, sacrificing necessary detail 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?
Given 5 parameters, no annotations, and sibling tools that suggest a migration workflow, the description fails to explain how this tool fits into the broader process or what the output contains.
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?
With 0% schema description coverage, the description adds no meaning beyond the schema. It does not explain the purpose of cypher_up, cypher_down, version, or how they relate to the migration process.
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 action (Record), the resource (graph schema/data migration), and the scope (for a project). It effectively distinguishes from sibling tools like apply_migration and get_migrations.
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 such as apply_migration or run_cypher. There is no mention of prerequisites, ordering, or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Append new observations to an existing entity.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| project | Yes | ||
| observations | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist. The description only says 'append new observations' without disclosing side effects, error states (e.g., if entity doesn't exist), permissions, or idempotency. For a mutation tool, this is insufficient.
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 sentence—efficient but overly minimal. It conveys the basic purpose but omits critical details, making it borderline under-specified.
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 3 required parameters, no parameter descriptions, no annotations, and only a one-sentence description, the agent lacks enough context to correctly invoke the tool. The existence of an output schema does not compensate for missing usage context.
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%. The description does not explain any parameters (name, project, observations) beyond their schema types and requirements. The agent gains no added meaning 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?
The description clearly states the verb 'append' and the resource 'observations to an existing entity', which is specific and distinct from sibling tools like create_entity or delete_entity.
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?
Implied usage: it appends observations to an existing entity. But no explicit guidance on when to use or when not to, nor any alternatives mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Execute a pending migration and mark it as applied.
| Name | Required | Description | Default |
|---|---|---|---|
| seq | Yes | ||
| project | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It only states it 'executes' and 'marks as applied' but doesn't mention side effects, idempotency, error handling, or required permissions. For a mutation tool, this is insufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no wasted words. It is front-loaded but lacks structure for additional details. While efficient, it sacrifices completeness 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?
Given no annotations and no parameter descriptions, the description is incomplete. It does not cover return values despite an existing output schema. The tool is simple but the description fails to provide sufficient context for an agent.
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 the parameters. 'project' and 'seq' are not described, leaving the agent uncertain about what values to provide. This is a significant 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 clearly states 'Execute a pending migration and mark it as applied.' This specifies the verb (execute), resource (migration), and outcome (mark as applied), effectively distinguishing it from sibling tools like add_migration or get_migrations.
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 on when to use this tool versus alternatives. No prerequisites, conditions, or exclusions are mentioned. The description does not help the agent decide between apply_migration and other migration-related tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create or update a knowledge entity in the graph.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| project | Yes | ||
| properties | No | ||
| entity_type | Yes | ||
| observations | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description must disclose behavioral traits. It only states 'create or update' without mentioning permissions, side effects, return format, or error conditions. The output schema exists but is not referenced.
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, but it is under-specified and fails to provide necessary details to justify its brevity. Conciseness is valuable only when information is complete enough.
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 complexity of the tool (5 parameters, mutation behavior, output schema), the description is very incomplete. It lacks parameter explanations, usage context, and behavioral notes, making it barely adequate even with the output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description adds no explanation for any of the five parameters (name, project, properties, entity_type, observations). Parameter names are only vaguely self-explanatory, leaving significant ambiguity.
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 action ('create or update') and the resource ('a knowledge entity in the graph'). However, it does not distinguish itself from sibling tools like 'add_observations' or 'create_relationship', leaving ambiguity about when to use this tool versus alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No usage guidelines are provided. The description does not indicate when to create versus update, or specify prerequisites or contexts where this tool is appropriate versus using other tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a typed relationship between two entities.
| Name | Required | Description | Default |
|---|---|---|---|
| project | Yes | ||
| to_entity | Yes | ||
| properties | No | ||
| from_entity | Yes | ||
| relation_type | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It only says 'create', implying mutation, but does not disclose side effects, authorization needs, idempotency, or what happens if the relationship already exists. The lack of detail limits agent understanding of consequences.
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, which is concise but overly terse. It could add a second sentence to clarify required parameters or the meaning of 'typed' without becoming verbose. Currently it under-delivers.
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 5 parameters (4 required) and an output schema, the description is insufficient. It does not explain parameter roles, output expectations, or how this relates to siblings like run_cypher. An agent would lack critical context for correct invocation.
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 information about the parameters (from_entity, to_entity, relation_type, project, properties). Parameter names offer some clues, but without descriptions, an agent cannot infer expected formats or constraints, especially for the complex 'properties' object.
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 action ('create') and the resource ('relationship'), and specifies it is 'typed' and involves two entities. This distinguishes it from siblings like delete_relationship and create_entity. However, it could elaborate on what 'typed' means in terms of relation types.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like run_cypher (which can also create relationships), or when not to use it. There is no mention of prerequisites or context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete an entity and all its relationships.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| project | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden. It states destructive action but omits details on cascading effects, permissions, or return value (output schema exists but not explained). Limited behavioral disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Though very short, the single sentence is under-informative for a tool with 2 required params and no parameter guidance. It sacrifices comprehensiveness 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?
Given low complexity (2 params, no enums), the description is still incomplete: missing usage guidelines, parameter semantics, and behavioral details. Output schema existence is not leveraged in the description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description provides no meaning for the 'name' and 'project' parameters. The agent must infer their purpose without any textual help.
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 action ('Delete'), the resource ('an entity'), and the scope ('and all its relationships'), distinguishing it from siblings like delete_relationship and create_entity.
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 on when to use this tool vs alternatives such as delete_relationship, or prerequisites like the entity existing. The description lacks context for appropriate usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a relationship between two entities.
| Name | Required | Description | Default |
|---|---|---|---|
| project | Yes | ||
| to_entity | Yes | ||
| from_entity | Yes | ||
| relation_type | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It only states 'delete' but does not describe any side effects, such as whether the relationship is actually removed or cascading effects, or what happens if the relationship does not exist.
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, which is concise, but it lacks structure and important details. It is not overly verbose, but it is under-specified.
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 4 required parameters, no annotations, and low schema coverage, the description provides very little context. It does not mention the output, error scenarios, or behavior on non-existent relationships. It is incomplete for effective 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?
The schema has 0% coverage, and the description does not add any meaning to the parameters. It does not explain what from_entity, to_entity, relation_type, or project represent. No mapping from description to parameters.
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 'delete' and the resource 'relationship', and specifies it is between two entities, differentiating it from sibling tools like delete_entity or create_relationship.
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 on when to use this tool vs alternatives such as delete_entity or run_cypher. No context on required permissions or consequences.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get an entity with all its incoming and outgoing relationships.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| project | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description mentions returning all incoming and outgoing relationships, which is a behavioral trait beyond a simple fetch. However, without annotations, it does not disclose potential depth limits, performance implications, or whether relationships are shallow or deep.
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?
Single sentence, no fluff, front-loaded with purpose.
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, description does not need to detail return values. However, the lack of usage guidelines and parameter semantics makes the description incomplete for an agent to confidently invoke the 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 0% meaning no parameter descriptions in schema. The tool description does not explain the parameters 'name' or 'project', leaving the agent to infer meaning from their names alone.
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 states the verb 'Get', the resource 'entity', and the scope 'with all its incoming and outgoing relationships'. This distinguishes it from sibling tools like 'search_knowledge' or 'get_project_graph'.
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 on when to use this tool versus alternatives like 'get_project_graph' or 'search_knowledge'. No exclusions or context provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the full migration history for a project.
| Name | Required | Description | Default |
|---|---|---|---|
| project | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It merely states 'full migration history' without disclosing any behavioral traits like idempotency, rate limits, permissions, or what 'full' entails. Minimal transparency.
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 waste, but it is underspecified and lacks structure. Front-loading is adequate, but brevity comes at the cost of completeness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (1 parameter, output schema exists), the description is minimally adequate. However, it does not cover context like project identification or output expectations beyond 'history'.
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 0% for the single parameter 'project'. The description adds no extra meaning about the parameter's format, source, or constraints, failing to compensate for the lack of schema documentation.
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 'Get the full migration history for a project,' specifying the action, resource, and scope. It distinguishes from sibling tools like add_migration or apply_migration which deal with individual migrations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use for retrieving migration history but provides no explicit when-to-use or when-not-to-use guidance, nor alternatives. The purpose is clear but lacks contextual usage direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the complete knowledge graph for a project.
| Name | Required | Description | Default |
|---|---|---|---|
| project | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description carries full burden for behavioral disclosure. It only states 'get' and 'complete,' without detailing what 'complete' entails, pagination, authentication needs, or any side effects. Minimal transparency.
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 short sentence that is front-loaded and free of fluff. However, it may be under-specified; conciseness is appropriate but brevity sacrifices detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having an output schema, the description does not explain what 'complete knowledge graph' means or any limitations. For a tool returning a complex structure, this is insufficient context.
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 adds no meaning to the single 'project' parameter. It does not clarify format (e.g., ID or name) or provide constraints, leaving the agent with no guidance beyond the property name.
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 states the tool retrieves the complete knowledge graph for a project, with a specific verb and resource. It is distinct from siblings like get_entity (single entity) and search_knowledge (search).
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 explicit guidance on when to use this tool versus alternatives like get_entity or run_cypher. The description implies usage for full graph retrieval but provides no exclusions or context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all projects stored in the knowledge graph.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description bears full responsibility for behavioral disclosure. It only states 'list all projects' without mentioning pagination, ordering, or any side effects, leaving significant gaps.
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 wasted words. It efficiently communicates the tool's purpose.
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 absence of parameters and the presence of an output schema, the description is largely adequate. However, it could briefly hint at the output format or scope to enhance completeness.
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?
There are no parameters, so schema coverage is 100%. The description does not need to add parameter information, and it effectively conveys the tool's trivial input requirements.
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 'List' and the resource 'all projects' within the knowledge graph. It is specific and distinguishes from sibling tools like 'get_project_graph' or 'search_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?
The description implies usage for retrieving all projects, but provides no explicit guidance on when to use this tool versus alternatives (e.g., no mention of limits or filtering capabilities).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Execute a Cypher query against the knowledge graph.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | ||
| params | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden but only says 'Execute,' which implies the query may read or write. No disclosure of side effects, permissions, or rate limits. Minimal transparency.
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 short sentence, which is concise but lacks essential details. It earns its place but does not provide sufficient 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?
Despite having an output schema (not shown) and only two parameters, the description is too sparse to guide an agent effectively. It does not explain return values or behavior.
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 adds no meaning beyond the schema field names. The two parameters (query, params) remain entirely undocumented.
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 'Execute' and the resource 'Cypher query against the knowledge graph,' making the tool's purpose unambiguous and distinct from siblings like create_entity or search_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 on when to use this tool versus alternatives (e.g., search_knowledge for natural language queries). No exclusions or prerequisites are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search the knowledge graph by text (entity names and observations).
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | ||
| project | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It does not disclose search behavior (e.g., full-text vs exact, pagination, limits, or case sensitivity), leaving the agent without critical operational details.
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 that is concise and front-loaded. Every word contributes to the purpose. No redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity and lack of schema descriptions, the description is too minimal. It omits search result ordering, filtering scope, and expected behavior, despite having an output schema which reduces need for return value details.
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 elaborate on the 'query' or 'project' parameters. The agent learns nothing beyond type and requirement, which is insufficient.
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 searches the knowledge graph by text, specifically entity names and observations, setting it apart from siblings like get_entity or get_project_graph which use IDs or full graph retrieval.
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 explicit guidance on when to use versus alternatives like run_cypher or get_entity. The description implies text-based search but does not mention exclusions or conditions.
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.0add_migrationadd_observationsapply_migrationcreate_entitycreate_relationshipdelete_entitydelete_relationshipget_entityget_migrationsget_project_graphlist_projectsrun_cyphersearch_knowledgeScored across 13 tools
Each tool has a clearly distinct purpose: entity CRUD, relationship CRUD, observations, graph queries, migrations, and project listing. Even similar tools like run_cypher and search_knowledge are differentiated by description.
All tool names follow a consistent verb_noun pattern with underscores (e.g., create_entity, delete_relationship, get_migrations), making them predictable and easy to parse.
13 tools is well-scoped for a knowledge graph management system, covering core operations without being too many or too few.
CRUD for entities and relationships is missing update operations, and there are no dedicated list tools for entities or relationships (only search_knowledge and get_project_graph). This leaves notable gaps in basic discovery workflows.
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
Repository knowledge graph MCP server for codebase understanding and debugging.
Token-free MCP server for structured RevoGrid Core, Pro, and Enterprise knowledge retrieval.
Hosted MCP server for AI-driven data ops. Create apps, manage schemas, and CRUD structured data.
