kimaai_chatbot_tools_registry Filter #

The kimaai_chatbot_tools_registry filter is the chatbot’s tools registry. It lets you register, modify, or remove AI tools (function definitions) that can be exposed to the model for tool-calling.

This filter runs on every chatbot request after basic validation and limits, and before the AI provider payload is finalized.

---

When it runs #

In the /kimaai/v1/chatbot flow, after the request:

• passes the gate (kimaai_chatbot_gate)
• passes rate limiting (maxMessages)
• passes input length checks (maxInputLength)

…the plugin calls:

$tools = apply_filters('kimaai_chatbot_tools_registry', [], $payload, $chatbot_settings);

Then it further restricts tools based on what the user/admin selected in settings:

• If the user selected tools, only those tool names are kept.
• If no tools were selected, no tools are exposed ($tools = []).

So this filter defines the full catalog, and the plugin later applies per-request selection.

---

Filter signature #

/**
 * Filter: tools registry (add/modify/remove tools).
 *
 * @param array $tools The array of tool definitions.
 * @param array $data The data from the request.
 * @param array $chatbot_settings The chatbot settings.
 * @return array The modified array of tool definitions.
 */
$tools = apply_filters('kimaai_chatbot_tools_registry', [], $payload, $chatbot_settings);

Parameters #

1) $tools (array) #

Initial tool list (defaults to an empty array []). Your callback should return an array of tool definitions.

2) $payload (array) #

Normalized request payload (commonly includes prompt, postId, sessionId, and selectedTools).

3) $chatbot_settings (array) #

Chatbot settings used for this request (provider/model/settings/limits/etc.).

Return value #

Return an array of tools. Each tool should be an associative array that matches your AI provider’s expected schema (the plugin later passes these to AiService, which may transform keys as needed).

At minimum, each tool should include a unique name.

---

Tool definition format #

Your tools should follow an OpenAI-style “function tool” shape (typical example):

[
  'type' => 'function',
  'name' => 'my_tool_name',
  'description' => 'What this tool does',
  'parameters' => [
    'type' => 'object',
    'properties' => [
      'query' => [
        'type' => 'string',
        'description' => 'Search query',
      ],
    ],
    'required' => ['query'],
  ],
]

Important: the plugin filters tools by $tool['name'] when matching user-selected tools. If name is missing/empty, the tool will be dropped.

---

Basic example: register a single tool #

add_filter('kimaai_chatbot_tools_registry', function (array $tools, array $payload, array $chatbot_settings): array {
  $tools[] = [
    'type' => 'function',
    'name' => 'site_contact_info',
    'description' => 'Returns the site contact email and phone number.',
    'parameters' => [
      'type' => 'object',
      'properties' => [],
    ],
  ];

  return $tools;
}, 10, 3);

---

Example: register multiple tools (search + page summary) #

add_filter('kimaai_chatbot_tools_registry', function (array $tools): array {
  $tools[] = [
    'type' => 'function',
    'name' => 'wp_search_posts',
    'description' => 'Searches WordPress posts by keyword and returns a small list of matches.',
    'parameters' => [
      'type' => 'object',
      'properties' => [
        'query' => ['type' => 'string', 'description' => 'Search keywords'],
        'limit' => ['type' => 'integer', 'description' => 'Max results (1-10)'],
      ],
      'required' => ['query'],
    ],
  ];

  $tools[] = [
    'type' => 'function',
    'name' => 'wp_get_post_excerpt',
    'description' => 'Returns an excerpt for a given post ID.',
    'parameters' => [
      'type' => 'object',
      'properties' => [
        'postId' => ['type' => 'integer', 'description' => 'WordPress post ID'],
      ],
      'required' => ['postId'],
    ],
  ];

  return $tools;
}, 10, 1);

Defining tools here only registers them. The actual execution/handler for tool calls is handled by your AI/tool integration layer (wherever your plugin maps tool calls to PHP functions).

---

Example: conditionally expose tools (admins only) #

add_filter('kimaai_chatbot_tools_registry', function (array $tools): array {
  if (!is_user_logged_in() || !current_user_can('manage_options')) {
    return $tools;
  }

  $tools[] = [
    'type' => 'function',
    'name' => 'wp_list_users',
    'description' => 'Lists WordPress users (admin-only).',
    'parameters' => [
      'type' => 'object',
      'properties' => [
        'limit' => ['type' => 'integer', 'description' => 'Max users'],
      ],
    ],
  ];

  return $tools;
}, 10, 1);

---

Example: remove/override a tool by name #

add_filter('kimaai_chatbot_tools_registry', function (array $tools): array {
  // Remove a tool named "wp_search_posts" if it exists.
  $tools = array_values(array_filter($tools, function ($tool) {
    return !is_array($tool) || ($tool['name'] ?? '') !== 'wp_search_posts';
  }));

  // Add a safer replacement.
  $tools[] = [
    'type' => 'function',
    'name' => 'wp_search_posts_safe',
    'description' => 'Searches published posts only (safe subset).',
    'parameters' => [
      'type' => 'object',
      'properties' => [
        'query' => ['type' => 'string'],
      ],
      'required' => ['query'],
    ],
  ];

  return $tools;
}, 10, 1)

---

How selection interacts with this registry #

Even if you register tools here, the plugin will restrict them based on the tools selected in settings / request:

• If the user selected tools: only tools whose name appears in selectedTools are kept.
• If no tools were selected: the final tool list becomes [] (no tools exposed to the AI).

This means:

• Registry defines what is possible
• Settings/selection defines what is allowed in this request

---

Best practices #

• Keep tool names stable and unique (they are used for selection filtering).
• Provide good description text—models use it to decide when to call a tool.
• Keep parameter schemas tight:
  • minimal required inputs
  • sensible bounds (e.g., limit max 10)
• Avoid exposing tools that can leak private data unless you enforce capability checks (role-based, login checks, etc.).
• Don’t do heavy work inside the registry filter—just return definitions.

---

Related hooks #

• kimaai_chatbot_ai_payload — final chance to include/adjust tools, toolChoice, etc.
• kimaai_chatbot_gate — allow/block request before any tools are used
• kimaai_chatbot_before_request — telemetry just before AI call
• kimaai_chatbot_after_response — telemetry after success