---
name: kimaai_tools_registry
type: filter
since: 1.4.0
tier: free
feature: function-tools
area: tools-addons
summary: Adds a tool to KimaAI's catalogue of tools, which the "Allowed functions" setting lists and Pro runs through the tool's callback.
parameters:
  - name: tools
    type: array
    description: The tools by name, each with label, description, hidden, sensitive, parameters and callback.
returns:
  type: array
  description: The tools by name.
---

# kimaai_tools_registry

## When it fires

Each time KimaAI reads its catalogue of tools, which is several times in a request: for the options of the setting "Allowed custom functions" (Chatbot Settings, section "Allowed functions"), for the definitions sent to the AI provider, and for each tool call. So a callback adds its definitions and does nothing else: no queries, no requests.

The catalogue holds KimaAI's own tools (`wp_get_post`, `wp_search_posts` and hidden ones such as the knowledge search) and those of the integrations. Each entry is keyed by the tool's name, which the model uses in its call: letters, digits and `_`, at most 64 characters, not starting with a digit; other names are dropped. The keys of an entry:

- `label` and `description`: the setting shows them, and the description tells the model when to call the tool. Write it for the model.
- `parameters`: the JSON schema of the arguments; without it the tool takes none.
- `callback`: a callable, or a function's name, that gets the arguments as an array and returns the result. KimaAI Pro runs it; it encodes an array as JSON for the model.
- `hidden`: true keeps the tool out of the setting, for a tool the add-on offers itself through `kimaai_chatbot_allowed_tools`.
- `sensitive`: true for a tool whose result holds a person's data. The result then reaches the model as it is, without the masking of card numbers and IBANs, and the stored conversation and the stream keep only the number of records.

With KimaAI Pro, the chatbot offers a catalogue tool when it is allowed: ticked in the setting, or added by `kimaai_chatbot_allowed_tools`. When the model calls it, `kimaai_tool_call_allowed` decides first, then the callbacks of `kimaai_chatbot_tool_call` at a priority below 10, and then the tool's `callback`. In the free version the setting is a Pro feature and the chatbot does not offer the catalogue; a tool there is defined with `kimaai_chatbot_tools_registry` and run with `kimaai_chatbot_tool_call`.

## Example

```php
add_filter(
  'kimaai_tools_registry',
  function (array $tools): array {
    $tools['my_opening_hours'] = [
      'label' => 'Opening hours',
      'description' => 'The shop\'s opening hours on one day of the week. Call it when the visitor asks when the shop is open.',
      'parameters' => [
        'type' => 'object',
        'properties' => [
          'day' => [
            'type' => 'string',
            'enum' => ['monday', 'tuesday', 'wednesday', 'thursday', 'friday', 'saturday', 'sunday'],
          ],
        ],
        'required' => ['day'],
        'additionalProperties' => false,
      ],
      'callback' => function (array $args): array {
        $hours = [
          'monday' => '9:00 to 18:00',
          'tuesday' => '9:00 to 18:00',
          'wednesday' => '9:00 to 18:00',
          'thursday' => '9:00 to 20:00',
          'friday' => '9:00 to 18:00',
          'saturday' => '10:00 to 14:00',
          'sunday' => 'closed',
        ];
        $day = (string) ($args['day'] ?? '');

        return isset($hours[$day]) ? ['day' => $day, 'hours' => $hours[$day]] : ['error' => 'Unknown day'];
      },
    ];

    return $tools;
  }
);
```

The tool shows in the setting as "Opening hours". Once it is ticked there, the chatbot of a Pro site answers "When are you open on Thursday?" from the tool's result.

## Related

- `kimaai_chatbot_allowed_tools`: allows a tool without the setting.
- `kimaai_chatbot_tools_registry`: offers a tool for one request, in the free version too.
- `kimaai_chatbot_tool_call`: runs a tool in a callback of its own.
- `kimaai_tool_call_allowed`: blocks a call before the tool runs.
