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., "@semantica Remember that the production database is read-only after 5 PM."
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.
这是一个可以直接运行的 Semantica 小项目，专门回答一件事：
agent 是怎么接到 Semantica 上的？
结论先说清楚：
Semantica 不是 agent 框架。
它不调度工具、不跑 ReAct、不管理 multi-agent 对话。
它是 agent 下面的语义层：记忆、知识图谱、决策审计。
任何 agent（自己写的循环、Agno、LangChain、CrewAI、Claude、Cursor）都通过同一组插头接入。
你的 agent（自己写 / Agno / LangChain / CrewAI / Claude）
│
├── memory AgentContext.store / list
├── knowledge ContextGraph.add_node / query
├── decisions record_decision / 因果链
└── tools 框架 Toolkit 或 MCP
▼
Semantica五课默认不需要 LLM。第 2 课的决策可以额外接本地 runtime 或云端 API key，两者走同一条 OpenAI 兼容插头。
Python 3.11+
Intel macOS 会自动钉住仍提供 x86_64 轮子的 torch / onnxruntime / numba。其它平台由 Semantica 自己解析依赖。
Related MCP server: Engram-Mem
git clone https://github.com/sin3000x/semantica-agent-starter.git
cd semantica-agent-starter
uv sync验证：
uv run python --version
uv run python -c "import semantica; print(semantica.__version__)"
uv run python main.py doctor第一次创建 VectorStore 可能下载 embedding 模型；第一次导入 Semantica 也会比较慢。
uv run python main.py
uv run python main.py 1课 | 做什么 |
1 | 插头就是 |
2 | 采购 agent：感知 → 查先例 → 决策 → 落盘 |
3 | 两个 agent 不发消息，读写同一张 |
4 | Agno / LangChain / CrewAI 只是把四个插座包成框架对象 |
5 | Claude / Cursor 走 MCP： |
uv run python main.py all第 2 课默认用规则：延期天数 > 库存天数 就升级。规则一直可测、可回退。
配置了 LLM 之后，decide() 会先问模型；解析失败或连不上就退回规则。Semantica 仍然只负责记住决定。
复制环境文件：
cp .env.example .envOpenCode 是一等 runtime：默认调用本机 opencode run，用你已经 opencode auth login 过的模型，不必再配一份 API key。
# 先装 OpenCode，并完成登录
# curl -fsSL https://opencode.ai/install | bash
# opencode auth login
SEMANTICA_LLM=opencode
# 可省略，缺省用 OpenCode 当前默认模型
# SEMANTICA_LLM_MODEL=anthropic/claude-sonnet-4-5已经 opencode serve 时，让 CLI 挂到现有服务上，避免每次冷启动：
SEMANTICA_LLM=opencode
OPENCODE_ATTACH=http://127.0.0.1:4096若你跑的是 OpenCode 的 OpenAI 兼容代理（例如 opencode-llm-proxy 的 :4010），把地址写成 /v1 即可：
SEMANTICA_LLM=opencode
SEMANTICA_LLM_BASE_URL=http://127.0.0.1:4010/v1也适合 Ollama、vLLM、LM Studio，以及任何 OpenAI 兼容服务。
# Ollama
ollama pull llama3.1
# .env
SEMANTICA_LLM=ollama
SEMANTICA_LLM_MODEL=llama3.1
OLLAMA_HOST=http://127.0.0.1:11434# LM Studio / vLLM
SEMANTICA_LLM=compat
SEMANTICA_LLM_BASE_URL=http://127.0.0.1:1234/v1
SEMANTICA_LLM_MODEL=local-model
SEMANTICA_LLM_API_KEY=local默认推荐 SpaceXAI / xAI（OpenAI 兼容，XAI_API_KEY）。
XAI_API_KEY=xai-...
# 可省略 SEMANTICA_LLM，有 XAI_API_KEY 就会自动选 xai
SEMANTICA_LLM_MODEL=grok-4.6也可以用 OPENAI_API_KEY 或 GROQ_API_KEY。探测顺序：显式 SEMANTICA_LLM → XAI_API_KEY → OPENAI_API_KEY → GROQ_API_KEY。
uv run python main.py doctor
uv run python main.py 2不要把 .env 提交进 git。
配置样例在 mcp/。把 /ABS/PATH/TO/semantica-agent-starter 换成你的克隆路径。
uv run python -m semantica.mcp_serveruv run pytesttests/test_llm.py 不访问网络。课程测试第一次大约需要几分钟（Semantica 导入和 VectorStore 初始化比较重）。
测试检查的是接入约束：
agent 写入的记忆和决定都能读回来
规则 agent 的第二次决定能追溯到第一次
两个 agent 共享同一张图
没配 key 时不会误接 LLM；配了坏响应会回退规则
框架 | 接到哪 |
自己写循环 | 直接调 |
Agno |
|
LangChain |
|
CrewAI |
|
Claude / Cursor | MCP |
本项目不安装这些 extra。第四课用一个小适配器把同样的四个插座跑通。
MIT
Add a node/entity to the Semantica knowledge graph.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Unique node ID | |
| type | No | Node type, e.g. 'Person', 'Organisation' | |
| label | No | Human-readable label | |
| metadata | No | Additional properties |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations and no behavioral details, the description only says 'add' without explaining idempotency, duplicate handling, whether existing nodes are updated, or what the operation returns. This leaves important mutation semantics 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, direct sentence with no redundant wording or irrelevant details. It is optimally concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the basic operation but omits important operational context such as uniqueness constraints, failure behavior, return value, and relationship to other tools. An agent would have to infer or discover these details elsewhere.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the parameters are already well-documented in the schema. The description does not add parameter-level meaning, but the schema sufficiently covers it, warranting the baseline score.
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?
Clearly states the operation ('Add') and the resource ('a node/entity to the Semantica knowledge graph'). This distinguishes it from the sibling 'add_relationship' tool by specifying the graph element type.
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?
Provides no guidance on when to use this tool versus alternatives like add_relationship, nor any exclusions or preconditions. The usage context is only implied by the tool name and description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add a directed relationship (edge) between two entities in the knowledge graph.
| Name | Required | Description | Default |
|---|---|---|---|
| type | No | Relationship type, e.g. 'WORKS_AT' | |
| source | Yes | Source node ID | |
| target | Yes | Target node ID | |
| metadata | No | Additional edge properties |
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 only states that it adds a relationship, implying a mutation, but does not disclose side effects, error conditions, requirements for entity existence, or whether the operation is idempotent. The absence of such details leaves the agent uncertain about the tool's 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, efficient sentence that front-loads the action and resource. There is no unnecessary detail or repetition, making it 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?
The tool has 4 parameters including a nested object and no output schema. The description does not explain return values, failure modes, or whether the operation is conditional (e.g., if entities must exist). This is insufficient for an agent to confidently invoke the tool, especially as a mutation 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 description coverage is 100%, so each parameter is already documented in the schema. The description adds minimal extra meaning, only clarifying that source and target refer to entities and that the relationship is directed. This meets the baseline for high schema coverage but does not enrich parameter understanding.
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 'directed relationship (edge) between two entities in the knowledge graph.' It distinguishes this from sibling tools like add_entity (which adds an entity) and extract_relations (which extracts relations from text) by specifying the exact operation on graph edges.
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 alternative guidance is provided, but the purpose is implied: use this when you need to create a link between existing entities. The description does not mention exclusions or prerequisites (e.g., entities must exist), leaving some ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Export the current knowledge graph. Formats: turtle, ttl, nt, xml, json-ld, json.
| Name | Required | Description | Default |
|---|---|---|---|
| format | No | Export format (default: json-ld) |
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 conveys a read-only snapshot-like action, but it does not explicitly state that the tool has no side effects, whether the output is returned inline or as a file, or any constraints like size limits.
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 short and front-loaded with the key action. The format list is somewhat redundant with the schema enum, but it is compact and harmless, so there is minimal wasted 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?
For a simple one-parameter tool, the description covers the core purpose and format options, but without an output schema it leaves ambiguity about what the exported result looks like. An agent might need extra context on whether the response is a serialized graph string, a file path, or a download action.
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 already fully describes the single optional 'format' parameter with an enum covering all valid values, so the description adds no new semantic meaning. The format list in the description mirrors the schema rather than extending it, meeting the baseline but not exceeding 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 uses a specific verb ('Export') and resource ('the current knowledge graph'), making the tool's action unmistakable. It also lists concrete output formats, which distinguishes it from sibling tools that summarize or analyze the 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 implies when to use this tool — when you need the full graph in a serialized format — but it never explicitly contrasts it with alternatives like get_graph_summary or get_graph_analytics. There is no 'if you need X, use Y instead' guidance, leaving the routing decision to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Extract named entities (people, places, organisations, concepts) from text using Semantica NER.
| Name | Required | Description | Default |
|---|---|---|---|
| text | Yes | Input text to extract entities from |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description only states that it uses Semantica NER and extracts entities. With no annotations provided, the description carries the full burden, but it does not disclose whether the tool is read-only, mutates any stored data, has input size limits, returns a list/JSON, or has any rate/error behavior. 'Extract' implies pure inference, but this is not confirmed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence that front-loads the verb, resource, and processing engine with zero wasted words. It communicates the core operation immediately and is structurally clean.
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 one-parameter extraction tool, the description covers the main purpose, but with no output schema and no annotations, the agent is left guessing about the result format, side effects, and failure conditions. Given the richness of sibling tools (e.g., add_entity), it should at least mention that this is a readonly extraction or that the result is a list of entity mentions.
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 for the only parameter, 'text', so the description does not need to add much. The description adds marginal entity-type context but no deeper semantics about text length, language, formatting, or what 'text' should contain beyond the schema's basic explanation.
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?
Uses a specific verb and resource ('extract named entities... from text') and lists the entity categories (people, places, organisations, concepts). This clearly distinguishes it from sibling tools like extract_relations, which targets relationships, and add_entity, which likely writes to the graph rather than extracting from text.
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 mentions of when to use this over alternatives or exclusions. It does not reference sibling tools such as extract_relations, add_entity, or run_reasoning, leaving the agent to infer the appropriate context 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.
Extract relations and (subject, predicate, object) triplets from text.
| Name | Required | Description | Default |
|---|---|---|---|
| text | Yes | Input text to extract relations from |
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 only states the operation without mentioning read-only nature, output format, or any side effects. For a tool that extracts relations, the read-only assumption is implied but not explicitly stated, leaving an agent without complete behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no redundant phrasing. Every word contributes to conveying the purpose, making it highly concise and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter, no output schema), the description is adequate for basic use. It clarifies the core operation but does not specify the output format (e.g., list of triplets) or any constraints. Since no output schema exists, describing the return shape would improve completeness, but the current description is sufficient for straightforward extraction.
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 for the single parameter 'text' is already descriptive ('Input text to extract relations from'), achieving 100% coverage. The description's mention of 'from text' adds no new meaning beyond what the schema provides, so it 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 states a specific verb ('extract') and resource ('relations and (subject, predicate, object) triplets') from text, making the tool's function immediately clear. It also distinguishes it from sibling 'extract_entities', which focuses on entities rather than 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?
The description implies usage when relations need to be extracted from text, but provides no explicit when-to-use guidance or exclusions. It does not mention alternative tools like 'extract_entities' or clarify when this tool should be preferred.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find past decisions similar to a given scenario using hybrid similarity search.
| Name | Required | Description | Default |
|---|---|---|---|
| scenario | Yes | Scenario description to find precedents for | |
| max_results | No | Max results (default 5) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the full burden. It discloses the hybrid similarity search behavior, which implies a read-only semantic lookup, but does not state that it is non-destructive, how results are ordered, or what the return payload looks like.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One compact sentence with no filler; the core action and method are front-loaded. It is easy to scan and every word contributes to understanding.
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 two-parameter search tool the description is minimally adequate, but with no output schema or annotations it still leaves uncertainty about return structure and lacks usage context relative to sibling query tools. It could be improved with a note on result ranking or a sample of what is returned.
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 documents both parameters with 100% coverage, so the description is not required to add much. It adds little beyond 'hybrid similarity search' and does not elaborate on max_results behavior or format, 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 a specific verb ('find'), a clear resource ('past decisions'), and a scope qualifier ('similar to a given scenario') that signals semantic matching. It does not explicitly contrast with sibling query_decisions, but the hybrid similarity phrasing helps an agent tell them apart.
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 find_precedents over query_decisions, run_reasoning, or get_causal_chain, nor are there exclusions or prerequisites. An agent must infer the use case from the name and description alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Trace the causal chain upstream or downstream from a decision.
| Name | Required | Description | Default |
|---|---|---|---|
| direction | No | Trace direction | |
| max_depth | No | Max chain depth (default 5) | |
| decision_id | Yes | Decision ID to trace |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must convey behavioral details. It only states the action without disclosing output format, side effects, or any constraints. There is no mention of whether it is read-only, what happens if the decision is missing, or how results are structured.
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 immediately states the action. It is front-loaded with the core purpose and contains no extraneous words, making it efficient and easy to parse.
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 describe what the returned causal chain looks like or any behavioral nuances. It also fails to mention default behavior (e.g., max_depth default) beyond what the schema provides. Given the lack of annotations and output schema, the description is incomplete for an agent to call 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?
The schema provides 100% coverage of parameter descriptions, so the description does not need to add parameter details. It does not offer extra meaning beyond the schema, which aligns with the baseline score 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: 'Trace the causal chain upstream or downstream from a decision.' It identifies a specific verb and resource, and the phrase 'causal chain' distinguishes it from sibling tools like query_decisions or find_precedents, though it 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?
The description provides no guidance on when to use this tool versus others. It does not mention conditions, exclusions, or alternatives, leaving the agent to infer usage from the tool name and context. This is a notable gap.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Compute PageRank centrality and community detection over the knowledge graph.
| 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 of behavioral disclosure. It does not explicitly state that this is a read-only operation, whether it mutates the graph, what the output shape is, or whether computation may be expensive or require prior graph construction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no filler. Every phrase adds meaning: the action, the target, and the specific analytics computed.
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 no annotations and no output schema, the description leaves the return format and side-effect profile unstated. However, for a zero-parameter analytics tool, the core invocation intent is adequately conveyed.
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 coverage is 100%, so there is no parameter documentation burden. The baseline of 4 applies because no parameter semantics are needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific operation (compute), the target resource (knowledge graph), and the concrete algorithms (PageRank centrality and community detection). This clearly distinguishes it from siblings like get_graph_summary or get_causal_chain, which serve different purposes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the use case: call this tool when graph-level analytic metrics are needed. It does not explicitly name alternatives or exclusions, but the algorithm names make the selection context clear enough for an agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return a high-level summary of the current knowledge graph: node count, decision count, status.
| 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 behavioral disclosure. It states it returns a summary, implying read-only behavior, but does not explicitly say it is non-destructive or describe any performance implications. There is no contradiction, but the description is minimal.
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, front-loaded with the verb and resource, and contains no filler. It efficiently communicates the purpose and contents.
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, zero-parameter read tool with no output schema, the description adequately conveys what the agent will receive. It could clarify how this differs from get_graph_analytics, but it is otherwise sufficient for a high-level summary.
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, so the schema is empty and coverage is trivially 100%. The baseline for 0-parameter tools is 4, and the description does not need to explain any parameters since none exist.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Return') and resource ('knowledge graph'), and explicitly lists the contents (node count, decision count, status). It clearly distinguishes itself as a high-level summary, which differentiates it from sibling get_graph_analytics that likely provides deeper analytics.
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 when to use it (when a high-level summary is needed) but does not explicitly mention alternatives or when not to use it. For a zero-parameter read tool, this is acceptable but could be more explicit about the distinction from get_graph_analytics.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Query recorded decisions by natural language, category, or get all recent decisions.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max results (default 10) | |
| query | No | Natural language query (optional) | |
| category | No | Filter by category (optional) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses the query modes but doesn't mention behavior like default limit, ordering, pagination, or whether 'all recent decisions' requires no parameters. The default limit of 10 is only in the schema, not the description, and the description doesn't clarify what 'recent' means.
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 main action and lists the query modes efficiently. It earns its place with no wasted words, though it could be slightly more 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 read-only query tool with 100% schema coverage and no output schema, the description is adequate but not complete. It doesn't explain return format, ordering, or how the three modes interact (e.g., can query and category be combined?). The lack of annotations raises the burden, and the description doesn't fully meet it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all three parameters. The description adds the concept of 'natural language' and 'category' as query modes, which aligns with the parameters, but doesn't add detail beyond what the schema provides. Baseline 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 states a clear verb ('Query') and resource ('recorded decisions') and lists three access modes: natural language, category, or all recent decisions. It distinguishes itself from sibling tools like record_decision (write) and find_precedents (precedent search), though it doesn't explicitly name 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 implies usage for retrieving decisions, and the optional parameters suggest flexible querying. However, it doesn't explicitly state when to use this tool over siblings like find_precedents or get_graph_summary, nor does it mention any exclusions or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Record a decision into the Semantica knowledge graph with full context, causal links, and metadata.
| Name | Required | Description | Default |
|---|---|---|---|
| outcome | Yes | Decision outcome, e.g. 'approved' | |
| category | Yes | Decision category, e.g. 'loan_approval' | |
| scenario | Yes | Natural-language situation description | |
| reasoning | Yes | Why this decision was made | |
| confidence | Yes | Confidence score 0–1 | |
| valid_from | No | ISO date validity start (optional) | |
| valid_until | No | ISO date validity end (optional) | |
| decision_maker | No | Who/what made the decision |
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, and it falls short. It does not state whether the operation is idempotent, whether duplicate decisions are prevented, whether existing records are merged or overwritten, what prerequisites exist (e.g., do entities need to already exist for causal links?), or what happens on success. The mention of 'causal links' raises more questions than it answers about how linking is handled.
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 the verb front-loaded, containing zero fluff or redundancy. However, it is so terse that it omits behavioral and usage context that would justify a few more words. Efficiency is high, but the economy comes at the cost of necessary 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?
For a write tool with 8 parameters, no annotations, and no output schema, the description is incomplete. It does not disclose prerequisites (such as whether referenced entities must pre-exist for causal linking), does not indicate what the tool returns on success or failure, and does not clarify the linking behavior implied by 'causal links'. An agent calling this tool has no way to predict side effects or failure modes.
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 baseline is 3 per the rubric. The schema already documents all 8 parameters with clear examples ('approved', 'loan_approval'). The description's mention of 'full context, causal links, and metadata' does not map to any specific parameters and adds no semantic value beyond the schema. This is a case where the schema does the heavy lifting and the description adds nothing extra.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Record'), resource ('decision'), and destination ('Semantica knowledge graph'), which makes the core purpose clear. However, it does not explicitly differentiate from siblings like add_entity or add_relationship, leaving the agent to infer why this tool is distinct. The phrase 'full context, causal links, and metadata' hints at scope but is not specific enough to separate it from the other write 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?
The description gives zero guidance on when to use this tool versus siblings such as add_entity, add_relationship, or run_reasoning. There is no 'use when' or 'use instead' language, and no indication of whether this tool is preferred for decision-specific writes versus generic entity or relationship additions. An agent must guess at the routing logic based solely on the name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run forward-chaining IF/THEN rules over a set of facts to derive new facts.
| Name | Required | Description | Default |
|---|---|---|---|
| facts | Yes | List of fact strings, e.g. ['Person(John)', 'Employee(John)'] | |
| rules | Yes | IF/THEN rule strings, e.g. ['IF Employee(?x) THEN WorkerBee(?x)'] |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, so the description must carry the full transparency burden. It never states whether derived facts are persisted, returned transiently, or materialized into the graph, leaving side effects ambiguous for a non-read-only-looking 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?
One tight sentence that front-loads the verb, key input concept (facts + rules), and purpose. No filler 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?
Without annotations or an output schema, the description should clarify what the caller receives and whether state changes. It does not disclose persistence, return value, failure behavior, or inference output structure, leaving an agent with incomplete execution expectations.
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 documents both parameters with examples, so the baseline is adequate. The description's 'IF/THEN' and 'forward-chaining' wording clarifies rule semantics but adds no new constraints, formats, or parameter-level behavior.
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 states a specific action ('Run forward-chaining IF/THEN rules'), a clear input ('facts'), and a distinct outcome ('derive new facts'). This clearly differentiates the tool from sibling extraction, query, and graph-mutation 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?
The description implies a clear usage context: use when you have facts plus rules and want derived facts. It does not explicitly name exclusions or when not to use it, but it is specific enough to route an agent effectively.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0add_entityadd_relationshipexport_graphextract_entitiesextract_relationsfind_precedentsget_causal_chainget_graph_analyticsget_graph_summaryquery_decisionsrecord_decisionrun_reasoningScored across 12 tools
Each tool targets a clearly distinct operation: extraction, knowledge graph mutation, decision querying, reasoning, analytics, and export. There is no meaningful overlap or ambiguity between the tool purposes.
All tool names follow a consistent snake_case verb_noun pattern, such as extract_entities, record_decision, query_decisions, and get_graph_analytics. The naming is predictable and easy to navigate.
Twelve tools is well-scoped for a knowledge graph and semantic reasoning server. Each tool covers a distinct capability without unnecessary bloat.
The tool set covers creation, querying, reasoning, analytics, and export, but lacks update/delete operations for entities, relationships, or decisions. This is a notable lifecycle gap that agents may need to work around.
Persistent AI memory shared across Claude, ChatGPT, coding agents, and compatible MCP clients.
Shared memory and actions for Claude, Kiro, OpenAI, Cursor, and other MCP-compatible AI clients.
Shared, governed long-term memory for AI agents across tools and sessions via MCP and REST.
Your memory, everywhere AI goes. Build knowledge once, access it via MCP anywhere.
