AI Tool System

Tools are functions that the AI can invoke to perform actions in your application.

Tool Categories

Navigation Tools

Tools for navigating the application:

Tool	Description
navigateTo	Navigate to a specific page
scrollToComponent	Scroll to a component by ID
goBack	Navigate to previous page

// Example: navigateTo tool
{
  name: 'navigateTo',
  description: 'Navigate to a specific page in the application',
  parameters: z.object({
    path: z.string().describe('The path to navigate to'),
    params: z.record(z.string()).optional(),
  }),
  execute: async ({ path, params }) => {
    // Navigation logic
    return { previousPath, currentPath: path };
  },
}

Component Tools

Tools for interacting with UI components:

Tool	Description
highlightComponent	Highlight a component with color
getComponentInfo	Get information about a component
clickComponent	Simulate a click on a component

Filter Tools

Tools for filtering and searching data:

Tool	Description
setFilter	Apply a filter to data
setDateRange	Set date range filter
clearFilters	Clear all active filters
getActiveFilters	Get currently active filters

Data Tools

Tools for querying and analyzing data:

Tool	Description
fetchData	Fetch data from a source
aggregateData	Aggregate data with grouping
analyzeData	Analyze patterns in data

Visualization Tools

Tools for creating visual outputs:

Tool	Description
createChart	Create a chart widget
createDataGrid	Create a data table widget
createMetric	Create a metric display

Memory Tools

Tools for remembering user preferences:

Tool	Description
rememberPattern	Save a usage pattern
recallPattern	Recall a saved pattern
listPatterns	List all saved patterns
forgetPattern	Remove a saved pattern

Creating Custom Tools

Tool Structure

import { z } from 'zod';
import type { SimpleTool } from '@/lib/ai';

const myTool: SimpleTool = {
  name: 'myTool',
  description: 'Description for AI to understand when to use this',
  parameters: z.object({
    input: z.string().describe('The input value'),
    option: z.boolean().optional().describe('Optional flag'),
  }),
  execute: async (input) => {
    // Tool logic here
    const result = await doSomething(input);
    return { success: true, result };
  },
};

Best Practices

1. Clear descriptions - AI uses descriptions to decide when to use tools
2. Typed parameters - Use Zod for type-safe parameters
3. Descriptive parameter names - Use .describe() for each parameter
4. Return structured data - Return objects that can be displayed as widgets

Tool Approval

Some tools require user approval before execution:

const dangerousTool: SimpleTool = {
  name: 'deleteData',
  description: 'Delete data from the system',
  parameters: z.object({
    id: z.string(),
  }),
  requiresApproval: true, // Requires user approval
  execute: async ({ id }) => {
    await deleteData(id);
    return { deleted: true };
  },
};

Using Tools in Chat

When AI invokes a tool, the message includes tool call parts:

// Tool call in message parts
{
  type: 'tool-call',
  toolCallId: 'tc-123',
  toolName: 'createChart',
  args: { type: 'bar', data: [...] },
  state: 'pending' | 'complete' | 'approval-requested'
}

// Tool result in message parts
{
  type: 'tool-result',
  toolCallId: 'tc-123',
  toolName: 'createChart',
  result: { chartId: 'chart-1', config: {...} }
}

Tool Configuration

Configure available tools in src/lib/ai/tools.ts:

export const allTools: SimpleTool[] = [
  ...navigationTools,
  ...componentTools,
  ...filterTools,
  ...dataTools,
  ...visualizationTools,
  ...memoryTools,
];

// Filter tools by category
export function getToolsByCategory(category: ToolCategory): SimpleTool[] {
  return allTools.filter((tool) =>
    TOOL_CATEGORIES[category].includes(tool.name)
  );
}