一个为 AI 智能体提供持久化记忆的 MCP 服务器，内置新鲜度跟踪和间隔重复功能。由 Elasticsearch 提供支持。
与简单的键值对记忆存储不同，mcp-brain-tools 会跟踪每条知识的陈旧程度，标记需要复习的内容，并允许智能体验证信息以保持其新鲜度——灵感来源于间隔重复如何帮助人类保持记忆。
间隔重复新鲜度 — 每个实体都有一个复习间隔，验证后该间隔会翻倍（上限为 365 天）。置信度标签（新鲜/正常/老化/陈旧/归档）告诉智能体哪些信息值得信任。
渐进式搜索 — 查询优先返回新鲜结果，仅在需要时自动扩大范围以包含旧数据。
作为实体的观察结果 — 每个观察结果都有其独立的新鲜度生命周期，因此“构建失败”（1 天复习）和“成立于 2015 年”（365 天复习）会独立老化。
记忆区域 — 按项目、团队或领域隔离知识。
AI 驱动的过滤 — 可选的 Groq 集成，根据相关性对搜索结果进行评分。
DRY 设计原则 — 工具描述引导智能体不要存储代码、git 或文档中已有的内容。
Related MCP server: Elastic Brain ZH
Node.js >= 18
Docker（用于 Elasticsearch）或远程 Elasticsearch 实例
npm install
npm run buildnpm run es:start或者通过 ES_NODE 环境变量指向您自己的实例。
添加到您的 Claude Code、Claude Desktop 或其他 MCP 客户端配置中：
{
"mcpServers": {
"memory": {
"command": "node",
"args": ["/path/to/mcp-brain-tools/dist/index.js"],
"env": {
"ES_NODE": "http://localhost:9200",
"GROQ_API_KEY": "your-key-here"
}
}
}
}GROQ_API_KEY 是可选的——用于启用 AI 驱动的搜索过滤和区域相关性评分。
记忆钩子在每条用户消息上运行，并自动注入相关上下文——无需智能体配合。
添加到 ~/.claude/settings.json：
{
"hooks": {
"UserPromptSubmit": [
{
"hooks": [
{
"type": "command",
"command": "node /path/to/mcp-brain-tools/dist/memory-hook.js"
}
]
}
]
}
}该钩子使用相同的 ES_NODE、AI_API_KEY/GROQ_API_KEY、AI_API_BASE 和 AI_MODEL 环境变量（在设置的 env 块中设置它们，或在 shell 配置文件中导出它们）。
AI_API_BASE 默认为 Groq 的端点，但也接受任何兼容 OpenAI 的 API URL。
实体代表任何值得记忆的事物——人、项目、决策、事实。每个实体都有：
名称 和 类型
间隔重复字段：verifiedAt、reviewInterval、nextReviewAt
置信度标签：根据新鲜度计算得出：1 - (daysSinceVerified / reviewInterval)
观察结果作为通过 is_observation_of 关系链接的独立实体存储。每个观察结果都有自己的复习节奏：
Entity: "iaptic-server" (type: Project, reviewInterval: 30 days)
<- "iaptic-server: uses TypeScript" (reviewInterval: 180 days)
<- "iaptic-server: migration in progress" (reviewInterval: 7 days)创建实体 — confidence: "fresh"，默认 7 天后复习
复习日期已过 — confidence: "aging"，needsReview: true
智能体验证（通过 verify_entity） — 间隔翻倍，置信度重置为新鲜
严重逾期 — confidence: "stale" 然后变为 "archival"，从默认搜索中排除
搜索时，服务器使用三轮筛选：
freshness >= 0 — 新鲜和正常的实体
freshness >= -2 — 增加老化和陈旧的实体
无过滤器 — 增加归档实体
这既保持了结果的整洁，又确保了信息不会永久丢失。
工具 | 描述 |
| 创建带有可选观察结果和复习间隔的实体 |
| 更新现有实体 |
| 删除实体（可选级联删除） |
| 将观察结果添加为具有独立新鲜度的独立实体 |
| 确认实体仍然准确，延长复习间隔 |
| 使用渐进式新鲜度过滤进行搜索 |
| 通过名称获取带有新鲜度元数据的特定实体 |
| 获取最近访问的实体 |
| 在实体之间创建关系 |
| 删除关系 |
| AI 驱动的实体检索，提供初步答案 |
| AI 驱动的文件内容检查 |
| 列出记忆区域（带有 AI 相关性评分） |
| 管理记忆区域 |
| 在区域之间转移实体 |
| 合并区域并解决冲突 |
| 获取区域的实体/关系计数 |
| 提升实体相关性评分 |
| 获取当前 UTC 时间 |
变量 | 默认值 | 描述 |
|
| Elasticsearch URL |
| — | Elasticsearch 用户名 |
| — | Elasticsearch 密码 |
| — | 用于 AI 过滤的 Groq API 密钥 |
|
| 逗号分隔的模型列表 |
|
| Elasticsearch 索引前缀 |
|
| 默认记忆区域 |
|
| 启用调试日志 |
为了让智能体主动使用记忆服务器，请在您的 CLAUDE.md（或等效指令文件）中添加类似以下内容：
## Memory
Use MCP Memory (`mcp__memory__*` tools) — a shared knowledge graph across all agents, projects, and computers.
**When to SAVE (immediately, before moving on):**
- Something you tried didn't work (non-transient) → save what failed and why, so no agent repeats it
- A decision was made (architectural, design, workflow) → save the decision and the reason
- The user corrects you or gives explicit instructions → save the rule
- You learn something non-obvious that took effort to discover → save it
**When to SEARCH (before starting, not after failing):**
- **At the start of every non-trivial task** — search before thinking, not after hitting a wall
- About to try an approach that might have been attempted before → search first
- User references something from a past session → search before asking
**Rules:**
- Skip anything easy to find in code, git log, or docs
- Use the project name as the zone for project-specific knowledge; `default` for general knowledge
- Keep entries short — the AI filters server-side, so be generous rather than selective
- Short `reviewInterval` (e.g. 3–7 days) for volatile facts; longer (30–180) for stable ones关键见解：智能体需要明确的基于触发器的指令（“当 X 时，做 Y”），而不仅仅是工具功能的描述。
npm run build # Compile TypeScript
npm run dev # Watch mode
npm run test:jest # Run Jest tests
npm run es:start # Start Elasticsearch
npm run es:stop # Stop Elasticsearch
npm run es:reset # Wipe data and restart
npm run import # Import from JSON
npm run export # Export to JSONMIT
Add observations to an existing entity in knowledge graph (memory)
| Name | Required | Description | Default |
|---|---|---|---|
| memory_zone | Yes | Optional memory zone where the entity is stored. If not specified, uses the default zone. | |
| name | Yes | Name of entity to add observations to | |
| observations | Yes | Observations to add to the entity |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It implies a write operation ('Add') but doesn't specify permissions needed, whether changes are reversible, rate limits, or what happens if the entity doesn't exist. This is a significant gap for a mutation tool with zero annotation coverage.
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, efficient sentence that front-loads the core purpose without unnecessary words. Every part earns its place by clarifying the action, target, and context ('knowledge graph (memory)'), making it highly concise and well-structured.
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 and no output schema, the description is incomplete. It lacks critical context such as error handling, response format, or behavioral details (e.g., idempotency, side effects), which are essential for safe and effective tool invocation by 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 100%, so the schema already documents all three parameters thoroughly. The description adds no additional meaning beyond what's in the schema (e.g., it doesn't explain observation format or memory zone implications), meeting the baseline for high coverage.
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 ('Add observations') and target ('to an existing entity in knowledge graph (memory)'), providing a specific verb+resource combination. However, it doesn't explicitly differentiate from sibling tools like 'update_entities' or 'mark_important', which might also modify entities, so it doesn't reach the highest 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 guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., entity must exist), exclusions, or compare to siblings like 'update_entities' or 'create_entities', leaving the agent with no usage context beyond the basic purpose.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Copy entities between zones with optional relation handling.
| Name | Required | Description | Default |
|---|---|---|---|
| copy_relations | No | Copy related relationships (default: true) | |
| names | Yes | Entity names to copy | |
| overwrite | No | Overwrite if entity exists (default: false) | |
| source_zone | Yes | Source zone | |
| target_zone | Yes | Target zone |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It mentions 'optional relation handling', which hints at the 'copy_relations' parameter behavior, but fails to describe critical aspects like whether this is a read-only or destructive operation, permission requirements, rate limits, or what happens on failure. For a tool that copies entities between zones—potentially involving data mutation—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, efficient sentence that front-loads the core purpose ('Copy entities between zones') and adds a key behavioral note ('with optional relation handling'). There is no wasted verbiage, making it highly concise and well-structured for quick comprehension.
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 copying entities between zones, no annotations, and no output schema, the description is incomplete. It lacks information on return values, error conditions, side effects, and how it differs from sibling tools. For a tool with 5 parameters and potential data implications, more context is needed to guide 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?
Schema description coverage is 100%, so the schema fully documents all 5 parameters. The description adds minimal value by implying 'optional relation handling' corresponds to 'copy_relations', but doesn't explain parameter interactions or provide additional context beyond the schema. This meets the baseline of 3 for high schema coverage.
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 ('Copy entities') and the scope ('between zones'), which is specific and actionable. It distinguishes from siblings like 'move_entities' by specifying copying rather than moving, and from 'create_entities' by involving source/target zones. However, it doesn't fully differentiate from 'merge_zones' or other zone operations, keeping it at 4 instead of 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention when to choose 'copy_entities' over 'move_entities', 'create_entities', or 'merge_zones', nor does it specify prerequisites or exclusions. This leaves the agent without contextual usage direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create entities in knowledge graph (memory)
| Name | Required | Description | Default |
|---|---|---|---|
| entities | Yes | List of entities to create | |
| memory_zone | Yes | Memory zone to create entities in. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden but only states the basic action without behavioral details. It doesn't disclose permissions needed, whether creation is idempotent, error handling, or rate limits, which are critical for a write operation in a knowledge graph system.
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, efficient sentence with no wasted words, clearly front-loading the core action. It's appropriately sized for the tool's complexity, making it easy to parse quickly.
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 a write operation in a knowledge graph with no annotations and no output schema, the description is incomplete. It lacks details on behavioral traits, error cases, or return values, leaving significant gaps for an agent to operate effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents both parameters ('entities' and 'memory_zone') thoroughly. The description adds no additional meaning beyond the schema, such as explaining what a 'memory_zone' represents or constraints on entity creation, meeting the baseline for high schema coverage.
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 resource ('entities in knowledge graph (memory)'), making the purpose understandable. However, it doesn't differentiate from siblings like 'update_entities' or 'add_observations', which would require specifying this is for initial creation only.
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. For example, it doesn't mention whether to use 'update_entities' for modifying existing entities or 'add_observations' for adding observations to existing entities, leaving the agent without context for tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create relationships between entities in knowledge graph (memory)
| Name | Required | Description | Default |
|---|---|---|---|
| auto_create_missing_entities | No | Whether to automatically create missing entities in the relations (default: true) | |
| memory_zone | No | Optional default memory zone specifier. Used if a relation doesn't specify fromZone or toZone. | |
| relations | Yes | List of relations to create |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions 'create' which implies a mutation, but fails to detail permissions, side effects, error handling, or response format. This is inadequate for a mutation tool, as it leaves critical behavioral traits unspecified.
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, efficient sentence that directly states the tool's purpose without unnecessary words. It is front-loaded and wastes no space, making it easy for an agent to parse quickly.
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 and no output schema, the description is insufficient. It lacks details on behavioral traits, error conditions, and return values, which are critical for safe and effective tool invocation. The high schema coverage does not compensate for these gaps in contextual information.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the input schema fully documents all parameters. The description does not add any semantic details beyond what the schema provides, such as examples or usage tips. Baseline score of 3 is appropriate as the schema handles parameter documentation effectively.
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 relationships') and the resource ('between entities in knowledge graph'), which is specific and understandable. However, it does not explicitly differentiate from sibling tools like 'delete_relations' or 'update_entities', missing an opportunity to clarify its unique role in the toolset.
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 'update_entities', nor does it mention prerequisites like existing entities or zones. It lacks explicit usage context, leaving the agent to infer based on the tool name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new memory zone with optional description.
| Name | Required | Description | Default |
|---|---|---|---|
| description | No | Full zone description. Make it very descriptive and detailed. | |
| name | Yes | Zone name (cannot be 'default') | |
| shortDescription | No | Short description of the zone. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states the tool creates a new zone but lacks details on permissions needed, whether the operation is idempotent, what happens on failure, or any rate limits. This is inadequate for a mutation tool with zero annotation coverage.
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, efficient sentence that is front-loaded with the core purpose. It wastes no words and is appropriately sized for the tool's complexity.
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 is a mutation (create operation) with no annotations and no output schema, the description is incomplete. It doesn't explain what the tool returns, error conditions, or behavioral traits, leaving significant gaps for an AI agent to use it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema fully documents all three parameters. The description adds minimal value by noting the description is optional but doesn't provide additional meaning beyond what's in the schema, such as usage examples or constraints not covered.
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 resource ('new memory zone'), specifying what the tool does. However, it doesn't differentiate from sibling tools like 'create_entities' or 'merge_zones', which also create resources, so it misses full sibling distinction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like 'merge_zones' or 'create_entities', nor any context on prerequisites or exclusions. The description only mentions optional parameters without usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete entities from knowledge graph (memory)
| Name | Required | Description | Default |
|---|---|---|---|
| cascade_relations | No | Whether to delete relations involving these entities (default: true) | |
| memory_zone | Yes | Memory zone specifier. Entities will be deleted from this zone. | |
| names | Yes | Names of entities to delete |
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 mentions deletion but lacks details on permissions, irreversibility, side effects, or error handling. The parenthetical '(memory)' adds minimal context, leaving significant gaps for a destructive operation.
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, efficient sentence with zero waste. It's front-loaded with the core action and resource, making it easy to parse quickly.
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 destructive tool with no annotations and no output schema, the description is inadequate. It doesn't explain what 'delete' entails (e.g., permanent removal), return values, or error cases, leaving the agent with insufficient context for safe 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 100%, so the schema fully documents all parameters. The description adds no additional meaning beyond what's in the schema, such as explaining 'memory_zone' or 'cascade_relations' in broader context. Baseline 3 is appropriate as the schema does the heavy lifting.
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') and resource ('entities from knowledge graph (memory)'), making the purpose immediately understandable. However, it doesn't differentiate from sibling tools like 'delete_relations' or 'delete_zone' beyond the resource type, which prevents 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?
No guidance is provided on when to use this tool versus alternatives like 'delete_relations' or 'delete_zone', nor does it mention prerequisites or constraints. The description only states what it does, not when it's appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete relationships from knowledge graph (memory)
| Name | Required | Description | Default |
|---|---|---|---|
| memory_zone | No | Optional memory zone specifier. If provided, relations will be deleted from this zone. | |
| relations | Yes | List of relations to delete |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden but provides minimal behavioral context. It states this is a deletion operation but doesn't mention whether deletions are permanent, reversible, require specific permissions, have side effects on connected entities, or provide confirmation of what was deleted. For a destructive operation with zero annotation coverage, 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 extremely concise at just 5 words plus a parenthetical clarification. Every element earns its place: 'Delete' specifies the action, 'relationships' specifies what's being deleted, 'from knowledge graph' provides context, and '(memory)' clarifies the domain. No wasted words or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive operation with no annotations and no output schema, the description is inadequate. It doesn't explain what happens after deletion, whether there's confirmation, error conditions, or behavioral constraints. Given the complexity of graph operations and complete lack of structured safety information, more descriptive context is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema fully documents both parameters. The description adds no additional parameter information beyond what's in the schema. The baseline score of 3 reflects adequate parameter documentation through the schema alone, with no value added by 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 action ('Delete') and target ('relationships from knowledge graph'), with parenthetical clarification that this refers to 'memory'. It distinguishes from siblings like 'delete_entities' by specifying relationship deletion rather than entity deletion. However, it doesn't explicitly contrast with 'delete_zone' or other deletion tools.
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 about when to use this tool versus alternatives. With siblings like 'delete_entities', 'delete_zone', and 'create_relations', there's no indication of when relationship deletion is appropriate versus entity deletion or zone deletion, or how this differs from other graph modification tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a memory zone and all its entities/relations.
| Name | Required | Description | Default |
|---|---|---|---|
| confirm | Yes | Confirmation flag, must be true | |
| name | Yes | Zone name to delete (cannot be 'default') |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the tool deletes a zone and all its entities/relations, which implies a destructive, irreversible operation. However, it lacks details on permissions needed, error handling (e.g., if the zone doesn't exist), side effects, or confirmation requirements beyond the 'confirm' parameter. The description adds minimal behavioral context beyond the basic action.
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, efficient sentence that directly states the tool's action and scope. It is front-loaded with the core purpose ('Delete a memory zone') and adds necessary detail ('and all its entities/relations') without redundancy. Every word earns its place, making it highly concise and well-structured.
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 destructive nature and lack of annotations or output schema, the description is minimally complete. It covers what the tool does but omits critical context like irreversible consequences, prerequisites, or error scenarios. For a deletion tool with no safety annotations, more guidance would be helpful, but the description meets a basic threshold.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema fully documents both parameters ('name' and 'confirm'). The description adds no additional parameter semantics, but with high schema coverage, the baseline is 3. Since there are only 2 parameters and the schema is comprehensive, a score of 4 reflects that the description doesn't need to compensate and the tool's purpose is straightforward.
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 resource ('a memory zone and all its entities/relations'), making the purpose specific and unambiguous. It distinguishes from sibling tools like 'delete_entities' and 'delete_relations' by specifying that it deletes the entire zone along with its contents, not just individual components.
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. It does not mention prerequisites (e.g., whether the zone must exist or be empty), exclusions (e.g., cannot delete the 'default' zone, though this is hinted in the schema), or comparisons to siblings like 'merge_zones' or 'list_zones' for verification. Usage context is implied but not explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get recently accessed entities from knowledge graph (memory) and their relations
| Name | Required | Description | Default |
|---|---|---|---|
| includeObservations | No | Whether to include full entity observations in results (default: false) | |
| limit | No | Max results (default: 20 if includeObservations is false, 5 if true) | |
| memory_zone | Yes | Optional memory zone to get recent entities from. If not specified, uses the default zone. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions retrieving 'recently accessed entities' but doesn't specify what 'recent' means (e.g., time window, access count), whether results are sorted, or if there are rate limits or permissions required. This leaves significant gaps for a tool that interacts with a knowledge graph.
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, efficient sentence that front-loads the core purpose without unnecessary words. It directly communicates the tool's function, making it easy to parse and understand quickly.
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 moderate complexity (3 parameters, no output schema, no annotations), the description is minimal but covers the basic purpose. However, it lacks details on behavioral aspects like recency definition, sorting, or error handling, which are important for a knowledge graph query tool. The absence of an output schema increases the need for more context, but the description doesn't compensate adequately.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema fully documents the three parameters (includeObservations, limit, memory_zone) with clear descriptions. The description adds no additional parameter semantics beyond what's in the schema, resulting in a baseline score of 3.
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 'Get' and the resource 'recently accessed entities from knowledge graph (memory) and their relations', which is specific and actionable. However, it doesn't explicitly distinguish this tool from sibling tools like 'search_nodes' or 'inspect_knowledge_graph', which might also retrieve graph data, 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 guidance on when to use this tool versus alternatives. For example, it doesn't explain how 'get_recent' differs from 'search_nodes' or 'inspect_knowledge_graph' in terms of recency filtering or scope, leaving the agent to infer usage from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the current UTC time in YYYY-MM-DD hh:mm:ss format
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
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 discloses the output format, which is a key behavioral trait. However, it does not mention other aspects like whether it's a read-only operation, if it has side effects, or any rate limits. The description is accurate but lacks comprehensive behavioral 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?
The description is a single, clear sentence that directly states the tool's purpose and output format without any unnecessary words. It is front-loaded and efficiently conveys all necessary information in minimal text.
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 low complexity (no parameters, simple time retrieval) and lack of annotations or output schema, the description is complete enough for basic use. It specifies the exact format, which is crucial. However, it could be more complete by mentioning that it returns a string or any potential errors, but for this simple tool, it is largely adequate.
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 0 parameters, and schema description coverage is 100% (as there are no parameters to describe). The description does not need to add parameter semantics, so it meets the baseline of 4 for tools with no parameters, as per the rules.
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 specific action ('Get') and resource ('current UTC time'), including the exact format ('YYYY-MM-DD hh:mm:ss'). It distinguishes itself from all sibling tools, which involve entity manipulation, file inspection, or zone operations, by being the only time-retrieval tool.
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 context (when you need the current UTC time in a specific format), but does not explicitly state when not to use it or name alternatives. Given the sibling tools are unrelated (e.g., 'add_observations', 'create_entities'), the distinction is clear by purpose, but no explicit guidance on alternatives is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Agent driven file inspection that uses AI to retrieve relevant content from multiple files.
| Name | Required | Description | Default |
|---|---|---|---|
| file_paths | Yes | Paths to the files (or directories) to inspect | |
| include_lines | Yes | Whether to include the actual line content in the response, which uses more of your limited token quota, but gives more informatiom (default: false) | |
| information_needed | Yes | Full description of what information is needed from the files, including the context of the information needed. Do not be vague, be specific. The AI agent does not have access to your context, only this "information needed" and "reason" fields. That's all it will use to decide that a line is relevant to the information needed. So provide a detailed specific description, listing all the details about what you are looking for. | |
| keywords | Yes | Array of specific keywords related to the information needed. AI will target files that contain one of these keywords. | |
| reason | No | Explain why this information is needed to help the AI agent give better results. The more context you provide, the better the results will be. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions AI-driven retrieval and token quota implications for 'include_lines', but doesn't cover critical aspects like whether this is a read-only operation, potential rate limits, authentication requirements, error handling, or what the response format looks like. The description adds some context but leaves significant gaps for a tool with 5 parameters.
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, efficient sentence that clearly states the tool's purpose. It's appropriately sized and front-loaded with the core functionality. While it could potentially benefit from more detail given the tool's complexity, what's present is well-structured without 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?
For a complex AI-driven file inspection tool with 5 parameters and no output schema, the description is insufficiently complete. It doesn't explain what the tool returns, how results are structured, what 'relevant content' means operationally, or how the AI component works. With no annotations and no output schema, users need more guidance about the tool's behavior and outputs.
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 description coverage is 100%, so the schema already documents all parameters thoroughly. The description doesn't add any meaningful parameter semantics beyond what's in the schema - it doesn't explain how parameters interact, provide examples, or clarify edge cases. With complete schema coverage, the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose as 'Agent driven file inspection that uses AI to retrieve relevant content from multiple files.' It specifies the verb ('inspect'), resource ('files'), and method ('uses AI to retrieve relevant content'). However, it doesn't explicitly differentiate from sibling tools like 'search_nodes' or 'inspect_knowledge_graph' which might have overlapping functionality.
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. It doesn't mention sibling tools like 'search_nodes' or 'inspect_knowledge_graph' that might be relevant for similar tasks. The only implied usage is for AI-driven file content retrieval, but no explicit context or exclusions are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Agent driven knowledge graph inspection that uses AI to retrieve relevant entities and relations based on a query.
| Name | Required | Description | Default |
|---|---|---|---|
| entity_types | No | Optional filter to specific entity types | |
| include_entities | No | Whether to include the full entity details in the response, which uses more of your limited token quota, but gives more information (default: false) | |
| include_relations | No | Whether to include the entity relations in the response (default: false) | |
| information_needed | Yes | Full description of what information is needed from the knowledge graph, including the context of the information needed. Do not be vague, be specific. The AI agent does not have access to your context, only this "information needed" and "reason" fields. That's all it will use to decide that an entity is relevant to the information needed. | |
| keywords | Yes | Array of specific keywords related to the information needed. AI will target entities that match one of these keywords. | |
| memory_zone | No | Memory zone to search in. If not provided, uses the default zone. | |
| reason | No | Explain why this information is needed to help the AI agent give better results. The more context you provide, the better the results will be. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions that the tool 'uses AI to retrieve relevant entities and relations', implying intelligent filtering, but doesn't disclose critical behaviors such as rate limits, authentication requirements, error handling, or what 'retrieve' entails (e.g., pagination, format of results). For a query tool with 7 parameters and no output schema, this lack of behavioral context is a significant gap.
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, well-structured sentence that efficiently conveys the core purpose without redundancy. It uses clear language ('Agent driven knowledge graph inspection', 'uses AI', 'retrieve relevant entities and relations', 'based on a query') and avoids unnecessary details, making it easy to parse and understand quickly. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (7 parameters, no annotations, no output schema), the description is incomplete. It doesn't explain what the tool returns (e.g., structure of entities/relations, pagination), how the AI-driven retrieval works, or any limitations. Without annotations or output schema, the agent lacks sufficient context to understand the tool's full behavior and results, making this inadequate 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?
Schema description coverage is 100%, so the schema already documents all 7 parameters thoroughly. The description doesn't add any parameter-specific semantics beyond what's in the schema (e.g., it doesn't explain how 'information_needed' and 'keywords' interact or provide examples). With high schema coverage, the baseline score of 3 is appropriate, as the description doesn't compensate but also doesn't detract from the schema's 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 the tool's purpose: 'Agent driven knowledge graph inspection that uses AI to retrieve relevant entities and relations based on a query.' It specifies the verb ('retrieve'), resource ('entities and relations'), and mechanism ('based on a query'). However, it doesn't explicitly differentiate from sibling tools like 'search_nodes' or 'get_recent', which appear related to knowledge graph operations, leaving some ambiguity about when to choose this specific inspection tool.
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. It doesn't mention any of the sibling tools (e.g., 'search_nodes', 'get_recent', 'open_nodes') that might overlap in functionality, nor does it specify prerequisites, exclusions, or typical use cases. The agent must infer usage from the purpose alone, which is insufficient for optimal tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all available memory zones with metadata. When a reason is provided, zones will be filtered and prioritized based on relevance to your needs.
| Name | Required | Description | Default |
|---|---|---|---|
| reason | No | Reason for listing zones. What zones are you looking for? Why are you looking for them? The AI will use this to prioritize and filter relevant zones. |
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 discloses that the tool lists zones with metadata and can filter/prioritize based on a reason, which adds context beyond basic listing. However, it lacks details on behavioral traits such as pagination, rate limits, authentication needs, or what happens if no zones exist. The description doesn't contradict any annotations (since none 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 two sentences, front-loaded with the core purpose and followed by an explanation of the optional parameter's effect. Every sentence earns its place by adding useful information without redundancy or fluff, making it efficient and well-structured.
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 low complexity (1 optional parameter, no output schema, no annotations), the description is somewhat complete but has gaps. It covers the purpose and parameter usage but lacks details on output format, error handling, or how metadata is structured. For a list tool with no output schema, more information on return values would improve 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?
The input schema has 1 parameter with 100% description coverage, providing a clear explanation of the 'reason' parameter. The description adds value by explaining that the reason is used to 'filter and prioritize relevant zones,' which gives semantic context beyond the schema's description. However, it doesn't elaborate on how filtering or prioritization works, keeping the baseline at 3 due to high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'List all available memory zones with metadata.' It specifies the verb ('List') and resource ('memory zones'), and mentions metadata inclusion. However, it doesn't explicitly differentiate from sibling tools like 'zone_stats' or 'search_nodes' in terms of scope or output format.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage by stating that zones can be filtered and prioritized when a reason is provided, suggesting this tool is for retrieving zones with optional relevance-based filtering. However, it doesn't explicitly state when to use this tool versus alternatives like 'search_nodes' or 'zone_stats', nor does it provide exclusions or prerequisites for usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Mark entity as important in knowledge graph (memory) by boosting its relevance score
| Name | Required | Description | Default |
|---|---|---|---|
| auto_create | No | Whether to automatically create the entity if it doesn't exist (default: false) | |
| important | Yes | Set as important (true - multiply relevance by 10) or not (false - divide relevance by 10) | |
| memory_zone | Yes | Optional memory zone specifier. If provided, entity will be marked in this zone. | |
| name | Yes | Entity name |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions the effect on relevance scores (multiply/divide by 10) and implies mutation ('mark'), but doesn't cover permissions, rate limits, side effects (e.g., impact on other entities), or response format. For a mutation tool with zero annotation coverage, this leaves significant gaps in understanding how it behaves.
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, efficient sentence that front-loads the core action ('mark entity as important') and includes key behavioral detail ('boosting its relevance score'). There is zero waste or redundancy, making it highly concise and well-structured.
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, no output schema, and a mutation tool with 4 parameters, the description is minimally adequate. It covers the purpose and basic effect but lacks details on usage context, behavioral traits, and return values. The high schema coverage helps, but for a tool that modifies data, more guidance would improve 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?
Schema description coverage is 100%, so the schema already documents all parameters thoroughly. The description adds no parameter-specific information beyond what's in the schema (e.g., it doesn't explain 'memory_zone' or 'auto_create' further). Baseline 3 is appropriate when the schema does the heavy lifting, though no extra value is added.
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 ('mark') and resource ('entity in knowledge graph') with the specific action of 'boosting its relevance score'. It distinguishes from siblings like 'create_entities' or 'update_entities' by focusing on importance marking rather than creation or general updates. However, it doesn't explicitly differentiate from all siblings like 'merge_zones' or 'move_entities' in terms of scope.
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 like 'update_entities' (which might handle importance) or 'create_entities' (with auto_create parameter). It mentions the effect on relevance scores but doesn't specify use cases, prerequisites, or exclusions, leaving the agent to infer usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Merge multiple zones with conflict resolution options.
| Name | Required | Description | Default |
|---|---|---|---|
| delete_source_zones | No | Delete source zones after merging | |
| overwrite_conflicts | No | How to handle name conflicts | skip |
| source_zones | Yes | Source zones to merge from | |
| target_zone | Yes | Target zone to merge into |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions 'conflict resolution options', which hints at some complexity, but fails to describe critical behaviors such as whether the merge is destructive, what happens to data in source zones, permission requirements, or error handling. For a mutation tool with zero annotation coverage, this is a significant gap.
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, efficient sentence that front-loads the core action ('merge multiple zones') and adds a key qualifier ('with conflict resolution options'). There is no wasted verbiage or redundancy, making it highly concise and well-structured.
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 merging zones (a mutation operation) and the lack of annotations and output schema, the description is insufficient. It doesn't explain what 'zones' are, the merge semantics, potential side effects, or return values, leaving the agent with critical gaps in understanding how to use this tool effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all parameters thoroughly. The description adds minimal value by implying that parameters relate to conflict resolution and merging, but doesn't provide additional context beyond what's in the schema. This meets the baseline for high schema coverage.
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 ('merge multiple zones') and mentions a key feature ('conflict resolution options'), which distinguishes it from sibling tools like 'create_zone' or 'delete_zone'. However, it doesn't specify what 'zones' are in this context or how the merge operation works at a high level, which prevents 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 guidance on when to use this tool versus alternatives like 'move_entities' or 'copy_entities', nor does it mention prerequisites or typical scenarios for merging zones. It lacks explicit when-to-use or when-not-to-use instructions, leaving the agent to infer usage from the tool name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Move entities between zones (copy + delete from source).
| Name | Required | Description | Default |
|---|---|---|---|
| move_relations | No | Move related relationships (default: true) | |
| names | Yes | Entity names to move | |
| overwrite | No | Overwrite if entity exists (default: false) | |
| source_zone | Yes | Source zone | |
| target_zone | Yes | Target zone |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It reveals the 'copy + delete' implementation, which implies destructive action on the source. However, it doesn't address critical aspects like permissions needed, whether the operation is atomic/transactional, error handling, or what happens if the delete fails after copying. For a destructive operation with zero annotation coverage, 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 extremely concise (one sentence) and front-loaded with the core purpose. Every word earns its place—'move' specifies the action, 'entities' and 'zones' define the resources, and 'copy + delete from source' clarifies the implementation without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of a destructive move operation with 5 parameters, no annotations, and no output schema, the description is incomplete. It lacks information about return values, error conditions, side effects, and how it differs from sibling tools. The agent would need to infer too much from the sparse 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 100%, so all parameters are documented in the schema itself. The description doesn't add any parameter-specific information beyond what's in the schema (like clarifying zone naming conventions or entity name formats). The baseline of 3 is appropriate when the schema handles parameter documentation 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 action ('Move entities between zones') and specifies the implementation method ('copy + delete from source'), which distinguishes it from simple copy operations. However, it doesn't explicitly differentiate from sibling tools like 'copy_entities' or 'merge_zones' beyond the move semantics.
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 like 'copy_entities' (which might copy without deletion) or 'merge_zones' (which might handle zone consolidation differently). There's no mention of prerequisites, constraints, or typical use cases for moving versus other operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get details about specific entities in knowledge graph (memory) and their relations
| Name | Required | Description | Default |
|---|---|---|---|
| memory_zone | Yes | Optional memory zone to retrieve entities from. If not specified, uses the default zone. | |
| names | Yes | Names of entities to retrieve |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the tool retrieves details about entities and relations, implying a read-only operation, but doesn't mention permissions, rate limits, error handling, or what 'details' include (e.g., properties, metadata). For a tool with zero annotation coverage, this is a significant gap 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, efficient sentence that front-loads the core purpose ('Get details about specific entities...'). There is no wasted text, and it directly communicates the tool's function without unnecessary elaboration.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (2 required parameters, no output schema, no annotations), the description is minimally adequate. It covers the basic purpose but lacks details on behavior, output format, or differentiation from siblings. With no output schema, it should ideally hint at return values, but the concise purpose statement meets a bare-minimum threshold.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents both parameters ('names' and 'memory_zone') with clear descriptions. The description adds no additional meaning beyond what the schema provides, such as examples or edge cases, but the high schema coverage justifies the baseline score of 3.
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 ('Get details') and resource ('specific entities in knowledge graph (memory) and their relations'), making the purpose understandable. However, it doesn't explicitly distinguish this tool from sibling tools like 'search_nodes' or 'get_recent', which might have overlapping functionality for retrieving graph information.
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 like 'search_nodes' (which might search broadly) or 'get_recent' (which might retrieve recent entities). It lacks explicit when/when-not instructions or named alternatives, leaving usage context implied at best.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search entities using ElasticSearch query syntax. Supports boolean operators (AND, OR, NOT), fuzzy matching (~), phrases ("term"), proximity ("terms"N), wildcards (*, ?), and boosting (^N). Examples: 'meeting AND notes', 'Jon', '"project plan"~2'. All searches respect zone isolation.
| Name | Required | Description | Default |
|---|---|---|---|
| entityTypes | No | Filter to specific entity types (OR condition if multiple). | |
| includeObservations | No | Include full entity observations (default: false). | |
| informationNeeded | Yes | Important. Describe what information you are looking for, to give a precise context to the search engine AI agent. What questions are you trying to answer? Helps get more useful results. | |
| limit | No | Max results (default: 20, or 5 with observations). | |
| memory_zone | Yes | Limit search to specific zone. Omit for default zone. | |
| query | Yes | ElasticSearch query string. | |
| reason | Yes | Explain why this information is needed to help the AI agent give better results. The more context you provide, the better the results will be. | |
| sortBy | No | Sort by match quality, access time, or importance. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes the search syntax and zone isolation, but misses key behavioral traits: it doesn't mention whether this is a read-only operation (implied but not stated), potential rate limits, error handling, or the format of results (especially since there's no output schema). The syntax examples are helpful but not comprehensive for 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 appropriately sized and front-loaded with the core purpose and syntax details. Every sentence adds value: the first states the action and syntax, the second lists supported operators, the third gives examples, and the fourth mentions zone isolation. There's no wasted text, though it could be slightly more structured (e.g., bullet points for operators).
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 (8 parameters, 4 required, no annotations, no output schema), the description is incomplete. It covers the search syntax and zone isolation well, but lacks details on result format, pagination, error cases, or performance considerations. Without an output schema, the description should ideally hint at what to expect (e.g., 'returns a list of matching entities'), but it doesn't, leaving gaps for the 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 100%, so the schema already documents all 8 parameters thoroughly. The description adds no parameter-specific information beyond what's in the schema (e.g., it doesn't clarify 'query' beyond stating it uses ElasticSearch syntax, which the schema already notes). Thus, it meets the baseline of 3 without adding extra semantic value.
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 specific action ('Search entities using ElasticSearch query syntax') and resource ('entities'), distinguishing it from sibling tools like 'get_recent' (which likely retrieves recent items without search) or 'open_nodes' (which might open specific nodes). The mention of 'zone isolation' further differentiates it from tools like 'list_zones' or 'zone_stats'.
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 clear context for when to use this tool (searching entities with ElasticSearch syntax) and implies when not to use it (e.g., for non-search operations like creating or deleting entities, covered by sibling tools). However, it lacks explicit alternatives (e.g., 'get_recent' for recent items without querying) or exclusions (e.g., when to use 'inspect_knowledge_graph' instead).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update entities in knowledge graph (memory)
| Name | Required | Description | Default |
|---|---|---|---|
| entities | Yes | List of entities to update | |
| memory_zone | Yes | Memory zone specifier. Entities will be updated in this zone. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It states 'Update' implying mutation but doesn't disclose behavioral traits like whether this overwrites or merges existing data, permission requirements, side effects, rate limits, or what happens on failure. For a mutation tool with zero annotation coverage, this leaves significant gaps in understanding its 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?
Extremely concise with a single, front-loaded sentence that wastes no words. The parenthetical '(memory)' adds brief clarification without redundancy. Every element earns its place efficiently.
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 complexity (mutation tool with 2 parameters, no annotations, no output schema), the description is incomplete. It lacks behavioral details, usage context, and output expectations, making it inadequate for safe and effective tool invocation by 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 100%, so parameters are fully documented in the schema. The description adds no additional meaning beyond implying the tool operates on 'entities' and uses 'memory_zone', which is already clear from the schema. Baseline 3 is appropriate as the schema does the heavy lifting.
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 ('Update') and resource ('entities in knowledge graph') with parenthetical clarification ('memory'). It distinguishes from siblings like 'create_entities' (new creation) and 'delete_entities' (removal), but doesn't explicitly differentiate from 'move_entities' or 'mark_important' which might have overlapping functionality.
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. It doesn't mention prerequisites (e.g., entities must exist), when to choose 'update_entities' over 'add_observations' or 'mark_important', or any constraints like memory zone requirements. The description provides only basic functional context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get statistics for entities and relationships in a zone.
| Name | Required | Description | Default |
|---|---|---|---|
| zone | Yes | Zone name (omit for default zone) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states the tool retrieves statistics but does not specify what types of statistics (e.g., counts, metrics), whether it's read-only, if it requires permissions, or any rate limits. This leaves significant gaps in understanding the tool's behavior and constraints.
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, clear sentence that directly states the tool's purpose without any unnecessary words or fluff. It is front-loaded and efficiently conveys the core functionality, making it highly concise and well-structured.
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 statistical tools and the lack of annotations and output schema, the description is insufficient. It does not explain what statistics are returned, their format, or any behavioral nuances, making it incomplete for effective agent use without additional 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?
The input schema has 100% description coverage, with the 'zone' parameter clearly documented as 'Zone name (omit for default zone)'. The description adds no additional parameter semantics beyond this, so it meets the baseline of 3 for adequate but not enhanced parameter information.
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 ('Get statistics') and target ('for entities and relationships in a zone'), which is specific and actionable. However, it does not explicitly differentiate this tool from siblings like 'inspect_knowledge_graph' or 'get_recent', which might also provide statistical or summary information, leaving room for ambiguity in sibling distinction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It lacks context such as prerequisites, typical use cases, or comparisons to siblings like 'inspect_knowledge_graph' or 'list_zones', leaving the agent without clear usage instructions.
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.0.0add_observationscopy_entitiescreate_entitiescreate_relationscreate_zonedelete_entitiesdelete_relationsdelete_zoneget_recentget_time_utcinspect_filesinspect_knowledge_graphlist_zonesmark_importantmerge_zonesmove_entitiesopen_nodessearch_nodesupdate_entitieszone_statsScored across 20 tools
Most tools have distinct purposes, such as create_entities vs. update_entities or list_zones vs. zone_stats. However, some overlap exists: open_nodes and get_recent both retrieve entity details, and copy_entities vs. move_entities could be confused, though descriptions clarify differences.
Tool names follow a consistent verb_noun pattern throughout, such as create_entities, delete_relations, and inspect_files. All use snake_case with clear, descriptive verbs, making the set predictable and easy to navigate.
With 20 tools, the count is slightly high but reasonable for managing a knowledge graph with zones, entities, and relations. It covers operations like CRUD, inspection, and zone management, though it might feel heavy compared to simpler servers.
The toolset provides comprehensive coverage for a knowledge graph domain, including entity and relation CRUD, zone management (create, delete, merge, list), search capabilities, and utilities like time retrieval. No obvious gaps are present; agents can perform full lifecycle operations.
Intelligent context infrastructure for AI teams: knowledge graph, sessions, tasks, documents.
Shared long-term memory for AI agents: save and recall context as a searchable knowledge graph.
Persistent knowledge graph for AI agents. Remember, recall, and forget facts.
Persistent memory and knowledge graphs for AI agents. Hybrid search, context checkpoints, and more.
