agent-web-search-setup
Fixes web search on an agent whose model backend can't run it: a relay/reseller proxying Claude or Codex returns empty instead of failing
Install / Use
npx skills add daymade/claude-code-skills --skill agent-web-search-setupInstalls into whichever agent you are using.
SKILL.md
Installable skill definition
Quality Score
Category
Development & EngineeringSupported Platforms
Tags
Our assessment of agent-web-search-setup
agent-web-search-setup scores 93/100 on our quality scale, 716th of 4,700 Development & Engineering skills we index (top 16%).
Its SKILL.md is 37 KB long, well organised into 9 sections with 10 code examples: a thorough specification that gives an agent plenty to work with.
With 1,426 GitHub stars, it is one of the more widely adopted skills in the catalogue.
Maintenance, license and trust
- The repository was last updated about 2 months ago, so agent-web-search-setup is actively maintained.
- Our last check on 2026-10-26 found the source still online.
- It is released under the MIT license, a permissive license that allows use, modification and commercial use with attribution.
- Its trust signals score 100/100, with no cautions. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.
Safety scan
ReviewOur scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review judged it risky: The skill instructs adding replacement MCP tool names (e.g. mcp__exa__web_search_exa and mcp__exa__web_fetch_exa) to permissions.allow in ~/.claude/settings.json, which is adding entries to a permission allow-list and weakens the agent's sa.
AI review: risky
- The skill instructs adding replacement MCP tool names (e.g. mcp__exa__web_search_exa and mcp__exa__web_fetch_exa) to permissions.allow in ~/.claude/settings.json, which is adding entries to a permission allow-list and weakens the agent's sa
- It directs the agent to disable built-in web search safeguards (permissions.deny for WebSearch/WebFetch and web_search = "disabled" in Codex config) and replace them with a third-party MCP server, a significant configuration change under ag
- It has the agent read API credentials from client config files and pass them to a local diagnostic script, and to run verification commands that modify user config files; while not exfiltratory, it involves credential handling and config ed
AI review by kimi-k2.7-code on 2026-10-04. Automated pattern scan on 2026-10-04. It catches known dangerous patterns, not every risk — read a skill before letting an agent act on it.
agent-web-search-setup compared with similar skills
All 4 of these similar skills score higher than agent-web-search-setup; compare them before choosing.
| Skill | Score | Stars | Updated | Format |
|---|---|---|---|---|
| agent-web-search-setup (this skill)by daymade | 93 | 1.4k | 53d ago | SKILL.md |
| taste-skillby Leonxlnx | 100 | 116.8k | 8d ago | CLAUDE.md |
| ai-job-searchby ai-job-search-dev | 100 | 72.1k | today | CLAUDE.md |
| claude-howtoby luongnv89 | 100 | 47.3k | 2d ago | CLAUDE.md |
| lobehubby lobehub | 100 | 85.6k | today | MCP Server |
Frequently asked questions
- How do I install agent-web-search-setup?
- Run
npx skills add daymade/claude-code-skills --skill agent-web-search-setup. The install tabs above show the steps for each supported agent. - Which AI agents does agent-web-search-setup work with?
- It is written for Claude Code and OpenAI Codex, as a SKILL.md file. Other agents that read the same format can often use it too.
- Is agent-web-search-setup safe to use?
- Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review judged it risky: The skill instructs adding replacement MCP tool names (e.g. mcp__exa__web_search_exa and mcp__exa__web_fetch_exa) to permissions.allow in ~/.claude/settings.json, which is adding entries to a permission allow-list and weakens the agent's sa. It is MIT-licensed and scores 100/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
- Is agent-web-search-setup still maintained?
- The repository was last updated about 2 months ago, so agent-web-search-setup is actively maintained.
Skill content
View source on GitHubname: agent-web-search-setup description: >- Fixes web search on an agent whose model backend can't run it: a relay/reseller proxying Claude or Codex returns empty instead of failing. Use when web search returns nothing, a model insists a shipped product doesn't exist, someone wants to give an agent internet access, or the user is on a third-party base URL, relay, or 中转站. Diagnoses which built-in tools are dead, removes them, and installs a working replacement.
Agent Web Search Setup
A model backend that cannot search is not the same as a model that searched and found nothing, but from inside the conversation the two look identical. This skill turns the first into the second, on whichever agent is in front of you. It configures the agent's tools; it is not itself a search engine, so nothing here answers a query directly — the proof of done is the agent's own session calling a real tool.
What actually breaks
Anthropic's web_search and web_fetch are server tools: the API runs them
during the request and splices results into the same response. OpenAI's Responses
API web_search works the same way. The client only ever declares the tool.
A reseller that proxies to another cloud cannot execute those. Anthropic's own documentation states that web fetch is unavailable on Amazon Bedrock and Google Cloud; search was measured failing the same way on both. What comes back is not an error. It is an empty shell, so the model concludes the topic does not exist and says so with total confidence. That is the whole bug, and it is why users report their agent has "gotten stupid" rather than reporting a broken tool.
Three things follow, each of which cost real time to establish:
- Switching models does not help. One reseller was measured routing four model names to three different backends; none produced a working search.
web_fetchbreaks with it. Fixing only search moves the failure from "I found nothing" to "I found links but cannot open them."- Installing an alternative is not enough on its own. With the dead tool still on the menu, a model made 21 web-search calls and 0 calls to an installed alternative whose description said the built-in was broken. Built-in tools win head-to-head. The dead tool has to be removed, or nothing else you do matters.
1. Prove it, on this machine
Do not take the user's word for which tool is broken, and do not take yours.
<skill> below is the directory holding this SKILL.md — substitute the real
path. If it is somehow not known, find ~ -type d -name agent-web-search-setup
locates it.
python3 <skill>/scripts/diagnose.py
It reads ANTHROPIC_BASE_URL / ANTHROPIC_AUTH_TOKEN / ANTHROPIC_MODEL, or the
OPENAI_ equivalents under --api openai, or takes --url --key --model. Exit
codes: 0 nothing to fix, 1 at least one tool is dead, 2 undetermined. --json
for parsing.
Those values are usually not in the shell — go and read them out of the client.
A person on a relay set it up through a provider switcher or a settings screen, not
by exporting variables, so a plain shell sees nothing and the probe stops before it
starts. For Claude Code they live in the env block of ~/.claude/settings.json;
for Codex, the base URL is under [model_providers.*] in ~/.codex/config.toml and
the key is in ~/.codex/auth.json. Read them from there and pass them with --url
and --key. Never print the key.
This step needs a working python3, and on a fresh Mac that is one dialog.
/usr/bin/python3 ships as a stub that opens the Command Line Tools installer the
first time it is called. Expect it, and say so before it appears rather than after.
The script itself is standard library only and runs on the 3.9 that macOS ships, so
nothing else has to be installed — which is exactly the difference between this one
dialog and an MCP server that wants Node plus an SDK.
It reports a verdict per tool and names the real backend from the tool-call id
prefix (toolu_vrtx_ Vertex AI, toolu_bdrk_ Bedrock, ws_ an OpenAI hosted
tool). A model that simply
declined to call the tool is reported as inconclusive, not as broken; re-run
or try another model rather than treating silence as evidence.
Slow is not dead, and the difference is easy to get wrong. One gateway was measured answering in about 15 seconds on two model ids and about 146 on a third. A timeout set between those two numbers reports a perfectly healthy endpoint as broken, which is the same misdiagnosis this skill exists to correct. The default allows for the slow case; if you shorten it, a timeout still reports inconclusive rather than a verdict.
Codex reaches its backend through a different API, so probe that one. Its
hosted search lives in the OpenAI Responses API, where a working endpoint returns a
web_search_call item. --api openai asks there. Asking only the Anthropic shape
leaves a Codex user with no verdict at all.
The commonest way that probe fails is not a refusal — it is a missing route, and
that is more decisive than it looks. A relay measured here answers the older
/v1/chat/completions with HTTP 200 and returns HTTP 404 for /v1/responses. Both
facts matter together: the endpoint really is OpenAI-compatible, and it simply does
not implement the surface hosted tools are served through. So hosted search cannot
run there at all, and for Codex that settles the whole question, because that route
is the one its hosted tools use. The probe makes this second request itself and
reports unavailable; a 404 with no working Chat Completions route stays
inconclusive, because then the key or the base URL is the likelier fault.
The two APIs do not share a model namespace, so --api both also needs
--openai-model (or OPENAI_MODEL). Without one the OpenAI probe is skipped and
says so, rather than sending a Claude model id to /v1/responses and collecting a
400 about the model that reads exactly like a verdict about the tool.
On the Codex side the setting is web_search. The values seen were disabled,
cached, indexed and live, but treat that list as a snapshot: an invalid value
makes Codex print the full set itself, which is both the fastest way to confirm the
current syntax and the only one that cannot go stale.
If every probe comes back working, stop and look elsewhere before configuring anything. The tools are fine on that endpoint, so installing a replacement adds a second way to search without fixing the first. Two causes have been seen on real machines: another installed component answers search-shaped requests before any tool is considered, and a client whose own setting turns search off. Both look exactly like a dead backend from inside the conversation.
2. Remove the dead tools
Only the tools diagnose.py actually reported dead. Removing a working tool is a
regression, not a safety margin.
| Agent | Where | What |
|---|---|---|
| Claude Code, terminal or the Code surface of the desktop app | ~/.claude/settings.json | add the dead tool names to permissions.deny |
| Codex | ~/.codex/config.toml | web_search = "disabled" |
| Claude Desktop, the chat surface | not a supported target | see below |
The client spells these differently from the API, and the wrong spelling fails
silently. diagnose.py reports web_search and web_fetch, because that is what
the API calls them. A deny list takes WebSearch and WebFetch. Writing the API
spelling into permissions.deny matches no tool at all, so the file changes, the
run reports success, and the tool is still on the model's menu — the same dead end
as not editing anything. The diagnostic prints the client spelling next to its
conclusion for this reason; use that one.
A bare tool name in permissions.deny removes the tool from the model's context
entirely, which is what you want. Verified by reading the session's init event:
the tool is absent from the list the model receives, rather than present with
advice against using it.
That event is referred to several times below, so here is how to actually get it.
Do not reach for the first line — on a machine with SessionStart hooks
configured it was measured arriving as line 24 of 24, behind the hooks' own output.
Filter by type instead, which is what this does:
claude -p "reply ok" --output-format stream-json --verbose < /dev/null > /tmp/init.jsonl
python3 -c "
import json
for line in open('/tmp/init.jsonl'):
d = json.loads(line)
if d.get('type') == 'system' and d.get('subtype') == 'init':
print('WebSearch:', 'WebSearch' in d['tools'], ' WebFetch:', 'WebFetch' in d['tools'])
break"
Two False values mean the tools are gone from what the model receives. The same
event carries permissionMode, which is worth reading at the same time for the
reason given in step 4.
A deny travels further than a grant does, and that asymmetry matters in step 4.
permissions.deny is honoured out of a project's own .claude/settings.json even
in a directory nobody has ever trusted — measured there by reading the init
event, which listed 24 tools with WebSearch and WebFetch absent and printed no
warning. The grant in step 4 does not behave this way. A restriction arriving from
an untrusted file is safe to obey; a privilege is not, and the client is right to
treat the two differently.
A second asymmetry, this one about synchronisation, decides where the deny goes
on a multi-profile machine. Step 4 sends the grant to the profile the others
sync from, because a synchroniser that converges settings.json drops it
anywhere else. The deny cannot follow it there: the source profile is the one
every other profile copies from, so a deny placed in it lands on profiles whose
built-in search works, and removing a working tool is the regression the top of
this step warns against. The layer that is both per-profile and out of the
synchroniser's reach is the settings file the profile launcher passes with
--settings; claude-switch-models-setup in this same marketplace documents
that file and the measurement showing a deny taking effect from it. Getting this
wrong has a symptom worth recognising on sight: the fix works in the session that
made it and stops working after the restart you asked the user to do, which reads
as the restart not taking rather than as something rewriting the file.
Both edits are small enough to show literally, which beats describing a shape the reader then has to build:
{ "permissions": { "deny": ["WebSearch", "WebFetch"] } }
web_search = "disabled"
That TOML line has to go above the first [table] header in the file, and
appending it to the end is the way to get this wrong. It is a bare key, so TOML
binds it to whatever table precedes it — drop it after a [model_providers.…]
block, which step 1 has just sent you into that same file to read, and it becomes
model_providers.<name>.web_search, a setting nothing reads. The file changes, the
command succeeds, and hosted search is still on. Put it on its own line at the top
of the file and read the file back.
Merge, never replace. These files hold the user's own configuration. Add the one key and leave the rest byte-identical. Show them the before and after.
Prefer pointing at a key over copying one in. Where the client supports reading a credential from the environment, register that reference rather than writing the secret into a config file. These files get screenshotted into help requests and shared wholesale; a key pasted into one travels with it.
The desktop app is two clients, not one. Its Code surface runs a real
claude binary the app downloads and carries the Claude Code settings engine, so
the row above covers it. The app's own bundle settles where that engine looks: the
config root is the value held in the app's settings store if one is set, otherwise
`process.env.CLAUDE_CONFIG_DI
Truncated for display — read the full file on GitHub.
Related Skills
taste-skill
116.8kAgent skills that give coding agents taste: art direction, reference images and a browser check instead of generic AI pages
ai-job-search
72.1kThe job search that runs on your machine. AI job application framework built on Claude Code: evaluate postings, tailor CVs, write cover letters, prep interviews. Fork it and own it.
claude-howto
47.3kA visual, example-driven guide to Claude Code — from basic concepts to advanced agents, with copy-paste templates that bring immediate value.
lobehub
85.6k🤯 LobeHub - Super-Agents on Your Team. Add super-agents to the chats your team already uses.They take on work by themselves and get better every week.
Languages
Trust signals
From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.
