> ## 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.

# Register Tools

> Define what humans and agents can do

![Register Tools](https://docs.skybridge.tech/images/tools.webp)

Tools are the entry point of your app: the model reads their metadata and triggers them when they fit the conversation. Think of them as an API: each tool has one job, and jobs can complement each other. Bind a view to a tool, and the host [mounts](https://docs.skybridge.tech/get-started/architecture.md#app-lifecycle) it inline in the conversation. The model isn't the only caller: the user can trigger tools too, via the [view](https://docs.skybridge.tech/build/view.md).

Here's a complete tool definition:

```ts server.ts theme={null}
import { Skybridge } from "skybridge/server";
import { z } from "zod";

export const app = new Skybridge({
  name: "personal-shopper",
  version: "0.0.1",
  handler: (server) =>
    server.registerTool(
      {
        name: "search-products",
        title: "Search Products",
        description: "Show products matching a query in a carousel.",
        inputSchema: { query: z.string().describe("Full-text product search") },
        outputSchema: {
          products: z.array(
            z.object({ id: z.string(), name: z.string(), price: z.number() }),
          ),
        },
        annotations: { readOnlyHint: true, openWorldHint: false, destructiveHint: false },
        view: { component: "carousel" },
      },
      async ({ query }) => {
        const products = await search(query);
        return {
          content: `Found ${products.length} products for "${query}".`,
          structuredContent: {
            products: products.map(({ id, name, price }) => ({ id, name, price })),
          },
          _meta: { images: products.map((p) => p.imageUrl) },
        };
      },
    ),
});
```

The sections below build this definition up piece by piece: the server it lives on, the metadata and schemas the model reads, the handler, the behavior annotations, host-specific tuning, and the view binding.

## Create the App

[`Skybridge`](https://docs.skybridge.tech/api-reference/skybridge) takes your app's identity and a `handler`. The handler receives a fresh [`McpServer`](https://docs.skybridge.tech/api-reference/mcp-server) for every request: chain every [`registerTool`](https://docs.skybridge.tech/api-reference/register-tool) call on it and return the chain.

```ts server.ts theme={null}
export const app = new Skybridge({
  name: "personal-shopper",
  version: "0.0.1",
  handler: (server) =>
    server
      .registerTool(/* … */)
      .registerTool(/* … */),
});

export type AppType = typeof app;
```

```ts index.ts theme={null}
import { app } from "./server.js";

export default await app.run();
```

Chaining accumulates your tool signatures into one type, and returning the chain is what carries it into `AppType`. Exporting `AppType` is what makes the generated view hooks type-safe end to end. Keep the handler to registration: it runs on every request, so anything expensive belongs in [`setup`](https://docs.skybridge.tech/api-reference/skybridge#setup), whose result is the handler's second argument.

## Describe It to the Model

```ts server.ts highlight={3-5} theme={null}
server.registerTool(
  {
    name: "search-products",
    title: "Search Products",
    description: "Show products matching a query in a carousel.",
    inputSchema: { query: z.string().describe("Full-text product search") },
    outputSchema: {
      products: z.array(
        z.object({ id: z.string(), name: z.string(), price: z.number() }),
      ),
    },
    annotations: { readOnlyHint: true, openWorldHint: false, destructiveHint: false },
    view: { component: "carousel" },
  },
  async ({ query }) => {
    /* … */
  },
);
```

* `name` identifies the tool. Keep it kebab-case and verb-led: `search-products`, `create-checkout`.
* `title` is the human-readable display name.
* `description` is read to decide *when* to call the tool.

These are prompt engineering. Write them for the model: state what the tool does and what it shows, so the model can pick the right tool among many and narrate it correctly to the user.

## Type the Contract

Schemas are plain [Zod](https://zod.dev/) shapes, or any other [Standard Schema](https://standardschema.dev) validator that can emit JSON Schema. [`inputSchema`](https://docs.skybridge.tech/api-reference/register-tool#inputschema-outputschema) declares what the model must provide. [`outputSchema`](https://docs.skybridge.tech/api-reference/register-tool#inputschema-outputschema) is optional and declares the shape of the [structured content returned](https://docs.skybridge.tech/api-reference/register-tool.md#return) to the model.

```ts server.ts highlight={6-11} theme={null}
server.registerTool(
  {
    name: "search-products",
    title: "Search Products",
    description: "Show products matching a query in a carousel.",
    inputSchema: { query: z.string().describe("Full-text product search") },
    outputSchema: {
      products: z.array(
        z.object({ id: z.string(), name: z.string(), price: z.number() }),
      ),
    },
    annotations: { readOnlyHint: true, openWorldHint: false, destructiveHint: false },
    view: { component: "carousel" },
  },
  async ({ query }) => {
    /* … */
  },
);
```

`.describe()` on a field is more prompt surface: it tells the model how to fill the argument.

> [!NOTE]
>
> While it's recommended to provide the output schema, it's optional and isn't used for type safety, which is inferred from the handler's return type.

## Write the Handler

The [handler](api-reference/register-tool#handler) receives validated input and returns the tool's [response](https://docs.skybridge.tech/api-reference/register-tool.md#return). Three fields, three audiences:

| Field | Consumed by |
| - | - |
| `content` | The model: what it reads and narrates from |
| `structuredContent` | The model **and** the view |
| `_meta` | The view only: never reaches the model |

```ts server.ts highlight={15-24} theme={null}
server.registerTool(
  {
    name: "search-products",
    title: "Search Products",
    description: "Show products matching a query in a carousel.",
    inputSchema: { query: z.string().describe("Full-text product search") },
    outputSchema: {
      products: z.array(
        z.object({ id: z.string(), name: z.string(), price: z.number() }),
      ),
    },
    annotations: { readOnlyHint: true, openWorldHint: false, destructiveHint: false },
    view: { component: "carousel" },
  },
  async ({ query }) => {
    const products = await search(query);
    return {
      content: `Found ${products.length} products for "${query}".`,
      structuredContent: {
        products: products.map(({ id, name, price }) => ({ id, name, price })),
      },
      _meta: { images: products.map((p) => p.imageUrl) },
    };
  },
);
```

Choosing the recipient is a design decision: it controls what context each actor sees. Keep `content` and `structuredContent` concise, since they're model context. Use `_meta` for data the model has no use for or isn't supposed to know (image URLs, sensitive record fields): the view still accesses it, the model never sees it.

Handlers also receive an `extra` argument carrying additional data such as `extra.http?.authInfo` or [client hints](https://docs.skybridge.tech/api-reference/register-tool.md#client-hints).

## Annotate Behavior

[Annotations](https://docs.skybridge.tech/api-reference/register-tool.md#annotations) tell the host how cautious to be. They drive confirmation prompts before invocation, and app directories check them at review time:

```ts server.ts highlight={12} theme={null}
server.registerTool(
  {
    name: "search-products",
    title: "Search Products",
    description: "Show products matching a query in a carousel.",
    inputSchema: { query: z.string().describe("Full-text product search") },
    outputSchema: {
      products: z.array(
        z.object({ id: z.string(), name: z.string(), price: z.number() }),
      ),
    },
    annotations: { readOnlyHint: true, openWorldHint: false, destructiveHint: false },
    view: { component: "carousel" },
  },
  async ({ query }) => {
    /* … */
  },
);
```

* `readOnlyHint`: only reads data, no side effects
* `destructiveHint`: deletes or overwrites user data
* `openWorldHint`: publishes content or reaches beyond the user's account

> [!NOTE]
>
> Be honest with them: hosts trust these hints, and mislabeling a tool (claiming a write is read-only, hiding a destructive action) is a common cause of plugin directory rejection.

## Tune the Host with `_meta`

Tool-level [`_meta`](https://docs.skybridge.tech/api-reference/register-tool#_meta) (distinct from the response `_meta` above) carries host-specific configuration:

```ts server.ts highlight={14-20} theme={null}
server.registerTool(
  {
    name: "search-products",
    title: "Search Products",
    description: "Show products matching a query in a carousel.",
    inputSchema: { query: z.string().describe("Full-text product search") },
    outputSchema: {
      products: z.array(
        z.object({ id: z.string(), name: z.string(), price: z.number() }),
      ),
    },
    annotations: { readOnlyHint: true, openWorldHint: false, destructiveHint: false },
    view: { component: "carousel" },
    _meta: {
      // Expose the tool to the model, the view, or both (default)
      ui: { visibility: ["model", "app"] },
      // ChatGPT status messages shown while the tool runs
      "openai/toolInvocation/invoking": "Searching the catalog…",
      "openai/toolInvocation/invoked": "Found products",
    },
  },
  async ({ query }) => {
    /* … */
  },
);
```

## Bind a View

Adding `view` to a tool makes the host mount a React component with the tool's result. `component` names a file in `views/`:

```ts server.ts highlight={13} theme={null}
server.registerTool(
  {
    name: "search-products",
    title: "Search Products",
    description: "Show products matching a query in a carousel.",
    inputSchema: { query: z.string().describe("Full-text product search") },
    outputSchema: {
      products: z.array(
        z.object({ id: z.string(), name: z.string(), price: z.number() }),
      ),
    },
    annotations: { readOnlyHint: true, openWorldHint: false, destructiveHint: false },
    view: { component: "carousel" }, // resolves to views/carousel.tsx
  },
  async ({ query }) => {
    /* … */
  },
);
```

```tsx views/carousel.tsx theme={null}
import { useToolInfo } from "../helpers.js"; // generated, type-safe from server schema

export default function Carousel() {
  const { output } = useToolInfo<"search-products">();

  return (
    <ProductGrid products={output.products} />
  );
}
```

Each model call to the tool mounts a fresh view instance. Tools without `view` are headless: data, no UI.

> [card] [All done!](https://docs.skybridge.tech/build/view.md)
>
> You now know how to register tools. Learn what happens inside the view in the next chapter.

## Go Further

> [card] [Create Views](https://docs.skybridge.tech/build/view.md)
>
> Craft interactive UIs rendered in conversation

> [card] [Manage State](https://docs.skybridge.tech/build/state.md)
>
> Decide what the model sees

> [card] [Authenticate Users](https://docs.skybridge.tech/build/auth.md)
>
> Know who's behind every tool call


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