docs(oracle): enrich MCP + OpenAPI discovery guidance for LLM clients

MCP server instructions and the OpenAPI info.description now describe the recommended workflow, project_path requirement, capability tiers, Bearer auth, and invocation, so Claude (MCP) and generic function-calling LLMs (REST) orient the same way.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: drknowhow

CHANGELOG.md

@@ -6,6 +6,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Changed
+
+- Discovery API guidance enriched for LLM clients: the MCP server `instructions` and the
+  OpenAPI `info.description` now spell out the recommended workflow (`list_projects` →
+  cross-project search → `c3_compress`/`c3_read`), the `project_path` requirement, the
+  read/safe-action capability tiers, Bearer auth, and how to invoke tools — so Claude (MCP)
+  and generic function-calling LLMs (REST) orient the same way.
+
 ### Fixed
 
 - **Ghost files (0-byte) from shell-redirect misinterpretation.** The output filter

oracle/mcp_oracle.py

@@ -23,12 +23,19 @@
 logger = logging.getLogger("oracle.mcp")
 
 _INSTRUCTIONS = (
-    "C3 Oracle Discovery — cross-project code & memory intelligence as tools. "
-    "Start with list_projects to see available projects, then use c3_search_cross "
-    "or search_facts to discover across all of them, or the per-project tools "
-    "(c3_search, c3_read, c3_compress, query_memory, read_graph) with a project_path. "
-    "suggest_action creates a PENDING suggestion for human approval; delegate_task runs "
-    "a configured Oracle agent. No code-editing tools are exposed."
+    "C3 Oracle Discovery — use C3's cross-project code & memory intelligence as tools.\n"
+    "\n"
+    "Recommended workflow:\n"
+    "1. list_projects — see which C3 projects exist (names + absolute paths).\n"
+    "2. Discover across ALL projects: search_facts (memory) or c3_search_cross (code).\n"
+    "3. Narrow to one project using its path: c3_search to find code; c3_compress "
+    "(mode='map') to see a file's shape before reading; c3_read for exact content; "
+    "query_memory / read_graph / cross_insights for that project's memory.\n"
+    "\n"
+    "Notes: per-project tools REQUIRE a `project_path` taken from list_projects. Every tool "
+    "returns JSON. suggest_action creates a PENDING suggestion for a human to approve (not a "
+    "direct write); delegate_task runs a configured Oracle agent. Read + safe-action tiers "
+    "only — no code-editing tools are exposed."
 )
 
 

oracle/services/tool_registry.py

@@ -398,8 +398,23 @@ def openapi_spec(self, server_url: str = "") -> dict:
             "info": {
                 "title": "C3 Oracle Discovery API",
                 "version": _c3_version(),
-                "description": "Read + safe-action discovery tools over C3's cross-project code and "
-                               "memory intelligence, for use by external LLMs.",
+                "description": (
+                    "Use C3's cross-project code & memory intelligence as tools, for external LLMs.\n\n"
+                    "**Workflow:** call `list_projects` first to get project names + absolute paths; "
+                    "discover across all projects with `search_facts` (memory) or `c3_search_cross` "
+                    "(code); then narrow to one project (pass its `project_path`) using `c3_search`, "
+                    "`c3_compress` (mode `map` to see a file's shape before reading), `c3_read` (exact "
+                    "content), `query_memory`, `read_graph`, or `cross_insights`.\n\n"
+                    "**Auth:** every request requires an `Authorization: Bearer <token>` header "
+                    "(get it from `/api/discovery/mcp-info` or by running `c3 oracle api info`).\n\n"
+                    "**Capability tiers:** `read` tools are pure discovery; `action` tools are safe and "
+                    "non-destructive — `suggest_action` creates a PENDING suggestion for human approval "
+                    "(not a direct write) and `delegate_task` runs a configured Oracle agent. No "
+                    "code-editing tools are exposed.\n\n"
+                    "**Invoke:** POST the arguments object to `/api/discovery/tools/{name}`, or POST "
+                    "`{\"tool\": \"<name>\", \"args\": {...}}` to `/api/discovery/call`. Per-project "
+                    "tools require a `project_path` from `list_projects`."
+                ),
             },
             "security": [{"bearerAuth": []}],
             "components": {