---
name: kimaai_tool_call_allowed
type: filter
since: 1.3.3
tier: free
feature: none
area: tools-addons
summary: Blocks a tool call before the tool runs, with a message for the AI model, or audits every tool call.
parameters:
  - name: allow
    type: true|string
    description: True to run the tool. A string blocks the call and reaches the model as its result.
  - name: name
    type: string
    description: The tool's name.
  - name: args
    type: array
    description: The arguments the model sent, decoded from JSON.
returns:
  type: true|string
  description: True to run the tool; anything else blocks it.
surfaces: [chatbot, admin_assistant, search]
---

# kimaai_tool_call_allowed

## When it fires

Once for each tool call the AI model makes, before anything runs the tool: in a chatbot answer, an admin assistant answer or a search answer, streamed or not. It covers every tool a request offered: the contact form of lead capture, the admin assistant's settings tools, your own tools, and in Pro the handoff, the meeting booking, the customer tools, the knowledge search, the custom functions and the WooCommerce, Contact Form 7 and Gravity Forms tools. A tool the request did not offer is refused before the filter. Buttons and quick actions, such as the handoff button, are not tool calls and do not pass it. In Pro, the MCP tool `inspect_retrieval` asks it for its knowledge search too.

Only `true` lets the tool run. A string blocks the call: the tool does not run, so no contact form, calendar or ticket appears, and the model gets `{"error": <your string>}` as the tool's result and answers the visitor from it. Write the string for the model. Any other value blocks the call with "Tool call blocked". The filter can only block: return `$allow` unchanged when it is not `true`. The customer tools (Pro) write a `blocked` row to their audit log for a blocked call.

Until this release only Pro's tool router and the customer tools asked the filter; the contact form, the handoff, the meeting booking and the admin assistant's tools ran without it. It gets no payload: read the visitor or the time with WordPress's functions.

## Example

```php
add_filter(
  'kimaai_tool_call_allowed',
  function ($allow, string $name) {
    if ($allow !== true || $name !== 'request_human' || !get_option('my_support_on_holiday')) {
      return $allow;
    }

    return 'The support team is on holiday until 6 January. Tell the visitor that they can write to support@example.com and get an answer after the holiday.';
  },
  10,
  2
);
```

While the option `my_support_on_holiday` is set, the chatbot does not hand conversations to the team (`request_human`, the handoff tool of Pro); the model passes the message on instead.

## More examples

Audit: log every tool call with its name, without blocking any:

```php
add_filter(
  'kimaai_tool_call_allowed',
  function ($allow, string $name) {
    error_log('KimaAI tool call: ' . $name);
    return $allow;
  },
  99,
  2
);
```

The arguments can hold what the visitor typed, so the example logs only the name.

## Related

- `kimaai_chatbot_tool_call`: runs the call when it is allowed.
- `kimaai_chatbot_allowed_tools`: keeps a tool out of a request altogether.
- `kimaai_chatbot_handoff`: fires when a conversation went to the team.
