WebSearch tool does not support query operators, but agents construct queries as if it does — wasting tokens and producing degraded results

Preflight Checklist

• [x] I have searched existing issues and this hasn't been reported yet
• [x] This is a single bug report (please file separate reports for different bugs)
• [x] I am using the latest version of Claude Code

What's Wrong?

Claude agents using the WebSearch tool routinely construct search queries with advanced syntax operators — specifically quoted phrases for exact matching and boolean OR — that the tool does not support. The operators are silently ignored, meaning the actual queries sent to the search engine are degraded, unqualified keyword searches. The agent has no awareness of this and no feedback mechanism to detect or correct it. Tokens are wasted and research quality is lower than it appears.

Additionally, there is a documented limitation that Claude models (except Opus 4.6) cannot reliably emit literal double-quote characters inside tool call string parameters — meaning quoted phrases are silently stripped before reaching the search engine even if the tool were to support them.

What Should Happen?

Either:

1. The WebSearch tool should support standard query operators (exact phrase matching, boolean OR) and pass them correctly to the underlying search engine, or
2. The agent should be informed of the tool's query syntax limitations and construct plain natural language queries accordingly — not silently construct ineffective operator-based queries

Error Messages/Logs

The following are actual WebSearch query strings constructed by a claude-sonnet-4-6 agent during a research task. These were extracted from the raw agent transcript:

"docs/requirements" OR "docs/specs" OR "docs/functional" software project folder convention
"functional specification" "non-functional" requirements folder repository "docs" site:github.com
software specification document repository best practice "docs/requirements" OR "docs/specs" OR "docs/functional"
software project folder structure "docs/requirements" OR "docs/specs" OR "docs/functional" convention
github repository "docs/requirements" OR "requirements/functional" specification folder convention
"docs/specs" OR "docs/requirements" OR "docs/functional-spec" software project folder github convention 2024 2025

All quoted strings and OR operators in these queries were silently stripped or ignored before reaching the search engine.

Steps to Reproduce

1. Instruct a Claude agent to perform research on any multi-faceted topic using the WebSearch tool
2. Capture the raw agent transcript
3. Extract all WebSearch tool use blocks (type: "tool_use", name: "WebSearch") from the transcript
4. Inspect the query strings in the input field of each tool use block
5. Observe that the agent constructs queries containing quoted phrases and boolean OR operators
6. Compare against the WebSearch tool documentation, which confirms the tool is designed for natural language queries and does not document operator support

Claude Model

Sonnet (default)

Is this a regression?

I don't know

Last Working Version

_No response_

Claude Code Version

2.1.87 Claude Code

Platform

Anthropic API

Operating System

Ubuntu/Debian Linux

Terminal/Shell

Other

Additional Information

Terminal/Shell: Bash on Debian.

A search of existing issues prior to filing this report found anthropics/claude-code#20534 ("[MODEL] Keyword choice restricts discovery") as a loosely related report.
However, that issue concerns the model's query formulation choices and is distinct from this bug, which concerns the tool silently ignoring operators that the agent explicitly constructs.

The official Anthropic documentation for the WebSearch tool (web_search_20260209) confirms the tool is designed for natural language queries. Domain filtering is handled through dedicated parameters (allowed_domains, blocked_domains) rather than query syntax, which further confirms that operator-based query syntax is not part of the tool's design.

There is also a documented limitation that Claude models (except Opus 4.6) cannot reliably emit literal double-quote characters inside tool call string parameters, meaning quoted phrases are silently stripped before reaching the search engine regardless of intent.

The 45 search queries referenced in this report were extracted programmatically from the raw agent task transcript using Python, parsing only tool_use blocks with name: WebSearch to ensure accuracy and exclude query strings appearing in tool results.

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