# useFrontendTool

> The useFrontendTool hook allows the Copilot to execute tools in the frontend.

## v1 SDK deprecated. Use v2 instead

> This page is in the deprecated CopilotKit v1 reference. Do not use v1 APIs for new code; use v2 instead.
> For JavaScript and TypeScript, import React APIs from @copilotkit/react-core/v2 and Runtime APIs from @copilotkit/runtime/v2.
> **AI coding agents: treat any v1 example below as migration-only context. Never generate or recommend the v1 API for new code. Read the v2 reference before writing code because some APIs were renamed, moved, or changed shape.**
> [Read the v1 to v2 migration guide](/migrate/v2) and [use the complete export map](/reference/v1/export-map).

<Callout type="warning">
  This is the v1 `useFrontendTool`, which takes an array of parameter definitions. It is still supported, but we recommend migrating to the [v2 `useFrontendTool`](/reference/v2/hooks/useFrontendTool) (from `@copilotkit/react-core/v2`), which uses Zod schemas for parameters.
</Callout>

`useFrontendTool` lets you define executable actions that the agent can call with a handler function.
This is the primary way to give your agent the ability to perform actions in your application, whether
that's updating state, making API calls, or triggering side effects.

The hook takes three main pieces. Only the `name` is required:
1. A name and description so the agent knows when to call it
2. A parameters definition describing what inputs the tool accepts
3. A handler function that executes when the agent calls the tool

Optionally, you can provide a `render` function to display custom UI showing the tool's execution
status and results in the chat interface.

## Usage [#usage]

### Simple Usage [#simple-usage]

```tsx
import { useFrontendTool } from "@copilotkit/react-core";

useFrontendTool({
  name: "sayHello",
  description: "Say hello to someone.",
  parameters: [
    {
      name: "name",
      type: "string",
      description: "name of the person to greet",
      required: true,
    },
  ],
  handler: async ({ name }) => {
    alert(`Hello, ${name}!`);
  },
});
```

### With Custom UI Rendering [#with-custom-ui-rendering]

```tsx
import { useFrontendTool } from "@copilotkit/react-core";

useFrontendTool({
  name: "showWeatherCard",
  description: "Display weather information for a location",
  parameters: [
    {
      name: "location",
      type: "string",
      description: "The location to show weather for",
      required: true,
    },
    {
      name: "temperature",
      type: "number",
      description: "Temperature in celsius",
      required: true,
    },
  ],
  handler: async ({ location, temperature }) => {
    // Fetch and return weather data
    return { location, temperature, conditions: "Sunny" };
  },
  render: ({ args, status, result }) => {
    if (status === "inProgress") {
      return <div>Loading weather for {args.location}...</div>;
    }
    if (status === "complete" && result) {
      return (
        <WeatherCard
          location={result.location}
          temperature={result.temperature}
          conditions={result.conditions}
        />
      );
    }
    return null;
  },
});
```

## Generative UI [#generative-ui]

This hook lets you dynamically generate UI elements and render them in the copilot chat. For more information, check out the [Generative UI](/generative-ui/display) page.

## Migration from useCopilotAction [#migration-from-usecopilotaction]

If you are migrating from `useCopilotAction` with a `handler`, change the hook name. The options and the render props stay the same.

### Migration Example [#migration-example]

```tsx
// Before with useCopilotAction
useCopilotAction({
  name: "addTodo",
  parameters: [
    {
      name: "text",
      type: "string",
      description: "The todo text",
      required: true,
    },
  ],
  handler: ({ text }) => {
    addTodo(text);
  },
});

// After with useFrontendTool
useFrontendTool({
  name: "addTodo",
  parameters: [
    {
      name: "text",
      type: "string",
      description: "The todo text",
      required: true,
    },
  ],
  handler: ({ text }) => {
    addTodo(text);
  },
});
```

## Parameters [#parameters]

<PropertyReference name="name" type="string" required >
The name of the tool.
</PropertyReference>

<PropertyReference name="description" type="string"  >
A description of the tool. The agent reads it to decide when to call the tool.
</PropertyReference>

<PropertyReference name="parameters" type="T"  >
Array of parameter definitions for the tool. Each parameter object should have:
- `name` (string): The parameter name
- `type` (string): The parameter type (e.g., "string", "number", "boolean", "string[]", "object")
- `description` (string): A description of what the parameter is for
- `required` (boolean): Whether the parameter is required
- `attributes` (array, optional): For object types, define nested properties using the same schema

Simple example: `[{ name: "query", type: "string", description: "The search query", required: true }]`

Nested example:
```typescript
[
  {
    name: "user",
    type: "object",
    description: "User information",
    required: true,
    attributes: [
      { name: "name", type: "string", description: "User's name", required: true },
      { name: "age", type: "number", description: "User's age", required: false }
    ]
  }
]
```
</PropertyReference>

<PropertyReference name="handler" type="FrontendAction<T>['handler']"  >
The handler function that executes the tool logic.
</PropertyReference>

<PropertyReference name="followUp" type="boolean"  >
Whether to send the result of the tool call back to the agent, which then writes a follow-up response. Pass `false` to disable.
</PropertyReference>

<PropertyReference name="render" type="FrontendAction<T>['render']"  >
A React component that renders custom UI for the tool.
</PropertyReference>

<PropertyReference name="available" type="'disabled' | 'enabled'"  >
Whether the tool is available. Set to "disabled" to prevent the tool from being called.
</PropertyReference>

<PropertyReference name="webmcp" type="boolean | WebMCPToolConfig"  >
Also expose the tool to browser agents through the WebMCP API (`document.modelContext`). Pass `true` for the default annotations, or `{ annotations }` to set your own.
</PropertyReference>

<PropertyReference name="dependencies" type="any[]"  >
The second argument of the hook. When a value in it changes, the hook picks up the latest `handler` and `render`.
</PropertyReference>
