The tools registry

A “tool” is something the chatbot can do beyond writing text — search your Knowledge Base, look up a product, read a cart. The registry is how tools are declared and how the model is told about them.

The shape

Tools are authored in the same shape as WordPress core’s Abilities API: a label, a description, a category, an input schema, an output schema, an execute callback, and a permission callback.

That is deliberate. A tool written against this registry reads like one written against core’s, and the concepts transfer.

What reaches the model is a normalised wire format, adapted for whichever provider is answering — including a rename of / to __ in tool names, because OpenAI’s function-name rules do not accept slashes.

The hooks

Registering:

• sohaychat_abilities_api_init — fires once per request during bootstrap. Subscribers register tools by calling sohaychat_register_ability(). Parallels core’s wp_abilities_api_init.
• sohaychat_abilities_api_categories_init — the same, for categories.

Intercepting registration:

• sohaychat_register_ability_args — mutate a tool’s arguments before registration validates them. Signature: ( array $args, string $name ).
• sohaychat_register_ability_category_args — the same for categories.

Around execution:

• sohaychat_before_execute_ability — after the permission check passes, before the callback runs. Args: ( string $name, mixed $input ).
• sohaychat_after_execute_ability — after execution, with the normalised result. Args: ( string $name, mixed $input, $result ).

Choosing what the model sees:

• sohaychat_tools — the resolved tool list for the request. This is the one most sites use.

The difference between removing and denying

Worth being precise about.

A tool removed via sohaychat_tools is never described to the model. It cannot call something it does not know exists, and none of that tool’s data can reach your provider.

A tool whose permission callback returns false is still described, still attempted, and refused at execution. The model knows it exists and may tell the visitor about it.

For anything privacy-relevant, remove it rather than denying it.

The activity log

Every tool invocation flows through sohaychat_after_execute_ability and lands in an audit table. That is where the Knowledge Base lookups and the WooCommerce tools both record what they were asked and what they returned.

It is the same hook to subscribe to if you want tool usage in your own telemetry.

Caching

A tool can declare a cache lifetime. The WooCommerce catalog tools use 60 seconds, the policy lookup 300, and the cart tools none at all — cart state is mutable, and a cached cart is a wrong cart.

Where to go next

Adding your own chat tool for building one, and Turning individual shopping tools off for removing one.