Tools
Define the actions your assistant can take in your app, and see which tools Baseera has received.
A tool is a function in your app that the assistant can call: look up an invoice, mark it as paid, draft a message. You define tools in your app's code, and they run in your app with the signed-in user's own session. Baseera never stores or runs them. The Tools page shows what your app has announced.
Read, draft and write tools
Every tool has a kind. The kind decides whether the user is asked first.
| Kind | What it does | Approval |
|---|---|---|
| Read | Looks something up and changes nothing. | Runs directly |
| Draft | Proposes a value or content for the user to accept. | Needs approval |
| Write | Changes data in your app. | Needs approval |
Choose the kind by what the call can do, not by how risky it feels. If a call could change anything, make it write. See Approvals for what the user sees.
Approval happens in the user's browser, in the SDK. The model asks for a write tool, the runtime passes the request to the browser, and the SDK holds it until the user decides. Only an approved call reaches your code. Your own API should still check permissions, because the tool runs as the signed-in user.
Define a tool
Tools are registered with useBaseeraTool from @baseera/react, inside a component that is mounted while the assistant is on screen. The input is a Zod schema, and Baseera checks what the model sends against it before anything runs.
"use client";
import { useBaseeraTool } from "@baseera/react";
import { z } from "zod";
const markPaidInput = z.object({ id: z.string().describe("Invoice number, for example INV-1042") });
export function InvoiceTools() {
useBaseeraTool({
name: "markInvoicePaid",
description: "Mark an unpaid invoice as paid.",
kind: "write",
input: markPaidInput,
describe: ({ id }) => `Mark invoice ${id} as paid`,
run: async ({ id }) => {
const res = await fetch(`/api/invoices/${encodeURIComponent(id)}/pay`, { method: "POST" });
if (!res.ok) throw new Error(`The API answered ${res.status}.`);
return res.json();
},
});
return null;
}descriptiontells the model when to use the tool. Write it like instructions to a colleague.describeis the sentence on the approval card. Write it for the person who clicks.- A tool can take an
undofunction, so the card offers Undo after it runs. See Approvals.
The full SDK reference is in Tools and approvals.
See which tools Baseera received
Open the agent and choose Tools in the sidebar.
Open your app and start a conversation, so the SDK sends the tool list with the first turn.
Reload Tools. Under Your app's tools each tool shows its Tool name and kind (Read, Draft, Write), Approval, Description, Last seen, Versions, First seen and the Pages it was sent from.
The page lists tools seen in the last 24 hours and counts earlier ones ("N tools were seen earlier"). A changed description or schema counts as a new version, and the earlier versions are kept. The Versions column says Never changed or Changed once, Changed twice and so on, so you can spot a tool whose meaning shifted.
If the page says "No tools seen yet", the first turn that sends tools has not happened. The Tools seen step of the first-run checklist turns done at the same moment.
Built-in tools
Built-in lists tools every agent can use without code in your app. Today that is knowledge.search, which searches the knowledge attached to the agent and cites the sources. It runs on Baseera's servers and reads only.
Tools that run without a page open
Importing an OpenAPI description, plain HTTP requests and MCP servers, which would run with no page open, are listed as Platform tools and are not available yet.
Test tools without calling your app
A test never calls your real tools. When you write a test, you give each tool a mock result, and a call to a tool without a mock fails with "No mock for ...". See Test suites.
What can go wrong
| Symptom | Cause and fix |
|---|---|
| "No tools seen yet" after chatting | The component that registers tools is not mounted on the page, or your app has not signed a user token. Check the Integrate health lines Tool manifest and Signed user tokens. |
| The model never calls a tool | Improve its description, and mention the tool's job in the system prompt. |
| The model gets "an error listing what is wrong" and retries | The input did not match your Zod schema. Make the schema's describe text clearer. |
| A write tool runs without a card | It was registered as read. Change kind to "write". |