Agent Data Tools: Web, documents and search

by io.github.Nutshell2000

Web search: top results for any query

web_search

Read-only

Web search: send a query and get the top web results as JSON (title, URL, snippet, published date), optionally with page text and highlights, filtered by domain, date or category. Results are for immediate use only (Brave API terms); failures are uncharged. Use when an agent needs current facts, sources or links. Example: q=x402 payment protocol. Price $0.01/call via x402 USDC or a card key (/credits); failed calls free. Reads or computes only and changes nothing; each call is charged, so repeats are not free.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "q": "<q>"
    },
    "name": "web_search"
  }
}

Input Schema

Name	Required	Description
`q`	Yes	Search query, at most 400 characters
`count`	No	Number of results (1-20, default 10)
`summary`	No	true: a 1-3 sentence AI summary of each of the top pages
`category`	No	news, research paper, github, pdf, tweet, linkedin profile, company, personal site or financial report
`textChars`	No	Return the live page text of the top results, this many characters each (500-20000, or true for 3000; default none)
`highlights`	No	true: the passages of each page that best match the query, with scores
`excludeText`	No	A phrase the results must not contain
`includeText`	No	A phrase the results must contain (up to 5 words)
`numSentences`	No	Sentences per highlight (1-10, default 3)
`summaryQuery`	No	What the summaries should focus on (default: the query)
`excludeDomains`	No	Never results from these domains: comma list or JSON array
`includeDomains`	No	Only results from these domains: comma list or JSON array, up to 20 (example.com, github.com/org)
`endPublishedDate`	No	Only pages published on or before this date (ISO 8601)
`highlightsPerUrl`	No	Highlights per result (1-5, default 1)
`startPublishedDate`	No	Only pages published on or after this date (ISO 8601, e.g. 2025-01-01)

Schema Changelog

Changes observed during successful MCP inspections.

AddedNov 9, 2026

TDQS

A3.6/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, openWorldHint=true and destructiveHint=false, so 'reads or computes only and changes nothing' largely restates structured data. The genuinely additive parts are commercial and legal behavior: $0.01/call via x402 USDC or a card key, failed calls free, results not for retention. Pricing is repeated three times in slightly different phrasing, which weakens the signal.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The purpose and return shape are front-loaded well, but the pricing/free-call point appears three separate times ('failures are uncharged', 'failed calls free', 'each call is charged, so repeats are not free'), and the closing safety clause duplicates readOnlyHint. Trimming the redundancy would make the definition materially tighter.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With 15 parameters and no output schema, the description usefully names the return fields and the optional enrichments, and it covers cost, failure handling, and usage restrictions. Gaps are minor: nothing about result ranking or ordering, and no mention that pagination is unavailable, but an agent has enough to call it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so every one of the 15 parameters is already documented, including ranges, defaults, and the domain/date filters. The description's recaps ('filtered by domain, date or category', 'optionally with page text and highlights') and the q example add modest grouping value but no new constraints, matching the baseline for full-coverage schemas.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description gives a specific verb and resource ('send a query and get the top web results') and even enumerates the returned fields (title, URL, snippet, published date). It stops short of distinguishing itself from adjacent siblings such as news_search or search_web, so an agent must infer the boundary from the name alone.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

'Use when an agent needs current facts, sources or links' gives a clear triggering condition, and 'Results are for immediate use only (Brave API terms)' adds a constraint on how to use output. There is no explicit when-not guidance or named alternative for narrower searches (news, papers, PDFs), which leaves some routing decisions to inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All Agent Data Tools: Web, documents and search tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.