---
summary: How a plugin gives the KimaAI chatbot a tool of its own, which the AI model calls to look something up on the site.
area: tools-addons
hooks:
  - kimaai_chatbot_tools_registry
  - kimaai_chatbot_allowed_tools
  - kimaai_chatbot_tool_call
  - kimaai_tool_call_allowed
  - kimaai_chatbot_max_tool_rounds
  - kimaai_tools_registry
---

# A tool for the chatbot

A tool is a function the AI model may call while it writes an answer: it sends the tool's name and arguments, KimaAI runs the tool on your site, and the model answers from the result. Three filters make one: `kimaai_chatbot_tools_registry` describes the tool to the model, `kimaai_chatbot_allowed_tools` allows it, and `kimaai_chatbot_tool_call` runs it. This guide builds a tool that finds the shop's stores in a city. It works in the free version and in Pro.

## Example

```php
add_filter(
  'kimaai_chatbot_tools_registry',
  function (array $tools): array {
    $tools[] = [
      'type' => 'function',
      'name' => 'my_find_store',
      'description' => 'The shop\'s stores in a city, with address and opening hours. Call it when the visitor asks for a store near them.',
      'parameters' => [
        'type' => 'object',
        'properties' => [
          'city' => [
            'type' => 'string',
            'description' => 'The city, for example Freiburg.',
          ],
        ],
        'required' => ['city'],
        'additionalProperties' => false,
      ],
    ];

    return $tools;
  }
);

add_filter(
  'kimaai_chatbot_allowed_tools',
  function (array $names): array {
    $names[] = 'my_find_store';
    return $names;
  }
);

add_filter(
  'kimaai_chatbot_tool_call',
  function ($result, string $name, array $args) {
    if ($result !== null || $name !== 'my_find_store') {
      return $result;
    }

    $stores = [
      'freiburg' => [
        ['address' => 'Market Square 1', 'hours' => 'Mon to Sat 9:00 to 19:00'],
        ['address' => 'Station Road 20', 'hours' => 'Mon to Fri 10:00 to 18:00'],
      ],
      'valencia' => [
        ['address' => 'Harbour Street 5', 'hours' => 'Mon to Sat 10:00 to 20:00'],
      ],
    ];
    $city = strtolower(trim((string) ($args['city'] ?? '')));

    return ['city' => $city, 'stores' => $stores[$city] ?? []];
  },
  5,
  3
);
```

Put the code in your plugin. When a visitor asks "Do you have a store in Freiburg?", the model calls `my_find_store` with `{"city":"Freiburg"}` and answers with the two addresses. The stores are a list in the code here; your tool reads them where they live on your site, a post type or an option. An empty list is a valid result: the model then says there is no store in that city.

## How a tool call runs

1. A chatbot request is prepared. `kimaai_chatbot_allowed_tools` gives the names the request may offer, then `kimaai_chatbot_tools_registry` the definitions. KimaAI keeps the definitions whose name is allowed and sends them to the AI provider with the visitor's message.
2. The model answers, or calls one or more tools. KimaAI refuses a tool the request did not offer, so the model cannot run a tool by naming it.
3. `kimaai_tool_call_allowed` decides whether the call may run.
4. `kimaai_chatbot_tool_call` runs it: the callback that knows the tool returns the result.
5. KimaAI sends the results back to the model, which answers or calls the next tool. Each of these rounds is another request to the AI provider.

Each request asks the filters again, so the tool can depend on the page or the visitor. `$payload['postId']`, the second argument of `kimaai_chatbot_tools_registry`, is the page the chat sits on; [the filter's page](https://kimaai.com/docs/hooks/kimaai_chatbot_tools_registry/) offers a tool on product pages only. The search answer keeps only the knowledge search, so a tool of your own runs in the chatbot only.

## Two registries

KimaAI has two filters with "tools registry" in their name:

- `kimaai_chatbot_tools_registry` is the list of one request, the definitions the model gets. The example uses it, so the tool works in every version.
- `kimaai_tools_registry` is the catalogue of tools: the setting "Allowed custom functions" (Chatbot Settings, Pro) lists it, so a site owner can switch a tool on and off by hand. An entry can carry a `callback` that runs the tool, and `sensitive` for a tool whose result holds a person's data. With Pro, every allowed catalogue tool goes into the request's list. In the free version the setting is a Pro feature and the catalogue does not reach the chatbot.

Use the catalogue for a tool the site owner should decide on, with Pro; [its page](https://kimaai.com/docs/hooks/kimaai_tools_registry/) has an example. Use the request's list for a tool your plugin always offers, or offers by page or visitor.

## Running the call

The callback of `kimaai_chatbot_tool_call` gets `null` and returns the result for its own tool; for any other tool it returns what it got. Add it at a priority below 10: at 10, Pro's tool router answers every tool it is asked about, and the result is no longer `null` when your callback runs.

- Return an array; KimaAI encodes it as JSON for the model. Keep it short: the result counts towards the request's tokens.
- For a case the tool cannot handle, return a result that says so, such as `['error' => 'Unknown city']`. The model reads it and tells the visitor in its own words.
- An exception your callback throws reaches the model as `{"error": <message>}`, and a streamed chat shows that the tool failed, so catch what you can.
- KimaAI masks card numbers and IBANs in the result while the chatbot's masking is on, and emails and phone numbers when the settings ask for it.
- The result is stored with the conversation and, in a streamed chat, sent to the browser with the tool's progress. Return only what the visitor may see.

The arguments come from the model. Treat them as the visitor's input: check them, and never let them choose whose data the tool reads. A tool for a logged-in customer reads the customer from WordPress's current user, not from an argument.

## Blocking a call

`kimaai_tool_call_allowed` runs before every tool call, KimaAI's own tools included. Return a string to block a call; the model gets it as the tool's result:

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

    return 'All stores are closed for stocktaking today. Suggest the online shop instead.';
  },
  10,
  2
);
```

To keep a tool out of a request altogether, remove its name in `kimaai_chatbot_allowed_tools` instead: the model then does not know it.

## Rounds

An answer may take 6 rounds of tool calls by default. When your tools are called one after another, an order lookup and then its delivery, raise the number with `kimaai_chatbot_max_tool_rounds`. Each round is a request to the AI provider and costs tokens. When the model still calls a tool after the last round, your tool does not run: the model gets a note that the budget is spent and answers with what it has, streamed or not.

```php
add_filter(
  'kimaai_chatbot_max_tool_rounds',
  function (int $max_rounds): int {
    return 8;
  }
);
```

## Related

- [kimaai_chatbot_tools_registry](https://kimaai.com/docs/hooks/kimaai_chatbot_tools_registry/): the definitions a request offers.
- [kimaai_chatbot_allowed_tools](https://kimaai.com/docs/hooks/kimaai_chatbot_allowed_tools/): the names a request may offer.
- [kimaai_chatbot_tool_call](https://kimaai.com/docs/hooks/kimaai_chatbot_tool_call/): runs the tool.
- [kimaai_tool_call_allowed](https://kimaai.com/docs/hooks/kimaai_tool_call_allowed/): blocks a call.
- [kimaai_chatbot_max_tool_rounds](https://kimaai.com/docs/hooks/kimaai_chatbot_max_tool_rounds/): the rounds of an answer.
- [kimaai_tools_registry](https://kimaai.com/docs/hooks/kimaai_tools_registry/): the catalogue the setting lists (Pro).
