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

# Tool policies

> Govern the function and MCP tools that models and agents call: auto-discover them, then set an input/output trust policy that the gateway enforces as a prompt-injection defense.

Tool policies are a security layer over the **tools** a model or agent invokes (function tools and MCP tools). It does not configure agents; it governs what the tools they call are allowed to do. Tools are auto-discovered from real usage, and you assign each one a trust policy that the gateway enforces on every request

<Info>
  This is a governance feature, not agent setup. Agents are configured on the Agentic pages; Tool Policies is the safety layer on the tools those agents (and any tool-calling completion) use
</Info>

## How tools get here

Tools are discovered automatically. Make a chat completion (or run an agent) that returns `tool_calls`, and each tool is recorded with a default policy and flagged as needing review. The page is empty until that first tool-calling request happens

Discovery runs through the spend pipeline, so a newly used tool appears after a short flush delay rather than instantly

## The two policies

Each tool has an **input policy** (governs the tool being *called*) and an **output policy** (governs the tool's *result*):

| Policy | Value       | Meaning                                                               |
| ------ | ----------- | --------------------------------------------------------------------- |
| input  | `untrusted` | allowed; the default for a newly discovered tool                      |
| input  | `trusted`   | allowed only if the conversation has no output from an untrusted tool |
| input  | `blocked`   | the tool call is rejected                                             |
| output | `untrusted` | the tool's output may be tainted; the default                         |
| output | `trusted`   | the tool's output is verified safe                                    |

### The trust chain

The `trusted` input policy is the interesting one. Before a tool marked `input_policy=trusted` (a sensitive or privileged tool) is allowed to run, the guardrail checks whether the conversation already contains output from any `output_policy=untrusted` tool. If it does, the request is blocked. This stops tainted, possibly prompt-injected content from an untrusted tool from ever reaching a privileged action. `blocked` is the hard kill switch for a tool you never want called

## Turn enforcement on

Discovering a tool and setting its policy does nothing until the `tool_policy` guardrail is active. Enable it in the gateway config with `default_on: true`; it is safe to leave on globally because newly discovered tools default to `untrusted` (allowed), so only `blocked` tools and the trust chain are enforced:

```yaml theme={null}
guardrails:
  - guardrail_name: tool_policy
    litellm_params:
      guardrail: tool_policy
      mode: pre_call
      default_on: true
```

Recreate the gateway after changing the config so it loads the guardrail

## Set a policy

Use the **Tool Policies** page (Tools -> Tool Policies) to change a tool's input or output policy, or the API:

```bash theme={null}
curl -X POST http://localhost:4000/v1/tool/policy \
  -H "Authorization: Bearer $ADMIN_KEY" -H "Content-Type: application/json" \
  -d '{"tool_name": "get_weather", "input_policy": "blocked"}'
```

The endpoint also accepts `team_id`, `key_hash`, or `key_alias` to scope a policy override to a specific team or key instead of the global default

## Verify end to end

Proven live against the running gateway:

```
1. chat completion with a get_weather tool  -> model returns tool_calls, tool auto-discovers (untrusted/untrusted)
2. POST /v1/tool/policy  {tool_name: get_weather, input_policy: blocked}  -> DB shows blocked
3. enable the tool_policy guardrail (default_on) + recreate the gateway
4. same tool-calling request again  -> 400 "Violated tool policy"
```

Before the guardrail was enabled the blocked policy had no effect; once it is on, the blocked tool is rejected. Set it back to `untrusted` to allow the tool again

## How this relates to agents

An agent's tool calls are governed here just like any other request. The mental model: agents and keys decide *who* and *what capabilities*, tool policies decide *whether the tools those agents call are allowed to run*. They are complementary