On this page
- 01What you'll set up
- 02How tool control works
- 03Allow and deny tools by name
- 04Allow and deny tool servers
- 05Servers that run tools for the provider
- 06Cap tool calls per run
- 07Try it in Monitor only first
- 08What happens on Enforce
- 09What callers see
- 10Test a denied tool
- 11Keep it as code
- 12If something goes wrong
01
What you'll set up
Agents are only as safe as the tools they can call. In about eleven minutes you will decide which tools and tool servers a policy allows, cap how many calls an agent run can make, and test the result before real traffic depends on it.
- A list of tools an agent may use, and a list it may not
- A list of tool servers an agent may reach
- A cap on tool calls per run
- A Monitor only trial before you enforce
- A test that proves a denied tool is really denied
You need an owner or admin role and a policy bound to your agent's traffic. If you do not have one, start with the guide on creating your first policy.
02
How tool control works
Cloptima sits between your agent and the model provider. It reads the tools your agent offers to the model and the tool calls the model asks for. It does not run the tools. Your agent or your provider does that. Cloptima decides which of those requests are allowed.
1Agent offers tools
Names, and servers if labeled
2Policy checked
Allow and deny lists
3Denied tools removed
The model never sees them
4Model answers
It may ask to call a tool
5Call checked
A denied call is stopped and recorded
The same rules apply on every provider and tool format Cloptima supports, including OpenAI chat and Responses, Anthropic, Gemini, and Bedrock. Cloud and edge gateways judge a request the same way.
03
Allow and deny tools by name
Tool lists are on the Advanced step of the policy form, under Tool & modality restrictions. Enter tool names or wildcard patterns separated by commas.
| Field | Example | What it does |
|---|---|---|
| Allowed tool names | lookup_customer, github_* | Only matching tools may be offered or called. Leave empty to allow any tool that is not denied |
| Denied tool names | github_delete_*, run_shell | Matching tools are never allowed. A deny wins over an allow |
04
Allow and deny tool servers
A tool server is a group of tools, such as an MCP server. Server lists are in the same section of the form.
| Field | Example | What it does |
|---|---|---|
| Allowed tool servers | jira, slack | Only tools from these servers may be used |
| Denied tool servers | remote-shell | Nothing from these servers is ever allowed |
Server names come from the registry. The next guide shows how to register a server. A request that names a server that is not registered is treated as unknown.
05
Servers that run tools for the provider
Some providers run MCP tools themselves, for example OpenAI's mcp tool and Anthropic's MCP connector. The provider reaches the server directly, so the policy is where you decide whether that is allowed.
- Name the server in the request, and list it under Allowed tool servers on the policy
- Name the tools the model may use, so the allow and deny lists can judge each one
- Leave require-approval on, so a person confirms calls the provider would make on its own
06
Cap tool calls per run
Agents can loop. Max tool calls puts a ceiling on how many tool calls one agent run can make.
- 1
Open the policy
Go to AI → Policies and open the policy bound to the agent.
- 2
Open Agent-loop & execution caps
On Advanced, find the section.
- 3
Set Max tool calls
Pick a number that fits a normal run. 10 to 25 suits many assistants.
- 4
Pair it with Max loop iterations
The same section has Max retry count and Max loop iterations for agents that retry or loop.
07
Try it in Monitor only first
Switch on tool rules without blocking anything. Cloptima records what would have been refused, so you can fix the lists before you enforce.
- 1
Set Mode to Monitor only
On the policy, choose Monitor only and fill in the lists.
- 2
Run your agent normally
Use it for a few days.
- 3
Review what was recorded
Open AI → Audit and look at the Policy Violations card for tool reasons.
- 4
Adjust the lists
Add tools your agent really needs. Deny the ones it should not have.
- 5
Switch Mode to Enforce
Do this on a policy bound to one agent first.
08
What happens on Enforce
On an enforcing policy, tool rules act in three places.
| When | What Cloptima does |
|---|---|
| The agent offers a denied tool | The tool is removed before the request reaches the provider. The model never sees it |
| The agent forces a denied tool | The request is refused with HTTP 403 and names the rule |
| The model asks to call a denied tool | The call is stopped and recorded as a policy violation |
Removing a denied tool lets the agent keep working with the tools it may use. You do not have to change the agent.
09
What callers see
A refused request returns HTTP 403 with a reason that says which rule applied.
{
"error": "Your AI request was blocked because the requested tool use is not allowed by the active Cloptima policy.",
"reason": "tool_denied",
"violations": ["tool_denied"]
}| Reason | Meaning | Fix |
|---|---|---|
| tool_denied | The tool is on the denied list | Remove it from the denied list, or stop sending it |
| tool_not_allowed | The tool is not on the allowed list | Add it to Allowed tool names |
| tool_server_denied | The server is on the denied list | Use another server, or remove it from Denied tool servers |
| tool_server_not_allowed | The server is not on the allowed list | Add it to Allowed tool servers |
| tool_server_unknown | The server is not registered, or its name is missing | Register the server and use its registered name in the request |
| max_tool_calls_exceeded | The run made more tool calls than allowed | Raise Max tool calls if the behavior is expected |
10
Test a denied tool
Prove the rule with a throwaway policy. Declare a tool you denied and see what the model receives.
- 1
Deny a test tool
On a test policy, add delete_repo to Denied tool names and set Mode to Enforce.
- 2
Bind it to a test key
Create a virtual key and bind the policy to it.
- 3
Force the denied tool
Send a request that selects the tool by name. You should see HTTP 403 with tool_denied.
curl https://api.cloptima.ai/v1/ai/chat/completions \
-H "Authorization: Bearer $CLOPTIMA_VIRTUAL_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-4o-mini",
"messages": [{"role": "user", "content": "Remove the old repo"}],
"tools": [{"type": "function", "function": {"name": "delete_repo", "parameters": {"type": "object", "properties": {}}}}],
"tool_choice": {"type": "function", "function": {"name": "delete_repo"}}
}'Remove tool_choice and send the same request. The call now succeeds, and the model sees no tools, because delete_repo was removed before it reached the provider.
11
Keep it as code
Tool rules can live in Terraform with the rest of the policy.
resource "cloptima_llm_gateway_policy" "support_agent" {
name = "support-agent"
mode = "enforce"
allowed_tool_names = ["lookup_customer", "create_ticket"]
denied_tool_names = ["delete_repo", "run_shell"]
allowed_tool_servers = ["jira"]
max_tool_calls = 20
}12
If something goes wrong
Most surprises come from names or from which policy applies.
| What you see | Likely cause | Fix |
|---|---|---|
| A denied tool still works | The policy is in Monitor only mode, or another policy applies | Switch Mode to Enforce and check the bindings |
| The agent lost a tool it needs | The tool is not on the allowed list | Add its exact name to Allowed tool names |
| tool_server_not_allowed for a server you registered | A provider-run server must also be on the policy's allowed list | Add the server to Allowed tool servers |
| A deny list does not match | The name differs from what the agent sends | Copy the exact name from the agent's tool definition |