codemap_edit_summary

Update an existing stored summary for a file. Errors with NO_SUMMARY_FOUND if no summary exists yet — use codemap_set_summary to create one first. Returns the previous value.

iosummarydocumentationmetadataupdate

Parameters

Name	Type	Required	Description
`filePath`	`string`	✅ Required	Relative path to the file
`summary`	`string`	✅ Required	Updated plain-language description (max 300 chars)

Usage Examples

MCP Usage (for AI Agents like Claude)

typescript

codemap_edit_summary({
  filePath: "src/core/GroupStore.ts",
  summary: "Persistent group storage with file-based JSON backend, backup rotation, and lazy loading."
})

Example Output

JSON Response

json

{
  "success": true,
  "data": {
    "filePath": "src/core/GroupStore.ts",
    "summary": "Persistent group storage with file-based JSON backend, backup rotation, and lazy loading.",
    "previous": "Persistent code group storage. File-based .codemap/groups.json with backup support.",
    "action": "updated"
  }
}

ℹ️When to Use This Tool

codemap_edit_summary

Update a stored summary and want an explicit error if it doesn't exist — prevents silent creation
Refactor summaries after a module's responsibility changes materially
Capture the previous summary text for audit logs, changelogs, or rollback tracking

💡Common Patterns

Update-only guard pattern

codemap_edit_summary  
  → NO_SUMMARY_FOUND → skip or fall back to set_summary
  → success → safe update confirmed

Use when you're scripting over a file list and only want to touch files that already have agent-maintained summaries.

Audit-aware refactor pattern

codemap_edit_summary  
  → capture result.previous
  → log { file, before, after, at }

Great for change-tracking when you're updating summaries across a large module reorganization.

💡Pro Tips

Treat NO_SUMMARY_FOUND as a feature, not a bug. It lets you distinguish between "first time documenting this file" and "refining existing documentation" without ambiguity.
Use the previous field for diff context. The old summary in the response is the single best signal for whether your edit actually changed meaning or was just a re-phrasing.
Chain with get-annotations or peek. After editing a summary, a follow-up codemap_peek shows the new summary alongside the current symbol graph — confirms it landed.

✅Best Practices

Prefer edit-summary over set-summary when you expect the summary to already exist — the error behavior catches typos in filenames that set-summary would silently "create around"
Keep the same voice and word count range across edits — summaries are discovered together in search and consistency helps scanning
When editing, re-read the actual file briefly to confirm the new summary still accurately describes the file's current purpose
Don't edit a summary purely for style; wait until you have a real semantic change to make

⚠️Common Mistakes

❌ Mistake: Using edit-summary for a file that never had a summary, expecting implicit creation
✅ Instead: Use codemap_set_summary — it creates or updates with no error, and returns the same action: "created" | "updated" field

❌ Mistake: Ignoring the previous field in the response
✅ Instead: Compare previous vs summary to confirm your edit actually changed meaning before moving on

❌ Mistake: Editing a summary every time a file changes
✅ Instead: Only edit when the file's *responsibility* changes — a new private method or internal refactor usually doesn't warrant a summary update

Changelog

1 release

- 🆕AddedNew tool added

Parameters

Usage Examples

MCP Usage (for AI Agents like Claude)

Example Output

JSON Response

Related Tools

codemap_io_set-summary

codemap_io_remove-summary

codemap_search_search

codemap_search_find-relevant