# useFrontendTools

> React hook for registering a list of client-side tools whose length can change between renders

## Overview [#overview]

`useFrontendTools` registers many client-side tools in one call. Use it when the set of tools is not known when you write the component: tools built from state, from props, or from a list the backend returned.

[`useFrontendTool`](/reference/hooks/useFrontendTool) registers exactly one tool per call, so it cannot be called in a loop over a list whose length changes. That breaks the rules of hooks. `useFrontendTools` runs a single effect over the whole array instead, so the array may be empty on one render and hold twenty entries on the next.

Each entry is the same `ReactFrontendTool` object that `useFrontendTool` takes. See that page for the full tool shape, including `parameters`, `handler`, `render`, and `webmcp`.

## Signature [#signature]

```tsx
import { useFrontendTools, ToolCallStatus } from "@copilotkit/react-core/v2";

function useFrontendTools(
  tools: ReadonlyArray<ReactFrontendTool<any>> | undefined,
  deps?: ReadonlyArray<unknown>,
): void;
```

## Parameters [#parameters]

<PropertyReference name="tools" type="ReadonlyArray<ReactFrontendTool<any>> | undefined" required>
  The tools to register. The array may be empty, may change length between
  renders, and may be `undefined` while data is still loading. Each entry takes
  the same fields as the `tool` argument of
  [`useFrontendTool`](/reference/hooks/useFrontendTool).

  Tools are identified by `name` plus `agentId`, so the same `name` can serve
  two different agents. If one array lists the same `name` and `agentId` twice,
  the last entry wins and a warning is logged.
</PropertyReference>

<PropertyReference name="deps" type="ReadonlyArray<unknown>">
  An optional dependency array. It has the same contract as the second argument
  of `useEffect`. Entries are compared by identity, and the array must keep a
  constant length across renders. Registration is refreshed whenever any entry
  changes. Use this when a handler captures external state that is not part of
  the tool definition, such as a router or a mutation function.

  Do not put the source collection here. The hook already keys on the contents
  of `tools`. Adding `reports` or `data` to `deps` would re-register every tool
  on every render, because that array is rebuilt each time.
</PropertyReference>

## Usage [#usage]

### Tools built from application state [#tools-built-from-application-state]

```tsx
function ReportTools({ reports }: { reports: Report[] }) {
  const navigate = useNavigate();

  useFrontendTools(
    reports.map((report) => ({
      name: `open_${report.id}`,
      description: `Open the ${report.title} report`,
      handler: async () => {
        navigate(`/reports/${report.id}`);
        return `Opened ${report.title}`;
      },
    })),
    [navigate],
  );

  return null;
}
```

When `reports` grows, the new tools are registered. When a report disappears from the list, its tool is unregistered and the rest stay registered.

### Tools described by the backend [#tools-described-by-the-backend]

```tsx
import { z } from "zod";

function BackendTools() {
  const { data, isLoading } = useQuery({
    queryKey: ["tool-descriptors"],
    queryFn: fetchToolDescriptors,
  });

  useFrontendTools(
    data?.map((descriptor) => ({
      name: descriptor.name,
      description: descriptor.description,
      parameters: z.object({
        query: z.string().describe("What to look up"),
      }),
      handler: async ({ query }) => {
        const result = await runDescriptor(descriptor.id, query);
        return JSON.stringify(result);
      },
    })),
    [],
  );

  return isLoading ? <Spinner /> : null;
}
```

Passing `undefined` while the query is in flight registers nothing. The tools appear once the data arrives, without a second code path for the loading state.

### Turning a subset of tools off [#turning-a-subset-of-tools-off]

```tsx
function PermissionedTools({ isAdmin }: { isAdmin: boolean }) {
  useFrontendTools([
    {
      name: "searchOrders",
      description: "Search orders by status",
      parameters: z.object({ status: z.string() }),
      handler: async ({ status }) => JSON.stringify(await search(status)),
    },
    {
      name: "refundOrder",
      description: "Refund an order by ID (admin only)",
      parameters: z.object({ orderId: z.string() }),
      handler: async ({ orderId }) => refund(orderId),
      available: isAdmin,
    },
  ]);

  return null;
}
```

`available: false` keeps the tool registered but hides it from the agent. Toggling it re-registers that tool, the same as with `useFrontendTool`.

### Tools with render components [#tools-with-render-components]

```tsx
function ChartTools({ metrics }: { metrics: Metric[] }) {
  useFrontendTools(
    metrics.map((metric) => ({
      name: `chart_${metric.key}`,
      description: `Chart the ${metric.label} metric`,
      parameters: z.object({ days: z.number() }),
      handler: async ({ days }) => JSON.stringify(await load(metric, days)),
      render: ({ status, result }) => {
        if (status !== ToolCallStatus.Complete || !result) {
          return <div className="animate-pulse">Loading {metric.label}…</div>;
        }
        return <Chart data={JSON.parse(result)} />;
      },
    })),
    [],
  );

  return null;
}
```

To render a tool call without a handler, use [`useRenderTool`](/reference/hooks/useRenderTool). To wait for the user before the tool returns, use [`useHumanInTheLoop`](/reference/hooks/useHumanInTheLoop).

## Behavior [#behavior]

- **Value-based re-registration**: The array is normally built inline, so its identity changes on every render. The hook keys on the `name`, `description`, `agentId`, `available`, and `webmcp` of every entry instead. A re-render that produces an equal list does not re-register anything.
- **Descriptions stay current**: `description` is part of the key. A description derived from your data, such as `` `Open the ${report.title} report` ``, reaches the agent as soon as the data changes, with no `deps` entry. This is the one place the key differs from [`useFrontendTool`](/reference/hooks/useFrontendTool), which keys only on `name`, `available`, and `webmcp`.
- **Adding and removing**: When the list changes, tools that are new get registered and tools that left get unregistered. Tools present in both the old and new list are re-registered with their latest definition.
- **Unmount**: Every tool the hook registered is unregistered on unmount.
- **Duplicate names**: A `name` and `agentId` pair listed twice in one array is a mistake in the calling code. The last entry wins and the hook logs a warning naming the tool.
- **Overriding another registration**: If a tool with the same `name` and `agentId` was already registered elsewhere, the hook overrides it and logs a warning, matching `useFrontendTool`.
- **Render component lifecycle**: Entries with a `render` function register a renderer. Renderers are deliberately left in place after unmount so that past tool calls still render in the chat history.
- **Handlers and parameters are not part of the key**: A `handler` is a function and a `parameters` schema is an object, so neither can be compared by value. Changing only one of them does not re-register on its own. Pass `deps` when a handler closes over a value that must stay current, as the examples above do with `navigate`.
- **No return value**: The hook returns `void`.
