[lit26]

Summary

MCP server tools no longer enter the prompt by default; the Step profile's existing find_tools loads the ones a turn needs.

No new tool name is introduced. find_tools already shipped in the Step tool profile and could only see tools that were already active. This change gives it a ranked, activating implementation and an exposure model that leaves tools registered but undeclared.

find_tools before and after

	before	after
Ranker	lowercase includes count per query token	Okapi BM25, name-field weighted, exact-name first, then coverage
Pool	active tools only (ExtensionContext.getToolCatalog())	deferred tools not yet active, plus active ones
Activation	none, it could only describe what was already declared	activates the deferred matches; they are declared on the next request
Answer	N. name [score=…] + description + schema	same numbered format, plus Newly available from your next call: …
Host plumbing	getToolCatalog()	getActiveTools() / getAllTools() / setActiveTools(); a host with only getToolCatalog() still gets the ranked answer, just without activation

The ranking lives in packages/coding-agent/src/core/tools/tool-search.ts (module name only). The tool_search tool and extension from the first commit were deleted in the second; squash on merge if you prefer a single commit.

Changes

• ToolDefinition.exposure:
  • direct (default): declared and active at session start.
  • deferred: registered, undeclared, loaded on demand by find_tools.
  • hidden: registered, unreachable, and left out of getAllTools().
  • An explicit selection still wins: a name in defaultTools activates a deferred tool, as does the --tools allowlist.
• src/step/mcp.ts: server tools publish as deferred by default. New per-server config.toml keys exposure and description.
• renderMcpServersSection(): a # MCP servers system-prompt section listing deferred servers with their one-line summary. Neither the declared tool list nor find_tools names them, so without this section the model cannot know they exist.
• ExtensionContext: getActiveTools(), getAllTools(), setActiveTools(), wired through the runner's existing session actions.
• step/permissions.ts: find_tools is read-only — it changes the session tool set and touches no files.

Review focus

• The default flip. Deferred is the default for every MCP server, so a model that never calls find_tools loses access to MCP tools. The prompt section is the mitigation. If that trade is too sharp for a default, the alternative is direct by default with per-server opt in — a one-line change in serverExposure().
• Activation semantics. find_tools only ever adds tools, never removes them, so the additive-activation path that records addedToolNames applies and the change survives resume and fork.

Configuration

[mcp_servers.github]
url = "https://api.githubcopilot.com/mcp/"
description = "GitHub issues and pull requests"
# exposure = "direct"   # small, frequently called server

Existing configs keep working: unknown keys are ignored, and a server without exposure becomes deferred.

Verification

• pnpm run check clean (biome, boundary checks, tsgo --noEmit, browser smoke).
• test/tool-search.test.ts — 16 tests: tokenizer and BM25 ordering, activation, deferred/direct/hidden session behavior, settings-based activation, read-only permission decision for find_tools.
• test/tool-search-integration.test.ts — 2 end-to-end agent turns on the faux provider with the real Step profile: the deferred tool is absent from request 1, declared on request 2, and addedToolNames records the activation.
• test/tool-search-mcp.test.ts — 2 end-to-end turns against a real streamable-HTTP MCP peer: deferred by default, the prompt section appears, find_tools loads the tool, the model calls it and the server receives the arguments; a direct server is declared without the section.
• Updated for the behavior change: src/step/mcp-startup.test.ts (+3 exposure and section tests), src/step/mcp-catalog.test.ts (late catalog and removal observed through find_tools), test/step-tool-profile.test.ts (description).
• 263 related tests green; 128 more across system prompt, extension catalog, and live context.
• Manual run with a real model and the CLI: pnpm step --approval-mode auto -e ./demo.ts "Find a tool that can look up weather, load it, then call it for Paris." loads weather_lookup through find_tools and answers sunny in Paris, with no settings or config change.
• A full vitest --run in this checkout fails 30 pre-existing tests that need a real provider credential (No API key found for step); unrelated.

Unit and end-to-end tests use the faux provider; no paid model requests.

Not in this change

• No codemode scripts and no searchTools(): Step has no codemode surface, so deferred is the only indirect exposure.
• No per-tool toolExposure patterns (get_*, delete_*): exposure is per server.
• Native deferred-declaration protocol paths (Anthropic tool_reference, OpenAI tool_search_call) already exist in packages/providers; this change relies on the existing additive-activation plumbing.