Tool Calling

Let agents invoke real functions in your environment—write files, call APIs, or modify state instead of just generating text.

Overview

Tool calling transforms your AI agents from text generators into capable assistants that can interact with the real world. Define tools with schemas, and the AI will decide when and how to use them.

Defining Tools

A tool consists of a name, description, JSON schema for parameters, and an invoke function:

tool-definition.ts

1import { promises as fs } from 'fs'
2import { MozaikAgent, MozaikRequest, Tool } from '@mozaik-ai/core'
3
4const tools: Tool[] = [
5  {
6    name: 'write_file',
7    description: 'Write text content to a file on disk.',
8    schema: {
9      type: 'object',
10      properties: {
11        filename: { 
12          type: 'string',
13          description: 'The name of the file to write'
14        },
15        content: { 
16          type: 'string',
17          description: 'The content to write to the file'
18        }
19      },
20      required: ['filename', 'content']
21    },
22    async invoke({ filename, content }) {
23      await fs.writeFile(filename, content, 'utf8')
24      return { success: true, path: filename }
25    }
26  }
27]

Using Tools with Agents

Pass your tools to the agent via the command:

tool-usage.ts

1import { MozaikAgent, MozaikRequest, Tool } from '@mozaik-ai/core'
2
3const tools: Tool[] = [
4  // ... your tool definitions
5]
6
7const request: MozaikRequest = {
8  model: 'gpt-5.1',
9  tools,
10  messages: [
11    {
12      role: 'system',
13      content: 'You are a helpful assistant. Use the tools available to complete tasks.'
14    }
15  ]
16}
17
18const agent = new MozaikAgent(request)
19
20// The agent will automatically use tools when appropriate
21await agent.act('Create a trip checklist and save it as trip-checklist.txt')

Multiple Tools

Provide multiple tools and the AI will choose which ones to use:

multiple-tools.ts

1const tools: Tool[] = [
2  {
3    name: 'read_file',
4    description: 'Read the contents of a file',
5    schema: {
6      type: 'object',
7      properties: {
8        path: { type: 'string' }
9      },
10      required: ['path']
11    },
12    async invoke({ path }) {
13      const content = await fs.readFile(path, 'utf8')
14      return { content }
15    }
16  },
17  {
18    name: 'write_file',
19    description: 'Write content to a file',
20    schema: {
21      type: 'object',
22      properties: {
23        path: { type: 'string' },
24        content: { type: 'string' }
25      },
26      required: ['path', 'content']
27    },
28    async invoke({ path, content }) {
29      await fs.writeFile(path, content, 'utf8')
30      return { success: true }
31    }
32  },
33  {
34    name: 'list_files',
35    description: 'List files in a directory',
36    schema: {
37      type: 'object',
38      properties: {
39        directory: { type: 'string' }
40      },
41      required: ['directory']
42    },
43    async invoke({ directory }) {
44      const files = await fs.readdir(directory)
45      return { files }
46    }
47  }
48]

Best Practices

Tip

Write clear, descriptive tool descriptions. The AI uses these to decide which tool to use.

•Validate inputs: Always validate tool inputs before executing operations.
•Return useful data: Include relevant information in return values for the AI to use.
•Handle errors gracefully: Return error information instead of throwing to let the AI recover.
•Keep tools focused: Each tool should do one thing well.

Next Steps

Vision

Enable multimodal image+text interactions

Workflows

Compose sequential and parallel task execution