Skip to main content
hc
Submit
guidesSource-backedReview first Safety ✓ Privacy ✓

Tool Search For Agents With Large MCP Tool Sets

Configure Claude Agent SDK and Claude Code tool search so large MCP catalogs defer schemas until needed, using ENABLE_TOOL_SEARCH modes, alwaysLoad discipline, and context budgeting from official tool-search documentation.

by kiannidev·added 2026-06-16·
Claude Code
HarnessClaude Code
Review first — review before installing

Open the source and read safety notes before installing.

Safety notes

  • Deferred tools still execute with full permissions once discovered—scope allowlists.
  • alwaysLoad on large servers negates tool search benefits.
  • Tool search adds a discovery step; verify critical tools are reachable under load.

Privacy notes

  • Tool schemas may describe internal APIs—treat deferred catalogs as sensitive config.
  • Search queries sent to discover tools enter model context like other prompts.

Prerequisites

  • Multiple MCP servers or large tool catalogs in Agent SDK or Claude Code.
  • Ability to set ENABLE_TOOL_SEARCH and edit .mcp.json alwaysLoad flags.
  • Representative tasks showing which tools are needed every turn versus rarely.

Schema details

Install type
copy
Reading time
8 min
Difficulty score
56
Troubleshooting
Yes
Breaking changes
No
Full copyable content
When MCP servers expose dozens of tools, enable tool search deferral, reserve alwaysLoad for small always-on servers, and monitor context with /context.

About this resource

TL;DR

Tool search keeps large MCP catalogs out of the initial context by deferring tool definitions until Claude needs them. Use default deferral, tune ENABLE_TOOL_SEARCH, and mark only tiny servers with alwaysLoad: true.

Step-by-Step Guide

  1. Inventory MCP servers and tool counts per server.
  2. Identify tools required on every turn (mark server alwaysLoad: true only if small).
  3. Leave tool search enabled for catalog servers with many tools.
  4. Set ENABLE_TOOL_SEARCH=auto if you want upfront load until 10% context threshold.
  5. Run /context before and after changes to measure savings.
  6. Test tasks that need rare tools to confirm discovery still works.

Troubleshooting

Issue: Claude never finds a rare tool Fix: Temporarily alwaysLoad that server or improve tool descriptions.

Issue: Context still full at start Fix: Remove alwaysLoad from large servers; reduce built-in tool list.

Source Verification Notes

Verified against Agent SDK tool-search and MCP docs on 2026-06-16: default deferral, ENABLE_TOOL_SEARCH modes, and alwaysLoad behavior.

Duplicate Check

Complements controlling-mcp-result-size-and-context-pressure (output token limits).

References

#agent-sdk#mcp#tool-search#context-window#claude-code

Source citations

Add this badge to your README

Show that Tool Search For Agents With Large MCP Tool Sets is listed on HeyClaude. Paste this Markdown into your README — it renders the badge and links back to this page.

