serper-search

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

1. If DNS/network fails, report it as an environment/network issue and retry only when external network is available.
2. If authentication fails, report that SERPER_API_KEY is missing or invalid without printing its value.
3. If results are irrelevant, refine the query with names, dates, locations, or source domains.