Tools Overview

HASP tools are capabilities the model can invoke during inference. They are not arbitrary code execution — every tool call passes through the AI Gateway’s pre-action authorization step, is scanned for PHI, is recorded in the integrity-chain audit log, and debits AI Credits from your org’s balance.

How tool calls work

When the model emits a tool call during a stream, HASP intercepts it at the gateway before any execution occurs:

Pre-action authorization — The gateway checks whether the caller (user, API key, or agent credential) holds the necessary scope to invoke this tool. Unauthorized calls return 403 TOOL_NOT_IN_SCOPE and are never executed.
PHI scan — Tool inputs are scanned for PHI. By default, PHI is redacted from inputs before execution. If your org’s phi_retrieval_behavior is block, calls with PHI in their inputs return 403 RETRIEVAL_PHI_BLOCKED instead.
Execution — The tool runs. Results are injected back into the model’s context.
Credit deduction — On success, AI Credits are debited: a flat per-call surcharge (tool-specific) plus the normal input-token cost for the injected result content. No charge is applied for failed tool calls.
Audit log — A tool invocation event is written to the integrity-chain audit log, recording the call, the PHI scan result, the outcome, and the credit debit.
Continuation — The model receives the result and continues the stream.

PHI guarantee

Tool inputs are scanned for PHI before any tool executes. External providers invoked by HASP tools (for example, web retrieval providers Tavily and Serper) never receive PHI under any circumstance. This is a hard architectural invariant, not a configuration option.

Billing

Tool calls consume AI Credits in two ways:

Flat per-call surcharge — debited on provider success, tool-specific (see each tool’s page for the amount). No charge for failed calls.
Injected-token cost — tool results injected into context count as input tokens at your normal per-token rate.

Agent-initiated tool calls (via the Agent SDK) additionally meter as Agent Actions — one Action per authorized tool invocation. See Agents for how agent credentials authorize tool use.

Agent scope grants

Agents must have an explicit scope grant to call a tool. A user or API key call always has access to built-in tools (subject to org-level feature availability). Agent credentials require an external.tool.invoke grant naming the specific tool — and a tool.destructive grant in addition for any tool flagged destructive below. See Scope Grants for how to authorize tool use in agent credentials.

Built-in tools

These are the tools an agent’s tool_allowlist may name — the same catalog GET /v1/tools serves, with each tool’s full input schema.

Tool	Description	Flags
`audit.fetch_entries`	Fetch the audit entries matching a validated filter (max 100 rows). Returns compact rows with their entry ids; cite those ids in the final findings. Narrow the filter and call again to cover a larger span.	read-only
`audit.name_subject_resolve`	Resolve a human name to candidate organization members (canonical user ids). Use this before filtering by a person. If multiple candidates are returned, list them in the findings and note which you used — never assume which person is meant.	read-only
`audit.query`	Translate a natural-language audit query into a validated filter and report the number of matching entries. Use this first to turn a lead into a filter, then fetch entries.	read-only
`audit.subject_hmac_lookup`	Compute the subject HMAC for a canonical subject id (e.g. a user id), to use as the “subject” filter key. Accepts canonical ids only, never names — resolve a name to an id first.	read-only
`audit.synthesize`	Generate a citation-grounded narrative summarizing the audit entries matching a validated filter. Use this to write findings; every factual claim is grounded in a real entry id.	read-only
`crm.upsert`	Create or update a CRM contact by email through the project’s bound CRM integration.	destructive
`email.send`	Send an email through the project’s bound email integration.	destructive
`http.request`	Make an outbound HTTP request through the project’s bound custom-HTTP integration.	destructive
`human.escalate`	Route a matter to a human. Use when a decision needs judgement you do not have, or authority you were not given.	—
`knowledge.search`	Search the organization’s uploaded knowledge base documents. Returns relevant excerpts with citations. Use when the user asks about content from their uploaded documents.	read-only
`slack.post`	Post a message to a Slack channel through the project’s bound Slack integration.	destructive
`solve.run`	Solve a deterministic constraint-satisfaction / assignment problem (staff scheduling, coverage rostering, resource allocation) against the closed HASP solver vocabulary. Accepts a literal spec, or resources_from/slots_from to source resources and slots from a project’s live records (pass `project`). `infeasible` is a successful result carrying the conflicting-constraint subset — never an error — so it is safe to inspect and reformulate the spec.	read-only
`web.fetch`	Fetch and extract the text content of a specific URL. Use when you have a specific page to read, such as documentation, an article, or a resource linked in the conversation.	read-only
`web.search`	Search the web for current information. Returns relevant results with excerpts. Use when you need information beyond your knowledge cutoff or for real-time data.	read-only

Tools flagged destructive additionally require a tool.destructive grant naming that tool; a wildcard is rejected. Integration-backed tools (email.send, slack.post, http.request, crm.upsert) act through the project’s bound integration and fail if no binding exists. Three tools have dedicated reference pages covering their input/output schemas, credit surcharges, and error codes:

Tool	Credit surcharge
`web.search`	5 AI Credits / call
`web.fetch`	2 AI Credits / call
`knowledge.search`	None — meters via Storage + AI Credits

Every tool is subject to PHI Guard and pre-action authorization.

AI Studio

Platform

AI API

App Builder SDK

Tools Overview

How tool calls work

PHI guarantee

Billing

Agent scope grants

Built-in tools

​How tool calls work

​PHI guarantee

​Billing

​Agent scope grants

​Built-in tools

How tool calls work

PHI guarantee

Billing

Agent scope grants

Built-in tools