Pensieve is a personal, agent-driven long-term memory system backed by SQLite that lets you capture, organize, and recall information across AI sessions. It provides full CRUD operations across streams, notes, entities, and assets:
Streams (top-level domains): create, list, get, edit, remove, and restore.
Notes (core information units): add to streams with entity tags, edit, remove/restore, file/unfile across streams, and tag/untag entities.
Entities (people, orgs, topics): list, fuzzy-search (find_entities), get full details, edit name/aliases, promote to threads, and remove/restore.
Threads: created by promoting a recurring entity into its own thread under a stream.
Recall / Search:
Full-text search across note content and asset pointers, stemmed and relevance-ranked.
Recent notes ordered by time, optionally filtered by date.
Assets (by-reference pointers to files, repos, URLs, images, docs): add with a usage hint, list by stream/thread/note, and remove.
A personal, agent-driven memory that survives across sessions.
You talk to an AI assistant (Claude Code) every day, but it forgets everything between sessions. Pensieve is the long-term memory you control: any time in a conversation you can say "add this to pensieve" to capture something, or "what do I know about X?" to pull it back — and it's there, organised, current, and yours.
The metaphor: deliberately draw out a strand of thought and deposit it in the vessel to revisit later.
It's a small Python + SQLite engine with two front doors: an MCP server the agent
uses, and a CLI for you. Your memory lives in a single file at ~/.pensieve.
Five ideas shape every decision in Pensieve:
An information lake, not a project manager. It stores what you know and lets you recall it. It deliberately has no tasks, statuses, or due dates — the agent infers state by reading, the store just holds the information.
Deliberate on both ends. Pensieve never acts on its own. It writes only when you say "remember this," and recalls only when you ask. No silent saves, no auto-loading your memory at the start of a session. You stay in control of what goes in and what comes out.
Structure emerges; you don't design it upfront. You don't build a taxonomy. You keep a few top-level streams (the domains you actually work in) and drop notes in. The people, orgs and topics your notes mention become entities automatically, and one that keeps recurring earns its own thread. Organisation is a consequence of use.
Notes are the atoms; everything else references them. A note can stand alone or live in several streams at once. Entities and threads are views over notes, not owners of them — so removing a topic never destroys a note that's also about something else.
Point at the world, don't copy it. Attach a repo, file or URL as an asset — a by-reference pointer with a one-line "how to use me" hint. Pensieve stores the pointer and reads it on demand; it never crawls your disk or follows a link on its own.
Want the reasoning in depth — the design decisions, the full model, the tradeoffs?
docs/philosophy.md.
Related MCP server: Mnemexa MCP
Thing | What it is |
stream | A top-level domain of your work/life — |
note | An atomic piece of information — the unit you capture. Can live in more than one stream. |
entity | A person / org / topic your notes are about. Born from a note (by tagging); never created in a vacuum. |
thread | An entity that recurred enough to earn its own focused sub-topic under a stream. |
asset | A by-reference pointer (repo / file / dir / URL / image / doc) + a usage hint, attached to a stream, thread, or note. |
Recall has three lenses: by name (find), by content (search — full-text,
stemmed, ranked), and by time (recent — what changed lately).
Assumes Python 3.12+.
Pensieve is a standard MCP server, so the quickest way in is pipx
(or uv):
pipx install pensieve-mcp # or: uv tool install pensieve-mcpThis puts pensieve (the CLI) and pensieve-mcp (the MCP server) on your PATH. Then point
your agent at it. For Claude Code:
claude mcp add --scope user pensieve -- pensieve-mcpFor any other MCP client, register the pensieve-mcp command as a stdio server. To run it
ad-hoc without installing, uvx pensieve-mcp works too.
Pensieve is listed in the official MCP Registry
as io.github.praveen-ilangovan/pensieve, so registry-aware clients can discover and install
it directly.
Note: the PyPI package is the engine (CLI + MCP server). The judgment-bearing Claude skill (the
capture/fetchflows) ships with the repo, not the wheel — if you want it, use the script install below, which drops it into~/.claude/skills/pensieve/for you.
git clone git@github.com:praveen-ilangovan/pensieve.git
cd pensieve
./install.sh # Claude Code (backward-compatible default)
./install.sh codex # Codex
./install.sh all # bothinstall.sh checks prerequisites up front (and changes nothing if any are missing), ensures
pipx, installs Pensieve (pensieve + pensieve-mcp on your PATH), installs the selected
agent skill, and registers the MCP server in that agent's user configuration. Claude's skill
lives in ~/.claude/skills/pensieve/; Codex's user-scoped $pensieve skill is symlinked at
~/.agents/skills/pensieve/, so it is available from every repository. It's idempotent —
re-run anytime to pick up updates.
The Codex MCP registration pins PENSIEVE_HOME=~/.pensieve, ensuring Codex reads and writes
the same personal store as Claude even when Codex is launched from this repository (whose
.env intentionally points development commands at .local/manual). The engine and MCP
tools are unchanged; the Codex skill supplies the same deliberate capture/recall discipline
as the existing Claude adapter.
Then restart the selected agent and, from any directory:
"what streams do I have? check pensieve"
Your memory lives in ~/.pensieve.
Pensieve shines through the agent — you speak naturally, it does the judgment and calls the tools. Everything below is just talking to Claude Code.
Set up your domains (do this once, deliberately):
"Create a pensieve stream called Career — for my job search and work."
Capture — any time something worth keeping comes up:
"Add this to pensieve: had a call with Maya about the platform role; she's reviewing my portfolio."
The agent filters for what's durable, routes it to the right stream, and recognises that
"Maya" is a person worth tracking — without you managing any of that. If a note spans two
domains (say, a talk that's relevant to both your career and a side-project), it files
one note in both.
Recall — pick the lens that fits the question:
"What do I know about Maya?" · "What did we decide about salary?" · "Catch me up — what's changed lately?"
Point at live context — so the agent knows where to read:
"Add my project repo at ~/projects/acme as an asset on the side-projects stream — hint: read README.md first." Later: "pull up the acme repo." (It follows the pointer only when you ask.)
Promote — when something recurs, the agent proposes it:
"Maya's come up across 5 notes — want her own thread under Career?"
Remove / restore — everything is soft and reversible:
"Remove that note." / "Actually, bring it back." / "I'm done with the X stream."
The same engine is a CLI too — handy for a quick check or scripting without the agent
(pensieve stream list, pensieve search "…", …). Full command reference with examples:
docs/cli.md.
SQLite store (~/.pensieve), self-migrating via Alembic on first use.
Full-text search via SQLite FTS5 + a porter stemmer (so "pricing" recalls "priced").
A clean ports/adapters core: services depend on a storage port with two interchangeable backends (SQLite + an in-memory double), kept honest by a conformance test.
The MCP server and CLI are thin "op" layers; the judgment (what to keep, how to
resolve an entity, when to promote) lives in the agent skill (adapters/claude/).
make install # poetry env + pre-commit hooks
make test # unit + integration
make eval # deterministic engine evaluators
make check # ruff (lint+format) + mypy
make manual ARGS="stream list" # run the CLI against the local dev storeThis repo is a self-contained dev environment — it never touches your real ~/.pensieve.
The in-repo MCP server and CLI use a local dev store (.env → .local/manual); the global
install (./install.sh) is what points at ~/.pensieve.
Design notes live in plans/ (one file per slice, plus
plans/roadmap.md) and docs/
(philosophy.md — the why + model, cli.md — commands).
Working and in daily use: streams · threads · notes · entities · promotion · assets ·
search · recency · multi-stream notes · soft remove/restore — all via CLI and MCP.
Built and validated slice by slice with a real agent. See plans/roadmap.md for what's next.
Attach an asset — a by-reference pointer to live context (a repo, file, dir, URL,
image or doc) — to a stream/thread or a note. Pensieve only stores the pointer; it does
NOT read or follow it. Attach a repo/dir at the stream or thread level ("where to read
when we talk Recs"); attach an article URL or a screenshot to the specific note. Always
include a one-line hint for how to use it.
Args:
target: A stream/thread id, or a note id (note-N).
location: A path or URL (stored by reference, never copied).
hint: One line on how to use it (e.g. "read CLAUDE.md first; backend in /api").
label: Optional short name.
kind: repo|file|dir|url|image|doc — inferred from the location if omitted.
| Name | Required | Description | Default |
|---|---|---|---|
| hint | No | ||
| kind | No | ||
| label | No | ||
| target | Yes | ||
| location | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must cover behavioral traits. It correctly states Pensieve does not read or follow the pointer and stores by reference. However, it omits details like idempotency, overwriting behavior, permissions, or whether the target entity must exist.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: a clear summary followed by an Args list. It is front-loaded with core purpose. One or two sentences could be trimmed without losing meaning, but overall it is efficiently written.
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 creation tool with 5 parameters, no output schema, and no annotations, the description covers the main functionality and parameter semantics well. It lacks details on return values, error scenarios, or side effects, but the essential context for correct invocation is present.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must explain parameters. It lists all five parameters with meaningful explanations: target (stream/thread or note id), location (path/URL, stored by reference), hint (one-line usage), label (optional name), kind (inferred from location if omitted). This substantially adds beyond the schema's type-only info.
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 attaches an asset (a by-reference pointer) to a stream/thread or note. It distinguishes from storing content by noting Pensieve only stores the pointer. Examples like repo/dir at stream level versus article URL at note level further clarify purpose.
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 specific scenarios: attaching repo/dir at stream/thread level, and article URL or screenshot to specific note. It advises always including a one-line hint. However, it does not explicitly state when not to use this tool or name alternative tools, though context with sibling tools is implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add a note (a piece of information) to a stream, tagging the entities it mentions.
Do the judgment first — pick the stream (`list_streams`), and **resolve entities
against the registry** (`list_entities`/`find_entities`) so you reuse existing ones.
A change in the world is a *new* note; use `edit_note` only to fix a mistake.
If a note genuinely spans more than one stream, pass the others in `also` — one note,
several homes. **Never duplicate** a note across streams. Most notes belong to one.
Args:
stream: Id of the primary stream (from `list_streams`).
text: The note text.
entities: The entities this note references. Each item is either
{"id": "<existing-entity-id>"} (reuse) or
{"name": str, "kind": "person|org|topic", "aliases": [str]} (create new).
also: Additional stream ids this note also belongs in (optional).
| Name | Required | Description | Default |
|---|---|---|---|
| also | No | ||
| text | Yes | ||
| stream | Yes | ||
| entities | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses entity creation/reuse, multi-stream handling, and that notes represent changes in the world. Missing information on return value or permissions, but overall good transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with a clear first sentence followed by workflow guidance and an Args section. Every sentence adds value without redundancy. Concise yet comprehensive.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description does not explain the return value (e.g., note ID). However, it covers usage, parameters, and behavioral context adequately. Slight omission of error handling or success response.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so description must compensate. It fully explains all parameters: stream (primary), text (note content), entities (with format for reuse or creation), and also (additional streams). Adds significant meaning beyond 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 a note to a stream') and specifies additional behavior ('tagging the entities it mentions'). It distinguishes from siblings by contrasting with edit_note (fix mistake) and implying that notes are for new information, not duplicates.
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?
Explicit guidance on when to use this tool vs edit_note, instructions on entity resolution (list_entities/find_entities), and rules against duplication. The 'also' parameter usage is explained for multi-stream notes.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new stream — a top-level domain of work/life.
Args:
name: Display name of the stream (e.g. "Recs", "Employment").
purpose: Why the stream exists — its enduring north-star (optional).
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| purpose | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so description carries full burden. It only states the creation action without disclosing side effects (e.g., whether duplicate names are allowed, if references are established, or any destructive potential). This lack of behavioral context is a significant gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is brief and to the point: one line for purpose followed by clear parameter definitions. It avoids unnecessary fluff while remaining understandable.
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 purpose and parameters, but given the tool's complexity (creation of a top-level entity), it misses details like return value, uniqueness constraints, or any side effects. The presence of an output schema partially compensates, but the description itself is incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema coverage, the description provides meaningful parameter explanations: 'name' is the display name with examples, and 'purpose' is described as 'Why the stream exists — its enduring north-star (optional).' This adds value beyond the bare schema types.
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 'Create a new stream — a top-level domain of work/life.' The verb 'create' and resource 'stream' are explicit, and the 'top-level domain' helps distinguish it from child entities. However, it does not explicitly differentiate from sibling tools like 'add_asset' or 'edit_stream'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like 'edit_stream' or 'list_streams'. The description does not mention prerequisites, conditions, or exclusions, leaving the agent to infer appropriate usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Rename an entity or replace its aliases. The id is immutable; if it's promoted, its thread label is kept in sync.
Args:
entity: Id of the entity (from `list_entities`).
name: New display name (optional).
aliases: New alias list — replaces the existing one (optional).
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | ||
| entity | Yes | ||
| aliases | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses key behaviors: id is immutable, thread label synced on promotion, aliases replace existing list. No annotations provided, so description carries the burden well, though missing auth or rate limit info.
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 sentences plus a bullet list, front-loaded with purpose, no redundant words. Every sentence adds value.
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?
Adequate for a simple mutation tool with no output schema. Covers inputs and behavioral traits. Could mention success/failure response, but not critical.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description fully explains all three parameters: entity source from list_entities, name and aliases are optional with clear semantics (replacement for aliases). Adds 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?
Clearly states the tool renames an entity or replaces its aliases, specifying the verb and resource. Distinguishes from sibling tools like edit_note or edit_stream by focusing on entity identity and aliases.
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?
Implies usage for renaming or changing aliases, but lacks explicit when-to-use vs alternatives such as promote_entity or edit_stream. No mention of prerequisites or conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Rewrite a note's text — only to fix a genuine mistake.
A change in the world is a *new* note (`add_note`), not an edit.
Args:
note: Id of the note to edit (e.g. "note-3").
text: The corrected text (replaces the note's text).
| Name | Required | Description | Default |
|---|---|---|---|
| note | Yes | ||
| text | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It explains the tool replaces note text and warns against using it for changes in the world. Could mention effects like irreversibility, but is sufficiently transparent for a simple edit.
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?
Concise and front-loaded: first sentence states purpose, second adds usage context, then parameter list. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple operation (2 required params, no output schema), the description covers purpose, usage, and parameters. It could mention error cases or return value, but is 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 coverage is 0%, so description adds meaning. The 'Args' section provides clear purpose for each parameter, including an example for 'note'. Brief but adequate.
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 rewrites a note's text for genuine mistakes only, distinguishing it from add_note which creates new notes. Verb 'rewrite' and resource 'note' are specific.
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?
Explicitly says to use only for fixing genuine mistakes and contrasts with add_note for world changes. Provides clear when-to-use and when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Rename or repurpose a stream. The id (slug) is immutable — only display fields change.
Args:
stream: Id of the stream (from `list_streams`).
name: New display name (optional).
purpose: New enduring purpose (optional).
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | ||
| stream | Yes | ||
| purpose | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. Discloses that the slug/id is immutable—a key behavioral trait. However, does not mention other behaviors like reversibility, permissions, or side effects. Adequate but not comprehensive.
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 sentences plus a concise args list. Front-loaded with the main purpose, no extraneous words. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given low parameter count and absence of nested objects, the description covers necessary info. Includes immutability note and clarifies parameter sources. Output schema exists but not needed for understanding. Lacks usage context but otherwise 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 coverage is 0% with only basic property names. The description adds essential meaning: explains that 'stream' is the id from list_streams, 'name' is optional new display name, and 'purpose' is optional enduring purpose. Greatly enhances 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?
Clearly states the tool renames or repurposes a stream, with specific verb+resource. Distinguishes from siblings like create_stream and remove_stream by focusing on modifications, and notes the id is immutable, adding clarity.
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?
Context is clear: use when you need to change display name or purpose of an existing stream. Lacks explicit when-not or alternatives, but the purpose is straightforward and the sibling list provides implicit differentiation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
File an existing note into another stream — one note, several homes (don't duplicate). Use when a note you already captured also belongs in a second stream.
Args:
note: Id of the note (e.g. "note-3").
stream: Id of the stream to also file it in.
| Name | Required | Description | Default |
|---|---|---|---|
| note | Yes | ||
| stream | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses the action (file into another stream without duplication) but does not mention side effects like whether the original note remains, authorization needs, or error 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 concise with a front-loaded purpose statement and a structured Args section. Every sentence adds value 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 (2 required params, no output schema), the description covers the action, parameters, and usage context well. It could mention what happens if the note or stream doesn't exist, but overall it is adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but the description explains both parameters: note (ID, example 'note-3') and stream (ID of target stream). This adds significant meaning beyond the schema's minimal labels.
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 it files an existing note into another stream, using a specific verb and resource. It distinguishes from siblings like tag_note and unfile_note by focusing on stream filing without duplication.
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 says 'Use when a note you already captured also belongs in a second stream,' providing clear context. It implies when not to use (not for new notes or moves) but does not explicitly name alternative tools like unfile_note.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fuzzy-search the entity registry by name/alias (a candidate shortlist).
Use to check "do I already have a 'Rafia'?" before creating a new entity, and to recall ("what do I know about X?").
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full responsibility. It mentions 'fuzzy-search' and 'candidate shortlist' to set expectations about approximate matching and limited results, but does not detail rate limits, authentication, or exact result ranking 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?
Two sentences with no redundant information, front-loading the core purpose. Every word earns its place, making it easy for an agent to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple fuzzy search tool with one parameter and an output schema, the description covers the essential purpose, usage, and expected behavior. It adequately informs the agent when to invoke 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?
The single parameter 'query' has 0% schema coverage, but the description adds meaning by specifying it's a name or alias. This provides sufficient context for the agent to understand what to input, though additional format details would be helpful.
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 performs a fuzzy search of the entity registry by name/alias, returning a shortlist. It distinguishes itself effectively from sibling tools like get_entity and list_entities by specifying the search behavior and candidate nature.
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 explicit use cases: checking existence before creation and recalling information. While it doesn't exclude alternatives directly, the context implies this is for fuzzy name matching, which is sufficient guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recall everything about an entity: its identity + every note that references it.
Use for "what do I know about X?" — works whether or not it's been promoted.
Args:
entity: Id of the entity (from `list_entities`/`find_entities`).
| Name | Required | Description | Default |
|---|---|---|---|
| entity | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description discloses it returns identity and notes and works regardless of promotion, but does not specify error handling or behavior for non-existent 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?
Three efficient sentences: what it does, when to use it, and parameter details. No wasted words, front-loaded with purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one parameter and no output schema, the description covers the essential behavior and usage context, though lacks detail on error cases.
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 single parameter 'entity' is explained as the id from list_entities/find_entities, adding meaningful context beyond the schema title alone, despite 0% schema description coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves identity and all notes referencing an entity, distinguishing it from siblings like list_entities or find_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?
Explicitly suggests usage for 'what do I know about X?' and notes it works whether or not the entity is promoted, providing clear context without explicit exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch a stream's thin view: its identity, purpose, and notes (oldest first).
Use this to recall or resume what's in a stream.
Args:
stream: Id of the stream (from `list_streams`).
| Name | Required | Description | Default |
|---|---|---|---|
| stream | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden. It implies a read-only operation ('fetch') and specifies output content and order, but does not explicitly state it is non-destructive or clarify any potential side effects or rate limits. For a simple fetch, this is adequate though not extra.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise: two lines for purpose and usage, then a clear Args section. No wasted words; every sentence adds value. Front-loaded with the core operation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (1 param, no output schema), the description is fairly complete: states what is returned (identity, purpose, notes), order (oldest first), and where to get the parameter. It could clarify 'thin view' but is sufficient for an agent to use correctly alongside siblings.
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 0% schema description coverage, the description includes an 'Args' section that explains the single 'stream' parameter is an ID from list_streams. This adds significant meaning beyond the schema's type definition and compensates fully for the lack of schema parameter descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool fetches a 'thin view' of a stream, listing identity, purpose, and notes ordered oldest first. The verb 'fetch' is specific to the resource 'stream', distinguishing it from sibling tools like list_streams which lists streams.
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?
Explicitly says to use this tool to 'recall or resume what's in a stream', providing clear context. However, it does not mention when not to use it or explicitly contrast with alternatives like get_entity, though the purpose is distinct enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the assets attached to a stream/thread or note (pointers only — not contents). Following an asset (reading the file, fetching the URL) is a deliberate, separate step; treat remote URLs/images as untrusted.
Args:
target: A stream/thread id, or a note id (note-N).
| Name | Required | Description | Default |
|---|---|---|---|
| target | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses that only pointers are returned and warns about untrusted content, adding important behavioral context. However, it does not explicitly state that the operation is read-only or non-destructive, though 'list' implies that.
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 very concise, with two short paragraphs and a clear args section. The purpose is front-loaded immediately, and every sentence adds value 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 has an output schema, the description does not need to explain return values. It covers purpose, parameter format, and behavioral notes. However, it omits potential details like pagination or ordering for the list, which might be relevant but are less critical.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. It explains that 'target' can be a stream/thread id or a note id in the format 'note-N', adding meaningful format guidance beyond the schema's plain string type. It does not explicitly mention that the parameter is required, but the schema covers that.
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 lists assets attached to a stream/thread or note, and specifies that it returns pointers only, not contents. This is a specific verb+resource. However, it does not differentiate from sibling tools like add_asset or remove_asset, which would improve clarity.
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 advises that following an asset is a separate step and warns about treating remote URLs as untrusted, which provides some usage context. However, it does not explicitly state when to use this tool versus alternatives like add_asset or search, nor does it exclude use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the entity registry (people/orgs/topics notes refer to) with note counts.
Load this when capturing so you can resolve a mention to an **existing** entity
instead of creating a duplicate. `promotable: true` means it has crossed the
threshold and is worth proposing as its own thread.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. Discloses output includes note counts and promotable flag meaning, but does not mention read-only nature, pagination, or rate limits. Minimal behavioral detail beyond what is already evident.
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?
Three sentences, no fluff. First sentence states purpose, second gives usage guidance, third explains a key output flag. Every sentence 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 no parameters and an output schema present, the description effectively explains what is returned (registry entities with note counts, promotable flag). Missing potential details like scope (all entities?) but sufficient for a simple list 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?
Input schema is empty (0 parameters), schema coverage 100% trivially. Baseline is 3; description does not add parameter-specific info, but none is 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?
Clearly states it lists the entity registry (people/orgs/topics) with note counts. Distinct from siblings like get_entity (single) and find_entities (search). Specific verb+resource.
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?
Explicitly says to load this when capturing to resolve mentions to existing entities. Provides clear context but no explicit when-not-to-use or alternative suggestions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all streams (the top-level domains) in the user's Pensieve.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses that the tool is a read operation listing all streams, but lacks details on pagination, ordering, or potential limitations. Output schema exists but description adds no extra 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?
Single sentence with no waste. Clearly conveys the action and scope without unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter list tool with output schema, the description is nearly complete. It mentions 'all streams' but omits details like ordering or pagination behavior, which are minor 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?
No parameters exist, so schema coverage is 100%. Baseline score of 4 is appropriate as no additional parameter meaning is 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 clearly states the tool lists all streams, specifying that streams are top-level domains. It distinguishes from sibling tools like get_stream (single) and create_stream (creation).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives like get_stream or search. Usage is implied but not clarified with when/when-not statements.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Promote a recurring entity into its own thread under a stream.
Propose this (with the user's OK) once an entity is `promotable` (see
`list_entities`). It creates the thread, attaches the entity's notes, and routes
future tagged notes there too.
Args:
entity: Id of the entity to promote (from `list_entities`).
stream: Id of the parent stream the thread should live under.
| Name | Required | Description | Default |
|---|---|---|---|
| entity | Yes | ||
| stream | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses core behaviors: creates thread, attaches notes, routes future tagged notes. However, it does not mention permissions, reversibility, or side effects. Adequate but not exhaustive.
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?
Four sentences, no fluff. First sentence states purpose, second gives context, then Args section. Front-loaded with key action. Every sentence 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?
No output schema, but description explains preconditions, action, and parameter sources. References sibling tool for eligibility. Complete for a mutation tool with clear effects.
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 Args section explains both parameters beyond the schema: entity is 'Id of the entity from list_entities' and stream is 'Id of the parent stream'. Since schema description coverage is 0%, this addition is essential and well-done.
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 'promote' and the resource 'recurring entity' into its own thread under a stream. It also mentions a precondition (entity must be promotable, referencing sibling tool list_entities), which distinguishes it from other tools like create_stream or edit_entity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance: 'Propose this (with the user's OK) once an entity is promotable (see list_entities).' It explains the effect and references a sibling tool for checking status. However, it does not explicitly state when not to use or list alternatives, but the context is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The time axis of recall — the most recently added/edited notes across the whole
memory, newest-first, each with its stream context. Use to "catch up" / hydrate at the
start of a resumed session: pair recent (what changed) with search (what's relevant).
Distinct from search (relevance) and find_entities (names). Live notes only, capped
with a truncated flag.
Args:
since: Optional ISO date/datetime — only notes updated at/after it (e.g. "2026-06-01").
limit: Max notes to return (default 20).
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| since | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description takes responsibility for behavioral disclosure. It mentions that only live notes are returned and results are capped with a 'truncated' flag. It could optionally mention auth or rate limits, but the current coverage is strong.
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 (2 sentences plus bulleted args) and front-loaded with a powerful opening analogy. Every sentence adds value 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 (2 optional params, no output schema, no annotations), the description is fully sufficient. It covers purpose, usage, parameters, and behavioral nuances like the capped result flag.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, but the description's 'Args' section provides clear, human-readable explanations for both parameters: 'since' (ISO date) and 'limit' (max count, default 20). This adds significant meaning beyond the raw 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 retrieves the most recently added/edited notes, newest-first, with stream context. It distinguishes itself from siblings like 'search' and 'find_entities' by specifying it focuses on the time axis.
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?
Explicitly advises to use 'recent' for catching up at session start and pairs it with 'search' for relevance. It also contrasts with 'search' and 'find_entities', providing clear when-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Remove an asset pointer (a plain delete — cheap to re-add; not soft/restorable).
Args:
asset: Asset id to remove (asset-N).
| Name | Required | Description | Default |
|---|---|---|---|
| asset | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It explains the delete is plain and cheap, and not restorable. However, it does not disclose side effects, permissions, return values, or whether the deletion cascades, which are relevant for a mutation tool.
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 very concise: two sentences total. The first sentence captures purpose and key behavioral traits, the second describes the parameter. Every word adds value with 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?
Given the tool's simplicity (1 param, no output schema), the description covers purpose, parameter format, and key behavioral aspects (plain delete, cheap, not restorable). It lacks details on return values or errors, but these are less critical for a simple deletion 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 0%, so the description must add meaning. It specifies the asset parameter format as 'asset-N', which is not in the schema. This clarifies the expected input pattern beyond the schema's generic string type.
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 'Remove an asset pointer' with a specific verb and resource. It distinguishes from soft delete by noting 'a plain delete — cheap to re-add; not soft/restorable', and differentiates from sibling tools like remove_entity and remove_note by specifying it's for asset pointers.
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 (permanent deletion) and when not (if restore needed) by stating 'not soft/restorable' and 'cheap to re-add'. It provides context on cost and re-addability, though it doesn't explicitly name alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Remove an entity (and its thread, if promoted). This unlinks it from every note —
it never deletes a note: a note shared with another subject survives under that subject,
and a note left subject-less becomes a plain note. Soft and reversible via
restore_entity. Tell the user it's recoverable.
Args:
entity: Id of the entity to remove (from `list_entities`).
| Name | Required | Description | Default |
|---|---|---|---|
| entity | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses that the tool performs a soft delete (unlinks entity from notes), does not delete notes, and is reversible via 'restore_entity'. These traits are clearly stated. However, it does not mention potential side effects like permissions required or impact on associated assets.
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 relatively concise, covering key points in a few sentences. It is front-loaded with the main action and includes a separate 'Args' section. However, the 'Args' section is redundant with the input schema, and the structure could be slightly more streamlined.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool is a simple mutation with one parameter and no output schema, the description adequately explains the main behavior, reversibility, and effect on notes. It mentions the related restoration tool. It does not cover error cases or permission requirements, but these are acceptable omissions for this level of 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?
The input schema has one parameter 'entity' with only a type and title. The description adds that the ID comes from 'list_entities', which provides context beyond the schema. This helps the agent know where to obtain the parameter value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool removes an entity and unlinks it from notes, emphasizing it never deletes notes. It distinguishes itself from sibling tools like 'remove_note' and 'remove_asset' by focusing on entities, and mentions the reversible nature via 'restore_entity'. However, it could more explicitly contrast with other sibling tools like 'edit_entity' or 'promote_entity'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives some usage guidance by noting the tool is soft and reversible, and instructs to tell the user it's recoverable. It mentions 'restore_entity' as an alternative for reversal. However, it does not provide explicit when-to-use or when-not-to-use guidance compared to other entity-related tools, such as when to remove versus edit or promote.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Remove a note. Soft and reversible — bring it back with restore_note. An entity
that loses its last live note disappears (derived). Tell the user it's recoverable.
Args:
note: Id of the note to remove (e.g. "note-3").
| Name | Required | Description | Default |
|---|---|---|---|
| note | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Fully discloses behavioral traits without annotations: soft deletion, reversibility, and derived entity consequence. No contradictions.
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?
Three sentences plus parameter detail, tightly packed with essential info. No 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?
Adequately covers purpose, side effects, and user guidance. Could mention return value, but tool is simple and well-integrated with sibling restore_note.
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 has no parameter descriptions (0% coverage). Description clearly defines 'note' as the Id to remove with an example, fully compensating for schema gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'Remove a note' with specific verb and resource. Differentiates from sibling restore_note by emphasizing soft deletion and reversibility.
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 usage context: soft deletion with recovery via restore_note, and mentions entity disappearance. Could be more explicit about when not to use, but siblings include only restore_note, making it clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Remove a stream and its threads. Soft and reversible — bring it back with
restore_stream. Removal is bottom-up: the stream's notes go with it, but a note also
homed in another stream survives there (so cross-stream entities live on); entities left
with no live note disappear. Tell the user it's recoverable.
Args:
stream: Id of the stream to remove (from `list_streams`).
| Name | Required | Description | Default |
|---|---|---|---|
| stream | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, but description fully discloses soft-delete behavior, bottom-up removal, cross-stream entity survival, and disappearance of orphaned entities. Also mentions note homing 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?
Concise and well-structured. Key information (soft delete, reversibility, parameter) is front-loaded. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 1 parameter, no output schema, and no annotations, the description covers all relevant aspects: behavior, recovery, side effects, and parameter guidance.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description adds value by specifying the parameter source ('from list_streams') and its role as the stream ID. For a single required parameter, this is sufficient.
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 'Remove a stream and its threads' with a specific verb and resource. Distinguishes from sibling restore_stream by mentioning reversibility.
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?
Explicitly states it's soft and reversible, recommends using restore_stream to undo, and instructs to tell the user it's recoverable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Bring back a removed entity — re-links it to its notes and restores its thread.
Args:
entity: Id of the entity to restore.
| Name | Required | Description | Default |
|---|---|---|---|
| entity | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description must disclose behavioral traits. It explains the restoration effect (re-link notes, restore thread) but lacks details on side effects, permissions, reversibility, or error handling. The description adds some context beyond the name but 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 very concise: two sentences plus an Args line. It front-loads the main action. However, the Args section redundantly repeats the parameter name already in the schema, which could be integrated for tighter structure.
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 action and effect. However, it lacks information about return values (no output schema), error conditions, and the prerequisite that the entity was previously removed. Given the presence of many sibling tools, this 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 description coverage is 0%, so the description must compensate. It describes 'entity' as an 'Id' of the entity to restore, which clarifies the parameter's semantic role beyond the schema's type 'string'. However, it does not explain how to obtain or format the ID, nor does it address potential values.
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 restores a removed entity, explicitly mentioning it re-links notes and restores the thread. This distinguishes it from sibling tools like remove_entity, restore_note, and restore_stream.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives. It does not mention prerequisites (e.g., entity must be removed) or when not to use it. Sibling tools like promote_entity have different purposes, but no comparative advice is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Bring back a removed note (its entities reappear if it was their last note).
Args:
note: Id of the note to restore (e.g. "note-3").
| Name | Required | Description | Default |
|---|---|---|---|
| note | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses a key side effect (entities reappear if the note was their last), indicating it's a mutation. It could be improved by noting if the operation is idempotent or requires special permissions.
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 sentences: first states purpose and key side effect, second explains the parameter with an example. No unnecessary words, front-loaded with the most important information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple restore tool with one parameter and no output schema, the description covers the purpose, side effect, and parameter usage. It lacks details on error conditions (e.g., if the note isn't removed) but is largely sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but the description adds significant meaning by specifying the 'note' parameter with an example format ('e.g. "note-3"'). This helps the agent understand how to provide the argument correctly.
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: restoring a removed note. It also specifies a behavioral consequence (entities reappear if it was their last note), which distinguishes it from siblings like remove_note or restore_entity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides context for when to use the tool (to bring back a removed note) and gives a conditional side effect. However, it does not explicitly state when not to use it or mention alternative tools for related actions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Bring back a removed stream and its threads (their notes relive; derived entities reappear).
Args:
stream: Id of the stream to restore.
| Name | Required | Description | Default |
|---|---|---|---|
| stream | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses that notes and derived entities are restored, but no details on idempotency, permissions, or error conditions. Adequate but not rich.
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?
Very concise: one sentence plus args. No wasted words, front-loaded with action.
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 one parameter and no output schema, the description covers the essential purpose and parameter. Could mention idempotency or error behavior, but adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description explains that 'stream' is the ID of the stream to restore, adding meaning beyond the schema's type-only definition.
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 it restores a removed stream and its threads/notes, distinguishing it from siblings like restore_entity or restore_note.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives, nor prerequisites (e.g., stream must be removed).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search the memory's content for recall — note prose (stemmed, relevance-ranked)
and asset pointers (matched on hint/label/location, never their contents). Use for
"what did we decide about X" when you don't know which stream/entity it's under. This is
distinct from find_entities (which matches names). Returns live results only, capped
with a *_truncated flag; it never follows an asset pointer.
Args:
query: Words to match (OR-ed; relevance floats full matches to the top).
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully covers behavioral traits: returns live results only, capped with truncated flag, never follows asset pointers, and notes stemming/relevance ranking for notes. No contradictions.
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?
Every sentence adds value: purpose, usage context, behavioral details, and parameter explanation. Well-structured and efficient with no 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?
For a simple 1-param tool with no output schema, the description covers all necessary context: what is searched, how results work, limitations, and difference from siblings. Complete for the complexity level.
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?
Single parameter 'query' has no schema description (0% coverage), but the description adds meaning: 'Words to match (OR-ed; relevance floats full matches to the top)', which compensates fully.
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-resource pair ('Search the memory's content') and explicitly distinguishes itself from the sibling `find_entities` tool by stating it searches content vs. names, making purpose very clear.
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 explicit guidance on when to use ('what did we decide about X' when location is unknown) and distinguishes from `find_entities`, effectively telling the agent when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Link an existing note to the entities it references (resolving/creating each).
Use when you spot a subject in a note that wasn't tagged at capture time. Resolve
against the registry first (`list_entities`/`find_entities`) to avoid duplicates.
Args:
note: Id of the note to link (e.g. "note-3").
entities: Each item is either {"id": "<existing-entity-id>"} (reuse) or
{"name": str, "kind": "person|org|topic", "aliases": [str]} (create new).
| Name | Required | Description | Default |
|---|---|---|---|
| note | Yes | ||
| entities | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Describes two modes (reuse existing entity or create new) and the structure of the entities argument. No annotations provided, but the description covers the core behavior well. Does not detail potential side effects like overwriting, but that seems unnecessary given the action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Concise: one-line purpose, one-line usage guidance, then two bullet-like arg descriptions. No redundant text, every sentence adds value.
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?
Fully covers the tool's operation with two params, no output schema, and moderate complexity. The description addresses both parameters and usage context, leaving no obvious 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?
Adds significant meaning beyond the input schema: specifies note format example 'note-3', details the entities object structure with id or name/kind/aliases, and lists valid kinds. Schema coverage was 0%, so description fully compensates.
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 'Link an existing note to the entities it references (resolving/creating each)', specifying the action and resource. Distinguishes from siblings like 'untag_note'.
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 explicit use case: 'when you spot a subject in a note that wasn't tagged at capture time' and recommends prior resolution via 'list_entities'/'find_entities' to avoid duplicates.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Remove a note from one of its streams (it stays in the others). Refuses to remove a
note's last home — use remove_note for that.
Args:
note: Id of the note (e.g. "note-3").
stream: Id of the stream to remove it from.
| Name | Required | Description | Default |
|---|---|---|---|
| note | Yes | ||
| stream | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses the constraint of not removing the last home and that the note stays in other streams, but does not mention return value or side effects. Still, it covers the key behavioral nuance.
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 sentences and an Args block, every sentence adds value. Front-loaded with primary action and constraint, very 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 removal tool with two parameters and no output schema, the description covers the operation's logic and refusal condition adequately, though it could optionally mention if any result 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?
Schema description coverage is 0%, but the description adds format and example for each parameter (e.g., 'note-3' for note ID), providing essential meaning beyond the bare schema types.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action 'Remove a note from one of its streams' and distinguishes from the sibling tool 'remove_note' by noting it refuses to remove the last home, making purpose precise and 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?
Explicitly warns about the refusal behavior when it's the last home and directs to use 'remove_note' for that case, providing clear when-to-use and when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Remove an entity tag from a note — correct a mis-tag (e.g. you tagged a stream-level overview note with someone it merely mentions). If the entity is promoted, the note is also detached from its thread.
Args:
note: Note id.
entity: Entity id to unlink (from `list_entities`/`get_entity`).
| Name | Required | Description | Default |
|---|---|---|---|
| note | Yes | ||
| entity | Yes |
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 transparently documents a key side effect: 'If the entity is promoted, the note is also detached from its thread.' This goes beyond the basic operation and helps the agent understand implications.
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 exceptionally concise: two sentences in the main body plus two parameter definitions. Every sentence adds value, with no redundancy or filler. The purpose is front-loaded, and the side effect is clearly stated second.
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 main action, a side effect, and parameter sources. Given the low complexity (2 params, no output schema), it is sufficient for an agent to use correctly. However, it omits any indication of the return value or success/failure conditions, leaving a minor gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. The 'Args' section defines 'note' as 'Note id' and 'entity' as 'Entity id to unlink (from list_entities/get_entity)', adding source information. However, it lacks format details or constraints, and the parameter names are self-evident. At baseline 3 for low coverage, this provides minimal but adequate additional meaning.
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 'Remove an entity tag from a note' and the resource 'note', with a specific example of correcting a mis-tag. It distinguishes itself from the sibling tool 'tag_note' by being the inverse operation.
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 context for when to use the tool ('correct a mis-tag') with an illustrative example. While it does not explicitly list alternatives or exclusion criteria, the example effectively contrasts correct usage from incorrect scenarios.
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_assetadd_notecreate_streamedit_entityedit_noteedit_streamfile_notefind_entitiesget_entityget_streamlist_assetslist_entitieslist_streamspromote_entityrecentremove_assetremove_entityremove_noteremove_streamrestore_entityrestore_noterestore_streamsearchtag_noteunfile_noteuntag_noteScored across 26 tools
Every tool has a distinct purpose: notes, streams, entities, assets, tagging, filing, search, and recent. There is no overlap in functionality, making it easy for an agent to select the correct tool.
All tool names follow a consistent verb_noun pattern (e.g., add_note, create_stream, remove_entity), using lowercase with underscores throughout, which is predictable and readable.
With 26 tools, the count is slightly on the higher side but still appropriate for a comprehensive memory management system covering streams, notes, entities, assets, and auxiliary operations like search and recent.
The tool set covers CRUD for all main resources (streams, notes, entities, assets) plus additional features like tagging, filing, promotion, search, and recent updates. Minor gaps like bulk operations exist but do not hinder core workflows.
Persistent memory for AI agents across Claude, ChatGPT and any MCP client.
Persistent memory for AI agents. Search, store, and recall across sessions.
Persistent memory shared across Claude, ChatGPT, Grok and other MCP clients.
Persistent memory for AI agents. Semantic search, memory graph, W3C DID identity.
