Callimachus is a local-first MCP server that indexes AI coding-agent conversations (from 11 agents: Claude Code, Codex, Cursor, Gemini CLI, Qwen, Goose, OpenCode, Continue, Cline, Roo Code, Kilo Code) into a local SQLite store, then exposes that history as searchable, writable memory for other agents.
Search & Discovery
search_threads — Full-text (BM25) or hybrid semantic+keyword search across all indexed conversations
search_current_project — Same, auto-scoped to the current git repo
recent_threads — List latest threads, filterable by source, project, tags, or starred status
threads_for_file — Find every past thread that mentioned a specific file path
Knowledge & RAG
ask_history — Ask a natural-language question and get a synthesized, cited answer from past sessions
get_thread — Fetch a full packed transcript of a thread
get_thread_knowledge — Distilled recap: summary, decisions, gotchas, and open TODOs for one thread
project_memory — Aggregated decisions, gotchas, and open TODOs across all sessions for a repo
Decision Guards
check_decision — Surface settled decisions before an agent re-litigates or silently overrides one
find_prior_work — Find prior sessions similar to a task you're about to start
recall_decisions / recall_gotchas — Semantically recall past technical decisions or discovered pitfalls
TODOs
list_open_todos — List unfinished TODOs extracted from past sessions, filterable by project/source
complete_todo — Mark a TODO as done (persists across re-indexing)
Writing Back
record_decision — Persist a technical decision (with optional rationale) into project memory
record_gotcha — Persist a discovered pitfall into project memory
Session Snapshots
snapshot_session — Save a resumable checkpoint (transcript + project memory) before context compaction or handoff
list_snapshots / load_snapshot — List and restore saved checkpoints
Other
linked_commits — List git commits a thread likely produced, inferred by overlapping discussed files with git log
list_tags — List all user-applied tags and thread counts for filtering
Local index & search for your AI coding-agent threads — across 11 tools (Claude Code, Codex, Cursor, Gemini CLI, Qwen Code, Goose, OpenCode, Continue, Cline, Roo Code, Kilo Code) — plus a provider-agnostic chat, an MCP server, a CLI, and a VS Code / Cursor extension. Everything stays on your machine.
Named for Callimachus, who built the first catalogue of the Library of Alexandria.
Grab the latest signed build from Releases — macOS (.dmg, Apple Silicon), Windows (.msi), or Linux (.AppImage / .deb). The app auto-updates from there on. Prefer to build it yourself? See Develop.
Related MCP server: Memory MCP
Indexes every conversation from 11 coding agents into one local SQLite store — Claude Code, Codex, Cursor, Gemini CLI, Qwen Code, Goose, OpenCode, Continue, Cline, Roo Code, and Kilo Code. Adding another source is a small, documented contract.
Searches them with hybrid ranking: keyword (SQLite FTS5 / BM25) fused with on-device semantic similarity (sqlite-vec KNN, no cloud) via Reciprocal Rank Fusion. Filter by source, project, subagents, starred, and tags.
Finds code-aware — type file:embed/mod.rs in the search bar (or cal files <path>) to find every thread that touched a path; backed by a file-mention index built at index time.
Distills knowledge — free heuristic TODO extraction, plus opt-in LLM distillation of decisions, gotchas, and summaries, with cross-thread semantic recall of past decisions/gotchas. Optional auto-distillation drains new/changed threads in the background so memory self-populates. Runs on local Ollama (keyless), your logged-in Claude Code or Codex CLI subscription (keyless, no API key), or a cloud API key.
Curates the facts — pin, edit, or delete distilled facts so your edits survive re-distilling, plus an LLM "Review conflicts" pass that flags decisions that contradict each other.
Remembers per project — a Projects tab aggregates each repo's decisions, gotchas, and open TODOs into durable memory (grouped by a canonical project key, so worktrees / symlinks / ~ don't split one repo), with an LLM brief and a managed .callimachus/memory.md. That memory is prepended when you "Open in CLI", and you can inject it into any agent automatically: Update AGENTS.md (or cal agents) writes a managed block into the repo's AGENTS.md / CLAUDE.md, and cal hook feeds it to a Claude Code SessionStart hook.
Asks your history (RAG) — a synthesized, cited answer over your own threads, with [thread N] citations back to the sources it used. Needs an LLM engine (Knowledge/distillation enabled).
Organizes into collections — star threads and attach free-form tags, then filter the list by starred or by tag.
Chats with an in-app agent (Anthropic / OpenAI / Gemini / OpenRouter / Ollama — local or Cloud — or your logged-in Claude Code / Codex CLI with no key) that can search your own history and run shell commands with your approval; streaming, cancellable, with live model lists. Chats are saved and become searchable too.
Carries context across tools — open any thread in any agent CLI ("Open in Claude / Codex / Gemini …", seeded with the packed transcript), resume a Claude Code / Codex thread in its native CLI, copy context, or export a thread to Obsidian (optionally AI-summarized with decisions / gotchas / TODOs).
Links threads to commits — infers on-device which git commits a thread produced, by overlapping the files a thread discussed with git log's changed files inside the thread's time window (shared-file count = confidence). See it as a thread→commit timeline (cal commits), per-thread in the desktop UI ("Produced commits"), or via the linked_commits MCP tool.
Snapshots agent sessions — durable, resumable checkpoints of a thread (packed transcript + carry-forward project memory) for handoff across a context-window compaction or across tools; auto-captured via Claude Code PreCompact / SubagentStop hooks. Take, list, and resume them (cal snapshot / cal snapshots / cal resume, or the snapshot_session / list_snapshots / load_snapshot MCP tools).
Guards decisions — decisions can carry a rationale ("why"), and an active guard surfaces settled decisions on a topic before an agent re-litigates one (cal check "<proposal>" / the check_decision MCP tool).
Recalls before you redo — an opt-in Claude Code hook quietly injects "you may have solved this before" into the agent's context on each prompt when it strongly matches prior work (Settings → Claude Code → Proactive recall, off by default, signal-floored and per-session deduped).
Mines recurring issues — surfaces the errors you keep hitting across all your tools (normalized signatures, last 180 days) so you fix the pattern, not the instance (a Coach card, or cal issues).
Shows what it cost — captures per-message token usage and model at index time, then estimates dollar spend by model and your priciest threads (a Stats card, or cal cost; reindex once to backfill).
Feeds PR audits — cal audit-pr <repo> --changed-files … --shas … returns one JSON bundle (per-commit provenance back to the session that produced it, per-file prior threads + reasoning, repo recurring errors, project memory) so an external local PR-review tool can show the history behind a diff.
Surfaces to your agents — a bundled MCP server (callimachus-mcp) exposes the index as tools any agent can call mid-session, and it's two-way: agents can write back into Callimachus's own memory (close TODOs, record decisions/gotchas, snapshot a session) without ever touching your files. The /recall skill teaches them when to use it.
Stays current via a background file watcher; stays private — API keys live in the OS keychain, nothing is sent anywhere except the LLM provider you pick.
Shell: Tauri 2 (Rust) + React 19 + TypeScript + Vite 8
Store/search: bundled SQLite + FTS5 (rusqlite); on-device embeddings via fastembed (bge-small-en-v1.5, 384-dim); KNN in SQL via sqlite-vec (vec0)
Watcher: notify + debouncer
Chat: multi-provider via the genai crate (Anthropic / OpenAI / Gemini / OpenRouter / Ollama local + Ollama Cloud), each with a configurable base URL, streaming tokens over a Tauri Channel, cancellable, with agent tool-calls (history search + approved shell)
Secrets: OS credential store via the cross-platform keyring crate — macOS Keychain, Windows Credential Manager, Linux Secret Service
Sidecars: callimachus-mcp (MCP server) and cal (CLI) — both reuse the desktop core lib against the same index.db
Editor: a VS Code / Cursor extension (apps/vscode, published to the Marketplace + Open VSX) that shells out to cal
This is a Turborepo + pnpm workspace.
apps/
desktop/ # the Tauri 2 desktop app + the cal CLI and MCP server (src-tauri)
vscode/ # VS Code extension (search history from the editor)
web/ # marketing + download site (reserved, not built yet)
packages/ # shared code, when it appears
.changeset/ # version + changelog management
scripts/ # version-sync, release taggingReleases, versioning, and the auto-updater are documented in RELEASING.md.
pnpm install
pnpm desktop:dev # launches the desktop window (tauri dev)
# from the repo root, across all apps:
pnpm build # turbo: build every app's frontend
pnpm typecheck # turbo: typecheck every appFirst launch: the index is empty — open Settings (or hit Reindex) to index your sources, then Build semantic index to enable semantic search. Reindex runs as a background job with a per-source progress bar, separate from Build semantic index — the two are mutually exclusive (one pauses while the other holds the write lock).
cd apps/desktop/src-tauri
cargo test # fast unit tests
cargo test -- --ignored --nocapture # real-data + model + keychain smoke testsThe --ignored tests touch live data on this machine: each source has a real_<source>_index smoke test that indexes your real history read-only (~/.claude, ~/.codex, Cursor, ~/.gemini, ~/.qwen, Goose, OpenCode, Continue, Cline/Roo/Kilo), plus the embedding-model download (first run, needs network) and a Keychain round-trip.
Beyond the desktop window, the same local index is reachable from your agents, terminal, and editor — all reading one index.db.
MCP server — let any agent search its own past work mid-session. The quickest way is npx (it downloads the prebuilt binary on first run); it's also listed on the official MCP registry as io.github.betabots-llc/callimachus:
claude mcp add callimachus -- npx -y callimachus-mcp # or any MCP clientAlready running the desktop app? callimachus-mcp is on your PATH, so claude mcp add callimachus -- callimachus-mcp works without npm. Building from a checkout instead? cargo install --path apps/desktop/src-tauri --bin callimachus-mcp.
Tools (21) — now read and write. Reads (17): search_threads, search_current_project (auto-scoped to the repo it runs in), recent_threads, get_thread, list_tags, list_open_todos, get_thread_knowledge, recall_decisions, recall_gotchas, find_prior_work (the "have I done this before?" guard — prior sessions similar to a task), project_memory (a project's aggregated decisions / gotchas / open TODOs), ask_history (a cited RAG answer over your history), threads_for_file (which sessions touched a path), check_decision (surface settled decisions before re-litigating a proposal), linked_commits (the commits a thread likely produced), list_snapshots (a project's session snapshots), and load_snapshot (restore a saved checkpoint). Writes (4, into Callimachus's own memory, never your code): complete_todo (close an open TODO), record_decision (optionally with a rationale), record_gotcha (persist a fact into a project's memory), and snapshot_session (checkpoint a thread for handoff). The bundled /recall skill (.claude/skills/recall) tells agents when to reach for them.
CLI — cal, pipe-friendly. Ships with the desktop app (on your PATH); or build from a checkout with cargo install --path apps/desktop/src-tauri --bin cal.
cal search "vector index migration" -y # -y = hybrid (semantic + keyword)
cal recent -n 10
cal cat 42 | pbcopy # packed transcript → clipboard
cal stats # index totals + per-source breakdown
cal export 42 --vault ~/Obsidian # write a thread as an Obsidian note
cal ask "how did we set up releases?" # cited RAG answer over your history
cal files embed/mod.rs # threads that touched a file path
cal memory # this repo's distilled memory (decisions/gotchas/TODOs)
cal done 17 # mark an open TODO done (id from `cal todos`)
cal remember decision "use sqlite-vec for KNN" --because "no cloud, KNN in SQL" # record a fact (+ rationale) into the repo's memory
cal check "switch to pgvector" # surface settled decisions before re-litigating one
cal commits # infer the thread→commit timeline for this repo (--json; or pass a path)
cal issues # recurring errors you keep hitting across sessions (last 180 days)
cal cost # estimated $ spend by model + your priciest threads
cal audit-pr . --changed-files a,b --shas s1,s2 # one JSON bundle for an external PR auditor
cal snapshot 42 -l "pre-refactor" # checkpoint a thread for handoff (transcript + project memory)
cal snapshots # list saved session snapshots (optionally for a project)
cal resume 7 -a claude # resume a snapshot in an agent CLI
cal agents # write the repo's memory into AGENTS.md (any agent reads it)
cal hook # print the repo's memory (use as a Claude Code SessionStart hook)star, tag, tags, todos, knowledge, distill, decisions, gotchas, and related also exist — run cal help for the full list.
VS Code / Cursor — the extension adds a "Callimachus History" sidebar, a status-bar search button, and commands to search / insert / copy threads (it shells out to cal). Install from the VS Code Marketplace or Open VSX (the registry Cursor and VSCodium use), or grab the .vsix from Releases. See apps/vscode/README.md.
Cross-platform (macOS / Windows / Linux). The only macOS-only piece left is the "Open in CLI" / "Resume" launchers (they drive Terminal via AppleScript); on Windows/Linux those actions return a "not supported yet" notice — everything else (index, search, chat, export, keychain) works everywhere.
Cline / Roo Code / Kilo Code are editor extensions with no CLI, so they are index-only (searchable, but not relaunchable via "Resume").
Cursor doesn't store a per-thread workspace, so Cursor threads currently have no project path.
Claude Code subagent transcripts are indexed but hidden behind a "subagents" toggle by default.
Large first index is a one-time cost (the Claude corpus here was ~90k messages in ~25s); subsequent passes skip unchanged files.
More sources (Charm Crush, Factory Droid, Copilot CLI) are scoped but not yet integrated — see the indexer guide.
Issues and PRs welcome. CONTRIBUTING.md covers local setup, conventions, and the release flow. Adding support for another agent is a small, documented contract — usually one indexer module + a migration + a few wiring points.
Callimachus is local-first by design: your conversation index never leaves your machine, API keys live in the OS keychain (never on disk), and the only outbound traffic is to the LLM provider you explicitly choose. To report a vulnerability, see SECURITY.md.
Dual-licensed. Free and open source under AGPL-3.0-or-later — use, modify, and share it; if you distribute it or run a modified version as a network service, you must release your source under the AGPL.
For closed-source, proprietary, or for-profit/SaaS use that the AGPL doesn't permit, a commercial license is required — see COMMERCIAL.md (contact ari@shaller.dev).
© 2026 Ari Shaller. See NOTICE for attributions. Contributions are accepted under the terms in CONTRIBUTING.md.
Built on Tauri, fastembed-rs, sqlite-vec, and genai. Named for Callimachus of Cyrene, who catalogued the Library of Alexandria.
Answer a question from the user's OWN past sessions (RAG): retrieves the most relevant threads and returns a synthesized answer with [thread N] citations + the source list. Use for 'how did we...' / 'what did I decide about...' instead of reading many threads. Needs an LLM engine configured (distillation enabled).
| Name | Required | Description | Default |
|---|---|---|---|
| question | Yes | The question to answer from the user's history. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses that the tool uses RAG, returns synthesized answers with citations, and requires a configured LLM engine. It could add details about potential latency or accuracy limitations, but the citation format and source list mention provide good transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded: first sentence presents the main action and output format, second sentence offers usage guidance and prerequisite. 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 simple input schema (one parameter) and no output schema, the description explains output format (synthesized answer with citations and source list) and dependency (LLM engine). It could mention error handling or what happens if the engine is not configured, but overall it provides sufficient context for a straightforward 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?
The schema has 100% coverage for the single parameter 'question', and the description adds 'The question to answer from the user's history.' which is similar to the schema description. Since baseline is 3 for high coverage, and no additional meaning is added, the score remains 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 that the tool answers a question from the user's past sessions via RAG, retrieves relevant threads, and returns a synthesized answer with citations. It effectively distinguishes itself from reading many threads manually.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit use cases ('how did we...' / 'what did I decide about...') and advises using this tool 'instead of reading many threads'. It also mentions a prerequisite (LLM engine with distillation enabled). However, it does not explicitly list alternative sibling tools for comparison.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
CONTRADICTION GUARD: before you make a technical decision or change, pass it as proposal to see SETTLED decisions on the same topic (each with its rationale), so you don't silently undo or re-litigate a past choice. Returns the closest prior decisions, best match first; an empty list means none conflict. Searches ALL projects unless project is given. Call this BEFORE acting on a non-trivial decision; if it returns something that contradicts your plan, reconcile with the user rather than overriding it. Requires distilled or recorded decisions.
| Name | Required | Description | Default |
|---|---|---|---|
| project | No | Substring-match the project path to scope results. Empty = all projects. | |
| proposal | Yes | The change/decision you are about to make. Returns settled decisions on the same topic. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It explains return format (closest prior decisions, best match first, empty list means none), prerequisite (requires distilled or recorded decisions), and implies read-only nature. Could mention performance 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?
Four sentences, front-loaded with purpose and usage, no redundancy. Every sentence adds informative value. Efficient and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, description covers return behavior, prerequisites, parameter effects, and user interaction guideline. Missing error handling info but sufficient 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 coverage is 100%, but description adds value beyond schema: explains 'proposal' as the change/decision to check, 'project' as substring match, and how to interpret results. Schema descriptions are good, but description enriches context.
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 checks if a proposed decision conflicts with prior settled decisions, with specific verb 'check' and resource 'settled decisions'. It distinguishes from siblings like 'record_decision' (write) and 'recall_decisions' (potential 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?
Explicitly says 'Call this BEFORE acting on a non-trivial decision' and instructs to reconcile conflicts with the user. Also clarifies scope: 'Searches ALL projects unless `project` is given'. Slight ambiguity on 'non-trivial' but overall strong guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Mark a TODO done so it drops out of the open-TODO lists. Pass the id from list_open_todos. The completion persists across re-indexing.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The TODO's id (the `id` field from list_open_todos). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It discloses key behavioral traits: the TODO drops out of open-TODO lists and the completion persists across re-indexing. This offers sufficient transparency for a simple mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is exceptionally concise at two sentences and 21 words. It front-loads the purpose in the first sentence and adds usage guidance and a behavioral note in the second, with no extraneous content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity (1 parameter, no output schema, no annotations), the description is complete. It covers purpose, how to obtain the input, and a behavioral guarantee. No additional information is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although schema coverage is 100%, the description adds meaning by specifying that the `id` comes from `list_open_todos`, providing a concrete source. This guidance enhances understanding beyond the schema's parameter description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Mark' and the resource 'TODO done', clearly stating the tool's function. It distinguishes itself from sibling tool 'list_open_todos' by focusing on completion rather than listing.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context by instructing to pass the `id` from `list_open_todos`, indirectly guiding when to use this tool (after listing). However, it does not explicitly mention when not to use it or compare to alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find PRIOR SESSIONS where the user already worked on something similar to a task you're about to start — the 'have I done this before?' guard. Pass a short description of the task/problem as query; returns past threads (each with its most-relevant decision or gotcha and the threadId) so you can reuse the earlier solution instead of redoing or re-deciding it. Searches ALL projects unless project is given. Call at the START of a task. Requires distilled threads.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max facts to return (default 20). | |
| query | Yes | What to recall about (e.g. "auth token refresh", "database migration approach"). | |
| project | No | Substring-match the project path to scope results. Empty = all projects. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses behavior: searches past threads, returns relevant decisions/gotchas and threadId, scopes to project if provided. It doesn't mention side effects, but none are implied for a read-only search.
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 4 sentences, each serving a purpose. The main verb and resource are front-loaded. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a search tool with no output schema, the description adequately explains the return value (past threads with decisions/gotchas and threadId). It also notes a prerequisite and when to call, making it self-contained.
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. The description adds meaning by explaining query as a task description, project as substring match, and limit default. This exceeds the schema's minimal descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool finds prior sessions similar to a task, using specific language like 'have I done this before?' guard. It distinguishes from siblings by specifying it searches all projects and returns decisions/gotchas with threadId.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description advises calling at the start of a task and to pass a short description as query. It doesn't explicitly state when not to use or compare to alternatives, but provides clear context including a prerequisite about distilled threads.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch one indexed thread as a packed markdown transcript (budget-limited, ready to drop into context). Pass a threadId from search_threads.
| Name | Required | Description | Default |
|---|---|---|---|
| thread_id | Yes | The thread id from a search result. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description fully carries the burden. It discloses that the result is 'budget-limited' and a 'packed markdown transcript', which are important behavioral traits. It does not mention error handling or modification, but for a fetch operation 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?
Two sentences with no wasted words. The first sentence packs the purpose, format, and constraints; the second provides a usage hint. 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?
For a simple tool with one parameter and no output schema, the description covers the core purpose, input source, and return format. It doesn't explain 'budget-limited' in detail, but overall it is adequate for an agent to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a single parameter. The description adds value by specifying the source: 'from a search result', which helps the agent understand where to obtain the ID. Baseline 3, plus 1 for added context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Fetch one indexed thread') and resource ('packed markdown transcript'), and distinguishes from siblings like search_threads by indicating it retrieves a single thread by ID.
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 the agent to 'Pass a threadId from search_threads', providing a clear prerequisite. Does not explicitly exclude alternatives, but the context is sufficient for a simple tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the distilled knowledge for one thread by threadId: a short summary plus key decisions, gotchas, and open TODOs. A fast, high-signal recap instead of reading the whole transcript. Decisions/gotchas/summary exist only if the user enabled distillation; TODOs are always available.
| Name | Required | Description | Default |
|---|---|---|---|
| thread_id | Yes | The thread id from a search/recent result. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses conditional availability of decisions/gotchas/summary versus always-available TODOs, a key behavioral detail for correct invocation.
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 wasted words. Main purpose stated first, then conditional details. Perfectly concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given simple input (one param, no output schema) and low complexity, the description covers purpose, usage, and conditionality. Slightly missing behavior on missing thread or disabled distillation, but still adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers 100% of parameters with a meaningful description ('thread id from a search/recent result'). The tool description reinforces the parameter's source, adding value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool gets distilled knowledge for one thread, summarizing decisions, gotchas, and TODOs, distinguishing it from full transcript retrieval or aggregate recall tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains this is a fast, high-signal recap alternative to reading the whole transcript, and clarifies that certain elements depend on distillation being enabled. No explicit sibling comparison, but context is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the git commits a thread likely PRODUCED — inferred on-device by overlapping the thread's discussed files with git log in the same time window. Answers 'which commit came out of this conversation?'. Each result has a short SHA, subject, and an overlap count (more shared files = higher confidence). Empty if none are inferred yet (the user runs cal commits in the repo to compute them). Pass a threadId from search_threads.
| Name | Required | Description | Default |
|---|---|---|---|
| thread_id | Yes | The thread id (from a search/recent result) to find produced commits for. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description bears full burden. It explains the inference method (overlapping files with git log), result fields (SHA, subject, overlap count), and empty result condition. Missing details on performance or side effects, but sufficient for basic behavioral understanding.
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 are compact and front-loaded with the main action. Every sentence contributes value: purpose, usage instruction, and behavior clarification. No redundant 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 only one parameter and no annotations, the description covers purpose, input source, output content details, and empty result handling. Lacks explicit output structure description but inferred from text. Reasonably complete for a simple 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% with a single thread_id parameter described. Description adds context that threadId comes from search_threads, which is helpful but not critical beyond schema. 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 lists git commits likely produced by a thread, with specific verb 'list' and resource 'git commits a thread likely PRODUCED'. It distinguishes from sibling tools like search_threads or get_thread by focusing on commit inference.
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 instructs to pass threadId from search_threads and notes that empty results occur if not yet computed (user must run `cal commits`). Provides clear context for when to use, though does not explicitly state when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List unfinished TODOs / action items the user left across past coding sessions (newest first), optionally scoped to a project path or source. Extracted heuristically from the history (markdown task checkboxes + TODO/FIXME markers), so it works with NO API key and no AI distillation. Each TODO carries the threadId it came from — fetch that thread for full context.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max TODOs to return (default 100). | |
| query | No | Optional text search over the TODO text + thread title (case-insensitive). | |
| source | No | Optional source filter (see search_threads). Empty = all sources. | |
| project | No | Substring-match the project path (e.g. a repo path) to scope results. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses key behaviors: extraction is heuristic from markdown checkboxes and TODO/FIXME markers, works without API key or AI distillation, and each TODO includes a threadId. However, with no annotations, it does not explicitly state read-only nature or performance characteristics.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three well-structured sentences. The first sentence states the purpose and ordering, the second explains the extraction method and benefits, and the third provides follow-up guidance. 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 no output schema, the description adequately covers what the tool returns (TODOs with threadId) and advises fetching the thread for full context. It could mention if there is any default limit or pagination, but overall sufficient for a listing tool with rich sibling context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with all parameters described. The description adds the ordering 'newest first' and mentions optional scoping to project or source, but does not provide deeper semantics beyond what the schema already gives. 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 the tool lists unfinished TODOs/action items from past coding sessions, newest first, with optional scoping. The verb 'list' and resource 'open TODOs' are specific, and it distinguishes itself from siblings like complete_todo by focusing solely on listing.
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 implicitly indicates when to use (when the user wants to see open TODOs) and mentions that each TODO carries a threadId to fetch full context, but it lacks explicit guidance on when not to use or alternatives beyond the sibling name 'complete_todo'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List saved session snapshots (newest first), optionally scoped to a project-path substring. Returns snapshot metadata with an id to load.
| Name | Required | Description | Default |
|---|---|---|---|
| project | No | Substring-match the project path to scope results. Empty = all projects. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description carries the full burden. It accurately describes the read-only nature ('List'), the ordering, and the filter behavior. No side effects or additional constraints are needed for a simple list operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences covering action, ordering, filter, and return content. No extraneous information; every phrase 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 exists, so the description must indicate return content. It specifies 'snapshot metadata with an id', which is sufficient for an agent to understand what is returned. However, it could be more explicit about what metadata fields are included.
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% for the single 'project' parameter. The description essentially repeats the schema's wording ('optionally scoped to a project-path substring'), adding no new 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?
Clearly states the verb 'list', the resource 'snapshots', ordering ('newest first'), optional filter by project path, and the return type ('snapshot metadata with an id'). This distinguishes it from sibling tools like load_snapshot which loads a specific snapshot by id.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear context for when to use the optional project filter and that an empty string means all projects. However, it does not explicitly state when not to use this tool or mention alternatives like load_snapshot for direct access.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all tags the user has applied to their threads, each with the number of threads it's on. Use to discover the user's topic labels / collections, then pass a tag to recent_threads to filter by it.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses that the tool lists tags with counts, implying a read-only operation. Could explicitly state no side effects, but the behavior is clear.
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, concise and front-loaded with key information (what it does and how to use the result). No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given zero parameters and no output schema, the description fully explains the output (tags with count) and usage context. It is complete for a simple listing 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?
No parameters; schema coverage is trivially 100%. Description adds no parameter info, but it's unnecessary. Baseline of 4 for zero parameters is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'List' and the resource 'tags the user has applied to their threads' with the extra detail of count. It distinguishes from sibling tools like recent_threads by indicating the output is used for filtering.
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 this tool to discover tags, then pass a tag to recent_threads for filtering. No alternative uses or when-not-to-use are needed given the context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Load a saved snapshot's full checkpoint (carry-forward project memory + packed transcript) as markdown, ready to drop into context to continue the session. Pass an id from list_snapshots.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The snapshot id (from list_snapshots or snapshot_session). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It states that the tool loads a checkpoint as markdown, which implies a read operation, but does not explicitly confirm it is non-destructive or mention any side effects. The description is adequate but could be more explicit about the tool's safety profile.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with two sentences, no redundancy, and front-loads the core action. Every word adds value, making it easy for an AI agent to quickly grasp the tool's purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one parameter and no output schema, the description covers the main aspects: what it does, the input source, and the output format. It is nearly complete, though it could explicitly state that the operation is read-only.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already describes the parameter 'id' with high coverage (100%). The description adds slight context by mentioning the id comes from list_snapshots or snapshot_session, but this is marginal. The baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('load'), the resource ('snapshot's full checkpoint'), and the output format ('as markdown'), making the tool's function unambiguous. It also distinguishes itself from siblings like list_snapshots by referencing it as the source for the id.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear usage context: use after list_snapshots, and pass an id from that tool. It implies the use case of continuing a session. However, it does not explicitly mention when not to use it or list alternative tools besides list_snapshots.
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 durable MEMORY: the decisions, gotchas, and open TODOs distilled across ALL past AI-coding sessions on it, with coverage counts. Omit project to use the repo the server runs in. Call this at the START of work on a project to recall what was already decided and what to watch out for. Decisions/gotchas need the user to have distilled threads; TODOs are always available.
| Name | Required | Description | Default |
|---|---|---|---|
| project | No | Project-path substring. Omit to use the git repo the server runs in. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses that decisions/gotchas require prior user distillation while TODOs are always available, and mentions coverage counts. No annotations are provided, so the description carries the full burden for behavioral info.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four concise sentences, each serving a distinct purpose: purpose, parameter usage, timing advice, and content availability. No fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers what the tool returns (decisions, gotchas, TODOs, coverage counts) but lacks specifics on the return format, which could be inferred from context but is not explicitly stated.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter is fully described in the schema (100% coverage), and the description adds no additional information beyond what is in the schema, meeting the baseline.
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 a project's durable memory including decisions, gotchas, and TODOs with coverage counts, distinguishing it from sibling tools that focus on individual components.
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 recommends calling at the start of work and explains when to omit the project parameter, but does not directly compare with sibling tools or specify when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recall concrete technical DECISIONS the user made across ALL past sessions (and why), semantically matched to a query. Use BEFORE re-deciding something the user may have already settled. Returns decision facts, each with the threadId it came from. Requires the user to have distilled some threads.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max facts to return (default 20). | |
| query | Yes | What to recall about (e.g. "auth token refresh", "database migration approach"). | |
| project | No | Substring-match the project path to scope results. Empty = all projects. |
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 a prerequisite (requires distilled threads) and mentions the return format includes threadId. However, it does not explicitly state that the operation is read-only or non-destructive, which would be helpful.
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 and front-loads the purpose. It is clear and actionable, though the second sentence could be integrated for slightly better flow. Overall, it is concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a recall tool with no output schema, the description adequately explains what is returned (decision facts with threadId) and the prerequisite. It could be more complete by noting that results are based on previously distilled threads, but it covers the essential aspects.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description for the 'query' parameter adds minimal additional meaning beyond the schema ('What to recall about'). The 'limit' and 'project' parameters are not further elaborated in the description, so it does not significantly enhance 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 it recalls 'concrete technical DECISIONS' across past sessions, semantically matched to a query. It specifies the resource (decisions) and the action (recall), and distinguishes it from sibling tools like 'recall_gotchas' and 'record_decision' through naming and context.
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 says to use this 'BEFORE re-deciding something the user may have already settled,' providing clear when-to-use guidance. It also implies a prerequisite (requires distilled threads). While it doesn't mention alternatives by name, the usage context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recall GOTCHAS / pitfalls / non-obvious constraints the user discovered across ALL past sessions, semantically matched to a query. Use to avoid repeating a known mistake. Returns gotcha facts with the threadId they came from. Requires the user to have distilled some threads.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max facts to return (default 20). | |
| query | Yes | What to recall about (e.g. "auth token refresh", "database migration approach"). | |
| project | No | Substring-match the project path to scope results. Empty = all projects. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that the tool returns gotcha facts with threadId and uses semantic matching. With no annotations, it carries the full burden, and it sufficiently describes the read-only retrieval behavior without contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no fluff, front-loading the purpose and providing necessary details efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple retrieval tool with 3 parameters and no output schema, the description covers the return format, matching behavior, and prerequisites, making it complete for the 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%, so baseline is 3. The description adds value by explaining 'query' with examples and clarifying 'project' substring matching and 'limit' defaults, enhancing clarity 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 recalls gotchas/pitfalls from past sessions, semantically matched to a query, and distinguishes it from siblings like recall_decisions and search_threads via the verb 'recall gotchas' and the specific use case of avoiding known mistakes.
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 ('to avoid repeating a known mistake') and mentions a prerequisite ('requires the user to have distilled some threads'), but does not explicitly list when not to use or compare to all siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the user's most recently updated conversation threads (newest first), optionally filtered by source or project path. Use this to see what the user has been working on lately. Returns thread summaries with a threadId to fetch.
| Name | Required | Description | Default |
|---|---|---|---|
| tags | No | Only threads tagged with ANY of these tags (see list_tags). Empty = all. | |
| limit | No | Max threads to return (default 20). | |
| project | No | Substring-match the project path (e.g. a repo path) to scope results. | |
| sources | No | Optional source filter (see search_threads). Empty = all sources. | |
| starred | No | If true, return only threads the user has starred. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description adds some behavioral context (returns thread summaries, threadId, newest first), but does not disclose safety, authentication, or pagination behavior. It prevents contradictions but lacks depth.
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 efficiently front-load the core action and filters, followed by use case and output hint. No redundant 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 5 parameters and no output schema, the description mentions only two filter types (source, project) and omits 'starred', 'tags', 'limit' details. It partially explains output but misses covering all options.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the description adds minimal value beyond paraphrasing 'source or project path' filters. It does not introduce new meaning for parameters like 'starred' or 'tags'.
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 'List the user's most recently updated conversation threads (newest first)' with specific verb and resource, and distinguishes from sibling tools like 'search_threads' by focusing on recency rather than search.
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 usage context ('Use this to see what the user has been working on lately') and mentions optional filtering, but does not explicitly state when not to use this tool or compare to alternatives like 'search_threads'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Record a DECISION you/the user just made for a project, so it persists in the project's memory and future cross-thread recall (and the check_decision guard). Pass the WHY as rationale when you have it. Omit project to use the repo the server runs in. Use when you settle a technical choice worth remembering.
| Name | Required | Description | Default |
|---|---|---|---|
| text | Yes | What to remember (one concrete sentence). | |
| project | No | Project-path substring to attach it to; omit to use the repo the server runs in. | |
| rationale | No | For a decision, WHY it was made (the rationale). Surfaced by check_decision later. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses that the decision persists in project's memory, is available for cross-thread recall, and interacts with the check_decision guard. It also explains the default project behavior. No contradictions or hidden traits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with zero waste. First sentence states action and effect; second provides parameter guidance and usage context. Perfectly front-loaded and concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple recording tool with 3 params and no output schema, the description covers purpose, usage, parameter details, and behavioral persistence. It doesn't mention return values or errors, but these are not critical given the simplicity. The mention of check_decision and cross-thread recall adds valuable context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds value by explaining the purpose of 'rationale' (WHY) and its future use by check_decision, and clarifying the 'project' default behavior. This goes beyond the schema's descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Record a DECISION' as the verb+resource, and specifies it's for a project with cross-thread recall. It is differentiated from sibling tools like record_gotcha and recall_decisions by focusing on technical decisions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use: 'Use when you settle a technical choice worth remembering.' It also provides guidance on omitting project and passing rationale. While it doesn't list explicit alternatives, the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Record a GOTCHA / pitfall just discovered for a project, so it persists in the project's memory and future recall. Omit project to use the current repo.
| Name | Required | Description | Default |
|---|---|---|---|
| text | Yes | What to remember (one concrete sentence). | |
| project | No | Project-path substring to attach it to; omit to use the repo the server runs in. | |
| rationale | No | For a decision, WHY it was made (the rationale). Surfaced by check_decision later. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. Description says it 'persists in the project's memory' but does not disclose whether entries are appended or overwritten, nor any side effects or limitations. For a simple record tool, more transparency is expected.
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 clear sentences. The first sentence declares purpose, the second provides a usage tip. No fluff, 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?
Given the tool's simplicity (3 params, 1 required, no output schema), the description is adequate but lacks behavioral details like idempotency, return values, or whether the text is appended. Meets minimum viability for a simple record 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 covers 100% of parameters. The description adds value for 'project' (omit for current repo) but misleads for 'rationale' by saying 'For a decision, WHY it was made' while the tool is for GOTCHAs, not decisions. This could cause confusion.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the action (record) and resource (GOTCHA/pitfall) and purpose (persist in memory). Distinguishes from sibling 'recall_gotchas' by being the recording counterpart, but does not explicitly differentiate from 'record_decision' which is for decisions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Only provides one piece of guidance: 'Omit project to use the current repo.' No information on when to use this tool versus alternatives like record_decision, or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the recurring ERRORS the user keeps hitting across their indexed sessions — normalized error signatures grouped by how often they recur (count) and how many threads they span. Scoped to the repo the server runs in by default; pass project (a path substring) for another repo, or "*" for all projects. Use this before retrying an approach to avoid repeating a known failure. Each cluster has an example line, a count, a thread count, and first/last-seen timestamps.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max error clusters to return (default 20). | |
| project | No | Path substring to scope to one repo. Omit to use the repo the server runs in; pass "*" for all projects. | |
| since_days | No | How far back to scan, in days (default 180). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description fully discloses behavior: output includes example line, count, thread count, timestamps; default limit and time range; scoping via project parameter. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four sentences, efficient and front-loaded with purpose. Each sentence adds necessary information without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 3 optional params and no output schema, the description covers return value structure, default behavior, and use case, making it complete for a list tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and description adds value by stating default limit (20), default since_days (180), and clarifying project scoping (omit for default, '*' for all). Adds 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 it lists recurring errors with normalized signatures grouped by count and thread span, specifying the verb 'list' and resource 'recurring errors'. It distinguishes from sibling tools by focusing on errors and recurrence.
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 it before retrying an approach to avoid repeating known failures, with clear scoping rules (default repo, project parameter, '*' for all). No exclusions but usage context is well-defined.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search only the conversation history for the CURRENT project — the git repository (or directory) this MCP server was launched in. Use this first when the user asks about prior work on the project you're in; it scopes results to this repo. Falls back to all sources within that project.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max results to return (default 20). | |
| query | Yes | The search query. | |
| hybrid | No | Fuse keyword + on-device semantic search. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It reveals the scope constraint and fallback behavior, but does not disclose read-only nature, rate limits, or exact fallback semantics. Adequate but could be more detailed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three efficient sentences: first defines scope, second gives usage guidance, third notes fallback. Front-loaded with key information, no waste. Perfectly sized.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Moderately complex tool with three parameters and no output schema. Description covers scope and usage guidance but lacks details on return format, pagination, or hybrid search semantics. Missing some contextual completeness for a full picture.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All three parameters are documented in the schema (100% coverage). The description does not add additional meaning beyond the schema descriptions; it only implies the query pertains to the current project. Baseline 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 it searches only the conversation history for the current project (the git repository/directory). It specifies the scope and distinguishes from broader search tools like search_threads by explicitly limiting to the current project.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-to-use guidance: 'Use this first when the user asks about prior work on the project you're in'. Mentions fallback but does not explicitly state when not to use or compare directly with siblings beyond implication.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search the user's indexed AI coding-agent conversation threads across every tool they use (Claude Code, Codex, Cursor, Gemini, Qwen, Goose, OpenCode, Continue, Cline, Roo Code, Kilo Code, and in-app chats). Keyword full-text by default; set hybrid=true to also use on-device semantic similarity. Returns matching threads with snippets and a threadId to fetch. Use this to recall past decisions, prior solutions, or earlier discussion before redoing work.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max results to return (default 20). | |
| query | Yes | The search query. | |
| hybrid | No | Fuse keyword + on-device semantic search (higher recall; loads the embedding model). | |
| sources | No | Optional source filter: any of claude_code, codex, cursor, gemini, qwen, goose, opencode, continue, cline, roo, kilo, in_app. Empty = all sources. | |
| include_subagents | No | Include Claude Code subagent transcripts (hidden by default). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses the search scope, default vs hybrid behavior, and mentions that hybrid loads the embedding model. It doesn't cover rate limits or authentication, but for a read-only search tool, it provides sufficient behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise paragraph of four sentences, front-loaded with the main purpose. Every sentence adds value—scope, default/option, output, and usage intent. No fluff or repetition.
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 5 parameters, no output schema, and 15 siblings, the description covers the tool's purpose, filtering options (sources, hybrid), and intended use. It could mention the return structure more explicitly, but the essentials are present.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds value by explaining hybrid's purpose (on-device semantic similarity, higher recall) and that it loads the embedding model, which aids parameter understanding beyond schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool searches AI coding-agent conversation threads across many specific tools, with keyword full-text by default and optional semantic search. It distinguishes from siblings like recent_threads and get_thread by focusing on search and recall of past decisions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear usage context: 'Use this to recall past decisions, prior solutions, or earlier discussion before redoing work.' It doesn't explicitly exclude alternatives, but the context and sibling names imply when other tools are appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Save a resumable SNAPSHOT of a thread: its packed transcript plus a carry-forward block of the project's distilled decisions/gotchas/open TODOs. Use this to checkpoint a session before context is compacted, or to hand work off to another agent or tool. Returns the snapshot id to load later. Pass a threadId from search_threads.
| Name | Required | Description | Default |
|---|---|---|---|
| label | No | Optional label for the snapshot; defaults to the thread title. | |
| thread_id | Yes | The thread id (from a search/recent result) to checkpoint. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, description accurately states it saves a snapshot and returns an id. It discloses the snapshot content (transcript + carry-forward block) but does not mention side effects, permissions, or whether it modifies existing data.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences: purpose, use cases, return value and input source. Each sentence is necessary and front-loaded, 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 no output schema, description explains return value (snapshot id). Explains what snapshot contains and how to get threadId. Fits well with sibling tools for listing/loading snapshots.
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 covers both parameters (100% coverage), so baseline is 3. Description adds value by specifying that threadId should come from search_threads, providing extra usage guidance 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 specifies exactly what the tool does: save a resumable snapshot of a thread including transcript and carry-forward block. It clearly distinguishes from sibling tools like list_snapshots and load_snapshot by focusing on creation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-to-use scenarios (checkpoint before context compaction, handoff to another agent/tool) and tells users to pass a threadId from search_threads. Lacks when-not-to-use but context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find every past thread that mentioned a file path (e.g. 'embed/mod.rs') — which sessions touched this file. Substring match over indexed file references. Returns thread summaries.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | A file path or substring (e.g. "embed/mod.rs"). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses that the operation is a substring match and returns thread summaries, implying a read-only search. However, it does not explicitly state safety, authorization needs, or any potential side effects, leaving some ambiguity.
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 succinct sentences: first presents purpose with an example, second explains the matching method and output. No extraneous information; every word 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?
For a simple one-parameter search tool with no output schema or annotations, the description is mostly complete. It covers what the tool does, how it matches, and what it returns. It could elaborate on scope (e.g., all past threads or only indexed ones), but the mention of 'indexed file references' provides sufficient context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a single parameter 'path' that already includes an example. Description adds no new semantic info beyond what is in the schema. Baseline 3 applies because schema fully describes the 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?
Description clearly states verb 'find', resource 'past threads', and mechanism 'substring match over indexed file references'. Distinguishes from siblings like search_threads by focusing on file path mentions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implies use when wanting threads related to a specific file path. Does not explicitly state when not to use or compare to alternatives, but the context is clear and intuitive for the targeted use case.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v0.8.2recurring_issuesv0.6.2check_decisionlinked_commitslist_snapshotsload_snapshotrecord_decision1 field changedInput schema / properties / rationaleAdded value: +{
+ "description": "For a decision, WHY it was made (the rationale). Surfaced by check_decision later.",
+ "type": [
+ "string",
+ "null"
+ ]
+}record_gotcha1 field changedInput schema / properties / rationaleAdded value: +{
+ "description": "For a decision, WHY it was made (the rationale). Surfaced by check_decision later.",
+ "type": [
+ "string",
+ "null"
+ ]
+}snapshot_sessionv0.6.0ask_historycomplete_todofind_prior_workget_thread_knowledgelist_open_todosproject_memoryrecall_decisionsrecall_gotchasrecord_decisionrecord_gotchasearch_threads1 field changedInput schema / properties / sources / descriptionPrevious value: -"Optional source filter: any of claude_code, codex, cursor, gemini, qwen,\ngoose, opencode, continue, cline, in_app. Empty = all sources."New value: +"Optional source filter: any of claude_code, codex, cursor, gemini, qwen,\ngoose, opencode, continue, cline, roo, kilo, in_app. Empty = all sources."threads_for_filev0.5.0get_threadlist_tagsrecent_threadssearch_current_projectsearch_threadsEach tool has a distinct purpose, but there are multiple search/retrieval tools (ask_history, search_threads, search_current_project, find_prior_work) that could cause some ambiguity, though descriptions clarify scopes. Overall mostly distinct.
Most tools follow a verb_noun pattern in snake_case, but a few like 'project_memory' and 'recent_threads' are noun phrases, introducing minor inconsistency. The majority are consistent.
With 21 tools, it exceeds the typical 3-15 range considered well-scoped. While each tool serves a specific need, the count feels slightly heavy for the domain, though still manageable.
The tool set covers the full lifecycle of memory management: recording decisions/gotchas, searching and retrieving threads, managing TODOs and snapshots. Minor gaps like editing records or tag management are absent but not critical.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Shared memory for coding agents. Stop re-explaining your codebase every session.
Persistent memory for AI agents. Search, store, and recall across sessions.
Universal memory for AI agents and tools. Save, organize and search context anywhere.
Shared memory for AI coding agents. Save once, reuse from Cursor, Claude Code, Codex.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/BetaBots-LLC/callimachus'
If you have feedback or need assistance with the MCP directory API, please join our Discord server