codemap_set_summary
Set or update the plain-language summary for a file. Creates the summary if none exists; updates it if one already does. Becomes immediately searchable with no rescan required.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
filePath | string | ✅ Required | Relative path to the file (e.g., "src/core/Scanner.ts") |
summary | string | ✅ Required | Plain-language description of the file's purpose (max 300 chars) |
Usage Examples
MCP Usage (for AI Agents like Claude)
typescript
codemap_set_summary({
filePath: "src/core/GroupStore.ts",
summary: "Persistent code group storage. File-based .codemap/groups.json with backup support. Handles load, save, and validation."
})Example Output
JSON Response
json
{
"success": true,
"data": {
"filePath": "src/core/GroupStore.ts",
"summary": "Persistent code group storage. File-based .codemap/groups.json with backup support. Handles load, save, and validation.",
"action": "created",
"source": "agent"
}
}When to Use This Tool
-
Use
- Document a file immediately after creating it so it becomes searchable by purpose, not just filename
- Override an auto-extracted heuristic summary that's imprecise or out of date
- Give cryptically-named files (
utils.ts,helpers.ts,index.ts) a meaningful searchable description - Seed a codebase with authoritative summaries before onboarding new contributors or AI agents
codemap_set_summary when you need to:
Common Patterns
Create-then-document pattern
Cleaner alternative: pass
Walk-and-document onboarding flow
codemap_create src/core/RateLimiter.ts (with content)
codemap_set_summary src/core/RateLimiter.ts "Token bucket rate limiter for API endpoints"Cleaner alternative: pass
summary directly to codemap_create in one call. Use set_summary separately only when documenting files that already exist.Walk-and-document onboarding flow
codemap_peek src/services/ (symbols: true)
→ review what each service does
codemap_set_summary for each file with a clear one-line description
codemap_search "" → files now surface by documented purpose Pro Tips
- Keep summaries under 200 chars even though the limit is 300. Shorter summaries render cleaner in search results and are easier to scan.
- Lead with the subject, not the verb.
"Persistent group storage..."beats"Handles persistent group storage..."— the first word is what readers scan. - Agent summaries beat heuristics permanently. Once you set a summary, the heuristic extractor will not overwrite it on subsequent scans. Use
codemap_remove_summaryto hand control back.
Best Practices
- Run
codemap_set_summaryon every file you create — make it a reflexive habit - Update summaries whenever a file's responsibility shifts meaningfully (new public API, scope change)
- Keep summary text in the same voice across the codebase (present tense, third-person, no first-person pronouns)
- Include 2-3 keywords that a future searcher might query on (e.g. mention "rate limit" in a rate limiter summary)
Common Mistakes
❌ Mistake: Writing summaries as code comments —
✅ Instead: Plain prose with no comment syntax — the UI renders this as-is
❌ Mistake: Repeating the filename in the summary —
✅ Instead: Assume the reader already sees the filename —
❌ Mistake: Exceeding 300 characters and getting a validation error
✅ Instead: Tighten to the file's single clearest responsibility; move detail to JSDoc
"// Handles X" or "/* Does Y */"✅ Instead: Plain prose with no comment syntax — the UI renders this as-is
❌ Mistake: Repeating the filename in the summary —
"GroupStore.ts: Store for groups"✅ Instead: Assume the reader already sees the filename —
"Persistent code group storage with backup rotation"❌ Mistake: Exceeding 300 characters and getting a validation error
✅ Instead: Tighten to the file's single clearest responsibility; move detail to JSDoc
Changelog
1 release- 🆕AddedNew tool added