> ## Documentation Index
> Fetch the complete documentation index at: https://docs.skybridge.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# useCallTool

> Call a tool from a view

`useCallTool` lets a [view](https://docs.skybridge.tech/build/view.md) call one of your server's [tools](https://docs.skybridge.tech/build/tools.md) and tracks the call's state, so an interaction in the view can run server logic and render the result. The model does not see a view-initiated call.

Import it from your [`generated helpers.ts`](https://docs.skybridge.tech/api-reference/generate-helpers): the typed hook infers the tool's argument and response types from your server, so you pass only the name.

## Examples

### Trigger a call and read the result

A shopper checks out their cart without leaving the view. The button shows progress while the server creates the checkout, then turns into a Pay now link, or explains why checkout could not start.

```tsx highlight={5-6,14-17,23,27} theme={null}
import { useCallTool } from "../helpers.js"; // generated, type-safe from server schema
import { useOpenExternal } from "skybridge/web";

function Cart({ items }: { items: string[] }) {
  const { callTool, isPending, isSuccess, isError, data, error } =
    useCallTool("create-checkout");
  const openExternal = useOpenExternal();

  return (
    <div>
      <button
        disabled={isPending}
        onClick={() =>
          callTool(
            { items },
            { onError: (e) => console.error("Checkout failed", e) },
          )
        }
      >
        {isPending ? "Checking out..." : "Check out"}
      </button>
      {isSuccess && (
        <button onClick={() => openExternal(data.structuredContent.checkoutUrl)}>
          Pay now
        </button>
      )}
      {isError && <p>Could not start checkout: {String(error)}</p>}
    </div>
  );
}
```

### Await the call

A shopper checks out and goes straight to payment. The view waits for the checkout, opens the payment page, and recovers if the request never completes.

```tsx highlight={5,10,12-13} theme={null}
import { useCallTool } from "../helpers.js"; // generated, type-safe from server schema
import { useOpenExternal } from "skybridge/web";

function Cart() {
  const { callToolAsync, isPending } = useCallTool("create-checkout");
  const openExternal = useOpenExternal();

  const checkout = async () => {
    try {
      const { structuredContent } = await callToolAsync({ items: ["jacket"] });
      openExternal(structuredContent.checkoutUrl);
    } catch (error) {
      console.error("Checkout failed", error);
    }
  };

  return (
    <button disabled={isPending} onClick={checkout}>
      Check out
    </button>
  );
}
```

## Type Parameters

The [generated helper](https://docs.skybridge.tech/api-reference/generate-helpers.md) infers both from your server. You set them by hand only when importing `useCallTool` from `skybridge/web` directly, which is not recommended.

### `ToolArgs`

```tsx theme={null}
ToolArgs extends Record<string, unknown> | null = null;
```

The arguments the tool accepts. Defaults to `null`, for a tool that takes no arguments.

### `ToolResponse`

```tsx theme={null}
ToolResponse extends Partial<{
  structuredContent: Record<string, unknown>;
  meta: Record<string, unknown>;
}> = Record<string, never>;
```

The shape of the tool's `structuredContent` and `meta`. Defaults to an empty object. Whatever you set here types those two fields on `data`.

## Parameters

### `name`

```tsx theme={null}
name: string;
```

**Required.** The name of the tool to call. It must match a tool registered on your [MCP server](https://docs.skybridge.tech/api-reference/mcp-server.md).

> [!NOTE]
>
> A view can call a tool only when the tool's `_meta.ui.visibility` includes `"app"`, which is the default behavior. See [Register Tools](https://docs.skybridge.tech/build/tools.md).

### `options`

```tsx theme={null}
options?: { timeout?: number };
```

`timeout` is the call's timeout in milliseconds, 60 seconds by default. Raise it for tools that wait on the user, such as a ChatGPT form. It must be a positive, finite number.

## Returns

`useCallTool` returns two call functions plus the live [state](https://docs.skybridge.tech/build/state.md) of the most recent call. Both functions keep the same identity across renders, so they are safe to list in effect dependencies.

### `callTool`

```tsx theme={null}
callTool(toolArgs: ToolArgs, sideEffects?: SideEffects): void;
callTool(sideEffects?: SideEffects): void; // overload available when the tool has no required arguments
```

Starts the call and tracks its state on the hook. Returns `void`: read the outcome from `status` / `data` / `error`. Drop `toolArgs` via the second overload when the tool has no required arguments.

**`sideEffects`** Optional callbacks bound to this specific call, firing even when a later call supersedes it.

```tsx theme={null}
type SideEffects = {
  // the call completed: the host returned a response (which may carry data.isError === true)
  onSuccess?: (data: CallToolResponse & ToolResponse, toolArgs: ToolArgs) => void;
  // the call failed to complete: the host rejected it
  onError?: (error: unknown, toolArgs: ToolArgs) => void;
  // runs after onSuccess or onError, with the other argument undefined
  onSettled?: (
    data: (CallToolResponse & ToolResponse) | undefined,
    error: unknown | undefined,
    toolArgs: ToolArgs,
  ) => void;
};
```

### `callToolAsync`

```tsx theme={null}
callToolAsync(toolArgs: ToolArgs): Promise<CallToolResponse & ToolResponse>;
callToolAsync(): Promise<CallToolResponse & ToolResponse>; // overload available when the tool has no required arguments
```

Tracks state on the hook exactly like `callTool`, and also returns a promise. It resolves with the [`response`](#data) when the call completes, and rejects with the thrown value when the call fails to complete. It accepts no `sideEffects`.

### `status`

```tsx theme={null}
status: "idle" | "pending" | "success" | "error";
```

* `"idle"`: no call has started.
* `"pending"`: a call is in flight.
* `"success"`: the most recent call completed and the host returned a response. The response may carry `data.isError === true`.
* `"error"`: the most recent call failed to complete and the host rejected it.

### `isIdle`, `isPending`, `isSuccess`, `isError`

```tsx theme={null}
isIdle: boolean;
isPending: boolean;
isSuccess: boolean;
isError: boolean;
```

Each is `true` when `status` equals the matching value and `false` otherwise. Exactly one is `true` at any time. `isError` here is the call-level flag (`status` is `"error"`). It is not `data.isError`, which marks a completed call whose tool reported a failure.

### `data`

```tsx theme={null}
data: (CallToolResponse & ToolResponse) | undefined;
```

The response, set only while `status` is `"success"`. It is `undefined` in every other state. A new call clears it to `undefined` as it enters `"pending"`. A tool that reports a failure still lands here, with `isError: true`; only a call that fails to complete sets `error` instead.

`CallToolResponse` is the fixed part of every response, which your `ToolResponse` type parameter narrows on `structuredContent` and `meta`:

```tsx theme={null}
type CallToolResponse = {
  content: ContentBlock[]; // the MCP content blocks the tool returned
  structuredContent: Record<string, unknown>;
  isError: boolean; // true when the tool itself reported a failure
  meta?: Record<string, unknown>;
};
```

### `error`

```tsx theme={null}
error: unknown | undefined;
```

The thrown value, set only while `status` is `"error"`. It is `undefined` in every other state. A tool that completes but reports its own failure is a `"success"`, not an `"error"`.

> [card] [Create Views](https://docs.skybridge.tech/build/view.md)
>
> Call tools back from a view in context

> [card] [generateHelpers](https://docs.skybridge.tech/api-reference/generate-helpers.md)
>
> The typed `useCallTool` that infers from your server

> [card] [useToolInfo](https://docs.skybridge.tech/api-reference/use-tool-info.md)
>
> Read the tool result the view mounted with


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.