Claude Session Continuity MCP provides zero-re-explanation session continuity for Claude Code projects through automated context capture, semantic memory, task tracking, error archiving, and project lifecycle management.
Automated Session Continuity Core functionality is driven by Claude Hooks that automatically capture and inject project context, recent history, directives, and relevant memories — no manual tool calls required. Supports multilingual semantic search (94+ languages).
Session Lifecycle
session_start – Load project context (tech stack, recent activity, tasks, blockers)
session_end – Save session state (summary, work done, next steps, blockers)
session_history – Retrieve chronological past session records
search_sessions – Semantic/keyword search across session history
Project Management
project_init – Initialize project with auto-detected tech stack
project_analyze – Detect tech stack, framework, platform, and directory structure
project_status – Get current status including task breakdown and blockers
list_projects – List all tracked projects
Task Management
task_add / task_update / task_list – Add, update, and filter tasks with priority and status tracking
task_suggest – Scan source files for TODO/FIXME/HACK/XXX comments and suggest tasks
Solution Archive
solution_record – Record error-solution pairs with FTS5 indexing
solution_find – Search archive by keyword or semantic similarity
solution_suggest – Get AI-powered fix suggestions from past solutions; auto-triggered on Bash errors
Verification / Quality Gates
verify_build / verify_test / verify_all – Run platform-specific build, test, and lint commands (pnpm/flutter/gradlew)
Memory System
memory_store – Store classified knowledge (observation, decision, learning, error, pattern) with tags and importance scores
memory_search – Search via FTS5 or semantic embeddings with type/project/tag filters
memory_get – Retrieve full memory content by ID
memory_related – Find related memories via graph traversal and/or semantic similarity
memory_stats – View aggregate memory statistics
Knowledge Graph
graph_connect – Create directed typed edges between memories (solves, causes, depends_on, contradicts, extends, etc.)
graph_explore – Traverse the graph with depth control and relation/direction filtering
Integrates with Git repositories to extract commit messages and track code changes from session transcripts, maintaining project history context across sessions for continuity.
Session continuity for AI coding agents. Your agent picks up where it left off — never re-explain your project again. Persistent memory for Claude Code, OpenAI Codex CLI & Google Gemini CLI, sharing one local db: auto context injection, compaction handover, semantic search, and error→solution recall. Zero config, zero API cost, 100% local.
⚡ One install → context auto-loads every session · 🧩 survives compaction (0 re-explaining) · 🔒 100% local, $0 API
Renamed (v2.0.0): this project was previously
claude-session-continuity-mcp. The old name suggested it was Claude-only — it never was. Claude Code, Codex CLI, and Gemini CLI are all first-class and share one local memory. Existing installs keep working: the oldclaude-hook-*commands still ship as aliases. See Migrating from v1.
Every new session — whether you're in Claude Code, Codex CLI, or Gemini CLI:
"This is a Next.js 15 project with App Router..."
"We decided to use Server Actions because..."
"Last time we were working on the auth system..."
"The build command is pnpm build..."5 minutes of context-setting. Every. Single. Time.
Related MCP server: Melchizedek
Fully automatic. Lifecycle hooks handle everything without manual calls — on Claude Code, OpenAI Codex CLI, and Google Gemini CLI, sharing one local memory so context carries across all three:
# Session start → Auto-loads relevant context + recent session history
# When asking → Auto-injects relevant memories/solutions
# During conversation → Tracks active files + auto-injects error solutions
# On compact → Structured handover context for continuity
# On exit → Extracts commits, decisions, error-fix pairs from transcript← Auto-output on session start:
# my-app - Session Resumed
📍 **State**: Implementing signup form
## Recent Sessions
### 2026-02-28
**Work**: Completed OAuth integration with Google provider
**Commits**: feat: add OAuth callback handler; fix: redirect URI config
**Decisions**: Use Server Actions instead of API routes
### 2026-02-27
**Work**: Set up authentication foundation
**Next**: Implement signup form validation
## Directives
- 🔴 Always use Zod for form validation
- 📎 Prefer Server Components by default
## Key Memories
- 🎯 Decided on App Router, using Server Actions
- ⚠️ OAuth redirect_uri mismatch → check env fileZero manual work. Context follows you.
Most Claude memory tools rely on explicit tool calls ("remember this"), a cloud API, or a background AI worker. This one is deliberately different:
passbaton | Typical cloud/AI-memory MCP | |
Setup |
| Manual server + API key |
Trigger | 5 automatic hooks (no commands) | You call a |
Storage | 100% local SQLite | Cloud / external service |
API cost | $0 — local embeddings | Per-token / subscription |
Latency | < 5ms (on-device) | Network round-trip |
Privacy | Never leaves your machine | Sent to a provider |
Search | FTS5 + local semantic, KO/EN/JA cross-lingual | Varies |
If you want zero-config, offline, no-cost memory that just happens while you work — this is it.
There's also a great class of local search tools (e.g. ctx) that index your agent history so you can query it (search "failed migration"). That's complementary, not the same job:
passbaton | Local-search tools (ctx, etc.) | |
How you use it | Automatic — context appears on session start, no command | You (or the agent) run a search query |
Compaction | PreCompact hook re-injects a handover → 0 context re-explained after a compact | Not its job (it's a search index) |
Best at | Never losing your thread across sessions & compacts, hands-off | Finding a specific past decision/command on demand |
Coverage | Claude Code + Codex CLI + Gemini CLI (where auto-injection is possible) | Often 30+ agents indexed for search |
Use search when you want to look something up. Use this when you want your context to follow you without asking.
Beyond Claude Code, this also supports OpenAI Codex CLI. If ~/.codex exists,
the installer registers the same hooks in ~/.codex/hooks.json (SessionStart,
UserPromptSubmit, PreCompact, Stop), and the hooks auto-detect the host and emit
the right output format (Codex's hookSpecificOutput.additionalContext).
The same local sessions.db is shared, so context carries across both agents:
what you did in Codex is available in Claude Code and vice versa.
Scope: session save + context injection work on both. Codex file-change
tracking (PostToolUse) isn't wired yet — session save already covers most of it
via transcript parsing. Codex's transcript_path is treated as an unstable
interface (it can be null at startup), so host detection uses an installer-injected
--codex marker rather than relying on the path.
Also supports Google Gemini CLI. If ~/.gemini exists, the installer registers
the hooks in ~/.gemini/settings.json (SessionStart, BeforeAgent, PreCompress,
SessionEnd — Gemini's event names), preserving your other settings. Same shared
local sessions.db, so context carries across all three agents.
Gemini's transcript format was verified against real ~/.gemini/tmp/.../chats/*.jsonl
files — it uses two shapes (a flat {type, content} line and an older
{"$set":{"messages":[…]}} diff line); the parser handles both. Like Codex,
transcript_path can be null at startup, so host detection uses a --gemini marker.
Honest scope note: session save (SessionEnd) and context output are verified working.
Gemini's SessionStart context injection is documented as advisory-only upstream
(gemini-cli#15413) — if your
Gemini build doesn't render the injected context on startup, that's an upstream limit,
not this tool. Session continuity still works via the saved history.
If you installed this as claude-session-continuity-mcp (v1.x), nothing breaks — the v1 claude-hook-* commands still ship as aliases in v2.
To move to the new name:
npm install -g passbaton # installs the new package
npm uninstall -g claude-session-continuity-mcp # optional: drop the old oneThe installer rewrites your hook entries to passbaton-hook-* and removes the old claude-hook-* lines — it matches on both names, so you won't end up with duplicates. Your existing sessions.db is untouched: all past sessions, memories, and solutions carry over.
Nothing else changes — same hooks, same database, same behavior.
Requires Node.js 22+. The native
better-sqlite3dependency only ships prebuilt binaries for Node 22, 24, and 26 (the currently supported lines — Node 18 and 20 are both end-of-life). On older Node it falls back to compiling from source, which fails without build tools. Node 22 and up install cleanly with no compiler needed.
npm install -g passbatonThat's it! The postinstall script automatically:
Registers MCP server in ~/.claude.json
Installs Claude Hooks in ~/.claude/settings.json
-g)?This tool is designed to track all your Claude Code projects in a single unified database. Global installation is strongly recommended because:
Reason | Detail |
Single source of truth | One binary serves every project — no version drift between projects |
Hooks are user-scoped |
|
Cross-project context | Sessions from |
One update = everything refreshed |
|
| Hooks call |
Important: Even with global install, you can still disable the hook for specific projects (see below). Global ≠ forced on every project.
Global install does not mean "always on everywhere". You have three layers of control:
Layer | File | Scope |
1. Global ON (default) |
| All projects |
2. Project-wide OFF |
| Whole team (committed) |
3. Personal-only OFF |
| Just you (gitignored) |
To disable hooks in a specific project, create the override file with empty hook arrays:
// <project>/.claude/settings.json (or settings.local.json for personal-only)
{
"hooks": {
"SessionStart": [],
"UserPromptSubmit": [],
"PostToolUse": [],
"PreCompact": [],
"Stop": []
}
}Empty arrays override the global setting → that project's sessions are no longer tracked.
npm install -g passbaton@latestThat's the only step — all projects pick up the new binary on next Claude Code restart. No need to reinstall in each project.
If you really want per-project install (e.g., locked version for one project):
cd <project> && npm install passbatonDrawback: you must install separately in every project, and npm exec may not find the local copy reliably from hook context (cwd-dependent). Stick with -g unless you have a specific reason.
MCP Server (in ~/.claude.json):
{
"mcpServers": {
"project-manager": {
"command": "npx",
"args": ["passbaton"]
}
}
}Claude Hooks (in ~/.claude/settings.json):
{
"hooks": {
"SessionStart": [{ "hooks": [{ "type": "command", "command": "npm exec -- passbaton-hook-session-start" }] }],
"UserPromptSubmit": [{ "hooks": [{ "type": "command", "command": "npm exec -- passbaton-hook-user-prompt" }] }],
"PostToolUse": [{ "matcher": "Edit", "hooks": [{ "type": "command", "command": "npm exec -- passbaton-hook-post-tool" }] }, { "matcher": "Write", "hooks": [{ "type": "command", "command": "npm exec -- passbaton-hook-post-tool" }] }],
"PreCompact": [{ "hooks": [{ "type": "command", "command": "npm exec -- passbaton-hook-pre-compact" }] }],
"Stop": [{ "hooks": [{ "type": "command", "command": "npm exec -- passbaton-hook-session-end" }] }]
}
}Note (v1.5.0+): Full lifecycle coverage with 5 hooks. Uses npm exec -- which finds local node_modules/.bin first.
Hook | Command | Function |
|
| Auto-loads project context on session start |
|
| Auto-injects relevant memories + past reference search |
|
| Tracks active files (Edit, Write) + auto-injects error solutions (Bash) |
|
| Structured handover context before compression |
|
| Extracts commits, decisions, error-fix pairs from transcript |
# Check hook status
npx passbaton-hooks status
# Reinstall hooks
npx passbaton-hooks install
# Remove hooks
npx passbaton-hooks uninstallAfter installation, restart Claude Code to activate the hooks.
Feature | Description |
🤖 Zero Manual Work | Claude Hooks automate all context capture/load |
🎯 Quality Memory Only | (v1.10.0) Only decisions, learnings, errors — no file-change noise |
🧠 Semantic Search | multilingual-e5-small embedding (94+ languages, 384d) |
🌍 Multilingual | Korean/English/Japanese + cross-language search (EN→KR, KR→EN) |
🔗 Git Integration | Commit messages auto-extracted from transcripts |
🕸️ Knowledge Graph | Memory relations (solves, causes, extends...) |
📊 Memory Classification | 5 types: observation, decision, learning, error, pattern |
✅ Integrated Verification | One-click build/test/lint execution |
📋 Task Management | Priority-based task management |
🔧 Auto Error→Solution | (v1.12.0) Bash errors auto-detect → inject past solutions; session-end auto-records error-fix pairs |
💰 Token Efficiency | (v1.11.0) Removed loadContext from UserPromptSubmit (saves 24-60K tokens/session) |
📑 Progressive Disclosure | (v1.11.0) memory_search returns index first, memory_get for full content |
⏳ Temporal Decay | (v1.11.0) Memory scoring with type-specific half-lives for relevance |
📝 Structured Handover | (v1.10.0) PreCompact saves work summary, active files, pending actions |
🚪 Smart Session End | (v1.10.0) Extracts commits, decisions, error-fix pairs from transcript |
🗑️ Auto Noise Cleanup | (v1.10.0) Auto-deletes stale observation memories (3d+) |
🔍 Past Reference Detection | (v1.8.0) "저번에 X 어떻게 했어?" auto-searches DB |
📝 User Directive Extraction | (v1.8.0) Auto-extracts "always/never" rules from prompts |
(v2.1.0+) Five behaviours are individually toggleable; the rest are shown for
transparency but are always on (a hook's mere existence is controlled by your
settings.json, not by config) or not yet wired. Config lives in a plain,
hand-editable JSON file (~/.claude/passbaton.config.json) — separate from your data,
so it survives a db reset. No file = today's defaults (nothing changes for existing users).
passbaton config # grouped table; ●/○ = toggleable, · = always on
passbaton config set solutionCapture off # flip a toggleable feature
passbaton config set strictSolutionGate on # opt into the strict error→fix filter
passbaton config preset minimal # minimal | default | everything
passbaton config reset # back to defaults
passbaton config path # print the active config file pathTrying to set an always-on / not-yet-wired feature is rejected with a clear message.
Each toggleable feature also has an env override for one-off/CI use:
PASSBATON_<FEATURE>=0 (e.g. PASSBATON_SOLUTIONCAPTURE=0) wins over the config file.
On-by-default rule: a feature ships on only if it's silent, safe, and universally useful. Anything that speaks unprompted, guesses, or writes speculative rows ships off.
Legend: ●/○ = toggleable (on/off) · · = always on, not a config toggle · ⋯ = not yet wired.
Feature | Key | Toggle | What it does |
Session start injection |
| · always on | Restore prior context on start |
Compaction handover+ |
| ● toggleable | Before a compaction, carry over your working state plus hot files and last build status — the one gap platform auto-memory structurally can't cover |
Session persist |
| · always on | Save session state on exit |
Auto memory surfacing |
| · always on | Auto-surface relevant past memories on start |
Task tracking |
| · always on | Read/write the task list via MCP + hooks |
Hot-path pre-warm |
| ● toggleable | On start, surface the files you edit most in this project, ranked by real access count |
Verification ledger |
| ● toggleable | Warn on start if a recent session left the build red or issues open |
sessionStart/sessionEndare "always on" because a hook either runs or it doesn't — that's controlled by the hook registration in~/.claude/settings.json, not by config. To disable them, remove the hook there.
Feature | Key | Toggle | What it does |
Cross-agent share |
| · inherent | One local db shared across Claude Code / Codex / Gemini (not a toggle — it's how storage works) |
Tool-use capture |
| · always on | Observe tool use to build hot-paths (low-noise) |
Solution capture |
| ● toggleable | Auto-record error→fix pairs to a solution archive. Set off to skip it entirely (session save is unaffected) |
Feature | Key | Toggle | What it does |
Strict solution gate |
| ○ opt-in | Stricter error→fix capture filter — fewer noise entries, but may drop some real ones |
Trigger matching |
| ⋯ not yet wired | (planned) Match prompt keywords to auto-inject solutions |
Pattern mining |
| ⋯ not yet wired | (planned) Mine work patterns and suggest workflows |
Memory auto-store |
| ⋯ not yet wired | (planned) Auto-write observation memories from prompts |
Status line |
| ⋯ not yet wired | (planned) Append a passbaton status line to session-start output |
The only genuinely user-flippable flags today are compactionHandover, hotPathPrewarm,
verificationLedger, solutionCapture (on) and strictSolutionGate (opt-in).
SessionStart Hook (npx passbaton-hook-session-start):
Auto-detects project: monorepo (apps/project-name/) or single project (package.json root folder name)
Loads context from .claude/sessions.db
Injects: Current state, 3 recent sessions with commits/decisions, directives, pending tasks, filtered key memories
Auto-cleans stale noise memories (3d+ auto-tracked, 14d+ auto-compact)
UserPromptSubmit Hook (npx passbaton-hook-user-prompt):
Runs on every prompt submission
(v1.11.0) No longer calls loadContext() — saves 24-60K tokens/session
Injects relevant context (filtered: decisions, learnings, errors only)
PostToolUse Hook (npx passbaton-hook-post-tool):
Tracks hot file paths and updates active_context.recent_files
(v1.12.0) Auto-detects Bash errors → searches solutions DB → injects past solutions into context
No longer creates observation memories (v1.10.0 — eliminates [File Change] noise)
PreCompact Hook (npx passbaton-hook-pre-compact):
Builds structured handover context: work summary, active file, pending action, key facts, recent errors
No longer stores auto-compact memories (v1.10.0)
Stop Hook (npx passbaton-hook-session-end):
Extracts commit messages from JSONL transcript (git commit -m patterns)
Extracts error-fix pairs (error → resolution within 3 messages)
(v1.12.0) Auto-records error→fix pairs to solutions table for future reuse
Extracts decisions ("because", "instead of", "chose" patterns)
(v1.11.0) Single-pass transcript parsing (4 JSONL reads → 1)
Stores structured metadata in sessions.issues column as JSON
# my-app - Session Resumed
📍 **State**: Implementing signup form
🚧 **Blocker**: OAuth callback URL issue
## Recent Sessions
### 2026-02-28
**Work**: Completed OAuth integration
**Commits**: feat: add OAuth handler; fix: redirect config
**Decisions**: Use Server Actions over API routes
**Next**: Implement form validation
## Directives
- 🔴 Always use Zod for validation
## Pending Tasks
- 🔄 [P8] Implement form validation
- ⏳ [P5] Add error handling
## Key Memories
- 🎯 Decided on App Router, using Server Actions
- ⚠️ OAuth redirect_uri mismatch → check env file# Check status
npx passbaton-hooks status
# Reinstall
npx passbaton-hooks install
# Remove
npx passbaton-hooks uninstall
# Temporarily disable
export MCP_HOOKS_DISABLED=trueWhen you ask about past work, the UserPromptSubmit hook automatically searches the database:
You: "저번에 인앱결제 어떻게 했어?"
→ Hook detects "저번에" + extracts keyword "인앱결제"
→ Searches sessions, memories (FTS5), and solutions
→ Injects matching results into context automaticallySupported patterns (Korean & English):
Pattern | Example |
저번에/전에/이전에 ... 어떻게 | "저번에 CORS 에러 어떻게 해결했지?" |
~했던/만들었던/해결했던 | "수정했던 로그인 로직" |
지난 세션/작업에서 | "지난 세션에서 결제 구현" |
last time/before/previously | "How did we handle auth last time?" |
did we/did I ... before | "Did we fix the database migration before?" |
remember when/recall when | "Remember when we set up CI?" |
Output example:
## Related Past Work (auto-detected from your question)
### Sessions
- [2/14] 카카오 로그인 앱키 수정, 인앱결제 IAP 플로우 수정
### Memories
- 🎯 [decision] 테스트: 인앱결제 상품 등록 완료
### Solutions
- **IAP_BILLING_ERROR**: StoreKit 2 migration으로 해결Previous versions used absolute paths or npx:
// v1.3.x - absolute paths (broke on multi-project)
"command": "node \"/path/to/project-a/node_modules/.../session-start.js\""
// v1.4.0-1.4.2 - npx (required global install or hit npm registry)
"command": "npx passbaton-hook-session-start"Now we use npm exec --:
"command": "npm exec -- passbaton-hook-session-start"npm exec -- finds local node_modules/.bin first, then falls back to global. Works with both local and global installation without hitting npm registry.
// Start of session - auto-loads context
session_start({ project: "my-app", compact: true })
// End of session - auto-saves context
session_end({
project: "my-app",
summary: "Completed auth flow",
modifiedFiles: ["src/auth.ts", "src/login/page.tsx"]
})
// View session history
session_history({ project: "my-app", limit: 5 })
// Semantic search past sessions
search_sessions({ query: "auth work", project: "my-app" })// Get project status with task stats
project_status({ project: "my-app" })
// Initialize new project
project_init({ project: "my-app" })
// Analyze project tech stack
project_analyze({ project: "my-app" })
// List all projects
list_projects()// Add a task
task_add({ project: "my-app", title: "Implement signup", priority: 8 })
// Update task status
task_update({ taskId: 1, status: "done" })
// List tasks
task_list({ project: "my-app", status: "pending" })
// Suggest tasks from TODO comments
task_suggest({ project: "my-app" })// Record an error solution
solution_record({
errorSignature: "TypeError: Cannot read property 'id'",
solution: "Use optional chaining: user?.id"
})
// Find similar solutions (keyword or semantic)
solution_find({ query: "TypeError property", semantic: true })
// AI-powered solution suggestion
solution_suggest({ errorMessage: "Cannot read property 'email'" })// Run build
verify_build({ project: "my-app" })
// Run tests
verify_test({ project: "my-app" })
// Run all (build + test + lint)
verify_all({ project: "my-app" })// Store a classified memory
memory_store({
content: "State management with Riverpod makes testing easier",
type: "learning", // observation, decision, learning, error, pattern
project: "my-app",
tags: ["flutter", "state-management"],
importance: 8,
relatedTo: 23 // Connect to existing memory
})
// Search memories — returns index (id, type, tags, score) for token efficiency
memory_search({
query: "state management test",
type: "learning",
semantic: true, // Use embedding similarity
limit: 10
})
// Get full memory content by ID (v1.11.0)
memory_get({ memoryId: 23 })
// Find related memories (graph + semantic)
memory_related({
memoryId: 23,
includeGraph: true,
includeSemantic: true
})
// Get memory statistics
memory_stats({ project: "my-app" })// Connect two memories with a typed relation
graph_connect({
sourceId: 23,
targetId: 25,
relation: "solves", // related_to, causes, solves, depends_on, contradicts, extends, example_of
strength: 0.9
})
// Explore knowledge graph
graph_explore({
memoryId: 23,
depth: 2,
relation: "all", // or specific relation type
direction: "both" // outgoing, incoming, both
})Type | Description | Use Case |
| Patterns, structures found in codebase | "All screens are separated in features/ folder" |
| Architecture, library choices | "Decided to use SharedPreferences for caching" |
| New knowledge, best practices | "Riverpod is better for testing" |
| Occurred errors and solutions | "Provider.read() doesn't rebuild → use watch()" |
| Recurring code patterns, conventions | "Avoid late keyword abuse" |
Relation | Description | Example |
| General relation | A and B are related |
| A causes B | Caching decision → folder structure change |
| A solves B | Riverpod learning → Provider bug fix |
| A depends on B | Folder structure → Caching decision |
| A conflicts with B | Two design decisions conflict |
| A extends B | late pattern → Extended to Riverpod learning |
| A is example of B | Specific code is example of pattern |
SQLite database at ~/.claude/sessions.db:
Table | Purpose |
| Classified memories (observation, decision, learning, error, pattern) |
| Full-text search index (FTS5) |
| Knowledge graph relations |
| Semantic search vectors (multilingual-e5-small, 384d) |
| Fixed project info (tech stack, decisions) |
| Current work state |
| Task backlog |
| Error solution archive |
| Session history |
Variable | Default | Description |
| - | Workspace root path (required) |
|
| Disable Claude Hooks |
|
| Log level (debug/info/warn/error) |
| - | Optional file logging path |
# Clone
git clone https://github.com/leesgit/passbaton.git
cd passbaton
# Install
npm install
# Build
npm run build
# Test
npm test
# Test with coverage
npm run test:coverageMetric | Value |
Context load (cached) | <5ms |
Memory search (FTS) | ~10ms |
Semantic search | ~50ms |
Build verification | Project-dependent |
v2 API (15 focused tools)
v4 API (24 tools - memory + graph)
v5 Claude Hooks (auto-capture)
Knowledge Graph with typed relations
Memory classification (6 types)
Semantic search (embeddings)
Multilingual pattern detection (KO/EN/JA)
Git commit integration
111 tests (6 test suites)
GitHub Actions CI/CD
Multilingual semantic search (v1.6.0 - multilingual-e5-small)
Cross-language search EN↔KR (v1.6.0)
Solution semantic search (v1.6.0)
Fix hooks settings file path (v1.6.1 - settings.json, not settings.local.json)
Auto-migrate legacy hooks (v1.6.1)
Fix PostToolUse matcher format to string (v1.6.3)
Fix README documentation for new hook format (v1.6.4)
Empty session skip and techStack save improvements (v1.7.1)
Past reference auto-detection in UserPromptSubmit hook (v1.8.0)
User directive extraction ("always/never" rules) (v1.8.0)
Memory quality overhaul — no more [File Change] noise (v1.10.0)
Structured handover context in PreCompact (v1.10.0)
Smart session-end: commit/decision/error-fix extraction from transcript (v1.10.0)
Auto noise cleanup (3d+ observations, 14d+ auto-compact) (v1.10.0)
3 recent sessions display with structured metadata (v1.10.0)
Token efficiency — remove loadContext from UserPromptSubmit, saves 24-60K tokens/session (v1.11.0)
Single-pass transcript parsing, 4 JSONL reads → 1 (v1.11.0)
Temporal decay for memory scoring with type-specific half-lives (v1.11.0)
Progressive disclosure — memory_search returns index, memory_get for full content (v1.11.0)
Memory consolidation via Jaccard similarity (v1.11.0)
Auto error→solution pipeline — PostToolUse detects Bash errors, injects past solutions (v1.12.0)
SessionEnd auto-records error-fix pairs to solutions table (v1.12.0)
Cross-project solution search with current project prioritization (v1.12.0)
sqlite-vec native vector search (v2 - when data > 1000 records)
Web dashboard
Cloud sync option
PRs welcome! Please:
Fork the repo
Create a feature branch
Add tests for new features
Ensure npm test passes
Submit PR
MIT © Byeongchang Lee
Model Context Protocol by Anthropic
Xenova Transformers for embeddings
If this saves you from re-explaining your project, consider giving it a ⭐ — it genuinely helps others find it.
Create a directed edge between two memories in the knowledge graph. Supports 7 relation types for structured knowledge organization. Side effects: inserts or replaces a row in memory_relations (upsert on sourceId+targetId+relation). Use memory_related to discover existing connections; use graph_explore to traverse the graph from a starting node.
| Name | Required | Description | Default |
|---|---|---|---|
| sourceId | Yes | Source memory ID (the "from" node) | |
| targetId | Yes | Target memory ID (the "to" node) | |
| relation | Yes | Edge type: related_to (general association), causes (A causes B), solves (A fixes B), depends_on (A requires B), contradicts (A conflicts with B), extends (A builds on B), example_of (A demonstrates B) | |
| strength | No | Connection strength 0.0-1.0 (default: 1.0). Lower values indicate weaker associations. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses the upsert behavior (inserts or replaces) which is important for understanding side effects. With no annotations, this is valuable. Lacks details on return value or error conditions, but overall adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four concise sentences without waste. Each sentence adds value: purpose, relation types, side effects, usage guidance. Front-loaded with the core action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers purpose, side effects, and usage alternatives. Lacks return value details and error handling, but for a simple create tool, it is mostly complete given no output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with detailed parameter descriptions. The description only mentions there are 7 relation types without adding new semantics beyond the schema, so it does not significantly enhance parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool creates a directed edge between two memories in the knowledge graph, with 7 relation types. It distinguishes from siblings by referencing memory_related for discovery and graph_explore for traversal.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly advises when to use alternative tools: memory_related to discover connections and graph_explore to traverse. Also notes the side effect (upsert), guiding appropriate usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Traverse the knowledge graph from a starting memory using depth-first search. Returns all connected memories up to the specified depth, with their relation types, strengths, and directions. Read-only. Supports filtering by relation type and traversal direction. Use memory_related instead for a combined graph+semantic approach; use graph_connect to add new edges.
| Name | Required | Description | Default |
|---|---|---|---|
| memoryId | Yes | Starting memory ID for graph traversal | |
| depth | No | Maximum traversal depth 1-4 (default: 2). Higher values return more results but may be slower. | |
| relation | No | Filter by relation type (default: "all") | |
| direction | No | Traversal direction — outgoing (A→B), incoming (B→A), or both (default: "both") |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description declares read-only access, depth limit (1-4), and performance trade-off for higher depths. No annotations exist, so description carries the burden; it does well but could add more about time complexity or result size.
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 no wasted words. All key information is front-loaded: purpose, behavior, alternatives.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description explains return value (connected memories with relation types, strengths, directions). It also covers filtering capabilities and read-only nature. Sufficient for most use cases, though could mention pagination if results are large.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has 100% description coverage, so baseline is 3. The description adds a performance note for depth, but overall the schema already explains each parameter adequately.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool traverses the knowledge graph via depth-first search, returning connected memories with relation details. It distinguishes from siblings by naming 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?
Explicitly tells when to use this tool (graph exploration) and when to use alternatives (memory_related for combined approach, graph_connect for adding edges). Also notes it is read-only.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all projects under the apps/ directory with their platform type (Web/Android/Flutter), initialization status, and whether session context exists. Read-only. Returns an array of project summary objects. No parameters required.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description declares it is read-only and returns an array of project summary objects. It does not detail the exact output fields or potential errors, but for a simple list tool it is fairly transparent.
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—three sentences covering purpose, return type, and parameters. No redundant or unnecessary text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no parameters and no output schema, the description is reasonably complete. It specifies what is listed, that it's read-only, and that it returns an array of summary objects. Missing detail on exact output fields, but overall 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?
There are no parameters, and schema coverage is 100% (empty). According to the rubric, 0 params gives a baseline of 4. The description adds no additional parameter info 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 it lists all projects under apps/ with specific fields (platform type, initialization status, session context). It is a specific verb+resource and distinguishes from siblings like project_init or project_analyze.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description says 'List all projects' but provides no guidance on when to use this tool vs alternatives like project_status or other listing tools. No comparisons 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.
Retrieve full content for one or more memories by ID. Designed as a follow-up to memory_search: first search to find relevant IDs, then use memory_get to load full details. Read-only. Accepts up to 20 IDs per call. Returns an array of complete memory objects including content, type, tags, importance, timestamps, and access count.
| Name | Required | Description | Default |
|---|---|---|---|
| ids | Yes | Array of memory IDs to retrieve (max 20) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite no annotations, description fully discloses behavior: read-only operation, response structure (array of memory objects with fields), and lack of 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?
Two concise sentences front-loading purpose and usage. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Without output schema, description fully covers return format (fields included) and constraints (max 20 IDs). Complete for a retrieval tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. Description adds context by explaining the retrieval workflow but does not add new parameter-level details beyond what the schema already 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?
Description explicitly states verb+resource: 'Retrieve full content for one or more memories by ID.' It distinguishes from sibling tool memory_search by framing as a follow-up step.
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?
Clear usage flow: 'first search to find relevant IDs, then use memory_get to load full details.' Also specifies read-only and batch limit of 20 IDs per call.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search stored memories using FTS5 full-text search or semantic/embedding similarity. Default mode returns compact index entries (id, type, truncated content) to save tokens — set detail=true for full content. Supports filtering by type, project, tags, and minimum importance. Read-only. Use memory_get to fetch full content for specific IDs found in search results. Use memory_related to explore graph connections from a known memory.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Natural language search query | |
| type | No | Filter by memory type (default: "all") | |
| project | No | Filter by project (optional) | |
| tags | No | Filter by tags — matches if any tag is present (optional) | |
| semantic | No | Use embedding-based semantic search instead of keyword FTS5 (default: false) | |
| minImportance | No | Minimum importance threshold 1-10 (default: 1) | |
| limit | No | Max results to return (default: 10) | |
| detail | No | Return full content per memory (default: false — returns compact index only) |
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 is read-only, explains the default compact output vs. detailed mode, and describes the truncation of content. It does not mention response format fields but covers essential behaviors.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences. It front-loads the main purpose, then details default behavior and filtering, ending with sibling guidance. It is efficient and clear, though the second sentence could be slightly more structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 8 parameters (all documented in schema) and no output schema, the description adequately covers the purpose and usage. However, it does not specify the full output structure beyond 'id, type, truncated content', leaving some return fields unmentioned.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, so the baseline is 3. The description adds minimal new semantics beyond the schema, mostly listing filter options already present. It echoes schema descriptions for 'semantic' and 'detail' but does not introduce new meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly specifies the verb 'search' and the resource 'stored memories', distinguishing it from siblings like memory_get and memory_related. It mentions both FTS5 keyword search and semantic embedding similarity.
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 explicitly states when to use alternative tools: 'Use memory_get to fetch full content for specific IDs found in search results. Use memory_related to explore graph connections from a known memory.' It also clarifies the read-only nature.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get aggregate statistics about the memory system: total count, breakdown by type (observation/decision/learning/error/pattern), breakdown by project, top 5 most accessed memories, and 5 most recent entries. Read-only. Useful for understanding memory distribution and system health. Optionally scope to a single project.
| Name | Required | Description | Default |
|---|---|---|---|
| project | No | Scope statistics to a single project (optional — omit for global stats) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explicitly notes 'Read-only,' which is a key behavioral trait. However, with no annotations provided, the description carries the full burden. It does not disclose other potential traits like idempotency, authentication needs, or performance characteristics, leaving some 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 extremely concise, containing only three sentences, each adding essential information. The key action and outputs are front-loaded, and there is no unnecessary verbosity.
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?
Despite lacking an output schema, the description enumerates the return values (count, breakdowns, top accessed, recent entries), providing sufficient context for an agent to understand what to expect. However, it omits error scenarios or data size limits, which would be beneficial for robust 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?
There is only one parameter, 'project', with a schema description explaining its role. The tool description adds a brief note ('Optionally scope to a single project') but does not significantly enhance understanding beyond the schema. With 100% schema coverage, a baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get aggregate statistics about the memory system' and lists specific breakdowns (count, type, project, top accessed, recent entries). This distinguishes it from sibling tools like memory_get, memory_search, and memory_store, which focus on individual memories or queries.
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 includes 'Useful for understanding memory distribution and system health' and 'Optionally scope to a single project,' which imply appropriate contexts. It does not explicitly state when not to use or mention alternatives, but the purpose is clear enough to guide selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Store a piece of knowledge in the memory system. Memories are typed (observation, decision, learning, error, pattern), tagged, and automatically embedded for semantic retrieval. Side effects: inserts into the memories table and asynchronously generates a vector embedding. If relatedTo is provided, also creates a knowledge graph edge. Returns the new memory ID. Use memory_search to verify no duplicate exists before storing.
| Name | Required | Description | Default |
|---|---|---|---|
| content | Yes | The knowledge content to store | |
| type | Yes | Memory type: observation (discovery/finding), decision (architecture/tech choice), learning (new knowledge), error (error encountered), pattern (code convention) | |
| project | No | Associated project name (optional — omit for cross-project knowledge) | |
| tags | No | Tags for filtering (e.g. ["auth", "performance"]) | |
| importance | No | Importance score 1-10 where 10 is critical (default: 5) | |
| relatedTo | No | ID of an existing memory to link via knowledge graph (optional) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description fully discloses side effects: inserts into table, async embedding, optional graph edge, and return value. Could mention timing of async operation, but current detail is strong.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with purpose, followed by side effects and usage guidance. Every sentence is valuable and succinct.
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 6 parameters and no output schema, the description covers all essential aspects: side effects, return value, duplicate checking advice. Complete for an AI agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions, so baseline is 3. Description adds context by explaining that memories are typed/tagged and that relatedTo creates a knowledge graph edge, going beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it stores knowledge in the memory system, lists memory types, and differentiates from sibling memory_search by advising to verify duplicates. It specifies verb and resource with distinct 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?
Explicitly advises using memory_search to verify no duplicate before storing, providing when-not-to-use guidance and an alternative tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Auto-detect a project's tech stack, framework, platform (Web/Android/Flutter/Server), directory structure, and dependency count by scanning its files. Read-only — does not persist results. Returns a structured analysis object. Use project_init to persist the detected configuration.
| Name | Required | Description | Default |
|---|---|---|---|
| project | Yes | Project name (must match a directory under apps/) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. States 'Read-only — does not persist results', clearly disclosing non-mutating behavior. Mentions returned analysis object, but lacks detail on permissions or cost.
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, no fluff, front-loaded with key purpose. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, but description lists output components (tech stack, etc.). Lacks details on async behavior, time cost, or whether scanning is heavy. Adequate but not fully complete given 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?
Single parameter 'project' with schema description (project name under apps/). Schema coverage 100%, so description adds no extra meaning beyond schema. Baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it auto-detects tech stack, framework, platform, directory structure, and dependency count. Verb 'detect' and resource 'project' are specific. Distinguishes from sibling project_init by noting persistence difference.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly tells user to use project_init for persistence, implying this tool is for inspection. Could be more explicit about when to use vs other siblings, but clear alternative provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Initialize a new project in the continuity system. Creates records in the project_context and active_context tables. Auto-detects tech stack from package.json/pubspec.yaml/build.gradle if present. Side effects: writes to SQLite. Idempotent — safe to call on an already-initialized project (updates existing record). Call this once when adding a new project, then use session_start for subsequent sessions.
| Name | Required | Description | Default |
|---|---|---|---|
| project | Yes | Project name (must match a directory under apps/) | |
| techStack | No | Tech stack override {framework, language, database, ...}. Omit for auto-detection. | |
| description | No | Human-readable project description |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses side effects (writes to SQLite), idempotency, and auto-detection behavior. Lacks details on error conditions or permissions, but adequate given 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?
Concise, front-loaded with main action, then key details. No redundant sentences.
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?
Covers purpose, usage, side effects, and idempotency. Lacks output schema but no output expected; sufficient for 3-param 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 coverage is 100%, baseline 3. Description adds context: project must match a directory under apps/ and techStack is an override. Adds value beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool initializes a new project, creates records in specific tables, and auto-detects tech stack. It distinguishes from siblings like session_start and project_status.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says to call once for new project, then use session_start for subsequent sessions. Also notes idempotency, guiding safe reuse.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a project's current status including completion percentage, task breakdown (pending/in-progress/done/blocked), recent session activity, and active blockers. Read-only. Returns a structured JSON object. Use session_start instead when bootstrapping a new conversation; use this for mid-session status checks.
| Name | Required | Description | Default |
|---|---|---|---|
| project | Yes | Project name (must match a directory under apps/) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It declares 'Read-only' and notes the return format, but omits other behavioral details like authentication, error cases, or rate limits. Decent but could add more 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 concise with three short sentences covering purpose, read-only nature, return format, and usage guidance. No fluff, every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description adequately explains the return value by listing included fields. It covers essential context for a simple status-check tool, though it could mention behavior for invalid projects or error handling.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage for the single parameter 'project' is 100%, so baseline is 3. The description does not add meaning beyond what the schema already provides (the schema already states 'must match a directory under apps/'). No extra value added.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool gets a project's current status and lists specific data returned (completion percentage, task breakdown, session activity, blockers). It explicitly distinguishes from session_start, making its purpose distinct among 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 gives explicit guidance on when to use (mid-session status checks) and when not (use session_start for bootstrapping). This directly helps the agent select the correct tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Semantic search across session history using multilingual embeddings (94+ languages). Finds past sessions by meaning, not just keywords — e.g. "when I worked on authentication" matches sessions about login, OAuth, JWT. Falls back to FTS5 keyword search when embeddings are unavailable. Read-only. Use session_history instead when you just need the N most recent sessions.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Natural language search query | |
| project | No | Filter by project (optional) | |
| limit | No | Max results to return (default: 5) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description declares the tool is 'Read-only' and explains the fallback behavior, adding value beyond the schema. No annotations are provided, so the description carries the full burden. It could be improved by mentioning any rate limits or authentication needs, but for a search tool this is adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with three sentences: defining the tool, giving an example, and providing fallback and alternative. No wasted words, front-loaded with purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite lacking an output schema, the description is complete for a search tool: it explains the semantic approach, multilingual support, fallback, and sibling tool. It covers what an agent needs to decide when to invoke this tool vs. alternatives.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents all parameters. The description reinforces the meaning of 'query' as natural language, 'project' as optional filter, and 'limit' defaulting to 5. It does not add new meaning beyond what the schema provides, hence a baseline score of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it performs 'Semantic search across session history' using multilingual embeddings, provides a concrete example, and distinguishes itself from the sibling tool 'session_history' by noting the latter is for recent sessions. The verb 'search' and resource 'sessions' are explicit.
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 explicitly tells when to use this tool vs. the alternative: 'Use session_history instead when you just need the N most recent sessions.' It also notes the fallback to FTS5 when embeddings are unavailable, giving clear guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Save the current session state before ending a conversation. Persists a summary, completed work, next steps, modified files, and blockers to SQLite. The saved state is automatically restored by session_start in the next session. Side effects: writes to the sessions table and updates the active_context record for the project. Idempotent — calling multiple times overwrites the previous session record.
| Name | Required | Description | Default |
|---|---|---|---|
| project | Yes | Project name (must match a directory under apps/) | |
| summary | Yes | One-line summary of this session | |
| workDone | No | Description of completed work | |
| nextSteps | No | Ordered list of next tasks to pick up | |
| modifiedFiles | No | Files modified during this session | |
| blockers | No | Current blockers or issues (null if none) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden and discloses side effects (writes to sessions table and updates active_context) and states idempotency. This provides meaningful behavioral transparency about persistence and overwrite 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 three sentences with no wasted words. It front-loads the core purpose, then explains restoration, and finally lists side effects and idempotency. Every sentence serves a 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?
The description covers what the tool does, its relationship to session_start, side effects, and idempotency. It does not explain return values (likely none) or error conditions, but these are not essential given the tool's simplicity and no output schema.
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?
All 6 parameters have descriptions in the input schema (100% coverage). The description adds context by listing the fields as being persisted, but does not add meaning beyond what the schema already provides, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it saves session state and lists specific fields (summary, work done, etc.). It distinguishes the tool's purpose from session_start by noting restoration, but does not explicitly differentiate from sibling session tools like session_history or search_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?
The description mentions using it 'before ending a conversation' and notes automatic restoration by session_start, providing clear usage context. However, it lacks explicit guidance on when not to use it or alternatives (e.g., session_history for viewing past sessions).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve past session records for a project. Returns an array of session objects ordered by most recent first, each containing summary, work done, modified files, and verification results. Read-only. Use search_sessions instead when you need semantic/keyword matching rather than a chronological list.
| Name | Required | Description | Default |
|---|---|---|---|
| project | Yes | Project name (must match a directory under apps/) | |
| limit | No | Max records to return (default: 5) | |
| days | No | Only return sessions from the last N days (default: 7) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description declares the tool as 'Read-only' and describes the return structure. It does not cover error behavior or permissions, but for a simple retrieval tool this is adequate.
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 long, front-loaded with the core purpose, and contains no redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a straightforward list tool with three well-documented parameters, the description covers purpose, behavior, return content, and usage guidance. No output schema exists, but the description suffices.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already explains the parameters. The description does not add further meaning beyond the schema, making a typical baseline score of 3 appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves past session records for a project, ordered chronologically, and lists the included fields (summary, work done, etc.). It explicitly distinguishes itself from the sibling tool 'search_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?
The description provides explicit guidance on when to use this tool (chronological listing) versus the alternative 'search_sessions' (semantic/keyword matching). No other usage 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.
Load project context at the beginning of a session. Typically auto-invoked by the SessionStart hook, but can be called manually. Returns the project's tech stack, recent activity, pending tasks, and active blockers as a compressed context payload (~650 tokens). Read-only — does not modify any state. Use this instead of project_status when you need the full session bootstrap context.
| Name | Required | Description | Default |
|---|---|---|---|
| project | Yes | Project name (must match a directory under apps/) | |
| compact | No | Return compressed format (default: true). Set false for verbose output. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description fully covers behavior: read-only, returns compressed payload (~650 tokens) with specific fields (tech stack, recent activity, pending tasks, active blockers).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, efficient, but last sentence partially redundant with earlier 'use instead' advice. Still well-structured and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and few annotations, description provides sufficient context: purpose, usage, behavior, output summary, and sibling distinction.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and descriptions are clear. Description adds no extra parameter meaning 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?
Description clearly states the tool loads project context at session start. It distinguishes from sibling project_status by specifying when to use each.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly mentions typical auto-invocation but allows manual calls. Provides alternative tool (project_status) and advises when to use this instead.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search the solution archive for previously resolved errors. Matches against error signatures, messages, and keywords using FTS5. Set semantic=true to enable embedding-based similarity search for better recall across different error phrasings. Read-only. Returns matched solutions with their fix descriptions and related files. Use solution_suggest instead if you want AI-powered fix recommendations.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Error message, signature, or natural language description of the problem | |
| project | No | Filter by project (optional — also includes cross-project solutions) | |
| limit | No | Max results to return (default: 3) | |
| semantic | No | Enable semantic/embedding search for fuzzy matching (default: false) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Declares read-only nature and return content (fix descriptions, related files). Lacks details like pagination or auth, but sufficient for a search 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?
Three sentences, each earning its place: purpose, optional feature, alternative. Front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers core functionality, read-only flag, and alternative tool. Lacks pagination details but adequate for a 4-param tool with no output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Adds context beyond schema by explaining semantic parameter and default limit. All parameters described in 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?
Description clearly states it searches for resolved errors using FTS5 and semantic search, distinguishing from sibling solution_suggest.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says when to use (searching resolved errors) and when not (use solution_suggest for AI-powered recommendations), providing clear alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Record an error-solution pair in the solution archive. Associates an error signature (the searchable key), optional full error message, the fix, and related files. Automatically extracts keywords for FTS5 indexing. Side effects: inserts into the solutions table. Use solution_find to check for existing solutions before recording a duplicate.
| Name | Required | Description | Default |
|---|---|---|---|
| project | No | Project name (optional — omit for cross-project solutions) | |
| errorSignature | Yes | Error pattern/signature used as the search key (e.g. "ENOENT: no such file", "WorkManager not initialized") | |
| errorMessage | No | Full error message or stack trace (optional) | |
| solution | Yes | Step-by-step fix description | |
| relatedFiles | No | Files that were modified to fix the error |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries burden. Discloses side effects (inserts into solutions table) and automatic keyword extraction for FTS5 indexing. Missing details on idempotency, error handling, or limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Concise multi-sentence description with no fluff. Each sentence adds value: purpose, components, side effects, and usage guidance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers purpose, components, side effects, and duplicate prevention. Lacks return value info, but no output schema exists. Adequate for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 100% coverage, baseline 3. Description adds value by explaining errorSignature as 'search key', noting optional fields, and mentioning automatic keyword extraction.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Record an error-solution pair' and lists components. It distinguishes from sibling solution_find by mentioning duplicate checking.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly advises to use solution_find before recording to avoid duplicates, providing clear context. Lacks explicit when-not-to-use but sufficient given siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get AI-powered fix suggestions for a current error based on the solution archive. Retrieves the most relevant past solutions and generates a contextual recommendation. Read-only. Use solution_find for direct archive lookup without AI synthesis; use solution_record after fixing an error to grow the archive.
| Name | Required | Description | Default |
|---|---|---|---|
| errorMessage | Yes | The current error message or stack trace | |
| project | No | Project name for context (optional) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, but description explicitly states it is read-only, which is a key behavioral trait. It does not detail other aspects like auth or rate limits, but the read-only flag adds value beyond the structured fields.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, each serving a distinct purpose: main action, read-only note, and sibling alternatives. No wasted words, front-loaded with the core functionality.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the tool's purpose, usage context, and behavioral trait (read-only). It does not explicitly state the return format, but the output is implied as a recommendation. Given the tool's simplicity and sibling guidance, it is largely 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 input schema has 100% description coverage, and the description restates the same parameter meanings without adding significant new context. Baseline 3 is appropriate as the description does not deepen understanding beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool provides AI-powered fix suggestions for errors using the solution archive. It specifies the action (get suggestions) and the resource (current error, solution archive), and distinguishes from 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?
Explicitly states when to use this tool versus alternatives: use solution_find for direct archive lookup and solution_record after fixing an error. This provides clear context for agent decision-making.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add a new task to a project's backlog. Tasks are persisted in SQLite with priority ranking and optional file associations. Side effects: inserts into the tasks table. Returns the created task ID. Use task_list to view existing tasks before adding duplicates. Use task_suggest to auto-generate tasks from code comments (TODO/FIXME).
| Name | Required | Description | Default |
|---|---|---|---|
| project | Yes | Project name (must match a directory under apps/) | |
| title | Yes | Task title (concise, actionable) | |
| description | No | Detailed description (optional) | |
| priority | No | Priority 1-10 where 10 is highest (default: 5) | |
| relatedFiles | No | Associated file paths (optional) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Since no annotations are provided, the description carries full responsibility. It mentions side effects (inserts into tasks table) and return value (task ID), but does not disclose error conditions, required permissions, or default behavior beyond basic schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences long, front-loaded with purpose, followed by behavioral notes and usage alternatives. Every sentence adds value with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 5 parameters, no output schema, and no annotations, the description covers purpose, side effects, return value, and alternative tools. It is mostly complete, though missing specifics on failure modes or default priority handling.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds context about persistence in SQLite and optional file associations, but does not significantly enhance parameter understanding beyond what the schema already 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 clearly states 'Add a new task to a project's backlog', specifying the verb (add) and resource (task to backlog). It distinguishes from siblings like task_list (view) and task_suggest (auto-generate).
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 explicitly recommends using task_list to check for duplicates and task_suggest for auto-generating from code comments, providing clear guidance on when to use this tool vs alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List tasks for a project, filtered by status. Returns an array of task objects with id, title, description, status, priority, related files, and timestamps, plus a summary count by status. Read-only. Default filter is "pending" — pass status="all" to see everything.
| Name | Required | Description | Default |
|---|---|---|---|
| project | Yes | Project name (must match a directory under apps/) | |
| status | No | Status filter (default: "pending") |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses the read-only behavior and return structure (array of task objects with fields, plus summary count), providing thorough 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?
Two concise sentences, no wasted words, front-loaded with key purpose and return info.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read tool with complete schema and clear return description, the description sufficiently covers all necessary context for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. Description adds useful default value for status and return context but does not significantly enhance parameter meaning beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'List', resource 'tasks', and scope 'for a project, filtered by status', distinguishing it from sibling tools like task_add or task_update.
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 read-only nature and default filter, guiding when to use, but lacks explicit 'when not to use' or direct alternatives among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Scan project source files for TODO, FIXME, HACK, and XXX comments and return them as suggested tasks. Read-only — does not create tasks automatically. Review the suggestions and use task_add to persist the ones you want. Optionally scope the scan to a specific subdirectory.
| Name | Required | Description | Default |
|---|---|---|---|
| project | Yes | Project name (must match a directory under apps/) | |
| path | No | Subdirectory path to limit the scan (optional, e.g. "src/components") |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explicitly declares the tool as read-only ('Read-only — does not create tasks automatically'), which provides important behavioral context. With no annotations, this disclosure is critical and well-stated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, no wasted words. The purpose is front-loaded, followed by behavior and usage guidance. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and no annotations, the description covers purpose, behavior, usage guidance, and optional parameter meaning. It could potentially mention the return format, but it is sufficiently complete for the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with both parameters already described. The description adds value by reinforcing the optional nature of the 'path' parameter ('Optionally scope the scan to a specific subdirectory'), going 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 scans project source files for specific comment types (TODO, FIXME, HACK, XXX) and returns them as suggested tasks. This specific verb+resource combination distinguishes it from sibling tools like task_add, task_list, and task_update.
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: 'Review the suggestions and use task_add to persist the ones you want.' It also mentions optional scoping. While it does not explicitly state when not to use this tool, it does give a clear alternative for persistence.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update a task's status. Valid transitions: pending → in_progress → done, or any state → blocked. Setting status to "done" automatically records a completion timestamp. Side effects: updates the tasks table. Idempotent. Returns success/failure and whether the row was actually modified.
| Name | Required | Description | Default |
|---|---|---|---|
| taskId | Yes | Task ID (from task_add or task_list) | |
| status | Yes | New status | |
| note | No | Optional note (e.g. completion summary or block reason) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description details side effects (updates tasks table), idempotence, return information, and automatic timestamp for 'done' status, fully covering behavioral traits without 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 concise with three sentences, front-loads purpose, and every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given low complexity, no output schema, but the description explains return; sibling tools are listed, making it complete for an update 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?
Although schema coverage is 100%, the description adds meaningful context for parameters: valid transitions for status and example usage for note.
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 updates a task's status and lists valid transitions, distinguishing it from siblings like task_add and task_list.
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 explains valid status transitions but does not explicitly guide when to use this tool versus alternatives like task_add or task_list.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run build, test, and lint sequentially for a project. Auto-detects platform-specific commands. Side effects: executes up to 3 shell commands with 5-minute timeouts each. Returns per-gate results and an overall pass/fail status. Use this as a quality gate before committing or ending a session. Use verify_build or verify_test individually when you only need one check.
| Name | Required | Description | Default |
|---|---|---|---|
| project | Yes | Project name (must match a directory under apps/) | |
| stopOnFail | No | Abort remaining gates on first failure (default: false — runs all gates) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description bears full responsibility. It discloses side effects (executes shell commands with timeouts), auto-detection of platform commands, and return format (per-gate results and overall status). It does not explicitly state no file modification, but the context is sufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, front-loaded with the main action, each sentence adds unique value, and there is no unnecessary text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (2 params, none nested, no output schema), the description covers what it does, side effects, return values, and usage guidance, leaving no gaps for an 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 100% coverage, and the description does not add new information beyond what the schema provides for each parameter. Therefore the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool runs build, test, and lint sequentially, and explicitly distinguishes itself from sibling tools verify_build and verify_test by advising when to use them individually.
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 tells when to use this tool ('as a quality gate before committing or ending a session') and explicitly provides alternatives ('Use verify_build or verify_test individually when you only need one check').
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run the project's build command (auto-detected per platform: "pnpm build" for Web, "flutter build" for Flutter, "./gradlew assembleDebug" for Android). Side effects: executes a shell command in the project directory with a 5-minute timeout. Returns {success, output} with the last 1000 chars of stdout/stderr. Use verify_all to run build + test + lint together.
| Name | Required | Description | Default |
|---|---|---|---|
| project | Yes | Project name (must match a directory under apps/) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses side effects (executes shell command), constraints (5-minute timeout), and return format (success, output with last 1000 chars). No annotations provided; description carries full burden.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, each serving a clear purpose: purpose, behavior, and alternative. Slightly verbose but efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Cover all necessary aspects: auto-detection, side effects, timeout, return format, and related tool. No output schema 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 coverage is 100%, so baseline is 3. Description does not add new meaning beyond the schema's description of the 'project' parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Explicitly states it runs the build command, auto-detected per platform, and distinguishes from sibling tool verify_all.
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?
Gives clear alternative (verify_all for combined build+test+lint) and implies when to use this tool for build-only.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run the project's test suite (auto-detected per platform: "pnpm test:run" for Web, "flutter test" for Flutter, "./gradlew test" for Android). Optionally scope to a specific test file or directory. Side effects: executes a shell command with a 5-minute timeout. Returns {success, output}. Use verify_all to run build + test + lint together.
| Name | Required | Description | Default |
|---|---|---|---|
| project | Yes | Project name (must match a directory under apps/) | |
| testPath | No | Specific test file or directory to run (optional — runs all tests if omitted) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses side effects (shell command execution, 5-minute timeout) and return shape, though could note permission or file system 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?
Three concise sentences with no redundancy, front-loaded with the main action and key details.
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?
Covers multi-platform, timeout, return format, and alternative tool, making it self-contained for an 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?
Adds meaning beyond schema by explaining that testPath is optional and defaults to all tests, and that project must match a directory under apps/.
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 runs the project's test suite with platform-specific commands, and distinguishes itself from siblings like verify_all and verify_build.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly advises when to use verify_all instead for combined build+test+lint, and implies scoping via testPath parameter.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Most tools have distinct purposes, but there is some overlap that could cause confusion. For example, memory_related and graph_explore both traverse the knowledge graph, though their descriptions clarify differences in approach. Similarly, search_sessions and session_history both retrieve past sessions, with one focusing on semantic search and the other on chronological listing, which might lead to misselection if not carefully read.
Tool names follow a highly consistent verb_noun pattern throughout, such as memory_search, project_init, and verify_all. All names use snake_case uniformly, with clear and descriptive verbs that align with their functions, making the set predictable and easy to navigate.
With 25 tools, the count feels heavy for the server's purpose of session continuity and project management. While the tools cover various aspects like memory handling, project tasks, and verification, the number may overwhelm agents, leading to inefficiency or confusion in tool selection, despite the broad scope.
The tool set provides comprehensive coverage for the domain, including CRUD operations for memories, projects, tasks, and solutions, along with session management and verification workflows. There are no obvious gaps; each tool supports a complete lifecycle, ensuring agents can handle end-to-end processes without dead ends.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Persistent memory for Claude Code and Cursor. Stop re-explaining your project every session.
Persistent context for Claude. Your AI always knows your projects and next actions across sessions.
Share context and questions between Claude instances — VS Code, claude.ai web, and mobile.
Shared memory for coding agents. Stop re-explaining your codebase every session.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/leesgit/passbaton'
If you have feedback or need assistance with the MCP directory API, please join our Discord server