diff --git a/CHANGELOG.md b/CHANGELOG.md
index 935f004..3e6f4a3 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- **Context diagnostics**: `codebase_context` now supports an optional `diagnostic` flag across MCP, OpenCode, and Pi. It exposes bounded routing, retrieval, and evidence-pack traces for troubleshooting without changing normal text output.
+
 ### Fixed
 
 - **Cross-repo comparison latency**: Omit non-comparable CodeGraph CLI startup time from fair quality tables while retaining raw timing artifacts for diagnostics.
diff --git a/docs/tools.md b/docs/tools.md
index 35ffe82..236eb55 100644
--- a/docs/tools.md
+++ b/docs/tools.md
@@ -75,6 +75,8 @@ Preferred entry point for general repository questions. It returns a bounded, de
 
 Important options include result limits, file and directory filters, path disambiguation, and a `tokenBudget` from 128 to 4000 tokens.
 
+Set `diagnostic: true` when troubleshooting a surprising result. MCP returns the normal text response unchanged and provides bounded routing, retrieval, and evidence-pack traces as structured content. OpenCode and Pi render the same diagnostics alongside the normal response. Leave it unset during normal use.
+
 ### `codebase_peek`
 
 Returns likely locations and metadata without full source bodies. Use it when you want to choose files before reading them.