WebSearch delegates search to an injected SearchProvider. The provider exposes both Search(ctx, query, max) and Endpoints(). This seam keeps network behavior in a product-owned provider while the tool validates the endpoint declaration and prepares the gate request.

Contract

The JSON shape is {"query":"Looprig","results":5}. Empty queries fail preparation. Results default to 5 and are capped at 10. Preparation normalizes and deduplicates every provider endpoint, then emits one network requirement per declared HTTPS target using the shared network capability and tcp://host:port match. A provider with no valid endpoint declaration cannot be prepared.

The direct tool carries no filesystem access. At runtime the provider must honor the caller context and fail closed on redirects or secondary targets outside its declared endpoints. A provider error becomes the generic result error: web search failed, not a transport detail or URL dump. SearchResult values contain title, URL, and snippet, and an empty result set becomes No results found.

NewDuckDuckGoProvider(client) declares html.duckduckgo.com:443, uses the injected client, bounds HTML parsing to 1 MiB, limits redirect chains, and parses malformed HTML defensively. A different provider can implement the same interface and declare its own endpoints.

// The provider owns the HTTP client and endpoint declaration.
provider := websearch.NewDuckDuckGoProvider(client)
search := websearch.NewWebSearch(provider)
request, artifact, err := search.PrepareCall(ctx, executionID,
	`{"query":"Looprig","results":5}`)
if err != nil {
	panic(err)
}
prepared := loop.WithPreparedCall(ctx, tool.PreparedCall{
	ExecutionID: executionID,
	Request: request,
	Artifact: artifact,
})
result, err := search.InvokableRun(prepared, `{}`)

Compare Fetch when the model already knows the URL. Both use the shared network capability and target matching. See Safety, Permissions, and Gates and Inference’s tool requests.

WebSearch

Contract

Source

Proof