The mcp-session-insight server provides AI-native observability into past coding sessions from Claude Code, OpenCode, and Codex, allowing you to query, analyze, and extract insights from historical session data.
List Sessions – Browse all past sessions with optional filtering by project path and result limits
Show Session Metadata – Get a quick overview of a session (project, time, message count) using full or prefix-matched session IDs
Search Sessions – Search across all sessions by keyword in content or session ID
Get Session Summary – Retrieve a comprehensive structured JSON summary (EnrichedSummary) covering duration, message density, file changes, classified bash commands, errors, decisions, tool usage stats, and git actions — designed for LLM synthesis at zero extra API cost
Get File Changes – See which files were created or modified during a session
Get User Requests – Extract a deduplicated list of user requests made during a session
Get Todo Progress – View todo snapshots and progress tracked during a session
Get Errors & Issues – Retrieve errors encountered during a session with contextual information
Get Key Decisions – Extract important decisions made (from thinking blocks) during a session
Get Conversation History – Retrieve conversation messages with optional filtering by role (user/assistant/all) and message limit
Get Git Logs – Collect and browse git commit history across all discovered projects, with filters for date range, author, and project
Collects git commit history across all Claude Code projects, allowing filtering by date range and project.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@mcp-session-insight summarize my last session's file changes and errors"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
AI-Native Session Observability for Claude Code, OpenCode, and Codex
简体中文 | English
AI coding sessions accumulate rich context — file changes, user requests, decisions, errors, git history — but that context vanishes when the session ends. Static rule files cannot answer "what did I work on today?" or "what went wrong in that last session?".
session-insight gives your AI assistant a read-only lens into all past sessions:
Session analytics — extract structured insights from JSONL: file changes, decisions, errors, tool usage, todo progress
Multi-source collection — read Claude Code JSONL, OpenCode SQLite sessions, and Codex JSONL sessions
Real work filtering — Codex collection ignores developer/system prompts and environment metadata, keeping only real user work content
EnrichedSummary — returns structured JSON instead of Markdown templates, letting the calling LLM synthesize concise summaries at zero extra API cost
Cross-project git logs — collect commit history across all projects with date range, project, and author filters
Semantic classification — bash commands classified into 9 categories (build/test/deploy/debug/network/run/git/explore/other)
Session handoff — generate structured context for seamless session continuation
Related MCP server: claude-find
# Install
npm install -g @morningljn/mcp-session-insight
# One-command setup
claude mcp add session-insight -- npx @morningljn/mcp-session-insightRestart your AI assistant and it can now query all past sessions.
Source | Default Location | Notes |
Claude Code |
| Reads project-scoped JSONL sessions |
OpenCode |
| Reads SQLite session, message, and part tables |
Codex |
| Reads JSONL sessions and filters hidden prompts/context |
Add to ~/.claude/mcp.json:
{
"mcpServers": {
"session-insight": {
"command": "npx",
"args": ["@morningljn/mcp-session-insight"]
}
}
}Tool | Description |
| Use first for daily reports or source-specific collection; returns source counts and structured sessions |
| List all sessions with optional project filter and limit |
| Show session metadata (supports prefix matching on session ID) |
| Search sessions by keyword in content or ID |
| Returns EnrichedSummary JSON for LLM synthesis |
| Get file changes (created / modified / read) |
| Get deduplicated user requests |
| Get todo progress snapshots |
| Get errors and issues with context |
| Get key decisions from thinking blocks |
| Get conversation history with role filter |
| Collect git commit logs across projects |
The server exits automatically when the MCP stdio input closes, so old Claude Code sessions should not leave orphaned npm exec or node processes behind. For an extra safety net, set SESSION_INSIGHT_IDLE_TIMEOUT_MS to a positive number of milliseconds:
{
"mcpServers": {
"session-insight": {
"command": "npx",
"args": ["@morningljn/mcp-session-insight"],
"env": {
"SESSION_INSIGHT_IDLE_TIMEOUT_MS": "1800000"
}
}
}
}get_session_summary (EnrichedSummary)Returns structured JSON instead of formatted text. The calling LLM reads the data and synthesizes a concise summary — zero extra API cost.
{
"sessionDuration": "116min",
"messageDensity": "low",
"classifiedBash": [{ "cmd": "npm test", "category": "test" }],
"errorsWithContext": [{ "message": "...", "trigger": "Bash", "relatedFile": "src/server.ts" }],
"fileChangeGroups": [{ "directory": "src", "created": ["git.ts"], "modified": [] }],
"dedupedRequests": ["refactor summary to structured JSON"],
"decisions": ["use Jaccard trigram for dedup"],
"toolStats": { "Bash": 93, "Read": 39, "Edit": 38 },
"gitActions": ["git commit -m \"feat: ...\"", "git push origin main"]
}get_git_logsCollect git commit history across all discovered projects:
[
{
"project": "/Users/user/project",
"projectName": "my-app",
"commits": [
{ "hash": "a1b2c3d", "message": "feat: add auth", "author": "user", "date": "2026-05-20T10:00:00+08:00", "files": ["src/auth.ts"] }
]
}
]┌───────────────────┐ stdio ┌──────────────────┐ read ┌──────────────────────────┐
│ MCP Client │◄─────────►│ session-insight │◄──────────►│ ~/.claude/projects/ │
│ Claude/OpenCode/ │ JSON │ server │ │ ~/.local/share/opencode/ │
│ Codex │ │ │ │ ~/.codex/sessions/ │
└───────────────────┘ └───────┬──────────┘ └──────────────────────────┘
│
┌──────┴──────┐
│ Provider │
│ Registry │
└──────┬──────┘
│
┌──────┴──────┐
│ Extractor │ Git Log
│ (summary, │ Collector
│ classify, │
│ dedup, │
│ errors) │
└─────────────┘Key design decisions:
Stateless — no app-owned database, no persistence, reads existing session stores on each request
Fixture-friendly providers — provider roots are configurable so tests do not scan real local history
LLM-friendly output — structured JSON that the calling LLM synthesizes into natural language
npm install
npm test # run tests with vitest
npm run build # compile TypeScript
npm start # start MCP serverMIT
Collect git commit logs across projects. Returns structured JSON grouped by project. Only call this if the user explicitly asks for git logs or commit history.
| Name | Required | Description | Default |
|---|---|---|---|
| since | No | Start date (YYYY-MM-DD or "yesterday"), default: today | |
| until | No | End date (YYYY-MM-DD), default: tomorrow (inclusive) | |
| project | No | Project path filter (partial match, e.g. "mcp-session") | |
| author | No | Git author name filter |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations present, so description must carry full burden. It reveals output format (structured JSON grouped by project) but does not disclose safety, side effects, or permissions. Adequate but not thorough.
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. Every word serves a purpose with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 4 parameters with full schema, no output schema, and good annotations, the description covers purpose, usage, and output format. Could include an example but still complete enough for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All four parameters are fully described in the input schema with 100% coverage. The description adds no extra meaning beyond what's in the schema, so 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?
Description clearly states it collects git commit logs across projects and returns structured JSON grouped by project. This is distinct from all sibling tools which focus on 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?
Explicitly states: 'Only call this if the user explicitly asks for git logs or commit history.' Provides clear context for when to use, though no alternatives are mentioned since siblings are unrelated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get file changes (created/modified) for a session. Only call this if the user explicitly asks for file changes.
| Name | Required | Description | Default |
|---|---|---|---|
| session_id | Yes | Session ID (supports prefix match) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description only states what the tool does without disclosing any behavioral traits such as side effects, permissions, or rate 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?
Two short sentences, no fluff, directly conveys the essential information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and no annotations, the description is minimal and does not explain what 'file changes' entails or the structure of the response, leaving some 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?
Schema coverage is 100%, and the description adds no extra meaning beyond the schema's description. 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 verb 'get' and the resource 'file changes for a session', distinguishing it from sibling tools which retrieve other session-related data.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit instruction 'Only call this if the user explicitly asks for file changes' provides clear when-to-use guidance, effectively preventing misuse.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get conversation messages for a session
| Name | Required | Description | Default |
|---|---|---|---|
| session_id | Yes | Session ID (supports prefix match) | |
| role | No | Message role filter | all |
| limit | No | Max messages |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description bears full responsibility for behavioral disclosure. It fails to mention that the tool is read-only, what the response contains, or any edge cases (e.g., empty sessions).
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 sentence and concise, but it merely restates the tool name without adding substantive value. It earns its place but could be more informative.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has three parameters and no output schema or annotations, the description is incomplete. It does not explain the output format, pagination, or how to interpret returned messages.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds no additional parameter context 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 the verb 'Get' and the resource 'conversation messages', and given sibling tools like get_session_changes and get_session_decisions, it effectively distinguishes itself as the tool for retrieving chat history.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like get_session_errors or get_session_todos. No when-to-use or when-not-to-use context is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get decisions for a session. Only call this if the user explicitly asks for decisions.
| Name | Required | Description | Default |
|---|---|---|---|
| session_id | Yes | Session ID (supports prefix match) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavior. It does not mention side effects, permissions, rate limits, or response structure. The only behavioral hint is 'supports prefix match' for the parameter.
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, front-loaded with purpose, and every word adds value. 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?
Given no output schema and sibling tools that likely return different structures, the description lacks details about the return format (e.g., list of decisions, data fields). Users might need to infer behavior from context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage for session_id with description 'Session ID (supports prefix match)'. The description adds the prefix-match behavior beyond the schema, adding value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves decisions for a session, using the specific verb 'get' and resource 'decisions'. This distinguishes it from sibling tools like get_session_changes or get_session_errors.
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 'Only call this if the user explicitly asks for decisions', providing a clear usage condition. However, it does not offer alternatives or state when not to use it beyond that condition.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get errors/issues for a session. Only call this if the user explicitly asks for errors.
| Name | Required | Description | Default |
|---|---|---|---|
| session_id | Yes | Session ID (supports prefix match) |
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 does not disclose behavioral traits such as read-only status, potential side effects, or response format. The only addition beyond the schema is the usage condition, which is more about guidelines than behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short, focused sentences: first states the purpose, second adds a usage guideline. No wasted words; every sentence contributes 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 tool with one parameter and no output schema, the description covers basic purpose and usage condition. However, it lacks behavioral transparency (e.g., read-only hint, response type) that would make it fully complete without relying on other cues.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with one parameter (session_id) already described in the input schema as 'Session ID (supports prefix match)'. The description does not add any further semantic meaning beyond what the schema 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 states 'Get errors/issues for a session' clearly identifying the verb and resource. However, it does not differentiate from sibling tools like get_session_changes or get_session_summary, which also retrieve session-specific data. The additional usage note helps, but sibling differentiation is missing.
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 'Only call this if the user explicitly asks for errors,' providing a clear condition for invocation. It does not specify when not to use or mention alternatives, but the condition is strong enough for guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get deduplicated user requests for a session. Only call this if the user explicitly asks for user requests.
| Name | Required | Description | Default |
|---|---|---|---|
| session_id | Yes | Session ID (supports prefix match) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description does not disclose any behavioral traits beyond the basic action (get, deduplicated). There is no mention of side effects, authentication, rate limits, or output details, which is a gap for a read operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with two sentences, no redundant information, and the purpose is stated upfront. 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?
For a simple tool with one parameter and no output schema, the description is adequate but lacks information about the return format or any additional context about what 'deduplicated user requests' entails. It is minimally 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 single parameter session_id is fully described in the schema (100% coverage). The tool description adds no additional semantic information beyond what the schema provides, so a 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 that the tool retrieves deduplicated user requests for a session. While it distinguishes from siblings by specifying 'user requests', it does not explicitly contrast with other get_session_* tools, but the purpose is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The explicit instruction 'Only call this if the user explicitly asks for user requests' provides clear usage context. It does not mention when not to use or alternatives, but the guidance is sufficient for this specific tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a comprehensive summary for a session. Returns structured JSON data (EnrichedSummary). Based on this data, synthesize a concise Chinese summary for the user covering: what was done, key files changed, errors encountered, and decisions made. This is the SINGLE tool to call when the user wants to understand what happened in a session. Do NOT call other tools after this.
| Name | Required | Description | Default |
|---|---|---|---|
| session_id | Yes | Session ID (supports prefix match) |
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 states it returns EnrichedSummary but then instructs the user to synthesize a Chinese summary from it, creating ambiguity about whether the tool itself performs synthesis. This partially obscures the direct output 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 somewhat verbose with instructions on how to use the output (synthesize a Chinese summary). The essential purpose is clear but could be more 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?
Given no annotations, no output schema, and a tool with important behavior (returning a summary), the description lacks details about the output structure, error handling, and what constitutes 'EnrichedSummary.' It is not complete for an agent to confidently invoke.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the description adds value by noting that session_id supports prefix match, which is not present in the schema definition.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns a comprehensive summary for a session and explicitly distinguishes it from 10 sibling tools by declaring it the single tool to call for understanding a session.
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: 'This is the SINGLE tool to call when the user wants to understand what happened in a session. Do NOT call other tools after this.' It sets clear context and exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get todo snapshots for a session. Only call this if the user explicitly asks for todo progress.
| Name | Required | Description | Default |
|---|---|---|---|
| session_id | Yes | Session ID (supports prefix match) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, and the description only says 'Get todo snapshots', implying a read operation. It does not disclose any behavioral details such as auth requirements, data freshness, or side effects. The description carries the full burden and falls short.
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. First sentence states purpose, second provides usage guidance. Highly efficient 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 the tool's simplicity (1 param, no output schema), the description is adequate. It explains what it does and when to use. No obvious gaps, though it could clarify what 'todo snapshots' contain.
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% (session_id with description). The description adds 'snapshots' context but does not elaborate on parameter meaning beyond the schema. 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?
Description clearly states the action ('Get todo snapshots') and resource ('for a session'). The conditional 'Only call this if the user explicitly asks for todo progress' distinguishes it from sibling tools like get_session_changes or get_session_summary.
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 call the tool: only when the user asks for todo progress. While it doesn't mention alternatives or when not to use, the conditional is clear and sufficient for this simple tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all sessions, optionally filtered by project
| Name | Required | Description | Default |
|---|---|---|---|
| project | No | Project path filter | |
| limit | No | Max results |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fails to disclose behavioral traits such as pagination, sorting, or whether the list includes all fields or summaries. It only restates the basic function.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise single sentence with no wasted words. It gets straight to the point and is easily scannable.
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 lack of output schema and the presence of many sibling tools, the description is too minimal. It does not explain what information is returned for each session, making it difficult for an agent to decide if this tool meets its needs.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the description adds no additional meaning beyond what the schema already provides for the two parameters. The mention of optional filtering mirrors the project 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 clearly states the tool lists all sessions with optional project filtering, which is a specific verb+resource. It distinguishes from sibling tools that focus on individual session details (e.g., get_session_*) but doesn't explicitly differentiate from 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?
No guidance on when to use this tool versus alternatives like search_sessions or show_session. The description only hints at optional filtering but lacks context for appropriate use cases or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search sessions by keyword
| Name | Required | Description | Default |
|---|---|---|---|
| keyword | Yes | Search keyword |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden for behavioral disclosure. It only states the basic operation without mentioning whether it is read-only, if pagination occurs, or what the response format is. This is insufficient for an agent to understand side effects or constraints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence, very concise and front-loaded. It could be improved by adding brief context without becoming verbose, but currently it is 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 simplicity (1 param, no output schema), the description is incomplete. It lacks details on what is searched (e.g., session names, content), case sensitivity, prefix/partial matching, and expected output. A search tool should provide more context for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 100% coverage describing 'keyword' as a search keyword, and the description adds no further meaning. Baseline 3 is appropriate since the schema already explains the parameter, but the description offers no additional semantic value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description states verb 'search' and resource 'sessions' with qualifier 'by keyword', clearly conveying basic purpose. However, it does not differentiate from sibling tools like list_sessions or get_session_conversation, and could specify what aspects of sessions are searched (e.g., titles, content).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No usage guidelines provided. The description does not indicate when to use search_sessions versus alternatives like list_sessions (for listing all sessions) or get_session_conversation (for retrieving specific content).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Show metadata for a session (project, time, message count). Use this for a quick overview. For full content, use get_session_conversation or get_session_summary.
| Name | Required | Description | Default |
|---|---|---|---|
| session_id | Yes | Session ID (supports prefix match) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description implies a read-only operation with no side effects, but no annotations are provided. It could mention that the tool does not modify state, but the verb 'show' is clear enough.
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 filler, front-loaded with purpose followed by 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 lists specific metadata fields, providing a good overview. Could improve by specifying exact return format, but adequate 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 description coverage is 100% for the single parameter, which already states 'Session ID (supports prefix match)'. The tool description adds no extra meaning beyond tying the parameter to the session.
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 shows metadata (project, time, message count) for a session, and distinguishes from siblings by directing to other tools for full content.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Use this for a quick overview' and 'For full content, use get_session_conversation or get_session_summary', providing direct when-to-use and when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.4.0get_git_logsget_session_changesget_session_conversationget_session_decisionsget_session_errorsget_session_requestsget_session_summaryget_session_todoslist_sessionssearch_sessionsshow_sessionScored across 11 tools
Each tool targets a distinct aspect of sessions (git logs, changes, conversation, decisions, errors, requests, summary, todos, listing, searching, metadata). Descriptions include explicit guidance on when to use each, preventing confusion.
All tools follow a consistent verb_noun pattern (e.g., get_git_logs, get_session_changes, list_sessions) using snake_case, with no deviations or mixed conventions.
With 11 tools, the server thoroughly covers session insight without redundancy. Each tool serves a unique query, fitting the scope well.
The tool set covers all common retrieval needs for session analysis (metadata, conversation, changes, errors, decisions, etc.), with no obvious gaps for a read-only insight server.
Persistent, governed institutional memory for Claude Code — specs, decisions, learnings.
Persistent cross-session memory shared by Codex, Claude Code, ChatGPT, and other AI agents.
One searchable history across every AI coding tool, with secret scanning and a shared task board.
Persistent memory for Claude Code and Cursor. Stop re-explaining your project every session.
