Tools

A tool is a pointer to one of your own backend endpoints, so the model can call it during a turn. Tools allow models to use and reference real data. When the model needs a customer’s orders, their loyalty tier, or the result of an action they asked for, it calls a tool in your backend.

The tool registry is where you add those endpoints: what each one is called, when the model should call it, its URL, what the model may pass to it, and who it runs for.

Tool definition

Tools can define a URL, parameters, whether they run at session start to provide initial context to the model, whether they carry information about the logged-in user, etc. You can read Defining a tool for all the details.

Safely calling third-party APIs

A tool’s URL should point at your own backend, not directly at a third-party service. The platform calls that URL and authenticates the call as itself, with a short-lived signed assertion your backend verifies. Registering a tool never hands the platform a key into that tool’s downstream services, so a leak on our side cannot reach a third party a tool depends on.

When a tool needs data from a third-party API that carries its own key, such as a payment processor, a shipping provider, or a mapping service, make your backend the endpoint the platform calls and have it forward the request to the third party with the credential it holds. The secret stays in your infrastructure, where you rotate and audit it, and the platform only ever sees the response your backend chooses to return. This is the same shape as the backend you already run to mint session tokens with the backend SDK: the tool call is one more request it authenticates and fans out from.

For the time being, any tool that reaches a third-party service does so through your backend.