| name | serper-search |
| description | Search the public web through Serper instead of the built-in WebSearch tool. Use when an agent needs current information, general web sources, or URLs not available from local files and project APIs. SERPER_API_KEY is available in the environment. |
Serper Search
Use Serper whenever external web search is needed. Prefer local files and project APIs when they already contain the required information.
Rules
- Do not use the built-in WebSearch tool.
- Do not expose the API key in answers, logs, committed fixtures, or browser/client code.
- Prefer authoritative and primary sources in the returned results.
- Refine the query when freshness, date, company, product, or source type matters.
API
- Endpoint:
POST https://google.serper.dev/search
- Auth header:
X-API-KEY: $SERPER_API_KEY
- Content type:
application/json
- Required body:
{"q":"query text"}
Curl
curl -s --location "https://google.serper.dev/search" \
--header "X-API-KEY: $SERPER_API_KEY" \
--header "Content-Type: application/json" \
--data '{"q":"apple inc"}'
Response Use
- Prefer
organic results for normal search answers.
- Use
searchParameters to confirm the query actually sent.
- Treat
credits as usage accounting.
- Verify important claims against the linked source rather than treating snippets as complete evidence.
- Summarize results with source titles and links; do not copy large passages from snippets or pages.
Failure Handling
- If DNS/network fails, report it as an environment/network issue and retry only when external network is available.
- If authentication fails, report that
SERPER_API_KEY is missing or invalid without printing its value.
- If results are irrelevant, refine the query with names, dates, locations, or source domains.
