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.
Parameters
| Name | Type | Description |
|---|---|---|
allow | true|string | True to run the tool. A string blocks the call and reaches the model as its result. |
name | string | The tool’s name. |
args | array | The arguments the model sent, decoded from JSON. |
Returns
true|string: True to run the tool; anything else blocks it.
Example
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 [email protected] 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:
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.