Tools

A tool is a named action the AI can call, with typed inputs — e.g. send_email(to, subject, body). Tools are declared in a skill’s tools.ts and, for tools your app serves, backed by an HTTP route in one of your components. This page is the source of truth for the tool contract; Skills covers where tools.ts lives.

Declaring a tool

Each entry in tools.ts has a provider-safe name, a friendly displayName, a description, a Zod input schema, and a target that says what Kazzle invokes.

import { z } from 'zod';
import type { KazzleTool } from '@kazzle/app/tools';

export const SaveBookmarkInput = z.object({
  url: z.string().url().describe('URL to save.'),
  title: z.string().optional().describe('Optional human-readable title.'),
}).strict();

const saveBookmarkTarget = {
  type: 'app',
  component: 'api',
  path: '/tools/save-bookmark',
  method: 'POST',
  body: '${input}',
} as const;

export const tools = [
  {
    name: 'save_bookmark',
    displayName: 'Save bookmark',
    description: 'Save a bookmark URL and return a confirmation.',
    input: SaveBookmarkInput,
    target: saveBookmarkTarget,
  },
] as const satisfies readonly KazzleTool[];

Targets

target is the reusable address for a tool or pending-input button. A direct AI tool call and a button click can use the same target object, so both run the same code.

Target	Fields	Runs where
`app`	`component`, `path`, `method`, optional `query`, `headers`, `body`	One of your own components. Kazzle resolves the component URL and adds a signed app identity token.
`url`	`url`, `method`, optional `query`, `headers`, `body`	An external endpoint. The URL origin and method are literal author values.
`kazzle`	`name`	A built-in client-side Kazzle handler.

HTTP targets use the same request fields:

type RequestSpec = {
  method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
  query?: Record<string, string>;
  headers?: Record<string, string>;
  body?: unknown;
};

There are no implicit request defaults. If your handler should receive the raw tool input as JSON, write body: '${input}'.

References

Kazzle resolves references in HTTP target query, headers, body, and url fields before dispatch:

${input} — the whole tool input, or the whole button input.
${input.path} — a nested value from the input.
${env.NAME} — a named environment variable from the owning app component’s declared env.collection + env.environment.

Resolution is single-pass. If a reference is missing or unknown, the tool fails instead of substituting an empty value. Use $${input.name} when you need literal ${input.name} text.

Handler request

For an app target, add the matching route in the target component. With body: '${input}', Kazzle sends the typed input as the JSON body:

{ "...": "the typed input" }

app targets also receive an Authorization: Bearer <identity token> header identifying the user + install. App targets cannot set Authorization through headers; Kazzle owns that header. A tool declared with no matching route does nothing useful — add both together. tools.json is not supported; the app compiler fails if it finds one.

Handler response

Return plain text, or JSON with up to three channels:

{ "content": "...", "markdown": "...", "embedUrl": "https://..." }

content — the plain result the AI reads (fed to the model). Required.
markdown — optional. A short rich-text summary rendered in the tool card (react-markdown; raw HTML is escaped). Good for a sentence, a small list, an inline link. A bare relative path renders as dead preformatted text — links must be absolute.
embedUrl — optional. An absolute URL your app serves; the card renders it in a sandboxed iframe. This is how you show a real, full-width UI — a connect screen, a dashboard, a chart. Your app hosts and owns the page, so it can be fully interactive against your own backend, cookies, and OAuth. Nothing is written to the drive.

embedUrl wins over markdown when both are set. Always keep a meaningful content — that’s what the AI reads.

if (req.method === 'POST' && new URL(req.url).pathname === '/tools/save-bookmark') {
  const input = await req.json();
  // ...do the work...
  return Response.json({ content: `Saved ${input.title}` });
}

Pending input

An app tool can pause the thread when it needs the user to act. Return type: 'pending_input' with a card title and buttons:

return Response.json({
  type: 'pending_input',
  title: 'Connect Gmail',
  description: 'Connect Gmail before Kazzle can search messages.',
  elements: [
    {
      type: 'button',
      id: 'connect',
      label: 'Connect Gmail',
      input: { scope: 'gmail.readonly' },
      target: {
        type: 'app',
        component: 'api',
        path: '/oauth/start',
        method: 'POST',
        body: '${input}',
      },
    },
  ],
});

Kazzle saves the card on the tool call, shows it on every device, and resumes the thread through /chat/resume after the user clicks a button. A button without target submits its input as the tool result. A button with a target runs that target first, then uses the target result as the tool result.

Rich UI — embed an app-hosted page

When a tool’s result is visual or interactive (a connect screen, a chart, a summary dashboard), serve the page from one of your components and return its absolute URL as embedUrl. Build the URL from the injected component URL — never a relative path.

// A tool that needs the user to connect their account:
return Response.json({
  content: "Gmail isn't connected yet — the user needs to connect it.",
  embedUrl: `${process.env.KAZZLE_APP_COMPONENT_URL}/connect?token=${identity}`,
});

The page runs in a cross-origin iframe (its own origin, cookies, and scripts). To size the card, post its height to the parent — the card listens for this and resizes (capped at 70% of the viewport):

// inside the embedded page
parent.postMessage({ __kazzle_height: document.body.scrollHeight }, '*');

Prefer embedUrl over emitting HTML strings: your app already serves pages, the UI stays interactive and versioned with your code, and no per-call artifacts are written anywhere.

​Tools

​Declaring a tool

​Targets

​References

​Handler request

​Handler response

​Pending input

​Rich UI — embed an app-hosted page