Claude Code forgets you every time you close the tab. Every architecture decision you explained. Every debugging session where you traced a bug through four layers of abstraction. Every "remember, we decided to use event sourcing, not CRUD" correction. Gone. Next session, you're a stranger to your own tools.
Cortex is a persistent memory engine for Claude Code built on computational neuroscience. It remembers what you worked on, how you think, what you decided and why. Not as a dumb text dump shoved into context, but as a living memory system that consolidates, forgets intelligently, and reconstructs the right context at the right time.
20 biological mechanisms. 33 MCP tools. 7 automatic hooks. Runs entirely on your machine. PostgreSQL + pgvector.
claude plugin marketplace add cdeust/Cortex
claude plugin install cortexRestart your Claude Code session, then run:
/cortex-setup-projectThis handles everything: PostgreSQL + pgvector installation, database creation, embedding model download, cognitive profile building from session history, codebase seeding, conversation import, and hook registration. Zero manual steps.
Using Claude Cowork? Install Cortex-cowork instead — uses SQLite, no PostgreSQL required.
Or add as a standalone MCP server (no hooks, no skills — just the 33 tools):
claude mcp add cortex -- uvx --from "neuro-cortex-memory[postgresql]" neuro-cortex-memoryClone + setup script:
git clone https://github.com/cdeust/Cortex.git && cd Cortex
bash scripts/setup.sh # macOS / Linux
python3 scripts/setup.py # Windows / cross-platformDocker:
git clone https://github.com/cdeust/Cortex.git && cd Cortex
docker build -t cortex-runtime -f docker/Dockerfile .
docker run -it \
-v $(pwd):/workspace \
-v cortex-pgdata:/var/lib/postgresql/17/data \
-v ~/.claude:/home/cortex/.claude-host:ro \
cortex-runtimeManual: See detailed manual setup instructions.
Related MCP server: rawthink
Cortex doesn't just remember — it authors. Every memory that passes the pipeline becomes a structured wiki page, editable in place with a full scientific writing environment:
CodeMirror 6 inline editor with live preview; save round-trips atomically to the .md file on disk (git-diffable).
LaTeX math — $E=\nabla \cdot F$ and $$…$$ blocks rendered live via KaTeX.
BibTeX citations — drop .bib files under wiki/_bibliography/, use [@friston2010] inline, and Citation.js resolves them to (Friston 2010) with an auto-generated APA bibliography.
Figure / equation / table auto-numbering — {#fig:arch} labels, {@fig:arch} cross-refs, resolved to Figure 1 / Equation 3 / Section 2.1.
Pandoc export — one click produces PDF (via LaTeX), TEX, DOCX, or HTML. Journal-submittable from the same markdown that feeds the memory pipeline.
The source stays markdown. Your .md files remain grep-able, diffable, and interoperable with any external tool. Cortex adds a rendering + editing + export layer on top without stealing your content into a proprietary format.
Monday. You spend an hour debugging a webhook handler. After tracing through four layers, you find the root cause: a race condition in the Redis session store where TTL expiry can fire between the auth check and the permission lookup. You discuss the fix with Claude, decide on an approach, and implement it. Session ends.
Thursday. Different project, but a user reports intermittent logouts. You open Claude Code. Before you even describe the bug, Cortex has already injected three memories: Monday's race condition analysis, a decision from two weeks ago to use Redis for all session state, and a lesson from an older session about TTL edge cases in distributed caches.
Claude doesn't just have your conversation history. It has context. It connects the current problem to past decisions, surfaces lessons you forgot you learned, and skips the part where you re-explain your entire architecture.
Three weeks later. Those individual debugging sessions have been consolidated into a general pattern: "authentication edge cases involving TTL-based caches." The specific Redis commands compressed to a summary. The debugging steps faded. The principle survived. Your next auth issue starts with institutional knowledge, not a blank page.
That's the difference. Not "here's what you said last time." Real recall — the kind where your tools understand the shape of what you've been building.
We tested Cortex against three published benchmarks. All scores are retrieval-only — no LLM reader in the evaluation loop. We measure whether the right memory shows up, not whether a model can generate a good answer from it.
LongMemEval (Wu et al., ICLR 2025): 500 human-curated questions embedded in ~40 sessions of conversation history (~115k tokens). The paper's best retrieval hit 78.4% Recall@10.
Cortex | What it means | |
Recall@10 | 97.8% | The right memory shows up in the top 10 results for nearly every question |
MRR | 0.882 | The correct answer is usually the first or second result |
Category | MRR | R@10 | Why this score |
Single-session (assistant) | 0.982 | 100.0% | Verbatim assistant responses are easy to match |
Multi-session reasoning | 0.936 | 99.2% | Entity graph connects evidence across sessions |
Knowledge updates | 0.921 | 100.0% | Heat decay naturally surfaces the newest version of a fact |
Temporal reasoning | 0.857 | 97.7% | Time anchors embedded directly in memory content |
Single-session (user) | 0.806 | 94.3% | User phrasing varies more than assistant responses |
Single-session (preference) | 0.641 | 90.0% | Preferences are implicit — harder to retrieve by keyword |
Knowledge updates scored highest because heat-based decay naturally pushes newer information above older versions of the same fact. This wasn't designed for the benchmark. It's just how the thermodynamic model works.
LoCoMo (Maharana et al., ACL 2024): 1,986 questions across 10 conversations, including adversarial trick questions designed to confuse retrieval, multi-hop queries requiring evidence from multiple turns, and temporal reasoning about when things happened.
Cortex | What it means | |
Recall@10 | 92.6% | Right memory in top 10 over 9 times out of 10 |
MRR | 0.794 | Correct answer is typically the first result |
Category | MRR | R@10 | Why this score |
Adversarial | 0.855 | 93.9% | Trick questions can't fool five fused signals |
Open-domain | 0.835 | 95.0% | Broad questions benefit from multi-signal coverage |
Multi-hop | 0.760 | 88.8% | Entity graph connects evidence across turns |
Single-hop | 0.700 | 92.9% | Direct factual questions — strong but room to improve |
Temporal | 0.539 | 77.2% | "When did X happen?" is the hardest category — needs better time-series matching |
No LLM at query time. No API calls. Just a 22MB embedding model, PostgreSQL with pgvector, and neuroscience algorithms doing the heavy lifting. Five retrieval signals fused server-side (vector similarity, full-text search, trigram matching, thermodynamic heat, recency), then reranked by a cross-encoder.
BEAM (Tavakoli et al., ICLR 2026) is the hardest long-term memory benchmark published. 10 conversations, each spanning 10 million tokens. 200 probing questions across 10 memory abilities, including three that no prior benchmark tests: contradiction resolution, event ordering, and instruction following.
Every system in the paper collapses at this scale. The best result reported (LIGHT on Llama-4-Maverick) scores 0.266. Context-window approaches can't fit it. Standard RAG drowns in noise.
Split | WRRF baseline | With Context Assembler | What happened |
BEAM-100K | 0.591 | 0.602 | Flat search still works at small scale |
BEAM-10M | 0.353 | 0.471 (+33.4%) | Structured assembly dominates when flat search drowns |
BEAM-10M per-ability breakdown (Temporal Context Assembler — no oracle labels, timestamps only):
Ability | MRR | R@10 | Δ vs WRRF | What happened |
knowledge_update | 0.950 | 100.0% | +0.115 | Day-level grouping keeps knowledge updates tighter than topic labels |
contradiction_resolution | 0.892 | 95.0% | +0.259 | Temporal proximity catches contradictions better than topic boundaries |
information_extraction | 0.592 | 75.0% | +0.144 | Same-day memories cluster the right facts |
preference_following | 0.508 | 60.0% | +0.096 | Preferences cluster by time, not topic |
abstention | 0.600 | 60.0% | +0.500 | Temporal scoping correctly empties irrelevant stages |
temporal_reasoning | 0.460 | 50.0% | +0.090 | Time anchors naturally align with temporal stages |
multi_session_reasoning | 0.425 | 60.0% | +0.010 | Cross-day bridging via entity graph — marginal gain |
instruction_following | 0.150 | 15.0% | +0.082 | Instructions still look like normal questions |
summarization | 0.083 | 11.1% | −0.103 | Temporal scoping too narrow for broad summary queries |
event_ordering | 0.050 | 5.0% | −0.017 | Chronological sequencing needs more than retrieval |
Eight of ten abilities improve. The key finding: temporal day-level partitioning outperforms BEAM's ground-truth topic labels (0.471 vs 0.429 with oracle plan_id). This was not predicted — it means temporal proximity is a stronger stage signal than topic boundaries for conversational memory, and the architecture generalizes without any oracle metadata.
At 10 million tokens per conversation, you have ~7,500 memories that all look similar to a vector search engine. The Structured Context Assembly architecture fixes this by breaking the conversation into stages (distinct topics), retrieving within the current stage first, following entity graph connections to related stages, and falling back to summaries for everything else. 8 of 10 memory abilities improve.
This architecture was originally designed in September 2025 for generating coherent 9-page PRDs on Apple Intelligence's 4096-token context window (ai-prd-builder, commit 462de01 — one month before the BEAM paper existed). It works because the problem is the same at both scales: you can't fit everything in context, so you need to be smart about what goes in.
Honest caveat: BEAM doesn't define a retrieval MRR metric — the paper uses LLM-as-judge nugget scoring. Our "MRR" is a retrieval proxy (rank of first substring-matching memory). The paper's "LIGHT" scores are end-to-end QA, shown for directional reference.
pip install -e ".[postgresql,benchmarks,dev]"
python benchmarks/beam/run_benchmark.py --split 100K # ~10 min
python benchmarks/beam/run_benchmark.py --split 10M # ~50 min
CORTEX_USE_ASSEMBLER=1 python benchmarks/beam/run_benchmark.py --split 10M
python benchmarks/locomo/run_benchmark.py # ~40 min
python benchmarks/longmemeval/run_benchmark.py --variant s # ~45 minAll scores on fresh database (DROP + CREATE per run), TRUNCATE between conversations, FlashRank preflight verified. See full methodology.
Cortex doesn't store memories the way a database stores rows. It treats them more like a brain treats experiences.
Memories have temperature. Every memory starts hot. Access it and it stays hot. Ignore it and it cools. Below a threshold, it compresses: full text → summary → keywords → fades entirely. This isn't a bug — it's rate-distortion optimal forgetting, the same mathematical framework your brain uses to decide what's worth keeping. Important memories resist compression. Surprising ones get a heat boost. Boring, redundant ones quietly disappear. (Anderson & Lebiere 1998; Ebbinghaus 1885)
Storage has a gatekeeper. Not everything deserves to be remembered. Cortex maintains a predictive model of what it already knows, and only stores information that violates its expectations. Tell it the same thing twice and the write gate blocks the second attempt. This is predictive coding — the same mechanism your neocortex uses to filter sensory input. Only prediction errors get through. (Friston 2005; Bastos et al. 2012)
Retrieval changes the memory. When you recall a memory in a new context, Cortex doesn't just passively hand it back. It compares the retrieval context against the storage context, and if there's enough mismatch, it reconsolidates — updates the memory to reflect what's true now. This is real neuroscience. Nader et al. showed in 2000 that retrieved memories become labile and can be rewritten. Your codebase evolves, and so do Cortex's memories of it. (Dudai 2012; Nader et al. 2000)
Emotional memories are stronger. Frustration during debugging, excitement when a test passes, urgency in a production incident — Cortex detects emotional valence and encodes those memories with more force. They decay slower, compress later, and surface faster. Like how you remember your worst production outage in vivid detail but can't recall last Tuesday's standup. (Wang & Bhatt 2024; Yerkes-Dodson 1908)
Background consolidation runs like sleep. When you're away, a consolidation cycle processes recent memories: decays old ones, compresses verbose ones, promotes recurring patterns into general knowledge (episodic → semantic transfer), discovers entity relationships, and runs "dream replay" where related memories are compared and new connections emerge. (McClelland et al. 1995; Foster & Wilson 2006; Buzsáki 2015)
Similar memories stay distinct. Pattern separation — modeled on the dentate gyrus, which keeps "Tuesday's standup" separate from "Wednesday's standup" even though they're almost identical. Without this, retrieval returns the same generic match for every similar query. (Leutgeb et al. 2007; Yassa & Stark 2011)
41 papers total. Every algorithm, constant, and threshold traces to a published source. Full citations, equations, ablation data, and per-module implementation audit: docs/science.md | Research post on structured context assembly
Claude Code has a 200k/1M token context window. During long sessions, when that window fills up, it compacts: summarizes older messages, strips tool outputs, paraphrases your instructions. Important nuance evaporates. Decisions you anchored early in the conversation dissolve into vague summaries.
Hippocampal Replay fixes this. Named after the neuroscience phenomenon where your brain replays important experiences during sleep to consolidate them, it treats context compaction as "sleep" and replays what matters when Claude "wakes up."
Before compaction hits, a hook fires. Cortex drains your active context — what you were working on, which files were open, what decisions you'd made, what errors were unresolved — and stores it as a checkpoint.
After compaction, a second hook fires. Cortex reconstructs your context intelligently. Not by dumping everything back in, but by assembling the right pieces: your latest checkpoint, any facts you'd anchored as critical, the hottest project memories, and predictions about what you'll need next.
You can be explicit about what matters:
cortex:anchor({ content: "We're using the event-sourcing pattern. All state changes go through the event bus.", reason: "Architecture constraint" })Anchored memories get maximum protection. They always survive compaction, no matter what.
Every time you store a memory, Cortex doesn't just save text — it extracts entities, builds relationships, detects schemas, and links the new memory into a growing knowledge graph. Over time, this becomes a living wiki of your project: decisions and their rationale, patterns that emerged, lessons learned, architectural constraints, and how they all connect.
Explore it through:
/cortex-visualize — interactive neural graph in your browser
get_causal_chain — trace how one decision led to another
get_project_story — auto-generated narrative of your project's evolution
detect_gaps — find areas where knowledge is thin or isolated
This isn't documentation you write. It's documentation that writes itself from how you work.
Launch with /cortex-visualize. Five views wired over the same data:
Graph View — force-directed neural graph showing domain clusters, memories, entities, and discussions connected by typed edges. Click any node for full context.
Wiki View — every memory admitted by the grounded-theory pipeline lands here as a structured page (ADR / spec / lesson / convention / note) with:
EB Garamond body, IBM Plex Mono code, centered academic-paper layout
Heat bar, lifecycle pill (active / area / archived / evergreen), staleness flag, backlinks footer
Inspector drawer — full audit trail (memos, source claim events, draft history) for every page
Inline CodeMirror 6 editor + live preview with KaTeX math (see Write Papers in Cortex above)
BibTeX citations, figure/equation/table auto-numbering, cross-references
Pandoc export → PDF / LaTeX / DOCX / HTML
Knowledge View — curated memory cards with heat-based left border, emotion tag, consolidation stage, and evidence file references. Filter by domain or emotion; click any card for a full-screen detail panel with Markdown + JSON pretty-print.
Board View — memories arranged across the four biological consolidation stages (labile → early_ltp → late_ltp → consolidated). Each card carries domain, heat, importance, and emotional tags so you can see what's hardening and what's still fragile.
Pipeline View — horizontal Sankey flow from domains through the write gate into consolidation stages. Width of each ribbon = memory volume. Makes retention and drop-off across stages visible at a glance.
Cortex works with teams of specialized agents. Each agent has scoped memory (agent_topic) while sharing critical decisions across the team — based on Wegner's transactive memory theory (1987): teams store more knowledge than individuals because each member specializes.
Specialization — each agent writes to its own topic. Engineer's debugging notes don't clutter tester's recall.
Coordination — decisions auto-protect and propagate. When engineer decides "use Redis over Memcached," every agent sees it at next session start.
Directory — entity-based queries span all topics. "What do we know about the reranker?" returns results from engineer, tester, and researcher.
Works with any custom agents. See zetetic-team-subagents for a ready-made team of 27 specialists — each with scoped memory that doesn't clutter the others.
Clean Architecture with strict dependency rules. Inner layers never import outer layers.
Layer | What lives here | Count |
core/ | Neuroscience + retrieval logic | 118 modules |
context_assembly/ | Structured context assembler | 10 modules |
infrastructure/ | PostgreSQL, embeddings, file I/O | 33 modules |
handlers/ | MCP tools | 62 tools |
hooks/ | Lifecycle automation | 7 hooks |
Storage: PostgreSQL 15+ with pgvector (HNSW) and pg_trgm. All retrieval in PL/pgSQL stored procedures.
Configuration: Set DATABASE_URL (default: postgresql://localhost:5432/cortex). All parameters use CORTEX_MEMORY_ prefix — see mcp_server/infrastructure/memory_config.py for the full list (~40 parameters).
Runs 100% locally — MCP over stdio, PostgreSQL on localhost, visualization on 127.0.0.1. No data leaves your machine. Audit score: 91/100.
pytest # 2080 tests
ruff check . # Lint
ruff format --check . # FormatMIT
@software{cortex2026,
title={Cortex: Persistent Memory for Claude Code},
author={Deust, Clement},
year={2026},
url={https://github.com/cdeust/Cortex}
}Add a neuro-symbolic rule to the memory store. Rules hard-filter or soft-rerank recall results based on conditions.
| Name | Required | Description | Default |
|---|---|---|---|
| condition | Yes | ||
| action | Yes | ||
| rule_type | No | soft | |
| scope | No | global | |
| scope_value | No | ||
| priority | No |
| Name | Required | Description |
|---|---|---|
| result | 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 explains that rules 'hard-filter or soft-rerank recall results', which gives some insight into behavior, but lacks details on permissions, side effects, error handling, or response format, leaving significant gaps 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 front-loaded and concise with two sentences that directly state the tool's purpose and effect. There's no unnecessary information, though it could be slightly more structured by explicitly listing key parameters.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (6 parameters, mutation operation) and lack of annotations, the description is minimally adequate but incomplete. It covers the basic purpose and effect, but with 0% schema coverage and an output schema present, it should provide more parameter context and behavioral details to be fully helpful.
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 for undocumented parameters. It mentions 'conditions' and hints at 'rule_type' (hard-filter vs. soft-rerank), but doesn't explain the meaning or usage of the 6 parameters (e.g., 'scope', 'priority'), failing to add sufficient value beyond the bare 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 resource ('neuro-symbolic rule to the memory store'), with a specific purpose of filtering or reranking recall results. However, it doesn't explicitly differentiate from sibling tools like 'get_rules' or 'validate_memory', which would require 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?
No guidance is provided on when to use this tool versus alternatives, such as when to add rules versus using other tools like 'recall' or 'validate_memory'. The description mentions the tool's effect but not the context for its application.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Mark a memory as compaction-resistant. Anchored memories survive context compaction, heat decay, and cannot be deleted without force. Use for critical facts and active decisions.
| Name | Required | Description | Default |
|---|---|---|---|
| memory_id | Yes | ||
| reason | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden and does an excellent job explaining behavioral traits: it discloses that anchored memories 'survive context compaction, heat decay, and cannot be deleted without force.' This provides crucial information about persistence and deletion constraints that isn't available elsewhere.
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 zero waste - the first explains what the tool does, the second provides usage guidance. Every word earns its place, and the most important information (what anchoring means) comes first.
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 no annotations, 0% schema coverage, but with an output schema, the description does well on behavioral aspects but completely misses parameter guidance. The existence of an output schema means return values are documented elsewhere, but the description should still explain parameter semantics given the poor schema coverage.
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 and 2 parameters, the description provides no information about what 'memory_id' or 'reason' parameters mean, their formats, or how they should be used. The schema shows 'reason' is optional with null default, but the description doesn't explain when or why to provide a reason.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Mark') and resource ('a memory') with specific purpose ('as compaction-resistant'), distinguishing it from sibling tools like 'forget' or 'rate_memory'. It explains what anchoring does rather than just restating the name.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use this tool ('Use for critical facts and active decisions'), giving practical guidance. However, it doesn't explicitly state when NOT to use it or mention specific alternatives among the many sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Evaluate knowledge coverage completeness for a project directory. Returns a 0-100 coverage score and actionable recommendations.
| Name | Required | Description | Default |
|---|---|---|---|
| directory | No | ||
| domain | No | ||
| stale_days | No |
| 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 the full burden of behavioral disclosure. While it mentions the tool returns a coverage score and recommendations, it doesn't describe what 'coverage' means, how the evaluation works, whether it's read-only or has side effects, performance characteristics, or error conditions. For a tool with 3 parameters and no annotation coverage, this is insufficient behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately concise with two sentences that efficiently state the tool's purpose and output. The first sentence clearly describes what the tool does, and the second sentence specifies the return format. There's no unnecessary verbiage or repetition, making it easy to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 3 parameters with 0% schema coverage and no annotations, but does have an output schema, the description is incomplete. While the output schema may document return values, the description doesn't adequately explain the tool's behavior, parameter usage, or relationship to sibling tools. For a coverage assessment tool in a complex memory/analysis system, more context about what 'coverage' means and how parameters affect the evaluation would be helpful.
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 and 3 parameters (directory, domain, stale_days), the description provides no information about what these parameters mean or how they affect the evaluation. It doesn't explain what 'directory' should contain, what 'domain' refers to, or what 'stale_days' controls. The description fails to compensate for the complete lack of parameter documentation 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 tool's purpose: 'Evaluate knowledge coverage completeness for a project directory' specifies the verb (evaluate) and resource (knowledge coverage for a project directory). It distinguishes from siblings like 'detect_gaps' or 'codebase_analyze' by focusing on coverage assessment rather than gap detection or code analysis. However, it doesn't explicitly differentiate from all potential alternatives like 'validate_memory' or 'checkpoint'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites, appropriate contexts, or exclusions. With many sibling tools like 'detect_gaps', 'validate_memory', and 'codebase_analyze' that might overlap in functionality, the absence of usage guidelines leaves the agent without direction on tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Auto-import prior Claude Code conversations into the memory store. Idempotent -- tracks already-processed session files by hash. Links historical work to core concepts automatically.
| Name | Required | Description | Default |
|---|---|---|---|
| project | No | ||
| max_files | No | ||
| min_importance | No | ||
| dry_run | No | ||
| force_reprocess | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden and does well by disclosing key behavioral traits: idempotency through hash tracking, automatic concept linking, and processing constraints ('already-processed session files'). It doesn't mention permissions, rate limits, or error handling, but provides solid operational context for a backfill operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences with zero waste: first states core function, second explains idempotency mechanism, third describes value-add (automatic linking). Each sentence earns its place by adding distinct, valuable information. Perfectly front-loaded with the primary 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 5-parameter tool with no annotations but an output schema, the description provides good operational context about what the tool does and its behavioral characteristics. It doesn't explain parameters or return values, but the output schema handles returns, and the description gives enough context for an agent to understand the tool's role in the memory system.
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 for 5 parameters, the description adds no explicit parameter information. However, it implies parameter semantics through context: 'auto-import' suggests batch processing, 'tracks already-processed' relates to idempotency parameters, and 'historical work' suggests scope parameters. This provides meaningful context despite no direct parameter documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with specific verbs ('auto-import', 'tracks', 'links') and resources ('prior Claude Code conversations', 'memory store', 'historical work', 'core concepts'). It distinguishes from sibling tools like 'import_sessions' by emphasizing automatic linking to concepts and idempotent processing.
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 importing historical conversations automatically, but doesn't explicitly state when to use this vs. alternatives like 'import_sessions' or 'seed_project'. It mentions idempotency which suggests it's safe for repeated runs, but lacks clear when/when-not guidance or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Hippocampal replay: save/restore working state across context compaction events.
| Name | Required | Description | Default |
|---|---|---|---|
| action | Yes | ||
| directory | No | ||
| current_task | No | ||
| files_being_edited | No | ||
| key_decisions | No | ||
| open_questions | No | ||
| next_steps | No | ||
| active_errors | No | ||
| custom_context | No | ||
| session_id | No |
| Name | Required | Description |
|---|---|---|
| result | 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. While 'save/restore' implies both read and write capabilities, it doesn't specify whether this is destructive, whether it requires special permissions, what the persistence characteristics are, or what happens during failures. The metaphorical language ('hippocampal replay', 'context compaction events') further obscures the actual behavior rather than clarifying it.
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 (one sentence) but inefficiently uses that space. The metaphorical framing ('hippocampal replay', 'context compaction events') adds complexity without clear benefit. While brief, it's not front-loaded with actionable information - the core function 'save/restore working state' is buried in metaphorical language rather than stated clearly upfront.
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 10 parameters (1 required, 9 optional), 0% schema description coverage, no annotations, but with an output schema, the description is inadequate. It doesn't explain what the tool actually does in concrete terms, provides no parameter guidance, and relies on metaphorical language that obscures rather than clarifies. While the output schema might document return values, the description fails to provide the necessary context for understanding when and how to use this complex state management 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?
With 10 parameters and 0% schema description coverage, the description provides no information about any parameters. It doesn't mention the required 'action' parameter or any of the 9 optional parameters like 'directory', 'current_task', 'files_being_edited', etc. The description fails to compensate for the complete lack of schema documentation, leaving all parameters semantically unexplained.
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 'Hippocampal replay: save/restore working state across context compaction events' uses metaphorical language ('hippocampal replay', 'context compaction events') that makes the purpose somewhat vague. It mentions 'save/restore working state' which indicates a state management function, but the metaphorical framing obscures the concrete action. It doesn't clearly distinguish this from sibling tools like 'record_session_end', 'remember', or 'backfill_memories' which might also involve state management.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no explicit guidance on when to use this tool versus alternatives. The phrase 'across context compaction events' hints at a specific triggering condition, but doesn't explain what those events are or when they occur. There's no mention of prerequisites, timing considerations, or comparison to sibling tools like 'remember' or 'record_session_end' that might serve similar purposes.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Analyze a codebase and store its structure as Cortex memories. Uses tree-sitter AST for cross-file resolution, call graphs, and community detection. Incremental: only processes changed files.
| Name | Required | Description | Default |
|---|---|---|---|
| directory | No | ||
| languages | No | ||
| max_files | No | ||
| max_file_size_kb | No | ||
| incremental | No | ||
| dry_run | No | ||
| domain | No |
| Name | Required | Description |
|---|---|---|
| result | 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 effectively describes key traits: it stores data as memories (implying persistence), uses tree-sitter AST for analysis (specifying the method), handles cross-file resolution and call graphs (detailing scope), and is incremental (explaining performance behavior). It lacks details on permissions, rate limits, or error handling, but covers significant operational aspects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized and front-loaded, with two sentences that efficiently convey the core functionality and a key behavioral trait (incremental processing). Every sentence adds value without redundancy, making it easy to scan and understand quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (codebase analysis with multiple parameters) and the presence of an output schema (which reduces need to explain return values), the description is partially complete. It covers the main purpose and some behavior but lacks parameter explanations and details on prerequisites or limitations, leaving gaps for effective use by an AI agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 7 parameters with 0% description coverage, meaning none are documented in the schema. The description does not mention any parameters, failing to compensate for this gap. It does not explain what 'directory', 'languages', 'max_files', etc., mean or how they affect the analysis, leaving semantics unclear.
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 with specific verbs ('analyze', 'store') and resources ('codebase', 'Cortex memories'), and distinguishes it from siblings by mentioning unique capabilities like tree-sitter AST processing, cross-file resolution, call graphs, and community detection. It goes beyond a simple restatement of the name.
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 through 'incremental: only processes changed files', which suggests when to use it for efficiency. However, it does not explicitly state when to use this tool versus alternatives like 'detect_domain' or 'explore_features', nor does it provide exclusions or prerequisites. The guidance is present but not comprehensive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run memory maintenance: heat decay, compression, and CLS consolidation cycles.
| Name | Required | Description | Default |
|---|---|---|---|
| decay | No | ||
| compress | No | ||
| cls | No | ||
| memify | No | ||
| deep | No |
| 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 the full burden of behavioral disclosure. It mentions 'memory maintenance' and specific operations, but doesn't explain what these operations entail (e.g., are they destructive, do they require special permissions, what are the side effects or performance impacts?). This leaves significant gaps in understanding the tool's behavior beyond its basic purpose.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the core action ('Run memory maintenance') and lists specific operations without unnecessary words. Every part of the sentence contributes directly to understanding the tool's purpose, making it appropriately concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (a maintenance tool with 5 parameters and no annotations) and the presence of an output schema (which reduces the need to describe return values), the description is moderately complete. It covers the purpose and hints at parameter semantics but lacks usage guidelines and detailed behavioral context, leaving room for improvement in guiding an agent effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 5 parameters with 0% description coverage, but the description compensates by implying the parameters' roles: 'heat decay' likely maps to 'decay', 'compression' to 'compress', and 'CLS consolidation cycles' to 'cls'. It doesn't mention 'memify' or 'deep', but the context suggests these are additional maintenance options. Since there are 0 required parameters, the baseline is 4, and the description adds meaningful context for most parameters 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 action ('Run memory maintenance') and specifies three specific operations (heat decay, compression, CLS consolidation cycles), which gives a good sense of what the tool does. However, it doesn't explicitly differentiate itself from sibling tools like 'memory_stats', 'rebuild_profiles', or 'validate_memory' that might also relate to memory management, leaving some ambiguity about its unique role.
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. With many sibling tools related to memory operations (e.g., 'memory_stats', 'rebuild_profiles', 'validate_memory'), there's no indication of context, prerequisites, or exclusions for using 'consolidate', making it unclear when an agent should select it over other options.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a prospective memory trigger: a future-oriented reminder that fires when a condition is met (keyword, time, file, or domain).
| Name | Required | Description | Default |
|---|---|---|---|
| content | Yes | ||
| trigger_condition | Yes | ||
| trigger_type | No | keyword | |
| target_directory | No |
| Name | Required | Description |
|---|---|---|
| result | 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 mentions the tool creates a trigger that 'fires when a condition is met', which implies an action, but doesn't specify permissions needed, side effects, rate limits, or what happens upon firing. This is a significant gap for a creation 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 a single, efficient sentence that front-loads the purpose and key details. Every word earns its place, with no wasted text, making it easy to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has an output schema (which covers return values) and no annotations, the description is moderately complete. It explains the core functionality but lacks details on behavioral traits and full parameter semantics, making it adequate but with clear gaps for a creation 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 compensate. It adds meaning by explaining that parameters relate to conditions like 'keyword, time, file, or domain', which helps interpret 'trigger_condition' and 'trigger_type'. However, it doesn't detail all 4 parameters (e.g., 'content', 'target_directory'), leaving gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('create') and resource ('prospective memory trigger'), defining it as a future-oriented reminder that fires based on conditions. It distinguishes from siblings like 'add_rule' or 'remember' by specifying its unique trigger-based nature, though it doesn't explicitly contrast them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like 'add_rule' or 'remember'. The description implies usage for creating reminders with conditions but lacks explicit when/when-not instructions or references to sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Lightweight domain classification from cwd, project, or first message. <20ms.
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | ||
| project | No | ||
| first_message | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses the tool is 'lightweight' and has a performance characteristic (<20ms), which is useful behavioral context. However, it doesn't mention error handling, output format, or whether it's read-only or has side effects, leaving gaps in transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the purpose ('Lightweight domain classification') and includes key details (inputs and performance). Every word earns its place with no redundancy or waste.
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 (which covers return values), no annotations, and low schema coverage, the description is reasonably complete. It specifies the action, inputs, and a performance trait, but could improve by clarifying the domain types or error cases to fully compensate for the lack of annotations.
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 lists the three parameters (cwd, project, first_message) and implies they are alternative inputs for classification, adding meaning beyond the bare schema. However, it doesn't explain what each parameter represents (e.g., 'cwd' as current working directory) or their relationships, resulting in a baseline score.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool performs 'domain classification' with specific inputs (cwd, project, or first message), distinguishing it from siblings like 'list_domains' or 'detect_gaps'. However, it doesn't specify what type of domains are classified (e.g., programming languages, project types), leaving some ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions the tool is 'lightweight' and fast (<20ms), which implies usage for quick classification, but provides no explicit guidance on when to use it versus alternatives like 'assess_coverage' or 'detect_gaps'. There are no exclusions or prerequisites stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Identify knowledge gaps in the memory store: isolated entities, sparse domains, temporal drift, and low-heat topic clusters.
| Name | Required | Description | Default |
|---|---|---|---|
| domain | No | ||
| include_entity_gaps | No | ||
| include_domain_gaps | No | ||
| include_temporal_gaps | No | ||
| stale_threshold_days | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It mentions what types of gaps are identified but doesn't describe how the tool behaves: whether it's read-only or modifies data, what permissions are needed, whether it's computationally intensive, what the output format looks like, or any rate limits. For a gap detection tool with 5 parameters, this leaves significant behavioral questions unanswered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that immediately states the tool's purpose and enumerates the specific gap types it identifies. Every word serves a purpose with no redundancy or unnecessary elaboration. It's appropriately sized for a tool with this level of 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 that there's an output schema (which handles return values), no annotations, and 5 parameters with 0% schema coverage, the description provides adequate basic purpose but lacks crucial context. For a gap detection tool that likely returns structured analysis results, the description should ideally mention what kind of output to expect or how results are organized, even with an output schema available. It's minimally viable but has clear gaps in behavioral 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?
The schema has 0% description coverage, so all parameters are undocumented in the schema. The description mentions gap types (isolated entities, sparse domains, temporal drift, low-heat clusters) which partially maps to parameters like 'include_entity_gaps', 'include_domain_gaps', and 'include_temporal_gaps', but doesn't explain 'domain' filtering or 'stale_threshold_days'. It adds some semantic context but doesn't fully compensate for the complete lack of schema documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Identify knowledge gaps in the memory store' with specific types of gaps listed (isolated entities, sparse domains, temporal drift, low-heat topic clusters). It distinguishes from siblings like 'assess_coverage' or 'memory_stats' by focusing on gap detection rather than coverage assessment or statistical reporting. However, it doesn't explicitly differentiate from 'detect_domain' which might overlap in domain analysis.
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. With siblings like 'assess_coverage', 'detect_domain', and 'memory_stats' that might serve related purposes, there's no indication of when this specific gap detection tool is preferred. The description only states what it does, not when it should be used.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Navigate into a fractal memory cluster. L2 cluster → shows L1 child clusters. L1 cluster → shows individual memories.
| Name | Required | Description | Default |
|---|---|---|---|
| cluster_id | Yes | ||
| domain | No | ||
| min_heat | No |
| 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 describes the navigation behavior (showing child clusters or memories) but lacks critical details: whether this is read-only or has side effects, permission requirements, rate limits, pagination, or error conditions. For a tool with 3 parameters and no annotation coverage, this is insufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences front-load the core purpose and behavior with zero waste. Each sentence earns its place by explaining the navigation action and level-dependent outcomes 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 3 parameters with 0% schema coverage, no annotations, but an output schema exists, the description is incomplete. It covers the basic purpose but misses parameter explanations, behavioral context, and usage guidelines. The output schema mitigates some gaps, but overall completeness is minimal viable.
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 mentions 'cluster_id' implicitly (via 'L2 cluster'/'L1 cluster') but doesn't explain its format or purpose. It omits 'domain' and 'min_heat' entirely, leaving 2 of 3 parameters undocumented. The description adds minimal 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 clearly states the verb ('Navigate into') and resource ('fractal memory cluster'), explaining that it shows child clusters or individual memories depending on the cluster level. It distinguishes from general navigation tools like 'navigate_memory' by specifying hierarchical exploration, though it doesn't explicitly differentiate from all siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for exploring hierarchical memory structures but provides no explicit guidance on when to use this tool versus alternatives like 'navigate_memory', 'recall_hierarchical', or 'explore_features'. No prerequisites, exclusions, or comparative context are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Explore interpretability features: dictionary features, attribution graphs, persona vectors, and cross-domain behavioral persistence. Inspired by Anthropic's mechanistic interpretability research.
| Name | Required | Description | Default |
|---|---|---|---|
| mode | Yes | ||
| domain | No | ||
| compare_domain | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It mentions exploring interpretability features but doesn't describe what the exploration entails - whether it's read-only, generates visualizations, performs analysis, has side effects, or requires specific permissions. The description is too vague about the tool's actual behavior and operational characteristics.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately concise with two sentences. The first sentence lists the features to explore, and the second provides research context. There's no unnecessary verbosity, though the content itself is insufficiently informative about the tool's actual function and usage.
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 that there's an output schema (which reduces the need to describe return values) but zero schema description coverage and no annotations, the description is incomplete. It mentions what features can be explored but doesn't explain how to use the tool, what the parameters mean, or how this differs from sibling visualization/analysis tools. For a 3-parameter tool with complex interpretability features, more guidance is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so all 3 parameters (mode, domain, compare_domain) are completely undocumented in the schema. The description provides no information about what these parameters mean, what values they accept, or how they affect the exploration. This leaves critical usage information missing that the description should compensate for but doesn't.
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 'Explore interpretability features' but doesn't specify what action 'explore' entails or what resource it operates on. It lists feature types (dictionary features, attribution graphs, etc.) but doesn't clarify whether this tool displays, analyzes, compares, or generates these features. The mention of being 'inspired by Anthropic's mechanistic interpretability research' adds context but doesn't define the tool's specific function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided about when to use this tool versus the many sibling tools. With 40+ sibling tools including 'open_visualization', 'get_methodology_graph', 'detect_domain', and others that might overlap with interpretability features, the description offers no differentiation or context for when this specific exploration tool is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a memory by ID. Supports soft (mark stale) or hard (permanent) deletion. Protected memories require force=True.
| Name | Required | Description | Default |
|---|---|---|---|
| memory_id | Yes | ||
| soft | No | ||
| force | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden and does well by disclosing key behavioral traits: it explains the two deletion modes (soft/hard), mentions protected memories requiring force parameter, and clarifies the destructive nature of the operation. However, it doesn't cover rate limits, authentication needs, or response format.
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 perfectly sized at two sentences with zero wasted words. The first sentence establishes core functionality, the second adds crucial nuance about protected memories. Every phrase earns its place and information is front-loaded effectively.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive operation with 3 parameters and no annotations, the description does well by explaining deletion modes and protection overrides. Since an output schema exists, it doesn't need to explain return values. However, it could mention authentication requirements or error conditions for a more complete picture.
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 compensates by explaining all three parameters: memory_id (target identifier), soft (deletion type), and force (override protection). It provides crucial semantic context about what each parameter controls that isn't available from the bare 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 purpose with specific verb ('Delete') and resource ('a memory by ID'), and distinguishes it from siblings like 'recall' or 'remember' by focusing on deletion rather than retrieval or creation. It provides additional nuance about deletion types (soft vs hard) and protected memories.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use specific parameters (force=True for protected memories), but doesn't explicitly state when to use this tool versus alternatives like 'validate_memory' or 'rate_memory'. It implies usage through the deletion functionality but lacks explicit sibling differentiation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Trace entity relationships through the knowledge graph. Returns causal/dependency chains from a starting entity or memory.
| Name | Required | Description | Default |
|---|---|---|---|
| entity_name | No | ||
| memory_id | No | ||
| relationship_types | No | ||
| max_depth | No | ||
| direction | No | both |
| 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 the full burden of behavioral disclosure. It mentions 'trace' and 'returns' but lacks details on permissions, rate limits, side effects, or output format. The description does not contradict annotations, but it is insufficient for a tool with 5 parameters and no annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded, using two sentences that efficiently convey the core functionality. There is no wasted language, though it could benefit from more detailed guidance without sacrificing brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (5 parameters, no annotations, but with an output schema), the description is moderately complete. It outlines the purpose and starting inputs but lacks usage guidelines, behavioral details, and parameter explanations. The presence of an output schema reduces the need to describe return values, but gaps remain in other areas.
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 for undocumented parameters. It only hints at 'entity_name' and 'memory_id' as starting points and 'relationship_types' through 'causal/dependency chains,' but does not explain 'max_depth' or 'direction.' This adds minimal value beyond the schema, failing to fully address the coverage 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?
The description clearly states the tool's purpose: 'Trace entity relationships through the knowledge graph' and 'Returns causal/dependency chains from a starting entity or memory.' It specifies the verb ('trace'), resource ('entity relationships'), and output type ('causal/dependency chains'), but does not explicitly differentiate it from similar sibling tools like 'get_methodology_graph' or 'navigate_memory'.
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 mentions 'starting entity or memory' but does not specify scenarios, prerequisites, or exclusions, nor does it reference sibling tools for comparison, leaving the agent without contextual usage direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns methodology map as graph data for 3D visualization. <100ms.
| Name | Required | Description | Default |
|---|---|---|---|
| domain | No |
| 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 the full burden of behavioral disclosure. It adds value by specifying the output format ('graph data for 3D visualization') and a performance characteristic ('<100ms'), which are useful beyond the input schema. However, it lacks details on permissions, error handling, or data scope, leaving gaps in behavioral understanding for a tool with no 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 and front-loaded, consisting of only two sentences that directly state the tool's purpose and a performance metric. Every word earns its place, with no redundant or vague language, making it efficient and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that there is an output schema (which should document return values), the description does not need to explain outputs. However, with no annotations, low parameter coverage, and complexity implied by 'graph data for 3D visualization', the description is somewhat incomplete. It covers purpose and performance but misses parameter details and broader context, making it minimally adequate but with clear 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?
The input schema has one parameter ('domain') with 0% description coverage, and the tool description does not mention any parameters. This leaves the parameter's purpose, format, and effect completely undocumented. Since schema coverage is low (<50%), the description fails to compensate, resulting in inadequate parameter semantics.
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: 'Returns methodology map as graph data for 3D visualization.' It specifies the verb ('returns'), resource ('methodology map'), and output format ('graph data for 3D visualization'), which is specific and actionable. However, it does not explicitly differentiate from sibling tools like 'query_methodology' or 'navigate_memory', which might have overlapping functions, so it falls short of a perfect score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It mentions a performance hint ('<100ms'), but this does not help in choosing between this tool and siblings such as 'query_methodology' or 'open_visualization'. There are no explicit when-to-use or when-not-to-use instructions, leaving the agent to infer usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate a period-based autobiographical narrative of project activity. Returns chronological 'chapters' of what happened during a time period.
| Name | Required | Description | Default |
|---|---|---|---|
| directory | No | ||
| domain | No | ||
| period | No | week | |
| max_chapters | No |
| 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 the full burden. It mentions the tool generates and returns something, but lacks details on permissions, rate limits, side effects, or error handling. For a tool with 4 parameters and no annotation coverage, this is insufficient behavioral disclosure.
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 (two sentences) and front-loaded with the core purpose. Every sentence adds value: the first defines the action, the second specifies the output format. No wasted words, though it could benefit from more detail given the 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 4 parameters with 0% schema coverage, no annotations, but an output schema exists, the description is incomplete. It adequately states what the tool does but fails to explain inputs or behavioral context. The output schema mitigates the need to describe return values, but other gaps remain significant.
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 parameters are undocumented in the schema. The description doesn't explain any parameters (directory, domain, period, max_chapters), their meanings, or how they affect the narrative. This leaves significant gaps in understanding how to use the tool effectively.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Generate a period-based autobiographical narrative of project activity' and specifies it returns 'chronological chapters'. It uses specific verbs ('generate', 'returns') and identifies the resource ('project activity'). However, it doesn't explicitly differentiate from sibling tools like 'narrative' or 'recall', which appear related.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites, context for selection, or exclusions. With many sibling tools (e.g., 'narrative', 'recall', 'get_causal_chain'), the lack of comparative guidance is a significant gap.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List active neuro-symbolic rules in the memory store, optionally filtered by scope or rule type.
| Name | Required | Description | Default |
|---|---|---|---|
| scope | No | ||
| rule_type | No | ||
| include_inactive | No |
| 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 the full burden of behavioral disclosure. It mentions 'active' rules and optional filtering, but fails to cover critical aspects like whether this is a read-only operation, potential rate limits, authentication needs, or what 'active' means in this context. This leaves significant gaps for a tool with no annotation support.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that efficiently conveys the core functionality and optional features without any wasted words. It's front-loaded with the main purpose and appropriately sized for the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (3 parameters, no annotations, but with an output schema), the description is minimally adequate. It covers the basic purpose and hints at parameters, but lacks details on usage guidelines, behavioral traits, and full parameter semantics. The presence of an output schema reduces the need to explain return values, but overall completeness is limited.
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 must compensate by explaining parameters. It mentions optional filtering by 'scope or rule type', which aligns with two of the three parameters ('scope' and 'rule_type'), and implies a focus on 'active' rules, hinting at the 'include_inactive' parameter. However, it doesn't fully detail all parameters or their semantics, such as default behaviors or what 'scope' entails, so it's not a perfect score.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('List') and resource ('active neuro-symbolic rules in the memory store'), making the purpose specific and understandable. However, it doesn't explicitly differentiate from sibling tools like 'list_domains' or 'get_causal_chain', which might also involve listing operations in the same domain, so it falls short of a perfect score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, such as 'list_domains' or 'get_causal_chain', which are sibling tools. It mentions optional filtering but doesn't specify contexts or prerequisites for usage, leaving the agent with minimal direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Import conversation history from ~/.claude/projects/ into the memory store. Extracts decisions, errors, architecture notes, and key insights from JSONL sessions.
| Name | Required | Description | Default |
|---|---|---|---|
| project | No | ||
| domain | No | ||
| min_importance | No | ||
| max_sessions | No | ||
| dry_run | No | ||
| full_read | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It mentions extraction of specific content types but omits critical details: whether this is a read-only or write operation (though 'import' suggests writing), what permissions are needed, whether it overwrites existing data, error handling, or performance characteristics. The description provides some context about what gets extracted but lacks comprehensive behavioral transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is efficiently structured in two sentences that convey core functionality. The first sentence covers the main action, source, and destination. The second adds valuable detail about extraction content. There's minimal waste, though it could be slightly more front-loaded by mentioning extraction in the first sentence.
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 6 parameters with 0% schema coverage and no annotations, but does have an output schema, the description is moderately complete. It explains the core purpose well but leaves parameters completely undocumented. The output schema existence means return values don't need description, but the parameter gap and lack of behavioral context are significant omissions for a data import 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?
With 0% schema description coverage for 6 parameters, the description provides no information about any parameters. It doesn't explain what 'project', 'domain', 'min_importance', 'max_sessions', 'dry_run', or 'full_read' mean or how they affect the import process. The description fails to compensate for the complete lack of schema documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Import conversation history'), source ('from ~/.claude/projects/'), destination ('into the memory store'), and what gets extracted ('decisions, errors, architecture notes, and key insights from JSONL sessions'). It distinguishes itself from siblings like 'record_session_end' or 'sync_instructions' by focusing on historical import rather than real-time recording or synchronization.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when needing to import historical session data into memory, but provides no explicit guidance on when to use this versus alternatives like 'backfill_memories' or 'seed_project'. There's no mention of prerequisites, exclusions, or comparative context with sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Overview of all detected cognitive domains. <10ms.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | 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 mentions the performance characteristic '<10ms' which is useful context about expected latency. However, it doesn't describe what 'detected cognitive domains' means, whether this is a read-only operation (implied but not stated), what format the output takes, or any limitations like pagination or filtering constraints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely brief - just two phrases totaling 8 words. While concise, it's arguably too terse given the complexity implied by 'cognitive domains' and the lack of other documentation. The front-loaded purpose statement is clear, but the timing information might be better placed after more fundamental behavioral context.
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 that there's an output schema (which should document return values), the description doesn't need to explain return format. However, for a tool dealing with 'cognitive domains' - a potentially complex concept in this system - the description feels minimal. With no annotations and siblings that suggest rich functionality (detect_domain, explore_features, etc.), more context about what this overview provides would be helpful.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters with 100% schema description coverage, so the schema fully documents the absence of inputs. The description doesn't need to compensate for any parameter documentation gaps. The baseline for zero parameters with complete schema coverage is 4, as there are no parameters whose semantics need explanation beyond what the structured data provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Overview of all detected cognitive domains' which indicates a listing/retrieval function, but it's somewhat vague about what 'cognitive domains' are in this context. It doesn't clearly distinguish this tool from other list/retrieval siblings like 'get_rules', 'wiki_list', or 'memory_stats'. The '<10ms' timing hint adds specificity but doesn't fully clarify the core 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?
No guidance is provided about when to use this tool versus alternatives. With siblings like 'detect_domain', 'explore_features', 'navigate_memory', and 'get_rules' that might provide related functionality, the description offers no context about appropriate use cases, prerequisites, or when other tools might be more suitable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Memory system diagnostics: counts, heat distribution, entities, triggers.
| 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 the full burden of behavioral disclosure. It mentions 'diagnostics' which implies a read-only operation, but doesn't specify whether this requires permissions, has side effects, or details about output format. For a tool with no annotation coverage, this leaves significant behavioral gaps unaddressed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient phrase that lists key diagnostic aspects. It's appropriately sized for a zero-parameter tool and front-loads the purpose. However, it could be slightly more structured by explicitly stating it's a read-only diagnostic tool.
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 0 parameters, 100% schema coverage, and an output schema exists, the description is minimally complete. However, as a diagnostic tool with no annotations, it should ideally clarify that it's read-only and what kind of diagnostic data it returns. The existence of an output schema reduces but doesn't eliminate the need for some behavioral context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has 0 parameters with 100% schema description coverage, so the schema fully documents the lack of inputs. The description doesn't need to compensate for any parameter gaps, and it appropriately doesn't mention parameters. A baseline of 4 is appropriate since no parameter information 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 states the tool provides 'memory system diagnostics' and lists four diagnostic aspects (counts, heat distribution, entities, triggers), which gives a general purpose. However, it doesn't specify a clear verb action or distinguish this from sibling tools like 'checkpoint', 'validate_memory', or 'get_causal_chain' that might also provide diagnostic information about the memory system. The purpose is somewhat vague rather than 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?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites, timing, or compare it to siblings like 'checkpoint' or 'validate_memory' that might serve similar diagnostic purposes. Without any usage context, the agent must infer when this tool is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate a project narrative/story from stored memories for a directory or domain.
| Name | Required | Description | Default |
|---|---|---|---|
| directory | No | ||
| domain | No | ||
| brief | No |
| 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 the full burden of behavioral disclosure. It states the tool generates a narrative from stored memories but doesn't explain what 'stored memories' are, how the generation works, whether it's deterministic or creative, what permissions are needed, or any rate limits. For a generation tool with zero annotation coverage, this leaves significant gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the core purpose. There's no wasted wording, and it directly communicates the tool's function without unnecessary elaboration.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has an output schema (which likely describes the generated narrative), the description doesn't need to explain return values. However, with 3 parameters at 0% schema coverage and no annotations, the description is incomplete—it doesn't fully compensate for the lack of structured data, leaving key behavioral and parameter details unclear.
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 schema provides no parameter documentation. The description mentions 'directory or domain', which maps to two of the three parameters (directory, domain), but doesn't explain what these mean or how they're used. It omits the 'brief' parameter entirely. The description adds minimal 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 clearly states the tool's purpose: 'Generate a project narrative/story from stored memories for a directory or domain.' It specifies the verb ('generate'), resource ('project narrative/story'), and source ('stored memories'). However, it doesn't explicitly differentiate from sibling tools like 'get_project_story' or 'recall', which appear related to story/narrative retrieval.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites, timing considerations, or compare it to siblings like 'get_project_story' or 'recall'. The agent must infer usage from the purpose alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Launch the unified 3D neural graph in the browser. Combines methodology profiles, memories, and knowledge graph.
| Name | Required | Description | Default |
|---|---|---|---|
| domain | No |
| 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 the full burden. It mentions launching in the browser and combining data types, but lacks details on behavioral traits such as whether this is a read-only operation, if it requires specific permissions, potential side effects, or how the visualization behaves (e.g., interactivity, persistence). This leaves significant gaps for a tool that likely involves complex interactions.
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 and concise, consisting of two efficient sentences that directly state the tool's purpose and key features without unnecessary elaboration. Every sentence adds value by specifying the action and data integration.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (involving 3D neural graphs and multiple data types), no annotations, and an output schema that exists but is unspecified, the description is incomplete. It covers the basic purpose but lacks details on behavior, parameters, and usage context, making it adequate but with clear gaps for effective agent use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has one parameter ('domain') with 0% description coverage, and the tool description does not mention parameters at all. Since there is only one parameter and schema coverage is low, the description fails to compensate by explaining what 'domain' means or how it affects the visualization. This results in a baseline score of 3, as the minimal parameter count mitigates some risk.
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 ('Launch') and the target resource ('unified 3D neural graph in the browser'), specifying it combines methodology profiles, memories, and knowledge graph. However, it does not explicitly differentiate this tool from potential siblings like 'get_methodology_graph' or 'navigate_memory', which might offer related functionality, keeping it from a perfect score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. With many sibling tools like 'get_methodology_graph', 'explore_features', or 'navigate_memory', there is no indication of specific contexts, prerequisites, or exclusions for using 'open_visualization'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns the user's cognitive profile for the current domain. Pre-computed, <50ms. Use at session start for context injection.
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | ||
| project | No | ||
| first_message | No |
| Name | Required | Description |
|---|---|---|
| result | 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 adds useful context by stating the profile is 'pre-computed' and has a performance metric ('<50ms'), which helps the agent understand efficiency and data freshness. However, it lacks details on permissions, error handling, or response format, leaving gaps for a tool with behavioral 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 highly concise and front-loaded, consisting of two sentences that efficiently convey the tool's purpose, performance, and usage timing. Every word adds value without redundancy, making it easy for an agent to parse and apply quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (involving user cognitive profiles), no annotations, and an output schema (which mitigates the need to describe return values), the description is partially complete. It covers purpose and usage but lacks parameter explanations and behavioral details like authentication or limitations, leaving room for improvement in guiding the agent fully.
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 3 parameters (cwd, project, first_message) with 0% description coverage, meaning their purposes are undocumented. The tool description does not mention any parameters or explain their roles, failing to compensate for the schema's lack of documentation. This leaves the agent guessing about when and how to use these inputs.
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 'returns the user's cognitive profile for the current domain,' specifying both the verb ('returns') and resource ('cognitive profile'). It distinguishes itself from siblings like 'get_methodology_graph' or 'rebuild_profiles' by focusing on the user's pre-computed profile for context injection, though it doesn't explicitly contrast with these alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance to 'use at session start for context injection,' indicating the optimal timing. However, it does not specify when not to use it or name alternative tools for similar purposes, such as 'get_project_story' or 'detect_domain,' which could be relevant for different context needs.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Rate a memory as useful or not. Drives metamemory confidence which affects decay resistance and recall ranking.
| Name | Required | Description | Default |
|---|---|---|---|
| memory_id | Yes | ||
| useful | Yes |
| Name | Required | Description |
|---|---|---|
| result | 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 states that rating 'drives metamemory confidence which affects decay resistance and recall ranking', which adds some context about the tool's impact. However, it doesn't disclose critical behavioral traits such as whether this is a read-only or mutation operation, permission requirements, rate limits, or error handling. For a tool with zero annotation coverage, this is insufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with zero waste: the first states the core action, and the second explains the impact. It is appropriately sized and front-loaded, with every sentence earning its place by adding essential 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 tool's moderate complexity (2 parameters, no annotations, but has an output schema), the description is partially complete. It covers the purpose and impact but lacks usage guidelines, behavioral details, and full parameter semantics. The presence of an output schema means the description doesn't need to explain return values, but other gaps remain, making it adequate but with clear omissions.
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 2 parameters with 0% description coverage, so the description must compensate. It explains that the tool rates a memory as 'useful or not', which clarifies the purpose of the 'useful' boolean parameter. However, it doesn't add meaning for 'memory_id' (e.g., what constitutes a valid ID) or provide syntax/format details beyond the schema. The description adds some value but doesn't fully compensate for the coverage 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?
The description clearly states the verb 'rate' and the resource 'memory', specifying the action of rating a memory as useful or not. It distinguishes this from sibling tools like 'remember', 'recall', or 'forget' by focusing on evaluation rather than creation, retrieval, or deletion. However, it doesn't explicitly differentiate from all possible siblings, such as 'validate_memory', which might have overlapping purposes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like 'validate_memory' or other memory-related tools. It mentions the effect on 'metamemory confidence', which implies a context of memory management, but lacks explicit when-to-use or when-not-to-use instructions, prerequisites, or comparisons to sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Full rescan of all session data to rebuild methodology profiles. <10s.
| Name | Required | Description | Default |
|---|---|---|---|
| domain | No | ||
| force | No |
| Name | Required | Description |
|---|---|---|
| result | 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 adds useful context about performance ('<10s') and scope ('all session data'), but doesn't cover critical aspects like side effects (e.g., whether this is a destructive operation), permissions needed, or error handling, which are gaps for a tool that likely modifies data.
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 with only two clauses, front-loading the core purpose and adding a performance note, with zero wasted words. Every sentence earns its place by providing essential information 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 tool's complexity (a rescan operation with 2 parameters) and the presence of an output schema (which reduces the need to describe return values), the description is partially complete. It covers purpose and performance but lacks parameter explanations and behavioral details, making it adequate but with clear gaps for safe invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, so the description must compensate but fails to do so. It doesn't explain the 'domain' parameter (e.g., whether it filters the rescan) or the 'force' parameter (e.g., what it overrides), leaving both parameters undocumented and their semantics unclear.
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 ('Full rescan of all session data') and the outcome ('to rebuild methodology profiles'), which is specific and actionable. It distinguishes itself from siblings like 'detect_domain' or 'query_methodology' by focusing on reconstruction rather than analysis or querying, though it doesn't explicitly name alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, such as 'sync_instructions' or 'backfill_memories', which might handle similar data tasks. It lacks context on prerequisites, triggers, or exclusions, leaving the agent to infer usage based on the purpose alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve memories using intent-adaptive PG recall with production enrichments.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | ||
| domain | No | ||
| directory | No | ||
| max_results | No | ||
| min_heat | No | ||
| agent_topic | No |
| Name | Required | Description |
|---|---|---|
| result | 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. While 'retrieve' implies a read operation, it doesn't specify whether this is a simple lookup or a complex search, what 'production enrichments' entail, or any performance characteristics. The description mentions technical implementation details ('intent-adaptive PG recall') but doesn't translate these to observable behaviors that would help an agent understand what to expect from the tool's operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise (one sentence), which could be efficient if it were informative. However, it wastes its limited space on implementation details ('intent-adaptive PG recall with production enrichments') rather than practical information about what the tool does and when to use it. While technically brief, it's not effectively structured to help an agent understand the tool's purpose and usage.
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 6 parameters with 0% schema coverage and no annotations, the description is inadequate for helping an agent understand how to use this tool effectively. However, the presence of an output schema somewhat mitigates the need to describe return values in the description. The description fails to compensate for the complete lack of parameter documentation and provides minimal practical guidance for a tool with multiple parameters and complex sibling relationships.
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 for all 6 parameters, the description provides no information about what any parameter means or how to use them. The description doesn't mention any parameters at all, leaving the agent with parameter names (query, domain, directory, max_results, min_heat, agent_topic) but no semantic understanding of what they control or how they affect the recall operation.
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 the tool retrieves memories, which is a clear verb+resource combination ('retrieve memories'). However, it uses technical jargon like 'intent-adaptive PG recall with production enrichments' without explaining what this means in practical terms. It doesn't distinguish this tool from sibling tools like 'recall_hierarchical', 'remember', or 'navigate_memory' that likely have similar memory-related functions.
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. With multiple sibling tools dealing with memories (recall_hierarchical, remember, navigate_memory, etc.), there's no indication of what makes this specific recall method appropriate or when to choose it over other options. The technical terminology doesn't translate to practical usage scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve memories using the fractal hierarchy (L0/L1/L2 clusters). Adaptive weighting based on query length — short queries search broad, long queries search specific.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | ||
| domain | No | ||
| max_results | No | ||
| min_heat | No | ||
| cluster_threshold | No |
| 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 the full burden. It discloses the adaptive weighting behavior based on query length, which is a key behavioral trait. However, it doesn't cover other aspects like performance characteristics, error handling, or what 'memories' entail in this context. The description adds some value but leaves gaps for a tool with 5 parameters and no annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized and front-loaded with the core purpose in the first sentence. The second sentence adds crucial behavioral context without redundancy. Every sentence earns its place, making it efficient and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (5 parameters, no annotations, but with an output schema), the description is partially complete. It explains the retrieval mechanism and adaptive behavior, but lacks details on parameter meanings and doesn't leverage the output schema to clarify return values. For a tool with multiple parameters and sibling alternatives, more context would be beneficial.
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 for undocumented parameters. It mentions 'query' and implies usage based on query length, but doesn't explain the semantics of other parameters like 'domain', 'max_results', 'min_heat', or 'cluster_threshold'. With 5 parameters total and only 1 addressed, the description fails to add sufficient meaning beyond the bare 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 purpose: 'Retrieve memories using the fractal hierarchy (L0/L1/L2 clusters).' It specifies the verb ('retrieve') and resource ('memories'), and mentions the hierarchical clustering mechanism. However, it doesn't explicitly differentiate from sibling tools like 'recall' or 'navigate_memory', which might offer similar retrieval functions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use this tool: 'Adaptive weighting based on query length — short queries search broad, long queries search specific.' This gives guidance on query length considerations. It doesn't explicitly mention when not to use it or name alternatives, but the adaptive weighting hint helps infer usage scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Incremental profile update after a session ends. <200ms.
| Name | Required | Description | Default |
|---|---|---|---|
| session_id | Yes | ||
| domain | No | ||
| tools_used | No | ||
| duration | No | ||
| turn_count | No | ||
| keywords | No | ||
| cwd | No | ||
| project | No |
| Name | Required | Description |
|---|---|---|
| result | 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 mentions performance ('<200ms'), which is useful, but fails to cover critical aspects like whether this is a read or write operation, if it requires specific permissions, what the update entails, or potential side effects. For a tool with 8 parameters and likely mutation, this is inadequate.
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 with two short phrases that are front-loaded and waste no words. Every element ('incremental profile update', 'after a session ends', '<200ms') earns its place by conveying purpose and a performance hint 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 tool's complexity (8 parameters, likely a mutation tool), no annotations, and 0% schema coverage, the description is incomplete. While an output schema exists (which mitigates the need to explain return values), the description lacks essential details on behavior, parameter meanings, and usage context, making it insufficient for effective tool invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 0%, meaning none of the 8 parameters are documented in the schema. The description does not add any meaning or context for parameters like 'session_id', 'tools_used', or 'duration', leaving them entirely unexplained. This fails to compensate for the lack of schema documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('incremental profile update') and the triggering event ('after a session ends'), which is specific and informative. However, it does not explicitly differentiate this tool from sibling tools like 'checkpoint', 'backfill_memories', or 'rebuild_profiles', which might also involve profile updates, so it lacks sibling differentiation for a perfect score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context ('after a session ends') but provides no explicit guidance on when to use this tool versus alternatives, such as other profile-related tools in the sibling list. There are no exclusions, prerequisites, or comparisons mentioned, leaving the agent with minimal direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Store a memory through the predictive coding write gate.
| Name | Required | Description | Default |
|---|---|---|---|
| content | Yes | ||
| tags | No | ||
| directory | No | ||
| domain | No | ||
| source | No | ||
| force | No | ||
| agent_topic | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure but provides almost none. 'Store a memory' implies a write operation, but we don't know if this is idempotent, what permissions are required, whether it's transactional, what happens on failure, or what the 'predictive coding write gate' entails. The description doesn't address rate limits, side effects, or any behavioral characteristics beyond the basic write implication.
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 (one sentence) but this brevity comes at the cost of being under-specified. While it's front-loaded with the core action ('Store a memory'), it lacks necessary elaboration. The sentence earns its place but doesn't provide enough value - it's concise to a fault rather than efficiently informative.
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 7-parameter write tool with no annotations and 0% schema coverage, the description is completely inadequate. While there's an output schema (which reduces the need to describe return values), the description fails to explain what this tool does, when to use it, how parameters work, or any behavioral characteristics. Given the complexity and complete lack of structured documentation, this description provides minimal contextual value.
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 7 parameters and 0% schema description coverage, the description provides no information about any parameters. It doesn't explain what 'content' should contain, what 'tags' are for, what 'directory' or 'domain' represent, what 'source' indicates, when to use 'force', or what 'agent_topic' means. The description fails completely to compensate for the lack of schema documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Store a memory through the predictive coding write gate' is tautological - it essentially restates the tool name 'remember' as 'store a memory'. While it mentions 'predictive coding write gate', this is vague technical jargon that doesn't clarify what the tool actually does or what a 'memory' represents in this system. It doesn't distinguish this from sibling tools like 'record_session_end' or 'wiki_write' which might also store information.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides zero guidance on when to use this tool versus alternatives. With many sibling tools that might store or record information (record_session_end, wiki_write, backfill_memories, etc.), there's no indication of when 'remember' is appropriate versus these other options. No context, prerequisites, or exclusions are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Drive the ai-architect pipeline end-to-end: discovery -> impact -> strategy -> PRD -> verification -> implementation -> PR. Connects to ai-architect MCP server over stdio.
| Name | Required | Description | Default |
|---|---|---|---|
| codebase_path | Yes | ||
| task_path | Yes | ||
| context_path | No | ||
| github_repo | No | ||
| server | No | ||
| max_findings | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It mentions the tool 'connects to ai-architect MCP server over stdio' which provides some implementation context, but doesn't describe critical behavioral aspects: whether this is a long-running operation, what permissions or prerequisites are needed, what happens if the pipeline fails at intermediate stages, or what the output contains. For a complex pipeline tool with 6 parameters, this is insufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately concise with two sentences that efficiently convey the core functionality and implementation method. The first sentence clearly states the pipeline stages, and the second provides technical context about the server connection. There's no wasted verbiage or unnecessary elaboration.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (6 parameters, end-to-end pipeline), no annotations, but an output schema exists, the description is moderately complete. It explains the high-level pipeline flow but lacks details about parameter usage, behavioral expectations, and differentiation from sibling tools. The existence of an output schema means return values are documented elsewhere, but the description should still address more operational aspects.
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 for all 6 parameters, the description provides no information about what 'codebase_path', 'task_path', 'context_path', 'github_repo', 'server', or 'max_findings' mean or how they should be used. The description doesn't mention any parameters at all, leaving them completely undocumented despite the schema's lack of descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Drive the ai-architect pipeline end-to-end' with a specific sequence of stages (discovery -> impact -> strategy -> PRD -> verification -> implementation -> PR). It provides a clear verb ('drive') and resource ('ai-architect pipeline'), though it doesn't explicitly differentiate from sibling tools like 'codebase_analyze' or 'navigate_memory' which might handle parts of this pipeline.
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. With many sibling tools like 'codebase_analyze', 'explore_features', and 'get_project_story' that might handle components of the pipeline, there's no indication of when this comprehensive tool is preferred over more targeted ones. The description only states what it does, not when it's appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Bootstrap memory from an existing codebase. Analyzes structure, config, docs, entry points, and CI/CD. Stores key discoveries as memories.
| Name | Required | Description | Default |
|---|---|---|---|
| directory | No | ||
| domain | No | ||
| max_file_size_kb | No | ||
| dry_run | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden but offers limited behavioral insight. It mentions analysis scope (structure, config, docs, entry points, CI/CD) and memory storage, but omits critical details like required permissions, whether it modifies the codebase, rate limits, or error handling. For a tool with 4 parameters and no annotation coverage, this is insufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately concise with two sentences that directly state the tool's function and outcome. It's front-loaded with the core purpose and avoids unnecessary elaboration, though it could be slightly more structured by separating analysis steps from storage.
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 4 parameters with 0% schema coverage, no annotations, but an output schema exists, the description is moderately complete. It covers the high-level purpose and analysis scope, but lacks parameter semantics and behavioral details. The output schema mitigates some gaps, but overall completeness is limited for a tool with this 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 0%, so the description must compensate but adds no parameter information. It doesn't explain what 'directory', 'domain', 'max_file_size_kb', or 'dry_run' mean or how they affect the bootstrapping process. This leaves all 4 parameters semantically undocumented.
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: 'Bootstrap memory from an existing codebase' specifies the verb and resource. It distinguishes from siblings like 'codebase_analyze' by emphasizing memory storage ('Stores key discoveries as memories'), but doesn't explicitly contrast with all similar tools like 'backfill_memories' or 'import_sessions'.
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 is provided. The description mentions analyzing structure, config, docs, etc., but doesn't specify prerequisites, timing, or contrast with siblings like 'codebase_analyze' or 'backfill_memories'. This leaves the agent without explicit usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Sync top memory insights into CLAUDE.md for the project directory. Adds or refreshes a '## Memory Insights' section.
| Name | Required | Description | Default |
|---|---|---|---|
| directory | No | ||
| max_insights | No | ||
| min_heat | No | ||
| dry_run | No |
| 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 the full burden of behavioral disclosure. It mentions the tool 'adds or refreshes' content, implying a write operation, but doesn't specify permissions required, whether changes are reversible, or how it handles existing sections. The description is minimal and misses key behavioral traits like error handling or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is highly concise and front-loaded, consisting of a single sentence that directly states the tool's purpose. Every word earns its place, with no redundant or vague language. It efficiently communicates the core functionality without unnecessary elaboration.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (4 parameters, write operation) and the presence of an output schema, the description is minimally adequate. It covers the basic purpose but lacks details on usage context, behavioral traits, and parameter meanings. The output schema helps, but for a tool that modifies files, more guidance on effects and alternatives would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description provides no information about parameters, and the schema description coverage is 0%. However, the schema itself documents 4 parameters with defaults, and an output schema exists, which reduces the need for detailed param explanations in the description. The baseline score of 3 reflects that the schema handles parameter documentation adequately, but the description adds no value beyond this.
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 with a specific verb ('sync'), resource ('top memory insights'), and target ('CLAUDE.md for the project directory'). It specifies the action of adding or refreshing a '## Memory Insights' section. However, it doesn't explicitly differentiate this tool from sibling tools like 'wiki_write' or 'record_session_end' that might also modify documentation.
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. With many sibling tools related to memory, documentation, and project management (e.g., 'wiki_write', 'record_session_end', 'backfill_memories'), there's no indication of the specific context or prerequisites for choosing 'sync_instructions'. It lacks any 'when' or 'when-not' statements.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Validate memories against current filesystem state. Marks stale memories whose referenced files no longer exist.
| Name | Required | Description | Default |
|---|---|---|---|
| memory_id | No | ||
| domain | No | ||
| directory | No | ||
| base_dir | No | ||
| staleness_threshold | No | ||
| dry_run | No |
| 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 the full burden. It discloses that the tool 'marks stale memories,' implying a mutation, but doesn't specify if this is reversible, what permissions are needed, or how it handles errors. It mentions a 'dry_run' parameter but doesn't explain its effect in the description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the core purpose and outcome. Every word earns its place with no redundancy or unnecessary elaboration, making it highly concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (6 parameters, mutation implied, no annotations) and the presence of an output schema, the description is incomplete. It lacks details on parameter usage, behavioral traits, and context, but the output schema may cover return values, preventing a lower score.
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 only implies parameters related to 'memories' and 'filesystem state' without detailing any of the 6 parameters. No meaning is added beyond the schema, leaving parameters like 'staleness_threshold' and 'domain' unexplained.
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 ('validate memories against current filesystem state') and the outcome ('marks stale memories whose referenced files no longer exist'). It distinguishes this tool from siblings like 'memory_stats' or 'backfill_memories' by focusing on validation against filesystem state rather than statistics or 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?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites, ideal scenarios, or exclusions, nor does it reference sibling tools for comparison. Usage is implied only through the action described.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a numbered ADR (architecture decision record) from structured fields. Auto-increments the ADR number.
| Name | Required | Description | Default |
|---|---|---|---|
| title | Yes | ||
| context | Yes | ||
| decision | Yes | ||
| consequences | Yes | ||
| status | No | accepted | |
| tags | No |
| 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 the full burden of behavioral disclosure. It mentions auto-incrementing ADR numbers, which is a useful behavioral trait, but lacks details on permissions, side effects (e.g., whether this creates persistent records), error handling, or response format. For a creation tool with zero annotation coverage, this leaves significant gaps in understanding its behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the core action ('Create a numbered ADR') and adds key behavior ('Auto-increments the ADR number'). There is no wasted text, and it's appropriately sized for the tool's complexity, making it highly concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that there is an output schema (which handles return values) but no annotations and low schema coverage, the description is moderately complete. It covers the basic action and a key trait (auto-incrementing), but for a creation tool with 6 parameters, it should provide more context on inputs, behavioral constraints, or usage scenarios to be fully 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 description coverage is 0%, so the schema provides no parameter details. The description mentions 'structured fields' but doesn't explain what those fields are (e.g., title, context, decision) or their purposes. It adds minimal semantic value beyond the schema, failing to compensate for the coverage gap, especially with 6 parameters (4 required).
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 creates a numbered ADR from structured fields with auto-incrementing numbers. It specifies the verb ('Create'), resource ('ADR'), and key behavior ('Auto-increments the ADR number'), making the purpose unambiguous. However, it doesn't explicitly differentiate from sibling tools like wiki_write or wiki_list, which prevents a perfect score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention sibling tools like wiki_write (which might handle general wiki content) or wiki_list (which might list ADRs), nor does it specify prerequisites or exclusions. Usage is implied only through the action described, with no explicit context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add a bidirectional link between two wiki pages. Updates the Related section of both files. Idempotent.
| Name | Required | Description | Default |
|---|---|---|---|
| from_path | Yes | ||
| to_path | Yes | ||
| relation | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses key behavioral traits: the bidirectional nature of the link, that it updates both files' Related sections, and idempotency. However, it doesn't cover permissions, error conditions, or what the output contains (though an output schema exists).
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 with three short sentences that are front-loaded with the core purpose. Every sentence adds value: the first states the action, the second specifies the effect, and the third provides an important behavioral trait (idempotency).
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 3 parameters with 0% schema coverage and no annotations, the description is incomplete—it doesn't explain parameters. However, an output schema exists, so return values needn't be described. The description covers the tool's core behavior adequately but leaves parameter semantics unaddressed.
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 schema provides no parameter descriptions. The description doesn't explain what 'from_path', 'to_path', or 'relation' mean, their formats, or valid values. It implies parameters exist but adds no semantic details beyond the schema's structure.
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 ('Add a bidirectional link'), the resource ('between two wiki pages'), and the effect ('Updates the Related section of both files'). It distinguishes from sibling tools like wiki_read or wiki_write by focusing on linking rather than reading/writing content.
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 wiki_write (which might handle content updates) or other wiki tools. It mentions idempotency but doesn't specify scenarios where this is preferable or when other tools should be used instead.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List authored wiki pages. Optionally filter by kind (adr/specs/files/notes).
| Name | Required | Description | Default |
|---|---|---|---|
| kind | No |
| 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 the full burden of behavioral disclosure. It mentions listing and optional filtering, but fails to disclose critical traits such as whether this is a read-only operation, if it requires authentication, how results are paginated or sorted, or what the output format is. The description is too minimal to adequately inform an agent about behavioral aspects beyond basic functionality.
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 with two short sentences that directly state the tool's purpose and parameter usage without any wasted words. It is front-loaded with the core action and efficiently includes necessary details, making it easy to parse and understand quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity (1 optional parameter) and the presence of an output schema, the description is minimally adequate. However, with no annotations and incomplete behavioral details, it leaves gaps in understanding operational constraints. The output schema likely covers return values, but the description should still address basic behavior like safety or permissions to be more complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds meaningful context for the single parameter 'kind' by specifying it as an optional filter with examples (adr, specs, files, notes), which goes beyond the schema's minimal coverage (0%). Since there's only one parameter and the schema provides no descriptions, the description effectively compensates by clarifying the parameter's purpose and possible values, making it highly useful for agent selection.
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 'list' and resource 'authored wiki pages', making the purpose specific and understandable. It distinguishes itself from other wiki tools like wiki_read, wiki_write, wiki_adr, etc., by focusing on listing rather than reading, writing, or linking. However, it doesn't explicitly differentiate from non-wiki list tools like list_domains, which slightly reduces 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 implies usage by mentioning optional filtering by kind (e.g., adr, specs, files, notes), which suggests when to use it for filtered vs. unfiltered lists. However, it lacks explicit guidance on when to use this tool versus alternatives like wiki_read for individual pages or other list tools, and no exclusions or prerequisites are stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read the raw markdown of a wiki page by its relative path.
| Name | Required | Description | Default |
|---|---|---|---|
| path | 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 carries the full burden of behavioral disclosure. It states the tool reads raw markdown but does not mention whether this is a read-only operation, what permissions are required, how errors are handled, or the format of the output. For a tool with zero annotation coverage, this leaves significant behavioral gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that is front-loaded with the core purpose. Every word earns its place, with no redundant or verbose language, 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?
Given the tool's low complexity (one parameter) and the presence of an output schema, the description is minimally adequate. However, it lacks details on behavioral aspects like error handling or permissions, which are important for a read operation in a wiki context. The output schema likely covers return values, but the description could benefit from more operational context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds meaningful context beyond the input schema, which has 0% coverage. It clarifies that the 'path' parameter is a 'relative path' to the wiki page, providing essential semantic information not present in the schema. With only one parameter, this adequately compensates for the low 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 specific action ('Read'), resource ('raw markdown of a wiki page'), and scope ('by its relative path'), distinguishing it from sibling tools like wiki_write, wiki_list, wiki_adr, and wiki_link. It precisely communicates what the tool does without ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as wiki_write, wiki_list, wiki_adr, or wiki_link. It lacks context about prerequisites, exclusions, or typical use cases, leaving the agent to infer usage from the tool name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Regenerate the wiki table of contents at .generated/INDEX.md. Authored pages are never touched.
| 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 the full burden. It discloses that the tool regenerates content and does not touch authored pages, which is useful behavioral context. However, it lacks details on permissions, side effects, or response format, leaving gaps 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 two concise sentences with zero waste, front-loaded with the main action and followed by an important clarification. Every sentence earns its place by providing essential 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?
Given the tool has 0 parameters, an output schema exists, and no annotations, the description is mostly complete for its purpose. It explains what the tool does and what it doesn't affect, but as a mutation tool, it could benefit from more behavioral details like error handling or success indicators.
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 0 parameters with 100% coverage, so no parameter documentation is needed. The description adds value by explaining the tool's effect on the wiki table of contents and authored pages, which compensates for the lack of 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 specific action ('Regenerate') and target resource ('wiki table of contents at .generated/INDEX.md'), distinguishing it from sibling wiki tools like wiki_read or wiki_write. It also explicitly notes what is not affected ('Authored pages are never touched'), providing clear differentiation.
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 by specifying the output location and that authored pages remain untouched, but it does not explicitly state when to use this tool versus alternatives like wiki_list or other wiki-related tools. No exclusions or prerequisites are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Author a wiki page (adr/specs/files/notes) or append/replace an existing one. Pages live under ~/.claude/methodology/wiki/ and are indexed in PostgreSQL as protected pointer memories for recall.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | ||
| content | Yes | ||
| mode | No | create | |
| tags | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It discloses that pages are stored in ~/.claude/methodology/wiki/ and indexed in PostgreSQL as protected pointer memories, adding useful context about persistence and recall mechanisms. However, it doesn't cover error handling, permissions, or what happens with existing content during replacement, leaving behavioral gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized with two sentences: the first states the core action, and the second adds storage and indexing context. It's front-loaded with the primary purpose, though the second sentence could be more directly related to usage.
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 4 parameters with 0% schema coverage and no annotations, the description provides basic purpose and storage context but lacks details on parameters, error cases, or output (though an output schema exists, reducing need for return value explanation). It's incomplete for a write tool with multiple parameters.
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 mentions 'path' and 'content' implicitly through 'wiki page' and 'append/replace', and 'mode' through 'author...or append/replace', but doesn't explain parameter meanings, defaults (e.g., mode='create'), or tag usage. This adds minimal value beyond what the schema names suggest.
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 ('author', 'append/replace') and resource ('wiki page') with specific types (adr/specs/files/notes). It distinguishes from siblings like wiki_read (read-only) and wiki_list (listing) by emphasizing write operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for creating or modifying wiki pages, with context about where pages live and how they're indexed. However, it doesn't explicitly state when to use this versus alternatives like wiki_adr (specific ADR tool) or wiki_link, nor does it mention exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The tools cover distinct functional areas (memory management, wiki operations, methodology analysis, etc.), but there is some overlap that could cause confusion. For example, 'recall' and 'recall_hierarchical' both retrieve memories with different algorithms, and 'backfill_memories' and 'import_sessions' both import conversation history, which might lead to misselection by an agent without careful reading of descriptions.
Most tools follow a consistent verb_noun or verb_adjective_noun pattern (e.g., 'add_rule', 'anchor', 'assess_coverage'), with clear and descriptive names. However, there are minor deviations like 'wiki_adr' (which mixes a prefix with an acronym) and 'run_pipeline' (which is less structured), slightly reducing consistency.
With 40 tools, the count is excessive for a single server, making it heavy and potentially overwhelming for agents to navigate. While the domain (cognitive memory and project management) is broad, the toolset feels bloated with many specialized operations that could have been grouped or streamlined, indicating poor scoping.
The tool set provides comprehensive coverage for memory storage, retrieval, maintenance, wiki management, and project analysis, with clear CRUD and lifecycle operations (e.g., 'remember', 'recall', 'forget', 'validate_memory'). There are no obvious gaps; it supports end-to-end workflows from data ingestion to visualization and narrative generation.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Persistent memory and cross-session learning for AI coding assistants (hosted remote MCP).
Persistent AI memory shared across Claude, ChatGPT, coding agents, and compatible MCP clients.
Private persistent memory for Claude, ChatGPT & Gemini via MCP - semantic search, zero-code setup.
Portable memory for AI agents: capture once, recall across Claude, Cursor, and any MCP client.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/cdeust/Cortex'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
