web.search

web.search performs a governed web search via HASP’s retrieval layer. The model receives up to 10 ranked results with title, URL, snippet, domain, and published date. HASP controls which provider executes, applies vertical-aware result ranking, and injects results into context before the model continues.

PHI enforcement

Two PHI scans run before any provider call:

On receipt — when the tool call is intercepted at the gateway, the query is scanned.
Pre-dispatch — immediately before the outbound provider call, the planned query is scanned again.

The retrieval-specific behavior is controlled by your org’s phi_retrieval_behavior setting (configured under Settings → Retrieval): redact (default) strips PHI from queries before they leave HASP; block rejects the tool call entirely if PHI is detected. Web search providers (Tavily by default) never receive PHI under any circumstance — this is a hard architectural invariant enforced at the platform level.

Billing

5 AI Credits flat surcharge per call, debited on provider success.
Normal input-token cost applies to the injected result content.

The surcharge is only charged when the provider returns a successful response. No charge is applied for failed provider calls or PHI-blocked calls.

Input parameters

Parameter	Type	Required	Description
`query`	string	Yes	The search query.
`maxResults`	integer	No	Number of results to return. Range 1–10. Default: `5`.
`freshnessWindow`	string	No	Freshness filter. Accepted values: `"7d"`, `"30d"`, `"1y"`. Omit for no filter.
`conversationId`	string	No	Correlation context. Passed automatically by HASP in chat sessions.

Output fields

Each result injected into context contains:

Field	Type	Description
`title`	string	Page title.
`url`	string	Source URL.
`snippet`	string	Relevant excerpt from the page.
`domain`	string	Apex domain (e.g., `nih.gov`).
`publishedDate`	string \| null	ISO 8601 date if known; `null` if unavailable.
`retrievedTimestamp`	string	ISO 8601 timestamp of retrieval.
`rank`	integer	Position in the result set (1-indexed).

Vertical-aware ranking

For orgs with a healthcare vertical configured, HASP applies boosted ranking for authoritative clinical and regulatory sources including NIH, CDC, FDA, CMS, and PubMed. Results from these domains are ranked higher than general-web equivalents when present in the provider response.

Citations

Results injected into the model’s context are persisted as citations linked to the conversation message. Citations survive page refresh and are available in the Audit endpoint. Each citation records the source URL, snippet, rank, and retrievedTimestamp.

Example

Tool call emitted by the model:

{
  "type": "tool_use",
  "name": "web.search",
  "input": {
    "query": "HIPAA breach notification rule requirements 2024",
    "maxResults": 3,
    "freshnessWindow": "1y"
  }
}

Result injected into context:

{
  "type": "tool_result",
  "name": "web.search",
  "results": [
    {
      "rank": 1,
      "title": "Breach Notification Rule | HHS.gov",
      "url": "https://www.hhs.gov/hipaa/for-professionals/breach-notification/index.html",
      "snippet": "The HIPAA Breach Notification Rule, 45 CFR §§ 164.400-414, requires HIPAA covered entities and their business associates to provide notification following a breach of unsecured protected health information.",
      "domain": "hhs.gov",
      "publishedDate": "2023-11-15",
      "retrievedTimestamp": "2026-05-16T14:22:01Z"
    },
    {
      "rank": 2,
      "title": "Breach Notification — CMS",
      "url": "https://www.cms.gov/priorities/key-initiatives/burden-reduction/administrative-simplification/hipaa/breach-notification",
      "snippet": "Covered entities must notify affected individuals, HHS, and in some cases the media, of a breach of unsecured PHI.",
      "domain": "cms.gov",
      "publishedDate": null,
      "retrievedTimestamp": "2026-05-16T14:22:01Z"
    }
  ]
}

Error codes

Code	Description
`RETRIEVAL_DISABLED`	Web retrieval is not enabled for this org.
`RETRIEVAL_PHI_BLOCKED`	PHI was detected in the query and `phi_retrieval_behavior=block` is set.
`RETRIEVAL_PROVIDER_UNAVAILABLE`	The upstream search provider returned an error or timed out.

See Errors for the full error envelope shape.

AI Studio

Platform

AI API

App Builder SDK

PHI enforcement

Billing

Input parameters

Output fields

Vertical-aware ranking

Citations

Example

Error codes

​PHI enforcement

​Billing

​Input parameters

​Output fields

​Vertical-aware ranking

​Citations

​Example

​Error codes

PHI enforcement

Billing

Input parameters

Output fields

Vertical-aware ranking

Citations

Example

Error codes