---
name: kimaai_chatbot_tools_registry
type: filter
since: 1.3.5
tier: free
feature: none
area: tools-addons
summary: Defines the tools one chatbot request offers the AI model, for example a tool only on product pages.
parameters:
  - name: tools
    type: array
    description: The tool definitions as the provider gets them, each with type function, name, description and parameters.
  - name: payload
    type: array
    description: The normalised request payload, with prompt, sessionId, postId, chatbot_settings and selectedTools, the names kimaai_chatbot_allowed_tools returned.
  - name: chatbot_settings
    type: array
    description: The chatbot settings.
returns:
  type: array
  description: The tool definitions.
surfaces: [chatbot, search]
---

# kimaai_chatbot_tools_registry

## When it fires

In every chatbot request, streamed or not, and every search answer, while the request is prepared: after `kimaai_chatbot_gate` and the limits, right after `kimaai_chatbot_allowed_tools`, before anything reaches the AI provider. It starts from an empty list. KimaAI adds its own at priority 10: the contact form tool of lead capture while it asks on buying intent and the conversation has no lead yet, and in Pro the catalogue of `kimaai_tools_registry`, the custom functions and the meeting booking tool.

Each definition is an array with `type` `function`, the tool's `name`, a `description` that tells the model when to call it, and `parameters`, the JSON schema of its arguments. After the filter KimaAI keeps only the definitions whose name is among the allowed tools (`$payload['selectedTools']`): a tool needs both filters, or an entry in the setting "Allowed custom functions" (Pro). With no allowed tool, the request offers none. A search answer keeps only the knowledge search.

The request offers the tool; `kimaai_chatbot_tool_call` runs it when the model calls it. A tool no request offered is never run, whatever the model asks for.

## Example

```php
add_filter(
  'kimaai_chatbot_tools_registry',
  function (array $tools, array $payload): array {
    if (get_post_type((int) ($payload['postId'] ?? 0)) !== 'product') {
      return $tools;
    }

    $tools[] = [
      'type' => 'function',
      'name' => 'my_delivery_time',
      'description' => 'The delivery time to a country in working days. Call it when the visitor asks when an order arrives.',
      'parameters' => [
        'type' => 'object',
        'properties' => [
          'country' => [
            'type' => 'string',
            'description' => 'The two-letter country code, for example DE.',
          ],
        ],
        'required' => ['country'],
        'additionalProperties' => false,
      ],
    ];

    return $tools;
  },
  10,
  2
);

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

The chatbot offers `my_delivery_time` on product pages only; elsewhere the model does not know it. `postId` is the page the chat sits on, 0 in a search answer. [The page of `kimaai_chatbot_tool_call`](https://kimaai.com/docs/hooks/kimaai_chatbot_tool_call/) runs the tool.

## Related

- `kimaai_chatbot_allowed_tools`: the names a request may offer.
- `kimaai_chatbot_tool_call`: runs the tool.
- `kimaai_tools_registry`: the catalogue of tools the setting lists (Pro).
- `kimaai_chatbot_max_tool_rounds`: how many rounds of tool calls an answer may take.
