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:

1. 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.
2. 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.
3. Execution — The tool runs. Results are injected back into the model’s context.
4. 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.
5. 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.
6. 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 a hasp.tool.invoke scope grant naming the specific tool. See Scope Grants for how to authorize tool use in agent credentials.

​

Built-in tools

The following tools are available to all orgs with retrieval enabled: Both tools are subject to PHI Guard and pre-action authorization. See each tool’s reference page for full input/output schemas and error codes.