Tools

Tools are the bridge between Pillar's co-pilot and your application. They represent things users can do — navigating to a page, opening a modal, filling a form, calling an API — and the co-pilot suggests them when relevant.

Without tools, the co-pilot can only answer questions. With tools, it becomes an assistant that does things on behalf of users.

How it works

1. You define tools in your code with descriptions the co-pilot can understand
2. A user asks a question ("How do I change my billing plan?")
3. The co-pilot matches the intent to your "Upgrade Plan" tool
4. The user clicks the suggested tool, and your handler runs

Example tool definition

{
  name: 'invite_team_member',
  type: 'trigger_tool',
  description: 'Invite a new member to the team workspace',
  parameters: {
    type: 'object',
    properties: {
      email: {
        type: 'string',
        description: 'Email address of the person to invite',
      },
      role: {
        type: 'string',
        enum: ['admin', 'member', 'viewer'],
        description: 'Role to assign to the new member',
      },
    },
    required: ['email'],
  },
  execute: async ({ email, role }) => {
    // Your logic here — open a modal, call an API, etc.
  },
}

The description helps the co-pilot understand when to suggest this tool. The parameters schema tells it what data to extract from the user's message. The execute function runs when the user confirms the tool.

Tool types

Auto-run behavior

Some tools run automatically without user confirmation:

• navigate, external_link, and copy_text tools auto-run by default (safe, instant actions)
• Other types like trigger_tool, open_modal, and fill_form require user confirmation
• Only the top-ranked tool in a response can auto-run, preventing multiple simultaneous actions

Setting autoRun: true on a tool enables auto-run for types that don't auto-run by default. Note that default auto-run types (navigate, external_link, copy_text) always auto-run when they are the top match — the default cannot be disabled per-tool.

Data extraction

When you register a tool on the client, you can define an inputSchema that tells the co-pilot what data to extract from the conversation. When a user says "invite sarah@acme.com as an admin," the co-pilot extracts { email: "sarah@acme.com", role: "admin" } and passes it to your client-side tool handler.

Context requirements

Tools can specify required context to only appear in relevant situations:

• An "Edit Project" tool only appears when context.projectId is set
• An "Admin Settings" tool only appears when context.userRole === 'admin'

This keeps suggestions relevant and prevents users from seeing tools they can't use.

Inline UI

Tools with type: 'inline_ui' render your components directly in the chat instead of running an execute function. The AI extracts data from the conversation via inputSchema and passes it to your render component.

{
  name: 'confirm_delete',
  type: 'inline_ui',
  description: 'Show a confirmation card before deleting a resource',
  inputSchema: {
    type: 'object',
    properties: {
      resourceName: { type: 'string' },
      resourceId: { type: 'string' },
    },
    required: ['resourceName', 'resourceId'],
  },
  render: ConfirmDeleteCard,
}

The render component receives:

• data — structured data the AI extracted from the conversation
• sendResult — a callback that sends a result back to the AI agent, continuing the conversation
• context — metadata about the card's position in the chat (isLatest, isReady)

There is no execute function. The render prop is required — inline_ui tools without one will not register and will log a warning.

For a full implementation walkthrough, see Building Inline UI.

Server-side tools

The tools above all run in the browser. If your tool needs database access, secret credentials, or backend business logic, use a server-side tool instead. Server tools run on your backend and are called via webhooks from Pillar Cloud.

Server tools are available for TypeScript (Express, Fastify, Hono, Next.js) and Python (Django, Flask, FastAPI). See Server SDKs for the full guide.

Next steps

• Setting up tools — Step-by-step client-side implementation guide
• Syncing tools — How to sync tools to Pillar's backend
• Building Inline UI — Render custom UI components in the chat
• Server SDKs — Define tools that run on your backend