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., "@MCP Notes create a new entity named 'Error Handling' with type 'concept'"
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 Notes is a powerful memory server that helps AI assistants remember and connect information over time. Think of it as a smart knowledge graph where you can store facts about people, projects, or concepts, link them together, and retrieve them intelligently—perfect for building AI agents with long-term memory.
Whether you're tracking user preferences, maintaining project context, or building relationship maps, MCP Notes provides a structured way to persist, search, and traverse your knowledge graph with confidence scores, timestamps, and rich metadata.
🏗️ Entity Management - Create, read, search, and delete entities with types and observations
📝 Observation Tracking - Add and remove observations with timestamps, confidence scores, and sources
🔗 Relation Management - Create and delete relations between entities to build connections
🔍 Knowledge Graph Operations - Read the entire graph, search for specific nodes, or traverse connected entities
⏰ Temporal Queries - Query entities by time range using createdAt/updatedAt timestamps
🚶 Graph Traversal - Walk relations to find connected entities (multi-hop BFS)
📊 Rich Metadata - Support for optional metadata, confidence scores, and source tracking
🔄 Auto-Migration - Automatically migrates legacy plain-string observations to rich format on load
💾 Persistent Storage - JSON file storage with daily logging for reliability
Related MCP server: KGrag MCP Server
# Clone the repository
git clone <your-repo-url>
cd mcp_notes
# Install dependencies
npm install
# Build the TypeScript code
npm run buildnpm startThe server runs on stdio and connects to any MCP-compatible client.
{
"entities": [
{
"name": "Alice",
"entityType": "person",
"observations": [
"Alice is a software engineer",
{
"content": "Alice lives in San Francisco",
"confidence": 0.9,
"source": "user_profile"
}
]
}
]
}Create relations between entities:
{
"relations": [
{
"from": "Alice",
"to": "Bob",
"relationType": "works with"
}
]
}create_entitiesCreate multiple new entities in the knowledge graph.
Parameters:
entities (array): Array of entity objects with:
name (string): The name of the entity
entityType (string): The type of the entity
observations (array): Initial observations (can be strings or objects with content, confidence, source)
metadata (object, optional): Additional metadata for the entity
add_observationsAdd new observations to existing entities.
Parameters:
observations (array): Array of observation additions with:
entityName (string): Name of the entity
contents (array): Observations to add (can be strings or objects with content, confidence, source)
create_relationsCreate relations between entities.
Parameters:
relations (array): Array of relation objects with:
from (string): Source entity name
to (string): Target entity name
relationType (string): Type of relation (use active voice)
delete_entitiesDelete entities and their associated relations.
Parameters:
entityNames (array of strings): Names of entities to delete
delete_observationsDelete specific observations from entities.
Parameters:
deletions (array): Array of deletion objects with:
entityName (string): Name of the entity
observations (array of strings): Observations to delete
delete_relationsDelete relations from the knowledge graph.
Parameters:
relations (array): Array of relation objects to delete
open_nodesRetrieve specific entities by name.
Parameters:
names (array of strings): Entity names to retrieve
read_graphRead the entire knowledge graph including all entities and relations.
search_nodesSearch for entities matching a query.
Parameters:
query (string): Search query (matches entity names, types, and observation content)
query_by_timeQuery entities and observations by time range using createdAt/updatedAt timestamps.
Parameters:
since (string, optional): ISO timestamp for start of time range (inclusive)
until (string, optional): ISO timestamp for end of time range (inclusive)
limit (number, optional): Maximum number of results to return
sort (string, optional): Sort order by updatedAt - "asc" or "desc" (default: "desc")
get_recentGet the most recently updated entities.
Parameters:
limit (number, optional): Maximum number of recent entities to return (default: 10)
traverse_graphTraverse the knowledge graph from a starting entity to find connected entities via relations.
Parameters:
start (string, required): Name of the entity to start traversal from
depth (number, optional): Number of hops to traverse (default: 1)
direction (string, optional): Direction of traversal - "out" (outgoing relations), "in" (incoming relations), or "both" (default: "both")
# Build
npm run build
# Watch mode for development
npm run devTypeScript types are defined in src/types.ts for:
Entity (with createdAt, updatedAt, metadata)
Observation (with content, createdAt, confidence, source)
Relation
ObservationAddition
ObservationDeletion
RelationDeletion
KnowledgeGraph
GraphTraversalResult
Observations are rich objects with metadata:
interface Observation {
content: string;
createdAt: string; // ISO timestamp
confidence?: number; // 0-1
source?: string;
}Entities include timestamps and optional metadata:
interface Entity {
name: string;
entityType: string;
observations: Observation[];
createdAt: string; // ISO timestamp
updatedAt: string; // ISO timestamp
metadata?: Record<string, unknown>;
}Legacy data with plain-string observations is automatically migrated on load. Plain strings are converted to Observation objects with createdAt set to the current time.
Add this server to your MCP client configuration:
{
"mcpServers": {
"memory": {
"command": "node",
"args": ["/path/to/mcp_notes/dist/index.js"]
}
}
}src/index.ts - Main MCP server with tool handlers
src/memoryService.ts - Core memory service managing the knowledge graph
src/types.ts - TypeScript type definitions
MIT
Add new observations to existing entities in the knowledge graph
| Name | Required | Description | Default |
|---|---|---|---|
| observations | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must fully disclose behavior. It only states that observations are added to existing entities, but fails to explain what happens if the entity doesn't exist, whether observations are appended or overwritten, idempotency, limits, or side effects.
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 that is front-loaded with the verb and resource. However, it lacks any structural elements like bullet points or additional context that could improve scannability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has one complex parameter (nested array) and no output schema or annotations. The description does not cover error handling, return values, or constraints on input data, making it insufficient for an agent to invoke correctly without additional knowledge.
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% (according to context), and the description does not compensate by explaining any parameters. It does not mention entityName, contents, or the structure of the input, leaving the agent to rely solely on 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 verb 'add' and the resource 'observations to existing entities', distinguishing it from sibling tools like create_entities (which creates new entities) and delete_observations (which removes them).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, such as using create_entities to add new entities first, or using delete_observations to remove observations. No context, 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.
Create multiple new entities in the knowledge graph
| Name | Required | Description | Default |
|---|---|---|---|
| entities | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description only states 'create', implying mutation. It does not disclose side effects, limits, error behaviors, or what happens on duplicate entries. 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, front-loaded sentence with no wasted words. However, it is so concise that it omits important details, making it slightly less effective.
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 a complex parameter (array of objects) and no output schema, the description is too brief. It lacks information on return values, error handling, or batch behavior, leaving gaps for an AI 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 reported as 0%, and the description does not add any meaning to the parameters. Although the input schema has some descriptions, the context indicates they are not considered; the description should compensate but fails to do so.
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 ('Create'), the resource ('multiple new entities'), and the context ('in the knowledge graph'). It distinguishes from sibling tools like add_observations (adds to existing entities) and create_relations (creates relations).
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. There is no mention of preconditions, when not to use, or comparisons with sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create multiple new relations between entities in the knowledge graph. Relations should be in active voice
| Name | Required | Description | Default |
|---|---|---|---|
| relations | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It only states 'create' and offers an active-voice guideline, but does not mention idempotency, validation of from/to entities, behavior on duplicates, or error handling.
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 a brief second clause. Every word earns its place and the main purpose is front-loaded.
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 no annotations or output schema, the description is too sparse. It omits critical details such as whether from/to entities must already exist, how duplicates are handled, and whether creation is atomic for the batch.
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% at the top level, so the description needed to compensate. It adds the active-voice guideline but does not explain the structure of the relations array or the meaning of from/to/relationType, which the schema already partially covers.
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), the object (multiple new relations), and the context (knowledge graph). It distinguishes from siblings like delete_relations and create_entities.
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 this tool is for creating relations, but it does not explicitly state when to use it versus alternatives or mention any prerequisites. The active-voice guideline is a style note, not usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete multiple entities and their associated relations from the knowledge graph
| Name | Required | Description | Default |
|---|---|---|---|
| entityNames | Yes | An array of entity names to delete |
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 does disclose that associated relations are deleted as part of the operation, which is a useful behavioral detail. However, it does not mention irreversibility, permissions, or whether observations are affected, leaving gaps in 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 concise sentence that front-loads the action and scope with no unnecessary words. Every word contributes to understanding 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?
For a simple one-parameter destructive tool with no output schema, the description conveys the core purpose but omits behavioral details such as error handling, atomicity, and return values. Given the lack of annotations, it is moderately complete but has room for improvement.
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 has 100% coverage of the parameter 'entityNames' with a description, so the baseline is 3. The tool description does not add any additional parameter semantics beyond what the schema already provides.
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 deletes multiple entities and their associated relations, using a specific verb ('Delete') and resource ('entities' and 'relations'). It distinguishes itself from sibling tools like delete_relations, which only handle relations, and delete_observations, which handles observations.
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 such as delete_relations or delete_observations. It does not state any exclusions, prerequisites, or scenarios where another tool would be more appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete specific observations from entities in the knowledge graph
| Name | Required | Description | Default |
|---|---|---|---|
| deletions | 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 the action without mentioning permanence, side effects, required permissions, or return format. As 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 sentence that directly conveys the core action, with no unnecessary words. It is well-structured and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has a non-trivial parameter schema and no output schema or annotations. The description is too minimal to fully inform usage, lacking details on how to specify deletions and what to expect in response.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description does not explain the 'deletions' parameter structure. Schema coverage is 0% for the top-level parameter, and the description adds no semantic meaning beyond the schema's nested field 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 function: deleting specific observations from entities in a knowledge graph. It distinguishes itself from sibling tools like delete_entities and add_observations by specifying the granularity ('specific observations').
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 such as delete_entities or when not to use it. The description lacks any context or conditions for usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete multiple relations from the knowledge graph
| Name | Required | Description | Default |
|---|---|---|---|
| relations | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full responsibility for disclosure. It only states the action (delete) without detailing consequences, permissions, or side effects. For a destructive operation, more transparency is needed.
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 that front-loads the primary action and resource. 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?
Given no output schema and no annotations, the description lacks details on return values, error handling, and usage context. It is adequate for a simple delete but could be more comprehensive.
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 already provides descriptions for each parameter (from, to, relationType), so the description adds no new semantic value. Baseline 3 as schema covers parameters adequately.
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 deletes multiple relations from the knowledge graph, using specific verb and resource. It distinguishes from siblings like delete_entities and delete_observations.
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 deleting relations but provides no explicit guidance on when to use this tool versus alternatives like delete_entities or delete_observations, nor any prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the most recently updated entities
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of recent entities to return |
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 the tool gets entities, giving no information about safety (read-only vs. destructive), authorization needs, rate limits, or pagination behavior beyond the limit parameter. The description is insufficient for understanding the tool's full behavior.
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 excessively brief. It lacks structure (e.g., sections or examples) and fails to provide enough information for effective use. Conciseness without completeness is not sufficient.
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 one parameter and no annotations or output schema, the description should cover behavior and usage more thoroughly. It omits details like which entities are considered, sorting order, or whether the limit is a hard maximum. The description is minimally adequate at best.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with a single parameter 'limit' fully described. The description adds no meaning beyond the schema, so baseline score of 3 is appropriate. No additional context like format or constraints is provided.
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 'Get' and resource 'entities' with a clear qualifier 'most recently updated', distinguishing it from siblings like 'query_by_time' or 'search_nodes'. However, it lacks specificity about what constitutes 'recently updated' (e.g., timestamp field), leaving some ambiguity.
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 exclusions or usage context provided. The description implies usage for fetching recent entities but offers no help in deciding between this and similar tools like 'query_by_time'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the version information of this memory MCP server
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, and the description does not elaborate on side effects, authentication, rate limits, or return format. Only states the basic purpose, falling short for a tool with zero annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single, front-loaded sentence with no extraneous words. Efficiently conveys 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?
No output schema exists, and the description only mentions 'version information' without specifying the format (e.g., string, JSON). Could be more complete for a tool with no 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?
No parameters exist (0 params), so baseline 4 applies. Description does not need to add parameter information 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?
Description clearly states verb 'Get', resource 'version information', and context 'memory MCP server'. Distinct from sibling tools which perform different 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?
No explicit when-to-use or when-not-to-use guidance. However, the purpose is straightforward and intended for one-off retrieval, so usage is implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Open specific nodes in the knowledge graph by their names
| Name | Required | Description | Default |
|---|---|---|---|
| names | Yes | An array of entity names to retrieve |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of disclosing behavior. It only says 'open', which implies read-only retrieval, but does not explicitly state that it is non-mutating, what it returns, or how missing names are handled. This leaves significant ambiguity.
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, efficiently worded sentence that directly states the action and resource. It contains no filler or redundant 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?
The tool has no output schema and the description does not clarify what 'open' returns (e.g., node attributes, observations, relations). For an agent to invoke the tool and interpret results correctly, this missing information is a notable gap.
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 has 100% coverage, already describing 'names' as 'An array of entity names to retrieve'. The tool description merely restates 'by their names', adding no extra semantic detail beyond the schema, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Open' and identifies the resource 'nodes in the knowledge graph', scoped by 'names', making it clear this is a direct retrieval by exact names. It implicitly differentiates from search_nodes (searching) and read_graph (full graph), but does not explicitly name 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 guidance is given on when to use this tool versus siblings. The description does not state that it should be used when exact node names are known, nor does it exclude using search_nodes for lookup or read_graph for broader context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Query entities and observations by time range using createdAt/updatedAt timestamps
| Name | Required | Description | Default |
|---|---|---|---|
| since | No | ISO timestamp for start of time range (inclusive) | |
| until | No | ISO timestamp for end of time range (inclusive) | |
| limit | No | Maximum number of results to return | |
| sort | No | Sort order by updatedAt (default: desc) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description does not disclose any behavioral traits such as whether the tool is read-only, performance characteristics, or side effects. For a query tool, basic safety information is missing.
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. However, it could be restructured to front-load the key action and include brief guidance.
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 no annotations, the description is insufficient. It does not mention response format, default behavior when no parameters are provided, or error conditions.
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% and each parameter has a clear description. The description adds value by specifying that the time range applies to both createdAt and updatedAt, which is not fully explicit 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 states the verb 'query' and the resource 'entities and observations', and specifies the method 'by time range using createdAt/updatedAt timestamps'. This distinguishes it from siblings like search_nodes or read_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?
The description provides no guidance on when to use this tool versus alternatives such as get_recent or search_nodes. It does not mention any prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read the entire knowledge graph
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry the full burden of behavioral disclosure, but it only states that the graph is read. It does not mention that the operation is read-only, whether it requires permissions, or that the response may be very large. The word 'read' implies non-destructive behavior, but no details are given.
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 that directly states the tool's purpose with no redundancy. It is well-structured and every word contributes to the meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of annotations and output schema, the description should explain what reading the graph returns or any caveats (e.g., large payloads). It does not, and it also fails to differentiate this tool from search_nodes for partial reads. The tool is simple, but the description is still incomplete for an agent to use it confidently.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and the schema is empty, so there is nothing to document. The baseline for zero parameters is 4, and the description correctly indicates that no inputs are needed, without adding unnecessary detail.
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 'read' and identifies the resource 'the entire knowledge graph,' clearly distinguishing it from sibling tools that create or delete entities. However, it is brief and doesn't elaborate on the output format or how it differs from export_to_obsidian, so it falls short of a perfect score.
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 explicit guidance on when to use this tool over alternatives like search_nodes or open_nodes. It is only implied that this is for reading the whole graph, with no mention of filtering or use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search for nodes in the knowledge graph based on a query
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | The search query to match against entity names, types, and observation content |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It describes the action as 'search' but does not disclose key behaviors such as case sensitivity, partial matching, result limits, ordering, or whether it searches across all entity fields or just specific ones.
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 wasted words, but it is vague and lacks structure. It could be improved by adding brief details or examples without increasing length significantly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter tool without an output schema, the description is minimally adequate. However, given the presence of sibling tools with overlapping functionality, more context (e.g., search scope, result format) would make it complete.
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 100% of the parameter with a description that explains what the query matches against. The tool description restates 'based on a query' but adds no additional semantics beyond the schema, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool searches for nodes in the knowledge graph based on a query, which is specific enough to distinguish from siblings like 'traverse_graph' or 'query_by_time'. However, it could be more precise (e.g., specifying it's a full-text 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?
The description provides no guidance on when to use this tool versus alternatives (e.g., 'query_by_time', 'traverse_graph', 'read_graph'). No exclusions or context for selection are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Traverse the knowledge graph from a starting entity to find connected entities via relations
| Name | Required | Description | Default |
|---|---|---|---|
| start | Yes | Name of the entity to start traversal from | |
| depth | No | Number of hops to traverse (default: 1) | |
| direction | No | Direction of traversal: out (outgoing relations), in (incoming relations), or both (default: both) | both |
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 only states the basic action without disclosing behavioral traits such as what is returned (only entities or also relations?), traversal algorithm (BFS/DFS?), depth limits, performance characteristics, or side effects. This is insufficient for an agent to understand full behavior.
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 superfluous words. It is efficiently front-loaded and gets straight to the point.
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 three parameters, no output schema, and no annotations, the description should provide more context about return format, traversal behavior, and handling of cycles or large graphs. It is incomplete for a graph traversal operation.
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 all three parameters. The description does not add any additional meaning beyond what the schema already provides, 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 uses a specific verb 'traverse' and resource 'knowledge graph', specifying the action from a starting entity via relations. It distinguishes from siblings like 'read_graph' (full read) and 'search_nodes' (query-based) by focusing on connectedness traversal.
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 exploring connections in the graph but does not explicitly state when to use this tool versus alternatives like 'search_nodes' or 'read_graph'. No guidance on prerequisites or exclusions is provided.
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.
v1.1.0add_observationscreate_entitiescreate_relationsdelete_entitiesdelete_observationsdelete_relationsget_recentget_versionopen_nodesquery_by_timeread_graphsearch_nodestraverse_graphScored across 13 tools
Each tool targets a specific operation on the knowledge graph, like creating entities, adding observations, or searching nodes. No two tools have overlapping purposes, ensuring clear distinction for an agent.
All tools use snake_case with a consistent verb_noun pattern (e.g., create_entities, delete_observations). Minor deviations like 'get_recent' still follow the pattern, making the set predictable.
With 13 tools, the server covers core knowledge graph operations without being bloated. Each tool serves a clear purpose, and the count is well-scoped for the domain.
The tool set includes create, read, delete, and query operations, but lacks dedicated update tools for entities, observations, and relations. While updates can be achieved via delete+create, this is a minor gap.
Persistent knowledge graph for AI agents. Remember, recall, and forget facts.
Governed personal world model and memory for your AI agent. Pair once, connect over MCP.
Intelligent context infrastructure for AI teams: knowledge graph, sessions, tasks, documents.
Company brain for AI agents — temporal knowledge graph search, exploration, and durable memory.
