web_search: For Discovery

+15 Mana ✨
Hermes Web Tools Reference(DOCUMENTATION)

Introduction

web_search is the tool to reach for when the agent does not yet know which page to read. It is a search engine wrapper: query in, list of results out. The point is discovery, not detail. If you know the URL already, you do not want web_search; you want web_extract or the browser.

Key Concepts

  • Discovery query: A search whose goal is to find candidates for further reading, not to answer the question directly.
  • Search operators: site:, filetype:, quotes for exact phrases. web_search understands the usual Google-style operators.
  • Result count: web_search returns up to five results by default, each with a title, URL, and short description.

Real World Context

When you ask Hermes what changed in Next.js 16 around the App Router?, the agent does not know the URL of the Next.js release notes off the top of its head. It runs web_search({ query: 'Next.js 16 App Router changes' }), gets five candidates, then uses web_extract on the most promising one. The pattern is search to find, extract to read.

Deep Dive

web_search returns a small, structured list:

yaml
results:
  - title: 'Next.js 16: What's New'
    url: 'https://nextjs.org/blog/next-16'
    description: 'A full breakdown of changes in Next.js 16, including the App Router...'
  - title: 'Next.js 16 Release Notes'
    url: 'https://github.com/vercel/next.js/releases/tag/v16.0.0'
    description: 'Official release notes and migration guide...'
  - ...

The agent reads this list and decides which URL to follow up on. Five results is enough for discovery without flooding context.

Three practical patterns:

  1. Refine before extract. If the first query is too broad, run a second web_search with operators (site:nextjs.org Next.js 16 App Router) before reaching for web_extract.
  2. Prefer official sources. When two results both look plausible, the official docs domain almost always wins. Tool descriptions and the model's training help with this, but you can also instruct it explicitly.
  3. Use site: to scope. site:github.com hermes-agent toolsets is a great way to find issues, releases, or examples without leaving GitHub.

Common Pitfalls

  1. Treating search results as answers: The titles and descriptions are clues, not facts. The agent should follow up with web_extract before claiming anything.
  2. Running web_search when the URL is already known: If the user said read the docs at this URL, the agent should jump straight to web_extract.

Best Practices

  1. Search then extract: Treat the pair as a discover-then-read flow.
  2. Use operators when broad queries fail: site:, filetype:, and quotes are still the cheapest way to refine.

Summary

  • web_search is a discovery tool: it returns candidates, not answers.
  • Returns up to five results with titles, URLs, descriptions.
  • Supports Google-style operators.
  • Pair with web_extract to actually read the chosen page.

Code Examples

yaml
# Discovery-style query, no specific URL in mind
tool_call:
  name: web_search
  arguments:
    query: hermes agent toolset configuration

# Returns a list of up to 5 results. The agent reads the
# descriptions, picks the best URL, then calls web_extract
# on that URL to get the actual content.
✓ Completed