# FrontendTool

> Definition of a frontend tool the agent can call in the browser.

## Overview [#overview]

`FrontendTool` describes a tool that runs in the browser. An agent can call it. You register frontend tools via [`CopilotKitCoreConfig.tools`](/reference/core/types/CopilotKitCoreConfig) (or at runtime on [`CopilotKitCore`](/reference/core/classes/CopilotKitCore)). A tool has a name, an optional parameter schema, and a handler that receives the parsed arguments and an execution context.

## Import [#import]

```ts
import type { FrontendTool } from "@copilotkit/core";
```

## Definition [#definition]

```ts
type FrontendTool<T extends Record<string, unknown> = Record<string, unknown>> = {
  name: string;
  description?: string;
  parameters?: StandardSchemaV1<any, T>;
  handler?: (args: T, context: FrontendToolHandlerContext) => Promise<unknown>;
  followUp?: boolean;
  reconnectBehavior?: "passive" | "resume-pending";
  agentId?: string;
  available?: boolean;
  webmcp?: boolean | WebMCPToolConfig;
};

type FrontendToolHandlerContext = {
  toolCall: ToolCall;
  agent?: AbstractAgent;
  signal?: AbortSignal;
  isReplay?: boolean;
};
```

## Properties [#properties]

<PropertyReference name="name" type="string" required>
  Unique name of the tool. This is the name the agent uses to call it.
</PropertyReference>

<PropertyReference name="description" type="string">
  Human-readable description of what the tool does. Helps the model decide when to call it.
</PropertyReference>

<PropertyReference name="parameters" type="StandardSchemaV1<any, T>">
  Standard Schema describing the tool's arguments. It defines the advertised
  tool schema and types the `args` passed to `handler`. Runtime arguments are
  JSON-parsed but are not validated against that schema.
</PropertyReference>

<PropertyReference name="handler" type="(args: T, context: FrontendToolHandlerContext) => Promise<unknown>">
  Function that runs when the agent calls the tool. Receives the parsed `args` and an execution context.

  <PropertyReference name="context.toolCall" type="ToolCall">
    The AG-UI tool call that triggered this handler.
  </PropertyReference>

  <PropertyReference name="context.agent" type="AbstractAgent">
    The agent that called the tool. Absent when the tool is called through WebMCP.
  </PropertyReference>

  <PropertyReference name="context.signal" type="AbortSignal">
    Aborted when `stopAgent()` is called. Handlers can check `signal.aborted` or pass the signal to `fetch`/`setTimeout` to cooperatively cancel.
  </PropertyReference>

  <PropertyReference name="context.isReplay" type="boolean">
    `true` when the call is run while the thread's history is restored (see `reconnectBehavior`). Absent for a call from a live run.
  </PropertyReference>
</PropertyReference>

<PropertyReference name="followUp" type="boolean">
  Whether the agent should run again after the tool result is returned.
</PropertyReference>

<PropertyReference name="reconnectBehavior" type='"passive" | "resume-pending"' default='"passive"'>
  What happens to a call of this tool that is still unanswered when the thread's history is restored, for example after a page reload. With `"passive"`, the call is shown but the handler does not run. With `"resume-pending"`, the handler runs for that call with `isReplay: true` in its context, and the run then continues as usual. Opt in only for a handler that is safe to run more than once. A call does not start twice at the same time on one page. A call can run again after a stop or a thread switch, if its result never reached the agent. Two tabs that restore the same thread can each run the call. If the agent calls this tool together with a tool that stays passive, the follow-up run sends the passive call without a result, which some model providers reject. Opt in every tool that the agent calls together, or set `followUp: false`.
</PropertyReference>

<PropertyReference name="agentId" type="string">
  Optional agent ID to constrain this tool to a specific agent. If specified, the tool is only available to that agent.
</PropertyReference>

<PropertyReference name="available" type="boolean" default="true">
  Whether this tool is available to the agent. Set to `false` to hide the tool without unregistering it.
</PropertyReference>

<PropertyReference name="webmcp" type="boolean | WebMCPToolConfig">
  Also exposes the tool to browser agents through WebMCP (`document.modelContext`). `true` registers it with default annotations. `{ annotations }` sets the annotations, for example `readOnlyHint`. When a browser agent calls the tool, the handler context has no `agent`.
</PropertyReference>

## Usage [#usage]

```ts
import type { FrontendTool } from "@copilotkit/core";
import { z } from "zod";

const setThemeTool: FrontendTool<{ theme: "light" | "dark" }> = {
  name: "setTheme",
  description: "Switch the app between light and dark mode",
  parameters: z.object({ theme: z.enum(["light", "dark"]) }),
  handler: async ({ theme }, { signal }) => {
    if (signal?.aborted) return;
    document.documentElement.dataset.theme = theme;
    return `Theme set to ${theme}`;
  },
};
```
