Tools

Tools (also called function calling) enable AI agents to execute actions in your application, transforming them from passive chatbots into active assistants.

What Are Tools?

Tools are executable functions you define that the AI agent can call to take actions in your application. They are passed via the tools prop and include:

• A name and description that tells the AI when to use the tool
• A parameters schema that defines required inputs
• A handler function that executes the action

Tools allow the agent to:

• Retrieve data - Fetch cart contents, search products, query databases
• Modify state - Add todos, update records, delete items
• Trigger actions - Send emails, create reports, export data
• Control UI - Filter lists, sort data, navigate pages

Example: Simple vs Advanced

Simple Chatbot (No Tools)

User: "Add milk to my shopping list"
Bot: "I've noted that you want to add milk to your shopping list.
      You can do that in the Shopping section."

The user still has to manually add the item.

Agent with Tools

User: "Add milk to my shopping list"
Agent: *calls addToShoppingList({ item: 'milk' })*
Agent: "I've added milk to your shopping list. You now have 5 items."

The agent actually performed the action.

How Tools Work

1. You define tools - Specify available functions and parameters via the tools prop
2. Agent decides when to call - AI chooses appropriate tool based on user intent
3. Handler executes - Your JavaScript function runs with the provided parameters
4. Agent uses result - AI incorporates result into response

Basic Example

import { InAppAI } from '@inappai/react';
import { useState } from 'react';

function App() {
  const [count, setCount] = useState(0);

  const tools = [
    {
      name: 'incrementCounter',
      description: 'Increment the counter when user asks to increase it',
      parameters: {
        type: 'object',
        properties: {
          amount: {
            type: 'number',
            description: 'Amount to increment by (default: 1)',
          },
        },
        required: [],
      },
      handler: async (params) => {
        const amount = params.amount || 1;
        setCount(prev => prev + amount);
        return { success: true, newCount: count + amount };
      },
    },
  ];

  return (
    <InAppAI
      agentId="your-agent-id"
      tools={tools}
      context={{ currentCount: count }}
    />
  );
}

When the user says “Increase the counter by 5”, the AI calls incrementCounter({ amount: 5 }) and the handler updates the state.

Tools vs Context

Understanding the distinction is important:

Use tools when: You want the AI to take actions (create, update, delete, trigger workflows)

Use context when: You want the AI to know about current application state (user info, page data, settings)

Combining Tools with Context

Tools work best when combined with context. Context provides read-only state so the AI understands the current situation, while tools allow the AI to take actions:

<InAppAI
  agentId="your-agent-id"
  // Context: Read-only state snapshot
  context={{
    todos: todos.map(t => ({ id: t.id, text: t.text, completed: t.completed })),
    totalTodos: todos.length,
    completedTodos: todos.filter(t => t.completed).length,
  }}
  // Tools: Executable actions
  tools={[
    {
      name: 'addTodo',
      description: 'Add a new todo item',
      handler: async ({ text }) => {
        const newTodo = { id: Date.now(), text, completed: false };
        setTodos([...todos, newTodo]);
        return { success: true, todo: newTodo };
      },
    },
  ]}
/>

The AI can see the current todos (via context) and add new ones (via tools).

Next Steps

• Function Calling Guide - Detailed implementation examples with complete code
• Context - Learn how to provide application state to the AI
• Getting Started - Build your first agent with tools