fix(mcp): narrow Tempo Docs tool schema (#1230)

* fix(mcp): narrow Tempo Docs tool schema

Co-authored-by: Derek Cofausper <256792747+decofe@users.noreply.github.com>

* fix(mcp): annotate generated code tool

---------

Co-authored-by: Brendan Ryan <1572504+brendanjryan@users.noreply.github.com>

Author: decofe

apps/mcp-docs-indexer/README.md

@@ -73,7 +73,6 @@ The local `search` tool accepts Code Mode-friendly top-level controls:
 | `max_results`  | Maximum chunks to return; defaults to `5`                      |
 | `max_chars_per_chunk` | Maximum compact text chars per chunk; defaults to `1200` |
 | `max_total_chars` | Maximum total compact chunk text chars; defaults to `2400` |
-| `include_raw`  | Return full AI Search chunks instead of compact chunks         |
 | `response_format` | Use `structured` to return data in MCP `structuredContent` with a short text summary |
 
 When `source` and `sources` are omitted, the server applies a conservative
@@ -100,15 +99,16 @@ enters an MCP client's context window. Compact output also returns at most one
 chunk per page, preserving result diversity and avoiding repeated snippets from
 the same URL. Search text is bounded by `max_total_chars` after page
 deduplication, so broad searches cannot accidentally fill the client context
-with five large excerpts. Advanced `ai_search_options` are still accepted and
-normalized into the current AI Search binding shape.
+with five large excerpts. The public tool schema exposes only bounded,
+task-specific controls; upstream AI Search configuration and raw chunk
+responses are not advertised to MCP clients.
 
 Pass `response_format: "structured"` on `search`, `find_pages`, or `read_page`
 when the client can read MCP `structuredContent`; this keeps the text content to
 a short status line while preserving the same machine-readable result object.
 
 AI Search response caching is enabled by default with the `close_enough`
-threshold. Clients can override this with `ai_search_options.cache`.
+threshold.
 The Worker also keeps a small 60-second in-memory cache of successful search
 results per isolate to skip repeated AI Search round trips for identical
 normalized searches.

apps/mcp-docs-indexer/src/lib/mcp.test.ts

@@ -107,6 +107,18 @@ describe('handleMcp', () => {
 			body.result.tools.map((tool: { name: string }) => tool.name),
 		).toEqual(['search', 'find_pages', 'read_page', 'code'])
 		expect(body.result.tools[3].description).toContain('codemode.search')
+		expect(body.result.tools[3].annotations).toEqual({
+			destructiveHint: false,
+			idempotentHint: true,
+			openWorldHint: true,
+			readOnlyHint: true,
+		})
+		expect(body.result.tools[0].inputSchema.properties).not.toHaveProperty(
+			'include_raw',
+		)
+		expect(body.result.tools[0].inputSchema.properties).not.toHaveProperty(
+			'ai_search_options',
+		)
 	})
 
 	it('normalizes simple source and result controls into retrieval options', async () => {

apps/mcp-docs-indexer/src/lib/mcp.ts

@@ -378,7 +378,10 @@ async function listCodeTools(
 	const codeServer = await createCodeServer(tools, context)
 	return withMcpClient(codeServer, async (client) => {
 		const result = await client.listTools()
-		return result.tools
+		return result.tools.map((tool) => ({
+			...tool,
+			annotations: READ_ONLY_TOOL_ANNOTATIONS,
+		}))
 	})
 }
 
@@ -1484,15 +1487,6 @@ function toolSchemas(sources: Source[]): Tool[] {
 						minimum: 300,
 						maximum: 50000,
 					},
-					include_raw: {
-						type: 'boolean',
-						description: 'Return raw AI Search chunks.',
-					},
-					ai_search_options: {
-						type: 'object',
-						description: 'Advanced AI Search options.',
-						additionalProperties: true,
-					},
 					response_format: {
 						type: 'string',
 						enum: ['text', 'structured'],