# Server Tools

> Define backend tools for your Built-in Agent.

## What are Server Tools? [#what-are-server-tools]

Server tools are functions that run on your backend that the Built-in Agent can invoke. They're defined using `defineTool()` with Zod schemas for type-safe parameters.

## When should I use this? [#when-should-i-use-this]

- Your agent needs to access databases, APIs, or other backend services
- You want type-safe tool parameters with validation
- The tool logic requires server-side secrets or resources

<Callout type="warn" title="The tool runs on the server; the UI still runs in the browser">
`execute` runs on your server, so it can reach secrets, a database, or an internal service.
It cannot touch the DOM, component state, or anything else in the page. When the *action*
itself belongs in the browser, register it as a [frontend tool](/react-native/frontend-tools) instead.

Rendering is separate from executing. A server tool's call still streams to the browser, so
you can give it UI with a render-only registration under the same tool name while `execute`
keeps running on the server.

</Callout>

## Defining a tool [#defining-a-tool]

```typescript title="src/copilotkit.ts"
import { BuiltInAgent, defineTool } from "@copilotkit/runtime/v2";
import { z } from "zod";

const getWeather = defineTool({
  name: "getWeather",
  description: "Get the current weather for a location",
  parameters: z.object({
    location: z.string().describe("The location's name"),
  }),
  execute: async ({ location }) => {
    // Your implementation here
    return { temperature: 72, condition: "sunny", location };
  },
});

const builtInAgent = new BuiltInAgent({
  model: "openai:gpt-6-luna",
  tools: [getWeather],
  maxSteps: 2                   //Important for tool calls
});
```

Ask the agent: "What is the weather in Paris?" The agent calls `getWeather` and replies that it is 72 degrees and sunny.

<Callout type="warn" title="`parameters` takes a schema validator, not JSON Schema">
`parameters` must be a Standard Schema v1 validator. Zod, Valibot, ArkType and others
qualify. Handing it a plain JSON Schema object throws while the tool's schema is being
converted. The validator is also what gives `execute` its inferred argument type, so a
hand-written JSON Schema loses that too.
</Callout>

## Tool response [#tool-response]

Tools can return any JSON-serializable value. The agent uses the response to continue the conversation.

## Multiple tools [#multiple-tools]

Pass an array of tools. The agent chooses which to call based on the user's request:

```typescript title="src/copilotkit.ts"
const searchDocs = defineTool({
  name: "searchDocs",
  description: "Search the documentation for relevant articles",
  parameters: z.object({
    query: z.string().describe("The search query"),
  }),
  execute: async ({ query }) => {
    const results = await search(query);
    return { results, count: results.length };
  },
});

const createTicket = defineTool({
  name: "createTicket",
  description: "Create a support ticket",
  parameters: z.object({
    title: z.string().describe("Ticket title"),
    priority: z.enum(["low", "medium", "high"]).describe("Ticket priority"),
    description: z.string().describe("Detailed description of the issue"),
  }),
  execute: async ({ title, priority, description }) => {
    const ticket = await db.tickets.create({ title, priority, description });
    return { ticketId: ticket.id, status: "created" };
  },
});

const builtInAgent = new BuiltInAgent({
  model: "openai:gpt-6-luna",
  tools: [searchDocs, createTicket], // [!code highlight]
  maxSteps: 2                        
});
```

<Callout type="warn" title="Two names to avoid">
`AGUISendStateSnapshot` and `AGUISendStateDelta` are injected for you whenever the Built-in
Agent makes the model call itself. If you define a tool with either name, the built-in tool
replaces it, and your `execute` never runs.

A server tool also wins any name collision with a frontend tool: define `getWeather` on both
sides and the model only ever sees the server one, so the frontend handler never fires. Give
each side a distinct name when both need their own.
</Callout>

## Complex Zod schemas [#complex-zod-schemas]

Use nested objects, arrays, enums, and optional fields for sophisticated tool parameters:

```typescript
const bookFlight = defineTool({
  name: "bookFlight",
  description: "Search for and book flights",
  parameters: z.object({
    trip: z.object({
      origin: z.string().describe("Origin airport code (e.g., SFO)"),
      destination: z.string().describe("Destination airport code (e.g., JFK)"),
      date: z.string().describe("Departure date in YYYY-MM-DD format"),
    }),
    passengers: z.array(
      z.object({
        name: z.string(),
        seatPreference: z.enum(["window", "middle", "aisle"]).optional(),
      })
    ).describe("List of passengers"),
    class: z.enum(["economy", "business", "first"]).default("economy"),
  }),
  execute: async ({ trip, passengers, class: seatClass }) => {
    const flights = await searchFlights(trip, seatClass);
    return { flights, passengerCount: passengers.length };
  },
});
```

## Error handling [#error-handling]

Throw errors or return error objects from your tool. The agent will see the error and can inform the user or try a different approach:

```typescript
const getUser = defineTool({
  name: "getUser",
  description: "Look up a user by email",
  parameters: z.object({
    email: z.string().email().describe("The user's email address"),
  }),
  execute: async ({ email }) => {
    const user = await db.users.findByEmail(email);
    if (!user) {
      throw new Error(`No user found with email: ${email}`); // [!code highlight]
    }
    return { id: user.id, name: user.name, role: user.role };
  },
});
```

<Callout type="warn" title="Return plain data">
Whatever a tool returns is serialized before the model sees it. A class instance, a circular
reference, or anything else `JSON.stringify` refuses is replaced by a placeholder string
naming the tool, and the model reasons over that instead of your data. Return plain objects, arrays and primitives, including for error shapes.
</Callout>

## Multi-step tool calling [#multi-step-tool-calling]

By default, the agent performs a single step. If your agent needs to chain tool calls (e.g., search first, then create a ticket), set `maxSteps`:

```typescript
const builtInAgent = new BuiltInAgent({
  model: "openai:gpt-6-luna",
  maxSteps: 5, // [!code highlight]
  tools: [searchDocs, createTicket, getUser],
});
```

With `maxSteps: 5`, the agent can:
1. Call `searchDocs` to find relevant info
2. Process the result
3. Call `createTicket` with details from the search
4. Continue until done (up to 5 iterations)

<Callout type="info">
See [Advanced Configuration](/react-native/advanced-configuration) for more options like `toolChoice`, `temperature`, and `providerOptions`.
</Callout>

<Callout type="warn" title="A factory ignores the `tools` array">
Everything on this page describes a Built-in Agent constructed with `model` and `tools`. If
you build one from a `factory` instead, the `tools` array is not read. The factory owns the
model call, so it has to pass the tools itself. Convert them with
`convertToolDefinitionsToVercelAITools` for an AI SDK factory, or the equivalent converter for
your runner, and pass the result into the call the factory makes. For factory samples with tools,
see [Custom Agent](/react-native/backend/custom-agent#with-tools).
</Callout>
