> ## Documentation Index
> Fetch the complete documentation index at: https://agentheya.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/sidebar-menu/tools#wrapping-a-built-in-tool) — 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:

```text theme={null}
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](/reference/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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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:

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