Tools

A tool exposes an app capability to an agent. For example, a shop tool might look up a product or request an inventory change.

Declaration and handler

A tool has two parts:

• A declaration describes its commands and inputs.
• A handler is your app code that performs an allowed command and returns its result.

With the TypeScript project API, declarations belong in config.tools. Register handlers in handlers, keyed by tool name. Handlers are executable app code; they do not belong inside a config snapshot.

Keep authority in your app

An agent’s request is not permission to perform an action. Validate the user’s identity, permissions, inputs, and current app state in the handler.

For example, a game inventory handler must check that an item can actually be purchased and that the player has enough currency. Do not accept a claimed balance from conversation text as the source of truth.

For an action that needs human confirmation, implement that approval in your app before performing the action. Do not rely on an instruction such as “always ask first” as the authorization check.

Return a useful result

Return the result of the action, or a clear refusal when it is not allowed. Avoid exposing secrets or unnecessary personal data in a tool response.

Start with a read-only capability, check its behavior, then add state-changing actions with the same permission checks you would use anywhere else in your app.