Listed on HeyClaude
[![Listed on HeyClaude](https://heyclau.de/badge/guides/tool-search-for-agents-with-large-mcp-tool-sets.svg)](https://heyclau.de/entry/guides/tool-search-for-agents-with-large-mcp-tool-sets)

How it compares

Tool Search For Agents With Large MCP Tool Sets side by side with 3 alternatives on trust, install, platform support, and disclosed safety notes — all from reviewed registry metadata.

FieldTool Search For Agents With Large MCP Tool Sets

Configure Claude Agent SDK and Claude Code tool search so large MCP catalogs defer schemas until needed, using ENABLE_TOOL_SEARCH modes, alwaysLoad discipline, and context budgeting from official tool-search documentation.

Open dossier 		Controlling MCP Result Size And Context Pressure

Reduce Claude Code context pressure from MCP tools using MAX_MCP_OUTPUT_TOKENS, anthropic/maxResultSizeChars annotations, tool search deferral, alwaysLoad discipline, and pagination patterns from official MCP documentation.

Open dossier 		Claude Code JetBrains Setup for Large Repositories

Configure Claude Code in JetBrains IDEs for large repositories: terminal rendering fixes, synchronized output, sparse context, and plugin workflows for IntelliJ-based teams.

Open dossier 		Claude Code on Amazon Bedrock Setup

Configure Claude Code on Amazon Bedrock: AWS region resolution, GovCloud inference profiles, credential export caching, service tiers, and CI empty-string pitfalls.

Open dossier
Trust
Install riskReview firstReview firstReview firstReview first
Notes Safety ✓ Privacy ✓ Safety ✓ Privacy ✓ Safety ✓ Privacy ✓ Safety ✓ Privacy ✓
Categoryguidesguidesguidesguides
Sourcesource-backedsource-backedsource-backedsource-backed
Authorkiannidevkiannidevkiannidevkiannidev
Added2026-06-162026-06-162026-06-142026-06-14
Platforms
Claude Code
Claude Code
Claude Code
Claude Code
Source repo————
Safety notes✓Deferred tools still execute with full permissions once discovered—scope allowlists. alwaysLoad on large servers negates tool search benefits. Tool search adds a discovery step; verify critical tools are reachable under load.✓Raising output limits increases context cost and may hide the need to paginate server responses. alwaysLoad: true on large servers loads every tool schema at session start—use sparingly. Truncated MCP output can omit fields needed for security review; verify critical data separately.✓Large-repo sessions amplify token usage—use sparse context and compaction hygiene to avoid runaway costs. JetBrains terminals on 2026.1+ use synchronized output; avoid custom ANSI themes that fight IDE rendering. Do not mount entire monorepo secrets into agent sessions; scope working directories per module.✓Bedrock credentials in shared CI must use OIDC or short-lived role assumption—not long-lived access keys in repos. Auto mode on Bedrock requires explicit `CLAUDE_CODE_ENABLE_AUTO_MODE=1` opt-in on third-party providers. Model picker may list models your account cannot serve—verify access before pinning defaults.
Privacy notes✓Tool schemas may describe internal APIs—treat deferred catalogs as sensitive config. Search queries sent to discover tools enter model context like other prompts.✓Large MCP payloads may contain secrets; shrinking output does not redact—sanitize at the server. Tool search defers schemas but invoked tools still return full results into context. Shared CI logs pasted through MCP can expose internal URLs in truncated previews.✓IDE-integrated sessions expose package names, module paths, and dependency graphs in prompts. Usage and session data follow the same data-usage policies as terminal Claude Code. Shared JetBrains licenses on VDI pools can leak session resumes—use per-developer config directories.✓Prompts and tool outputs flow through your AWS account boundary; align with AWS logging and CloudTrail retention. Cross-account `awsCredentialExport` paths may expose role ARNs in `/status` output during debugging. Do not embed customer payloads in prompts when Bedrock logging to third-party observability is enabled.
Prerequisites
  • Multiple MCP servers or large tool catalogs in Agent SDK or Claude Code.
  • Ability to set ENABLE_TOOL_SEARCH and edit .mcp.json alwaysLoad flags.
  • Representative tasks showing which tools are needed every turn versus rarely.
  • One or more MCP servers returning large JSON, logs, or file dumps.
  • Ability to set environment variables for Claude Code sessions.
  • Optional access to MCP server source to add pagination or size annotations.
  • Understanding of your project's context budget for long sessions.
  • JetBrains IDE 2025.2+ or 2026.1+ with the Claude Code plugin approved.
  • A large repository with documented sparse-context or monorepo CLAUDE.md hierarchy.
  • Sufficient heap for indexing; pilot on a representative module before org-wide rollout.
  • Team policy for MCP servers and permissions synced to IDE sessions.
  • AWS account with Bedrock model access for required Anthropic model IDs.
  • IAM role or credential chain reachable from developer laptops and CI runners.
  • AWS region decision documented, including GovCloud if applicable.
  • Network path to Bedrock endpoints through corporate proxy if required.
Install————
Config————
Citations
ClaimUnclaimedUnclaimedUnclaimedUnclaimed

Signals

Loading live community signals…

More like this, weekly

A short, calm digest of reviewed Claude resources. Unsubscribe any time.