Skip to Content
Baseera Docs

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.

KindWhat it doesApproval
ReadLooks something up and changes nothing.Runs directly
DraftProposes a value or content for the user to accept.Needs approval
WriteChanges 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.

src/components/invoice-tools.tsx
"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;
}
  • description tells the model when to use the tool. Write it like instructions to a colleague.
  • describe is the sentence on the approval card. Write it for the person who clicks.
  • A tool can take an undo function, 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

SymptomCause and fix
"No tools seen yet" after chattingThe 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 toolImprove its description, and mention the tool's job in the system prompt.
The model gets "an error listing what is wrong" and retriesThe input did not match your Zod schema. Make the schema's describe text clearer.
A write tool runs without a cardIt was registered as read. Change kind to "write".

Next steps

On this page