fix(mcp): explore's maxFiles text gives the real default, not 12

codegraph_explore's maxFiles parameter said "(default: 12)" and its
schema carried default: 12, but the handler picks 4, 5 or 8 files by
project size (clamped to 1 to 20), and nothing applies 12. A client that
fills in schema defaults sent maxFiles 12 and overrode the size-based
default. The description now gives the real default and says total
output is also capped in characters by project size, and the schema
default is gone. The query description no longer tells the agent it
needs no prior codegraph_search, a tool not on the default list.

explore-output-budget's small-tier test asserted that the output does
not contain "Complete source code is included above", text the
completeness note no longer has, so it could not fail. On this fixture
the note reads "Complete source for 1 file is included above", which
the PR's replacement ("files is included above") misses too. It now
checks "is included above", and the medium-tier test checks the note is
there, so a rewording can't leave the absence check behind again. With
the small tier's completeness note switched on, main's assertion and
the PR's both still pass, and this one fails. The interface comment
names the note by its current wording.

Left out of PR #1972: its rewrite of the server instructions' "Trust
codegraph's results" line, which is agent steering and needs an A/B
first; and its codegraph_node hint and footer changes, which main
already has (PRs #2783, #2077).

Original PR #1972 by @bompus.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

__tests__/explore-output-budget.test.ts

@@ -197,7 +197,10 @@ describe('codegraph_explore output respects the adaptive budget', () => {
     const result = await handler.execute('codegraph_explore', { query: 'Session method helper' });
     const text = result.content?.[0]?.text ?? '';
     expect(text).not.toContain('### Additional relevant files');
-    expect(text).not.toContain('Complete source code is included above');
+    // The completeness note, which reads "Complete source for 1 file is
+    // included above…" on this fixture ("Verbatim source for N files…" after
+    // a trim).
+    expect(text).not.toContain('is included above');
     expect(text).not.toContain('advisory only, NOT a quota');
   });
 
@@ -213,6 +216,9 @@ describe('codegraph_explore output respects the adaptive budget', () => {
       const text = result.content?.[0]?.text ?? '';
       expect(text).toContain('advisory only, NOT a quota');
       expect(text).toContain('extra calls are never rejected or rate-limited');
+      // The completeness note is on here, so the small tier's check for its
+      // absence above still names text the note has.
+      expect(text).toContain('is included above');
       expect(text).not.toContain('remaining calls');
       expect(text).not.toContain('Synthesize once');
     } finally {

src/mcp/tools.ts

@@ -296,7 +296,7 @@ export interface ExploreOutputBudget {
   includeRelationships: boolean;
   /** Include the "Additional relevant files (not shown)" trailing list. */
   includeAdditionalFiles: boolean;
-  /** Include the "Complete source code is included above…" reminder. */
+  /** Include the "… source for N files is included above" reminder. */
   includeCompletenessSignal: boolean;
   /**
    * Include the advisory exploration-guidance note at the end. Purely
@@ -1832,12 +1832,11 @@ export const tools: ToolDefinition[] = [
       properties: {
         query: {
           type: 'string',
-          description: 'Symbol names, file names, or short code terms to explore (e.g., "AuthService loginUser session-manager", "GraphTraverser BFS impact traversal.ts"). For a flow question, name the symbols spanning the flow (e.g. "mutateElement renderScene"). A natural-language question works too — no prior codegraph_search needed.',
+          description: 'Symbol names, file names, or short code terms to explore (e.g., "AuthService loginUser session-manager", "GraphTraverser BFS impact traversal.ts"). For a flow question, name the symbols spanning the flow (e.g. "mutateElement renderScene"). A natural-language question works too.',
         },
         maxFiles: {
           type: 'number',
-          description: 'Maximum number of files to include source code from (default: 12)',
-          default: 12,
+          description: 'Maximum number of files to return source from, 1–20. Omit it to use a default sized to the project (4 files below 150 indexed files, 5 below 500, 8 otherwise). Total output is also capped by characters (about 13K–24K by project size), so a higher maxFiles spreads that budget over more files rather than returning more text.',
         },
         projectPath: projectPathProperty,
       },