Tools

Tools are the bridge between Pillar's co-pilot and your application. They represent things users can do—like navigating to a page, opening a modal, or triggering a workflow—and the co-pilot suggests them when relevant.

Why Tools Matter

Without tools, the co-pilot can only answer questions. With tools, it becomes an assistant that helps users do things:

Without Tools	With Tools
"Here's how to invite a team member..."	"Here's how to invite a team member. [Invite Team Member]"
User reads instructions, navigates manually	User clicks the tool, modal opens automatically

With tools, the co-pilot can take action on behalf of users, not just answer questions.

How It Works

You define tools in your code

Describe what each tool does in natural language the AI can understand.

User asks a question

"How do I change my billing plan?"

AI matches intent to tools

The co-pilot finds your "Upgrade Plan" tool based on semantic similarity.

User clicks the suggested tool

Your handler runs—navigates to billing, opens the upgrade modal, whatever you defined.

Tool Types

Pillar supports five tool types for different use cases:

Type	What It Does	Example
`navigate`	Goes to a page in your app	Settings, dashboard, detail pages
`trigger_tool`	Runs your custom logic	Opens modals, starts wizards, toggles features
`query`	Search or filter data	Search products, find users
`open_modal`	Opens a modal or dialog	Confirmation forms, settings dialogs
`external_link`	Opens a URL in a new tab	Documentation, external resources

Auto-Run Behavior

Some tools run automatically without user confirmation:

navigate tools auto-run by default (just takes user to a page)
external_link tools auto-run (opens a new tab)
trigger_tool requires user confirmation (executes custom logic)

You can override this with the autoRun property on any tool.

Data Extraction

Tools can define an inputSchema that tells the co-pilot what data to extract from the conversation:

examples/features/tools/invite-member.tsx

import { usePillarTool } from '@pillar-ai/react';

usePillarTool({
  name: 'invite_member',
  type: 'trigger_tool',
  description: 'Invite a team member',
  inputSchema: {
    type: 'object',
    properties: {
      email: { type: 'string', description: 'Email address to invite' },
      role: { type: 'string', description: 'Role: admin, member, or viewer' },
    },
    required: ['email', 'role'],
  },
  execute: ({ email, role }) => {
    // email and role are populated from the conversation
    inviteUser(email, role);
  },
});

When the tool runs, your execute handler receives the extracted data as its input.

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 execute.

Next Steps

Setting Up Tools — Step-by-step implementation guide
Syncing Tools — How to sync tools to Pillar's backend

Search documentation