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., "@rawthink search for decisions about database"
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.
Persistent memory for AI thinking partnerships. A knowledge graph you can argue with, search that spans every session you have ever had, and a record of not just what you decided but what you rejected.
MCP server for Claude Code. Python, local, no cloud.
Every conversation with an AI starts from nothing. You explain the same context, re-derive the same conclusions, and rediscover decisions you already made — and the reasoning that produced them is gone the moment the window scrolls.
Chat history does not fix this. History is a transcript; what you need is structure: which ideas connect, which beliefs you have since abandoned, which alternatives you considered and dropped, and why.
RAWThink keeps that structure in three layers, in files you own.
Related MCP server: Memora
Hybrid semantic search across every session and note — BGE-M3 dense embeddings and BM25 sparse vectors, fused with RRF. Ask "what did I think about free will?" and get the passages, not a keyword match.
A temporal knowledge graph where observations carry dates and status. Beliefs can be marked invalidated and linked to what replaced them, so the archive remembers not only what you think but what you used to think.
Session lifecycle — a close command that exports the conversation, extracts entities into the graph, and writes a handoff the next session loads automatically.
Activation decay — unused knowledge fades on a ~23-day half-life, accessed knowledge stays warm. Old material is still there; it just stops crowding out what you are working on now.
Python 3.10+
Docker for Qdrant — or set QDRANT_PATH for embedded mode
Ollama with bge-m3: ollama pull bge-m3
pip install rawthink-mcp
rawthink-install # creates ~/rawthink-vault with everything inside
cd ~/rawthink-vault
docker compose up -d # starts Qdrantrawthink-install writes the vault structure, CLAUDE.md,
THINKING_DIRECTIVES.md, SETUP.md, docker-compose.yml and the /rtclose
command. Use rawthink-install --vault ~/my-vault for a different location.
claude mcp add --scope user rawthink -- rawthink-mcprawthink-doctorNine checks with a fix line for each failure: vault, graph schema, BM25 state format, Qdrant, index coverage, vector dimension, Ollama, MCP registration.
The index coverage check is the one worth knowing about. Indexing can stop partway and leave a collection that looks healthy — it exists, it has points, queries return results. They are results from part of the vault, and nothing else tells you that.
1.5.0 changed the graph schema and 2.0.0 changes the sparse index. Migrate the graph before writing anything:
python -m rawthink_mcp.migrate --path vault/memory.jsonl --guess-domains --heal-danglingThat is a dry run — it prints what would change and writes nothing. Read the
report, then re-run with --apply. A timestamped backup is taken first.
Then re-encode the search index, because BM25 term IDs changed:
reindex(full=True)A plain reindex skips unchanged chunks and will leave the old encoding in
place. rawthink-doctor tells you if this is still pending.
See CHANGELOG.md for what changed and why.
> search_thoughts("what have I decided about caching?")
> record_decision(
name="api/cache: read-through",
domain="software",
decided="read-through cache in front of the read model",
because="the write path is already the bottleneck; adding invalidation there costs more",
rejected=["write-through — couples the write path to cache health",
"no cache — p99 was 400ms against a 200ms SLO"]
)Close with /rtclose. It exports the conversation, extracts what is worth
keeping into the graph, and leaves a handoff for next time — which the next
session loads on its own.
This is the part worth understanding, because it is what keeps the graph queryable over years rather than months.
entityType answers what role does this node play. Closed list of ten:
type | for |
| a choice made, with alternatives rejected |
| an idea, theory, model, analogy |
| something discovered or measured — a bug, a result, an audit |
| a durable constraint or pattern to follow |
| unresolved, waiting on evidence |
| a project, tool, document, feature, source |
| a realisation that changed how something is seen |
| a unit of intended work |
| something that happened at a point in time |
| a person, object or substance named directly |
domain answers what subject is it about: software, music, history,
philosophy, health, writing, neuro, finance, personal, galaxy.
Keeping these apart is not tidiness. When one field carries both, the type list
grows by one entry per subject — a real vault reached 46 types this way, with
saglik-bulgusu, teknik-karar and bug-pattern sitting next to karar. At
that point nothing can be filtered, because no two entries agree on what a type
means.
Canonical vocabulary: supports, contradicts, evolved_into, depends_on,
exemplifies, part_of, caused_by, enables, supersedes, related_to,
investigates, informs, uses.
Close synonyms fold automatically — connected_to → related_to, aspect_of →
part_of. Anything else raises.
An earlier version accepted unknown types with a warning. Nothing acted on the warning and 56 one-off types accumulated. A warning that lets the write through is a decision to allow it, written in the voice of disapproval.
assertion, hypothesis, speculation — or unknown when unstated.
unknown is deliberate. If a session did not establish something, recording it
as an assertion promotes a claim nobody made. The migration follows the same
rule: 144 entities with no epistemic field became unknown, not assertion.
> revise(entity_name="api/cache: read-through",
observations=["read-through cache in front of the read model"],
superseded_by="moved to write-through after the read model split",
superseding_entity="api/cache: write-through")The old observation is marked invalidated, dated, and linked to what replaced it. Delete tools exist but sit outside the default agent-facing profiles: an archive that forgets its own reversals cannot answer the question it was kept for.
record_decision stores decided, because, and rejected as separately
queryable observations. The rejected alternatives are the part worth keeping —
what was chosen stays readable in the code forever, what was considered and
dropped exists nowhere else. That is the question that gets asked six months
later.
Tool definitions sit in the context window from the first token of a session, so the surface is a standing cost rather than a per-call one. Profiles load only what a given step needs.
RAWTHINK_TOOL_PROFILE=recall # 4 tools, ~900 tokens — read-only
RAWTHINK_TOOL_PROFILE=record # 5 tools, ~1750 tokens — the write path
RAWTHINK_TOOL_PROFILE=full # 17 tools, ~4200 tokens — everything (default)A tool outside the active profile stays an ordinary function — reachable from the CLI and from tests. It simply is not in front of an agent that will not call it.
tool | what it does |
| Hybrid search. |
| Full content of a session by ID |
| Save a quick note as a qnote |
| Re-index the vault into Qdrant |
tool | what it does |
| Bounded. Filters by |
| Specific entities with their relations |
| Whole graph, paginated, with a summary mode |
tool | what it does |
| Entities, relations and observations in one validated, atomic call |
| A decision with its rejected alternatives |
| Mark observations superseded, link what replaced them |
| Lower-level equivalents |
| Belief revision without the relation link |
|
|
record() validates the whole batch before writing any of it. A half-valid
batch writes nothing — a graph left in a state nobody asked for is worse than a
rejected write. Relations may only point at entities that already exist or are
created in the same call.
Every tool carries MCP annotations (readOnlyHint, destructiveHint,
idempotentHint), so a host can tell deletion apart from search.
Claude Code
│ MCP (stdio)
▼
rawthink-mcp
├── search ──► Qdrant dense (BGE-M3) + sparse (BM25), RRF fusion
├── graph ──► memory.jsonl entities, relations, temporal observations
└── export ──► vault/ sessions, qnotes, handoffs as markdown
│
Ollama (bge-m3)Everything runs locally. The vault is plain markdown with YAML frontmatter — open it in Obsidian to browse visually, no plugins needed.
Human-readable, git-diffable, no dependency. You can open it, read it, and see a meaningful diff when it changes — which matters for something meant to hold your reasoning.
The tradeoff is load time: the whole file is parsed per read. Fine at a few hundred entities, slower as it grows. Past tens of thousands, SQLite is the obvious next step.
session start handoff loads automatically (SessionStart hook)
↓
think together
↓
/rtclose export → extract entities → write handoff → update MEMORY.md/rtclose exports the conversation to clean markdown, extracts entities and
relations through record(), writes a project-scoped handoff, and updates
MEMORY.md.
The lifecycle commands currently require Claude Code. The search and graph tools work with any MCP client.
Setting | Env var | Default |
Vault path |
|
|
Knowledge graph file |
|
|
Qdrant URL |
|
|
Qdrant embedded path |
| — (set it to skip Docker) |
Ollama URL |
|
|
Embedding model |
|
|
Tool profile |
|
|
Turkish normalization |
|
|
Evaluation set |
|
|
Vocabularies — ENTITY_TYPES, DOMAINS, RELATION_TYPES, RELATION_ALIASES —
live in rawthink_mcp/config.py. Adding a domain is a one-line change.
CLAUDE.md — the thinking companion's role, tone and modes.
THINKING_DIRECTIVES.md — discipline for the partnership. Every rule was
written after failing at it. Add your own; the only bad version of that file is
one followed without understanding why each rule exists.
Both are copied into your vault by rawthink-install. If you edit the repo
copies, run python scripts/check_templates.py — the installer embeds them, and
two copies of one document drift silently.
Stated plainly, because a README that lists only strengths is not much use.
Ollama being unavailable degrades to sparse-only. The embedding cache helps repeated queries; it is not a fallback. Retrieval quality drops noticeably.
Graceful shutdown is POSIX-only. Signal handlers release the Qdrant
directory lock and the graph file lock on SIGINT/SIGTERM. Windows has no real
SIGTERM — a terminating client calls TerminateProcess and no handler runs — so
a hard stop there can leave a lock behind. Ctrl-C still unwinds, and
rawthink-doctor reports the stale lock.
Load time grows with the graph. The whole JSONL is parsed on the first read after a change. Subsequent reads reuse a cache keyed on (mtime, size).
Search quality has not been benchmarked at scale. The retrieval numbers
that used to be here were never re-measured, so they were removed rather than
carried forward. tests/search_quality.py runs against a synthetic vault and
reports MRR/nDCG; point RAWTHINK_EVAL_GT at your own evaluation set for a
number that means something for your data.
Next — graph visualisation, MCP-native session lifecycle so the close command is not Claude Code specific, support for more MCP clients, and a retrieval benchmark that runs on data anyone can regenerate.
Issues and pull requests welcome.
If you change the schema, change config.py, the migration in migrate.py, and
the session-close instructions together. They are three views of one contract,
and they drift apart quietly when they are not edited as a set.
docs/postmortem-bm25-term-drift.md is the clearest example — a defect that
looked fine from every angle until someone evaluated the two retrievers
separately.
MIT
Add new observations to existing entities in the knowledge graph.
| Name | Required | Description | Default |
|---|---|---|---|
| observations | Yes | List of dicts with keys: entityName, contents (list of strings). |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already convey read/write and idempotency characteristics, and the description adds the constraint that entities must exist. However, it does not describe edge-case behavior (e.g., duplicate observations, missing entities) or error handling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single 11-word sentence that is direct and free of extraneous detail. It gets straight to the point.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple one-parameter schema and available annotations, the description covers the core functionality. It could benefit from a note about error handling or idempotency behavior, but the output schema likely fills in return-value details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already describes the parameter shape (list of dicts with entityName and contents). The description adds the semantic requirement that entities must already exist, which is not stated in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Add') and the resource ('new observations to existing entities in the knowledge graph'), using a specific verb and object. It distinguishes from sibling tools like 'create_entities' (which creates entities) and 'delete_observations' (which removes observations).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly state when to use this tool versus alternatives. However, the action is clear and the sibling context implies its use for enriching existing entities. It lacks explicit exclusions or alternative recommendations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create multiple new entities in the knowledge graph.
If an entity with the same name exists, new observations are merged.
Each entity can have:
name (required): Entity name
entityType: Type (default "concept")
observations: List of observation strings
epistemic: "assertion" | "hypothesis" | "speculation" (optional)
Observations are stored with temporal metadata (created date, status). Entities get activation tracking (activation=1.0, last_accessed=today).
| Name | Required | Description | Default |
|---|---|---|---|
| entities | Yes | List of dicts with keys: name, entityType, observations (list of strings), epistemic (optional). |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes well beyond the annotations by disclosing merge behavior, default entityType, temporal metadata, and activation tracking. These details explain the tool's non-destructive, idempotent nature and side effects on existing entities.
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 concise, front-loaded with the main action, and uses bullet points for clarity. Every sentence contributes meaningful information without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists, the description fully covers purpose, parameters, and behavioral effects. It explains merge semantics, defaults, and metadata, providing an agent with sufficient information to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
While the schema simply lists keys, the description enriches them with essential semantics: required name, default 'concept' for entityType, observations as list of strings, and the epistemic enum. This fills in type/default/enum details missing from the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Create multiple new entities in the knowledge graph', specifying a distinct verb and resource. It also notes merging behavior for existing names, which distinguishes it from sibling tools like create_relations or delete_entities.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context that this tool can also merge observations into existing entities, implying an upsert use case. However, it does not explicitly mention when to prefer alternatives like add_observations, so there are no formal exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create multiple new relations between entities. Relations should be in active voice.
Canonical relation types: supports, contradicts, evolved_into, depends_on, exemplifies, part_of, caused_by, enables, supersedes, related_to.
Non-standard types are accepted but return a warning.
| Name | Required | Description | Default |
|---|---|---|---|
| relations | Yes | List of dicts with keys: from, to, relationType. |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds behavioral context beyond the annotations: it requires active voice, lists canonical relation types, and warns that non-standard types are accepted but return a warning. This complements the annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false) without contradicting them.
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 three sentences: the first states the purpose, the second lists canonical types, and the third warns about non-standard types. It is concise, front-loaded, and every sentence earns its place 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 tool's simplicity, the annotations, and the presence of an output schema, the description covers the essential aspects: purpose, valid relation types, and warning behavior. It could be more explicit about when to use the tool versus alternatives, but it is reasonably complete for the task.
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 describes the 'relations' parameter as 'List of dicts with keys: from, to, relationType,' so coverage is 100%. The description adds value by specifying the active voice requirement, enumerating canonical types, and noting the warning for non-standard types, which enriches parameter understanding beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Create multiple new relations between entities.' This is a specific verb+resource combination that distinguishes it from sibling tools like create_entities (which creates entities) and delete_relations (which removes 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 for creating relations and provides canonical relation types, but it does not explicitly state when to use this tool versus alternatives or when not to use it. It lacks explicit exclusions or references to other tools, so guidance is present but not fully spelled out.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete multiple entities and their associated relations from the knowledge graph.
| Name | Required | Description | Default |
|---|---|---|---|
| entityNames | Yes | List of entity names to delete. |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover destructive and idempotent hints. The description adds valuable behavioral context: it cascades to associated relations and handles multiple entities batch-wise. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded with action and scope. No filler words; every element is meaningful and 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?
For a simple one-parameter deletion tool with output schema and annotations, the description sufficiently covers purpose, scope, and cascade behavior. Could be slightly more explicit about irreversibility or partial failure, but generally complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% (single entityNames parameter described as 'List of entity names to delete'). Description adds no further parameter detail, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description uses a specific verb ('delete') and resource ('entities and their associated relations'), clearly distinguishing from sibling tools like delete_relations. It also specifies batch handling ('multiple'), making the tool's scope unambiguous.
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 want to delete entities and their relations) but does not explicitly state when to use this tool vs alternatives like delete_relations or create_entities. No exclusions or preconditions are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete specific observations from entities in the knowledge graph.
| Name | Required | Description | Default |
|---|---|---|---|
| deletions | Yes | List of dicts with keys: entityName, observations (list of strings to remove). |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, destructiveHint=true, and idempotentHint=true. The description adds no extra behavioral context, such as permanence, error handling, or effects on related data. It merely restates 'delete' which is consistent with the annotations but adds no new information.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one concise, front-loaded sentence that directly states the action and scope. There is no redundant or filler content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has a simple input schema and annotations covering destructive and idempotent behavior. The description states the core function, but lacks any usage context or clarification on when to choose this over similar siblings like invalidate_observations. It is adequate but not thorough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the schema already provides a detailed description of the 'deletions' parameter. The tool description adds no parameter-specific meaning, so it relies on the schema. Baseline 3 is appropriate 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 verb 'delete' and the resource 'specific observations from entities in the knowledge graph'. It distinguishes from sibling tools like delete_entities and delete_relations by specifying the granularity (observations within entities).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention exclusions or when another sibling like invalidate_observations or delete_entities would be more appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete multiple relations from the knowledge graph.
| Name | Required | Description | Default |
|---|---|---|---|
| relations | Yes | List of dicts with keys: from, to, relationType. |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint true, idempotentHint true, and readOnlyHint false. The description adds no additional behavioral context beyond what annotations provide, such as permanence or effects on connected entities.
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, focused sentence with no filler. Every word contributes to the meaning and is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple one-parameter structure, existing output schema, and annotations covering safety, the one-sentence description is sufficient for an agent to understand the tool's core action. No additional return value or parameter explanation 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?
The input schema fully documents the 'relations' parameter with keys from, to, relationType. The description repeats 'multiple' but adds no syntax or format details beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Delete', the resource 'relations', and the scope 'knowledge graph', making it specific and distinguishable from sibling tools that delete entities or observations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like delete_entities or create_relations. It does not mention prerequisites, context, or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get full content of a session by reading the markdown file directly.
| Name | Required | Description | Default |
|---|---|---|---|
| session_id | Yes | Session identifier (e.g. "2026-03-16_001"). |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds valuable context by revealing that the tool reads the markdown file directly, implying it may bypass indexes or caches, and that the content is full (not truncated). This goes beyond what annotations provide, earning a 4.
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 that directly states the action and purpose. There is no redundant information or filler, making it highly concise and efficient.
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 retrieval tool with one parameter, clear annotations, and an output schema present, the description is complete enough. It conveys the key behavioral detail (direct file read) and the output schema covers return values. No further elaboration is necessary.
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% because the only parameter, session_id, has a clear description with an example. The tool description does not add further parameter-level meaning, but the schema already carries the semantic load, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Get full content of a session by reading the markdown file directly.' It specifies a concrete action (get), a resource (session content), and the method (direct markdown file read), which distinguishes it from sibling tools like search_thoughts or open_nodes.
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 clearly defining what the tool does, but it does not explicitly state when to use it versus alternatives or provide exclusions. It lacks guidance such as 'Use this when you need the raw session content rather than search results.'
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Mark observations as invalidated (belief revision tracking).
Sets status='invalidated' and records invalidated_at date. Optionally records what superseded the old belief.
| Name | Required | Description | Default |
|---|---|---|---|
| entity_name | Yes | Name of the entity whose observations to invalidate. | |
| observations | Yes | List of observation text strings to invalidate. | |
| superseded_by | No | Optional description of what replaced these beliefs. |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With annotations already declaring idempotentHint=true and destructiveHint=false, the description adds concrete mechanics: it sets a status field and a timestamp, and optionally records a superseding belief. This gives context beyond the annotations without contradicting them.
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 concise sentences plus a header line, front-loading the purpose. No filler or redundant repetition of schema/annotations.
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 100% schema coverage, an output schema, and annotations, the description covers the essential behavioral contract: it states the action, the exact state change, and the optional input semantics. It doesn't address edge cases like non-existent observations, but that level of detail is typically not required.
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%, and the description adds no additional parameter-level detail beyond what the schema already specifies (e.g., superseded_by matches 'Optional description of what replaced these beliefs'). It does mention the automatic invalidated_at date, but that's not a parameter.
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: 'Mark observations as invalidated' with a specific state change ('Sets status='invalidated' and records invalidated_at date'). This distinguishes it from deletion siblings by framing it as a soft invalidation with belief revision tracking.
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 through 'belief revision tracking' and the optional 'superseded_by' parameter, but it never explicitly says when to choose this over delete_observations or revise. No when-not guidance or alternatives are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Open specific nodes in the knowledge graph by their names.
Returns the requested entities and all relations connected to them.
| Name | Required | Description | Default |
|---|---|---|---|
| names | Yes | List of entity names to retrieve. |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds valuable context that the tool returns not just the requested entities but also all relations connected to them, which is a behavioral trait not evident from the schema alone. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise, front-loaded sentences with zero wasted words. It states the action, the resource, and the return value 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 the simple parameter set (one array), strong annotations, and an existing output schema, the description is nearly complete. It does not explicitly clarify when to use this over search_nodes or read_graph, which is a minor gap given the sibling context, but overall it provides sufficient context for a simple retrieval tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% (the 'names' parameter is described as 'List of entity names to retrieve'). The description reinforces that 'names' refers to entity names, but it adds no additional syntactic or format details beyond the schema, so a 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 states a specific verb ('open') and resource ('specific nodes in the knowledge graph'), and further clarifies the return value ('entities and all relations connected to them'). It is clear and distinct from siblings, but it doesn't explicitly differentiate itself from search_nodes or read_graph.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied: use when you know the exact names of nodes to retrieve. However, there is no explicit when-to-use vs alternatives, no exclusions, and no mention of cases where search_nodes or read_graph would be more appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read the entire knowledge graph — all entities and relations.
By default returns full entities with pagination (offset/limit). Use summary=True for a compact overview (names + types + observation counts).
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max entities to return (for pagination). Default 20. | |
| offset | No | Skip first N entities (for pagination). Default 0. | |
| summary | No | If True, return compact overview. If False (default), return full entities with pagination. | |
| entity_type | No | Filter entities by type (e.g. "concept", "decision", "insight"). |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, so the read-only safety is covered. The description adds useful behavioral details beyond annotations: pagination with offset/limit, the summary mode, and what the summary contains (names + types + observation counts). It doesn't mention all nuances like relation handling in default mode, but the added context is valuable.
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 three sentences, front-loaded with the primary purpose. Every sentence adds value: the core action, default pagination, and summary option. No fluff or repetition. It is 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 has an output schema and full schema coverage for parameters, the description adequately covers the main use case (read whole graph) and the two modes. It could mention performance implications of reading the entire graph or explicitly clarify that relations are also returned in the default paginated result, but it is mostly complete for a read tool with pagination and summary options.
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. The description adds extra meaning beyond the schema by specifying what summary=True provides ('names + types + observation counts') and clarifying default pagination behavior. This supplements the schema, justifying a 4 rather than a 3, though it doesn't heavily elaborate on other parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Read the entire knowledge graph — all entities and relations.' It uses a specific verb (read) and resource (knowledge graph), and distinguishes itself from siblings like search_nodes and search_thoughts by emphasizing the whole graph rather than focused search. The mention of summary mode adds further clarity about the tool's 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 implies when to use the tool: when you need to read the entire knowledge graph, as opposed to searching. It provides clear context about default behavior (full entities with pagination) and the alternative summary mode. However, it does not explicitly name sibling tools as alternatives or state when not to use this tool, so it falls short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Write entities, relations and observations in one validated, atomic call.
This is the single write path. Everything is validated before anything is written, so a batch that is half-valid writes nothing.
Entity fields: name, entityType (required for new), domain (required for new), epistemic (assertion|hypothesis|speculation|unknown, default unknown), visibility (private|shareable, default private), observations. An observation may be a string, or {"text": ..., "kind": ...} where kind is note|decided|rejected|because|touches.
Relations use the canonical vocabulary; close synonyms are folded, unknown types are rejected. A relation may only point at an entity that exists or is being created in this same call.
| Name | Required | Description | Default |
|---|---|---|---|
| entities | No | Entities to create or merge into. | |
| relations | No | Relations to create. | |
| observations | No | [{"entityName": ..., "contents": [...], "kind": ...}] |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description reveals important behavioral traits beyond annotations: atomicity ('a batch that is half-valid writes nothing'), validation before writing, entity field constraints, and relation vocabulary handling (synonyms folded, unknown rejected). Annotations already indicate idempotent and non-destructive behavior, but the description adds meaningful context. No contradiction found.
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 front-loaded with the core purpose, then systematically details atomicity, entity fields, observations, and relations. Every sentence earns its place, though the length is justified by the tool's complexity. 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?
The description covers the tool's complex behavior comprehensively: atomic writes, field specifications, observation structure, and relation rules. With an output schema present, return values are handled elsewhere. Minor gaps include not explicitly stating failure handling beyond 'writes nothing' or listing the canonical relation vocabulary, but overall it is highly complete for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite 100% schema coverage, the schema descriptions are terse ('Entities to create or merge into'). The description compensates by elaborating entity fields (name, entityType, domain, epistemic, visibility), observation formats (string or object with kind), and relation constraints. This adds significant semantic value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Write entities, relations and observations in one validated, atomic call', using a specific verb and naming the exact resources. It further distinguishes the tool as 'the single write path', separating it from sibling write tools like create_entities or add_observations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'This is the single write path' gives strong usage guidance, implying it is the preferred route for any write operation. The atomicity and validation details also clarify when this tool should be chosen over non-atomic alternatives, though it stops short of explicitly naming alternatives or exclusion conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Record a decision: what was chosen, what was rejected, and why.
rejected is the field that makes this worth recording. What was chosen
stays readable in the code forever; what was considered and dropped exists
nowhere else, and it is the question that gets asked months later.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Stable identifier, e.g. "banking/phase-7: reference ID strategy". | |
| domain | Yes | Subject area (software, music, history, ...). | |
| because | Yes | The constraint or reasoning that forced it. | |
| decided | Yes | What was chosen. | |
| touches | No | Files or symbols this decision governs. | |
| rejected | No | Alternatives considered and dropped, each with its reason. | |
| epistemic | No | assertion | hypothesis | speculation | unknown. | assertion |
| supersedes | No | Name of a decision this one replaces. | |
| visibility | No | private (default) | shareable. |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate this is a write operation (readOnlyHint=false), idempotent (idempotentHint=true), and non-destructive (destructiveHint=false). The description adds context about the rationale for the rejected field, but does not directly disclose important side effects such as whether this creates a new record or updates an existing one (the 'supersedes' parameter hints at replacement but is not explained). This is acceptable given the annotations, but the description could add more operational clarity.
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 concise and front-loaded. The first sentence immediately states the purpose and fields. The subsequent sentences justify the 'rejected' field without redundancy. Every sentence contributes to understanding, and the length is appropriate 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 rich input schema (100% coverage) and presence of an output schema, the description provides enough context for selecting and invoking the tool. It clarifies the main purpose and the distinguishing rejected field. It does not explicitly compare with sibling tools like 'record' or 'store_thought', but the focus on decisions is strong enough. A brief note on when to use this versus those siblings would make it fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds meaningful semantic value by highlighting the importance of the 'rejected' parameter, explaining why it is the core of a decision record. This goes beyond the schema and helps the agent understand how to populate that field correctly. However, it does not elaborate on other parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Record') with a clear resource ('a decision') and enumerates the core fields ('what was chosen, what was rejected, and why'). It distinguishes itself from siblings like store_thought or record by focusing on decisions and emphasizing the rejected alternatives, making the tool's intent unmistakable.
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 clearly implies the tool is for recording decisions, and it provides context on why this is valuable (preserving rejected alternatives). However, it does not explicitly mention when to use this over siblings like store_thought or record, nor does it state any exclusions or alternatives. This is clear context without explicit comparison.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Re-index vault content into the search database.
| Name | Required | Description | Default |
|---|---|---|---|
| full | No | Force full vault re-index. | |
| session_id | No | If provided, reindex only this session. |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already disclose read-only (false), idempotent (true), and non-destructive (false) hints. The description adds that it targets the search database, but doesn't disclose any side effects like whether it clears the existing index or is expensive. It provides minimal extra context beyond the name.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence of 8 words, perfectly concise and front-loaded. No 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 simple tool with 2 optional parameters and an output schema, the description is adequate but minimal. It doesn't discuss use cases, nor does it mention that it can be scoped. Given the annotations and schema, the description is complete enough for basic invocation, but lacks deeper context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds no parameter information, leaving the schema to explain the full and session_id parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (re-index) and the object (vault content) into a specific target (search database). This is specific and distinct from sibling tools like search_thoughts, which query rather than rebuild the index.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this tool is used to update the search index after vault changes, but it doesn't explicitly state when to use it or mention alternatives. There is no guidance on when a full reindex vs session-specific reindex is appropriate, though that is covered by the parameter descriptions. With no exclusions mentioned, it gets a 3 for implied usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Mark observations as no longer held, and link what replaced them.
Deliberately not a delete. Keeping the superseded belief, dated and linked, is what lets the archive answer "why did we change our mind" later.
If you pass superseding_entity, record that entity first — a relation
cannot point at a name the graph does not know.
| Name | Required | Description | Default |
|---|---|---|---|
| entity_name | Yes | Entity whose observations are being revised. | |
| observations | Yes | Exact observation texts to invalidate. | |
| superseded_by | No | Short description of what replaced them. | |
| superseding_entity | No | Name of the entity that supersedes this one. |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (write, idempotent, non-destructive), the description reveals that the tool preserves superseded observations for later audit ('dated and linked') and imposes an ordering constraint for relations. This adds significant behavioral context not present in the annotations. No contradiction detected.
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 three concise sentences, front-loaded with the primary action, followed by a rationale and a conditional guideline. Every sentence carries useful information with no redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of annotations, full schema coverage, and an output schema, the description sufficiently covers the tool's purpose, behavior, and parameter prerequisites. It explains the non-destructive nature, the archival intent, and the ordering constraint, making it complete enough for safe and correct usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers all 4 parameters with descriptions (100% coverage), so the baseline is 3. The description adds value by explaining the role of superseding_entity and the need to record that entity first, enhancing the schema's plain description. However, it doesn't enrich superseded_by or the other parameters beyond their schema text, hence a 4.
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 function: marking observations as no longer held and linking what replaced them. It explicitly distinguishes itself from deletion ('Deliberately not a delete') and explains the archival rationale, making it distinct from sibling tools like invalidate_observations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides guidance on when to use it by contrasting with deletion ('Deliberately not a delete') and explains why preserving is important. It also gives a conditional prerequisite for superseding_entity, telling the agent to record that entity first. However, it doesn't explicitly name alternative tools for simpler invalidation, so it stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search the knowledge graph. Bounded: returns total_matched alongside
a capped page, so a truncated result is visible rather than silent.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max entities returned (default 10). | |
| query | Yes | Matched against entity names, types and observations. | |
| domain | No | Narrow to one subject area (software, music, history, ...). | |
| entity_type | No | Narrow to one role (decision, concept, finding, rule, ...). | |
| max_relations | No | Max relations returned (default 50). |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint and idempotentHint, so the description needs only to add non-obvious behavioral context. It discloses a crucial behavior: results are capped, and total_matched is returned to signal truncation. This goes beyond annotations and helps the agent understand that search results may be incomplete yet explicitly indicated. Does not contradict annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two sentences totaling 21 words. It front-loads the primary purpose and then adds a single valuable behavioral nuance. No redundancy or wasted words; every element 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?
With an output schema present and full parameter coverage in the schema, the description doesn't need to explain return values or parameters. It adds the essential nuance about result capping and total_matched, which is critical for the agent to interpret search results correctly. The description is complete for this tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all five parameters are fully documented in the schema. The description adds no parameter-specific meaning (e.g., what query matches against, what domain/entity_type filter, or how limit/max_relations work), which is already covered. Given high schema coverage, a 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 function: 'Search the knowledge graph'—a specific verb with a clear resource. It differentiates from siblings like search_thoughts (which likely targets thoughts specifically) and read_graph (a broader read operation) by focusing on search behavior. The added boundedness detail further distinguishes it as a search with explicit result handling.
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: use this to search the knowledge graph. However, it does not explicitly say when to prefer this over alternatives like search_thoughts or read_graph, nor does it mention exclusions or prerequisites. The context is clear but lacks explicit guidance on alternatives or when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search vault content with hybrid semantic + keyword search.
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | "full" returns matching passages; "overview" returns one line per session (id, title, score) for orientation before drilling in. | full |
| tags | No | Filter by tags (e.g. ["philosophy", "consciousness"]). | |
| limit | No | Max results (default 10). | |
| query | Yes | Natural language query (e.g. "what did I think about consciousness?"). | |
| source_type | No | Filter by "session" or "qnote". |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint and idempotentHint, so the safety profile is covered. The description adds the 'hybrid semantic + keyword search' behavior, which is useful, but it does not disclose other behavioral aspects like result ordering, pagination, or error handling. With annotations present, this is adequate but not exceptional.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence with no wasted words. It is front-loaded with the verb 'Search' and includes the key differentiator 'hybrid semantic + keyword search'. This is appropriately sized.
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 rich input schema (100% coverage), annotations, and presence of an output schema, the description's brevity is acceptable. It provides a sufficient high-level summary, though it could have added more context about use cases or how this relates to sibling search tools.
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%, meaning all five parameters are fully described in the schema. The tool description itself adds no extra parameter semantics, 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 clearly states the tool searches 'vault content' using 'hybrid semantic + keyword search', which specifies both the resource and method. However, it does not explicitly distinguish itself from sibling tools like 'search_nodes', so it falls short of a 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, no exclusions, and no context for choosing between search_thoughts and search_nodes or other siblings. It merely states what the tool does without situating it in a workflow.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Store a new thought — embed and save to vault as a qnote.
| Name | Required | Description | Default |
|---|---|---|---|
| tags | No | Optional tags for the note. | |
| text | Yes | The thought text to store. | |
| session_id | No | Session reference linking this qnote to its source conversation. Recommended — pass the current or most recent session ID (e.g. from handoff) so qnotes can be traced back to their session context. |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate a non-read-only, non-idempotent, non-destructive operation. The description adds that the thought is embedded and saved as a qnote, but it does not disclose potential side effects like vector index updates or failure modes. This adds some context beyond annotations but not deeply.
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 that wastes no words. It immediately states the action and mechanism, making it easy to scan and understand.
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 create tool with complete schema descriptions and an output schema, the description is sufficient. It could benefit from explicit usage guidance relative to sibling tools, but the combination of schema, annotations, and output schema fills most gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with each parameter well-documented (text, tags, session_id). The tool description offers no additional parameter-specific semantics beyond what the schema provides, 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?
Description clearly states the action ('Store'), the resource ('a new thought'), and the mechanism ('embed and save to vault as a qnote'). This distinguishes it from sibling tools like search_thoughts (search) and record_decision (decisions).
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 tool is for capturing thoughts but does not explicitly say when to use it over alternatives like 'record' or 'create_entities'. No exclusions or alternative recommendations are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v2.0.1add_observationscreate_entitiescreate_relationsdelete_entitiesdelete_observationsdelete_relationsget_sessioninvalidate_observationsopen_nodesread_graphrecordrecord_decisionreindexrevisesearch_nodessearch_thoughtsstore_thoughtScored across 17 tools
Multiple tools have overlapping purposes: record overlaps with create_entities, create_relations, and add_observations as a 'single write path,' and revise and invalidate_observations both mark observations as invalidated with optional supersession info. These unclear boundaries will lead to agent misselection.
Most tools follow a clear verb_noun snake_case pattern (e.g., search_thoughts, create_entities, delete_relations), but a few use bare verbs (reindex, record, revise) that break the pattern. The overall convention is readable and predictable with only minor deviations.
With 17 tools, the count is slightly above the typical 3-15 range, but it is justified by the server's dual focus on vault/thoughts and knowledge graph management. Each tool serves a distinct subdomain, though some could be consolidated (e.g., individual write tools vs. record).
The knowledge graph supports creation, reading, and deletion for entities and relations, but lacks explicit update operations for entity metadata or relation modifications. The vault side has no update or delete for thoughts, and there is no listing mechanism for sessions, leaving notable gaps in the intended lifecycle coverage.
Persistent, outcome-grounded episodic memory for Claude. 14ms CPU retrieval, no GPU, no vector DB.
Persistent memory and knowledge graph for AI assistants — keyword + vector + graph search.
Persistent memory and knowledge graphs for AI agents. Hybrid search, context checkpoints, and more.
Persistent memory for Claude Code and Cursor. Stop re-explaining your project every session.
