WebSearch cannot express max_uses, and lets mutually exclusive domain lists through

[saarnilauri]

src/Tools/DTO/WebSearch.php carries exactly two fields, allowedDomains and disallowedDomains. The file is unchanged since the 0.1.0 release. Two consequences, one additive and one that needs a decision.

1. max_uses cannot be expressed, so providers hardcode it

ai-provider-for-anthropic hardcodes it at src/Models/AnthropicTextGenerationModel.php:588-597 (trunk):

if ($webSearch) {
    $tools[] = array_filter([
        'type' => 'web_search_20250305',
        'name' => 'web_search',
        'max_uses' => 1,
        'allowed_domains' => $webSearch->getAllowedDomains(),
        'blocked_domains' => $webSearch->getDisallowedDomains(),
    ]);
}

Every grounded request performs at most one search and a caller cannot change it. Per Anthropic's web search documentation, "Simple factual queries typically use 1-3 searches; comparative or multientity research can use 10 or more", and exceeding the cap yields a max_uses_exceeded error inside the result block rather than a failed request. So a cap of 1 quietly truncates the research a comparative question needs, and the caller sees a thinner answer rather than an error.

This is not a provider oversight: maxUses and userLocation appear nowhere in src/ (case-insensitive grep), so there is nothing for a provider to read.

Suggested: an optional $maxUses constructor parameter with getMaxUses(): ?int, null meaning "provider default", rejecting values below 1. Purely additive — no existing caller changes, and the key is omitted from toArray() when unset so serialisation round-trips unchanged.

2. Mutually exclusive domain lists are not rejected

Anthropic's documentation is explicit: "Provide allowed_domains or blocked_domains, not both. If a request includes both, the API returns a 400 error."

Nothing prevents it. WebSearch::__construct() accepts both lists, and the array_filter above only drops empty arrays — so a WebSearch carrying both populated lists produces a request with both keys and a guaranteed 400.

I am raising this rather than patching it because the fix has a real design question attached. Mutual exclusivity is currently an Anthropic constraint, not a universal one, so enforcing it in a provider-agnostic DTO encodes one vendor's rule into shared code. The options as I see them:

1. Throw from WebSearch::__construct() when both lists are non-empty. Fails at the point of the mistake, but it is a breaking change: 11 tests in tests/unit/Tools/DTO/WebSearchTest.php construct WebSearch with both lists populated (testCreateWithBothAllowedAndDisallowedDomains, testWithDuplicateDomains, testWithEmptyStringsInArrays, testWithSingleDomainInEachList, testWithManyDomains, testMultipleInstances, testWithCommonDomainPatterns, testToArrayWithBothDomainLists, testFromArrayWithBothDomainLists, testArrayRoundTrip, testArrayRoundTripWithSpecialCharacters). If the test suite does it that freely, callers will too.
2. Guard in the Anthropic provider, where the constraint actually lives, leaving the DTO permissive.
3. Document the exclusivity on the DTO and leave enforcement to providers.

I lean towards 2, and towards 1 only if maintainers consider the combination meaningless in general rather than merely unsupported by one vendor.

Offer

I have the maxUses half implemented against trunk with unit tests, PHPCS and PHPStan clean and PHP 7.4 compatible. Happy to open that PR immediately if the shape above is acceptable. I would rather have the domain-list half settled here before writing it.

Related: WordPress/ai-provider-for-anthropic#41 reaches the same hardcoded max_uses from the usage-reporting angle.

[saarnilauri]

Two corrections to my own reasoning above. The first reverses the recommendation I gave in section 2.

1. Mutual exclusivity is not Anthropic-specific

I argued that "mutual exclusivity is currently an Anthropic constraint, not a universal one, so validating it in a provider-agnostic DTO encodes one vendor's rule into shared code," and leaned towards option 2 on that basis. That premise does not hold. Other vendors state the same rule, in their own documentation:

• Anthropic: "Provide allowed_domains or blocked_domains, not both. If a request includes both, the API returns a 400 error."
• xAI: "allowed_domains cannot be set together with excluded_domains in the same request." (maximum 5 domains each)
• Perplexity: "The filter works in either allowlist mode (include only) or denylist mode (exclude), but not both simultaneously." (maximum 20 domains; denylist entries take a - prefix)

OpenAI's wording is weaker — "up to 100 allowed_domains or up to 100 blocked_domains" — which implies the same exclusivity without stating it as a prohibition, so I would not count it as evidence either way.

Three independent vendors treating an allowlist and a denylist together as incoherent is a different situation from one vendor's quirk. That makes option 1 — rejecting both in WebSearch::__construct() — considerably better supported than I made it sound. The breaking-change cost is unchanged and real (11 tests in WebSearchTest construct it with both lists populated), so it remains a judgement call, but it should be made knowing the rule is shared rather than vendor-specific.

2. A caveat against my own maxUses proposal

I suggested adding maxUses to the DTO. Weighing against it: a cap on the number of searches appears to be Anthropic's alone. xAI documents no search-count parameter. The gateway-style tools cap the number of results instead (maxResults, numResults, count) — a different quantity — and OpenAI caps neither, offering search_context_size and return_token_budget.

So the concern (bounding what a grounded request costs) is universal, while the parameter is not; it has at least three incompatible expressions. A formal maxUses would model one vendor's expression of a shared concern, and every provider unable to honour it would have to accept and ignore it — exactly the failure mode in #293.

The alternative is a per-tool provider options bag on WebSearch, carrying max_uses and user_location without the SDK growing a field per vendor knob. One caveat if that route is taken: the existing ModelConfig::customOptions cannot serve it. In the Anthropic provider, custom options merge into top-level request params through a conflict-throwing loop, and tools is already populated whenever a web search config exists, so tool-level options collide and throw. There is prior art for better merge semantics in the ecosystem: the Vercel AI Gateway provider plugin's WithProviderOptionsTrait::amendProviderOptions() merges nested provider options structurally with per-leaf conflict detection.

#295 implements the options bag: a providerOptions map keyed by provider ID, so a configuration cannot hand one vendor's keys to a provider that has never heard of them. It is additive, and the key is omitted from toArray() when empty, so existing serialisation is unchanged.

The domain-list half is deliberately not in that PR. Option 1 is a breaking change, so it belongs in a maintainer decision rather than arriving inside a patch.