tool_guards

Per-tool parameter guards: validation rules that reject a tool call and transforms that silently fix it, applied before every tool runs.

tool_guards — Tool Guards

Pre-flight validation and transformation rules that sit in front of every tool call — built-in, custom code, wrapped, MCP, Composio connector, OpenAPI, and skill tools all pass through the same guard layer before their code runs. Validation rules reject a bad call with a structured fix-it message the model can act on; transform rules silently fix the arguments and let the call proceed.

Section key tool_guards · Shape object · Tier All plans
Edit in the dashboard: Tools page — the Parameter guards section of the wrap editor, or the Tool Guards dialog for any tool by its runtime name

Per-tool guards, keyed by exact tool name.

Guards are keyed by the tool’s runtime name: a built-in by its plain name (web_search), one of your custom tools as tool_<name>, and an MCP/connector tool by its namespaced name. A tool with no guard entry passes through untouched.

Fields

Field	Required	Type	Allowed values / constraints	Default	Description
tools	no	object	keyed by exact tool name	—	Per-tool guards. Each value is a guard object with the fields below.

Per-tool guard fields

Field	Required	Type	Allowed values / constraints	Default	Description
block	no	boolean	—	—	Refuse every call to this tool, regardless of parameters.
blockMessage	no	string	max 2000 chars	—	Message fed back to the model when block refuses the call. Defaults to The "<tool>" tool is disabled for this agent and cannot be called.
params	no	object	keyed by top-level parameter name	—	Per-parameter rules. Item fields below.

Per-parameter rule fields

Each rule combines any of three kinds of field. Validation rules reject the call when violated; transform rules never reject — they change the value and let the call continue.

Validation (reject) rules:

Field	Required	Type	Allowed values / constraints	Default	Description
required	no	boolean	—	—	The parameter must be present and non-empty (missing, null, and "" all fail).
forbidden	no	boolean	—	—	The parameter must not appear in the call at all.
type	no	enum	one of string, number, integer, boolean, array, object	—	Type check. number also accepts integers.
pattern	no	string	regex source, max 500 chars	—	The string value must match this regular expression. An invalid regex is skipped, never rejects.
enum	no	array	max 50 items	—	The value must strictly equal one of these.
min / max	no	number	—	—	Numeric bounds (inclusive). Without clamp, an out-of-range number rejects.
minLength / maxLength	no	integer	≥ 0	—	Length bounds — characters for strings, items for arrays.
custom	no	enum	one of email, url, no_newlines, nonempty	—	Named server-side check: valid email address, valid http(s) URL, no line breaks, or non-blank.

Transform (silently fix) rules:

Field	Required	Type	Allowed values / constraints	Default	Description
trim	no	boolean	—	—	Strip leading/trailing whitespace from a string value.
lowercase / uppercase	no	boolean	—	—	Case-fold a string value.
default	no	string or number	max 2000 chars	—	Fill this value when the parameter is missing. A default can satisfy required.
hardSet	no	string or number	max 2000 chars	—	Force this value regardless of what the model supplied.
clamp	no	boolean	—	—	With min/max: pull an out-of-range number into range instead of rejecting.

Messaging and advertising:

Field	Required	Type	Allowed values / constraints	Default	Description
advertise	no	boolean	—	—	Append a compact constraint hint (e.g. [valid email], [length 0–200]) to this parameter’s description in the schema the model sees.
hint	no	string	max 2000 chars	—	Override the auto-generated advertise hint.
message	no	string	max 2000 chars	—	Override the auto-generated rejection reason for this parameter.

Evaluation order

For each guarded call:

1. block — if set, the call is refused immediately with blockMessage; no parameter rules run.
2. Per parameter, rules apply in a fixed order: forbidden → default (fill if missing) → hardSet (always override) → string transforms (trim, lowercase, uppercase) → required → and then, only when a value is present: type, numeric min/max (or clamp), minLength/maxLength, pattern, enum, custom.
3. Violations are collected across all parameters and reported together in one message, so the model can fix everything in a single retry.
4. If nothing violated, the tool runs with the transformed arguments. The model’s original message is never mutated — transforms apply to a copy.

What the model sees on a violation

A rejected call never reaches the tool — the guard’s message is surfaced to the model as an error tool result, so it can self-correct in the next step. The message is structured plain English:

Tool call to `send_email` was refused before running because some parameters are invalid:
- to "bob@gmial": failed rule `custom:email` — must be a valid email address.
Fix the parameters listed above and call `send_email` again.

Each bullet names the parameter, previews the offending value (truncated to 60 chars), names the failed rule, and gives the reason (your message override if set). Blocked tools produce a “Tool call to … was refused before running.” message naming the tool, plus the block message. Guard refusals also fire your post_tool_call hooks with the error summary, and are recorded as refused tool calls in the conversation’s interaction trace.

Layering and precedence

Three guard layers merge per turn, weakest first: subscriber → owner → platform. A stronger layer’s field wins on the same parameter; block is OR-ed across layers, so a weaker layer can block a tool but never un-block one. Guards a subscriber adds on their own Tools page are forced reject-only — the value-mutating fields (default, hardSet, clamp, trim, lowercase, uppercase) are stripped, so a subscriber can tighten your rules but can never transform an argument past them.

Examples

Validate an email recipient — reject any send_email call without a well-formed address, and tell the model up front:

{
  "tools": {
    "send_email": {
      "params": {
        "to": { "required": true, "custom": "email", "advertise": true }
      }
    }
  }
}

Pin and clamp a search tool — force the region, keep limit sane without ever failing the call:

{
  "tools": {
    "tool_search_products": {
      "params": {
        "region": { "hardSet": "eu-west" },
        "limit": { "type": "integer", "min": 1, "max": 25, "clamp": true }
      }
    }
  }
}

Block a dangerous tool outright — with a custom refusal the model will relay:

{
  "tools": {
    "tool_delete_record": {
      "block": true,
      "blockMessage": "Deletions are disabled on this agent. Ask the user to contact support instead."
    }
  }
}