[DOCS] Clarification of regex constraints and query limits in Tool Search Tool (Beta)

Documentation Type

Unclear/confusing documentation

Documentation Location

URL: https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-search-tool

Section/Topic

Section: Tool definition -> Deferred tool loading / Common mistakes

Current Documentation

Warning: Regex variant query format: Python regex, NOT natural language. When using tool_search_tool_regex_20251119, Claude constructs regex patterns using Python's re.search() syntax... Maximum query length: 200 characters.

Under Common Mistakes:

Claude doesn't find expected tools: Claude uses broad patterns like ".*weather.*" not exact matches.

Under Limits:

Maximum tools: 10,000 tools in your catalog.

What's Wrong or Missing?

The documentation presents a logical contradiction regarding the complexity of searches versus the restrictive character limit.

1. Tight Constraint for Large Catalogs: The documentation states support for up to 10,000 tools. However, the 200-character limit for regex queries is extremely restrictive if Claude needs to perform complex, multi-tool discovery using OR logic (e.g., (?i)weather_service|forecast_api|temperature_lookup|meteorology_stats).
2. Ambiguous "Exact Match" Guidance: The "Common Mistakes" section says Claude uses broad patterns and "not exact matches." This is confusing given that Python's re.search() (which the docs say is used) does support exact matches via ^ and $ anchors.
3. Implicit vs. Explicit Guidance: There is no guidance on how to handle the pattern_too_long error if Claude attempts to be too specific in a large library, nor is there a clear recommendation on when to prefer the BM25 variant over the Regex variant for large-scale (10k tool) catalogs.

Suggested Improvement

• Clarify Regex Behavior: Explain that while Claude defaults to broad patterns, users can instruct Claude to use anchors if exact matches are required.
• Provide "Multi-Tool" Examples: Add an example showing an efficient way to search for multiple relevant tool categories within the 200-character limit.
• Steer towards BM25 for Scale: Explicitly state that for very large catalogs (approaching 10,000 tools) where regex complexity might exceed 200 characters, the tool_search_tool_bm25_20251119 variant is the recommended choice for natural language discovery.

Suggested Text Addition:

Note on Regex Complexity: In large tool catalogs, Claude may attempt to combine multiple search terms. To avoid the pattern_too_long error, ensure your tool descriptions use shared keywords that allow for short, high-entropy regex patterns like (?i)finance|billing rather than listing every specific tool name. If your discovery needs are complex, use the BM25 variant which supports longer, natural language queries.

Impact

High - Prevents users from using a feature

Additional Context

In massive tool catalogs (the 10,000 limit mentioned), the "needle in a haystack" problem is significant. If the model is penalized for over-explaining or high token usage, it might try to "perfect" its tool search with long regex strings, which will then trigger a silent failure or an error from the 200-character truncation/limit. Clearer guidance helps developers decide which variant to implement to avoid these edge cases.