Search documentation

Search documentation

Customize your docs experience — choose your preferred framework for code examples:

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.

Without toolsWith tools
"Here's how to invite a team member...""I can invite them for you. [Invite Team Member]"
User reads instructions, navigates manuallyUser clicks the tool, modal opens pre-filled

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

Tool types

TypeWhat it doesExample
navigateGo to a page in your appSettings, dashboard, detail pages
trigger_toolRun your custom logicOpen modals, start wizards, toggle features
queryFetch data from the client and return it to the agentSearch products, look up records
open_modalOpen a modal or dialogConfirmation forms, settings dialogs
fill_formPre-fill form fieldsInvite forms, transfer forms
external_linkOpen a URL in a new tabDocumentation, external resources
copy_textCopy text to clipboardAPI keys, code snippets
start_tutorialStart a walkthroughOnboarding tours
inline_uiShow interactive UI in chatConfirmation cards, data previews

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.

Next steps