---

date: 2026-06-18 tags: [laravel-ai, tools, web-search, phpstan, testing] status: active graduated_to:

Adding a laravel/ai ProviderTool to an agent needs the Tool|ProviderTool docblock and breaks exact tool-list tests

Symptom — Adding (new WebSearch)->max(5) to an agent's tools() (ChatAgent, TaskThreadAgent) failed PHPStan L7 and turned two exact tool-list tests red (BulkTaskToolsTest, HelperSkillChatToolsTest).

Root cause — Laravel\Ai\Providers\Tools\WebSearch extends ProviderTool, which does not implement Laravel\Ai\Contracts\Tool. The framework's HasTools::tools() is typed @return array<Tool|ProviderTool> (the Anthropic gateway maps provider tools on a separate branch to web_search_20250305), but our agent docblocks had narrowed it to array<int, Tool>. Separately, the tool-list tests assert the full ordered list with ->toBe([...]), so any added tool fails them by design — that is the assertion working, not a regression.

Fix — Widen the agent tools() docblocks to @return array<int, Tool|ProviderTool>, and update the exact-list assertions to include the new tool in the right order. PR #568, SHAs acf0115 + 06b90ee.

Guard — AgentConfigTest asserts each agent carries a WebSearch capped at 5; BulkTaskToolsTest + HelperSkillChatToolsTest pin the exact ordered tool list, so a dropped or reordered tool fails. The union docblock keeps PHPStan green. When adding the next provider tool (WebFetch/FileSearch, e.g. for #78), expect both the docblock and these two lists to need the edit.