Tools

Tools are callable actions on your MCP server. Use a tool when the client should look up data, run a workflow, mutate server-side state, or return an MCP App widget. This guide focuses on tool design and common implementation patterns. Use the Tools API reference for ToolDefinition, callback signatures, type inference, defaults, and return types.

Start with a model-friendly tool

A good tool is narrow enough for a model to choose correctly. Give the tool a clear name, describe when to use it, validate every input with Zod, and return the smallest useful result.

import { MCPServer } from "mcp-use";
import { z } from "zod";

const server = new MCPServer({
  name: "inventory-server",
  version: "1.0.0",
});

export const getInventoryItem = server.tool(
  {
    name: "get_inventory_item",
    description: "Look up one inventory item by SKU.",
    inputSchema: z.object({
      sku: z.string().describe("Inventory SKU, such as SKU-1234"),
    }),
    annotations: {
      readOnlyHint: true,
      destructiveHint: false,
      openWorldHint: true,
    },
  },
  async ({ sku }) => {
    const item = await inventory.getItem(sku);
    return {
      content: [{ type: "text", text: JSON.stringify(item) }],
      structuredContent: item,
    };
  },
);

Use names that describe the user task, not the internal API method. get_inventory_item is easier for a model to choose than inventoryFindByPrimaryKey.

Assign every statically declared tool to an exported constant. The generated mcp-env.d.ts derives view types from exported tool refs, and useCallTool("name") fails type checking when the matching ref is not exported. Use useDynamicTool<Args, Result>("name") only for tools registered from runtime data, loops, OpenAPI documents, or other dynamic sources.

Describe inputs with Zod

Use Zod schemas for all tool inputs. The server validates the incoming arguments before your handler runs, and TypeScript infers the handler parameter type from the schema.

export const searchOrders = server.tool(
  {
    name: "search_orders",
    description: "Search customer orders by status and date range.",
    inputSchema: z.object({
      status: z.enum(["open", "fulfilled", "cancelled"]).optional(),
      fromDate: z.string().date().describe("Start date in YYYY-MM-DD format"),
      toDate: z.string().date().describe("End date in YYYY-MM-DD format"),
      limit: z.number().int().min(1).max(50).default(10),
    }),
    annotations: {
      readOnlyHint: true,
      destructiveHint: false,
      openWorldHint: true,
    },
  },
  async ({ status, fromDate, toDate, limit }) => {
    const orders = await orders.search({ status, fromDate, toDate, limit });
    return {
      content: [{ type: "text", text: JSON.stringify({ orders }) }],
      structuredContent: { orders },
    };
  },
);

Prefer descriptive field names and .describe() text that tells the model what value to provide. Use defaults for ordinary behavior, but keep defaults visible when they affect cost, safety, or output size.

Add tool annotations

Tool annotations tell clients and models how risky a tool is. Set the main behavior hints explicitly, especially for tools exposed to ChatGPT or MCP catalogs.

annotations: {
  readOnlyHint: true,      // The tool does not change server or external state.
  destructiveHint: false,  // The tool does not delete or overwrite data.
  openWorldHint: true,     // The tool reads from external systems or live data.
}

Use readOnlyHint: false for tools that create, update, delete, send, purchase, deploy, or otherwise change state. Use destructiveHint: true when the change can remove data or is hard to undo. Add idempotentHint when retry behavior matters. Set it to true only when repeating the same call has the same effect as running it once.

Return the right kind of result

Prefer raw MCP CallToolResult shapes. Deprecated response helpers still work for upgrades, but new code should return the wire envelopes directly.

export const reserveInventory = server.tool(
  {
    name: "reserve_inventory",
    description: "Reserve inventory for one order.",
    inputSchema: z.object({
      orderId: z.string(),
      sku: z.string(),
      quantity: z.number().int().positive(),
    }),
    annotations: {
      readOnlyHint: false,
      destructiveHint: false,
      openWorldHint: true,
    },
  },
  async ({ orderId, sku, quantity }) => {
    const reservation = await inventory.reserve({ orderId, sku, quantity });

    if (!reservation.ok) {
      return {
        isError: true,
        content: [{ type: "text", text: reservation.reason }],
      };
    }

    const data = {
      reservationId: reservation.id,
      status: "reserved",
    };
    return {
      content: [{ type: "text", text: JSON.stringify(data) }],
      structuredContent: data,
    };
  },
);

Use:

Use case	Return
Human-readable output	`{ content: [{ type: "text", text }] }`
Structured JSON	`{ content: [{ type: "text", text: JSON.stringify(data) }], structuredContent: data }`
Error	`{ isError: true, content: [{ type: "text", text: message }] }`
Multiple content blocks	`{ content: [/* ContentBlock… */] }`
View-bound tool	`view: { name }` + `{ content, structuredContent }`

See Response Helpers for the deprecated-helper migration table and Response helpers API reference for signatures.

Return views from tools

Bind a view on the tool definition, then return a plain CallToolResult with view props in structuredContent and model-facing text in content. The deprecated widget() helper builds the same envelope. The view.name value must match a view under resources/ (or your views directory).

export const searchProducts = server.tool(
  {
    name: "search_products",
    description: "Search products and display matching results.",
    inputSchema: z.object({
      query: z.string().describe("Product search query"),
    }),
    outputSchema: z.object({
      query: z.string(),
      results: z.array(z.object({ id: z.string(), name: z.string() })),
    }),
    annotations: {
      readOnlyHint: true,
      destructiveHint: false,
      openWorldHint: true,
    },
    view: {
      name: "product-search-result",
    },
  },
  async ({ query }) => {
    const results = await searchProducts(query);
    const data = { query, results };

    return {
      content: [
        {
          type: "text",
          text: `Found ${results.length} products for "${query}"`,
        },
      ],
      structuredContent: data,
    };
  },
);

The model sees content. The view reads structuredContent via useToolContext(). See MCP Apps for view workflow guidance.

Use `ctx` for request-aware tools

The second callback argument, usually named ctx, exposes per-call authentication, request-scoped client metadata and capability checks, elicitation, progress, and logging.

export const privateProfile = server.tool(
  {
    name: "private_profile",
    description: "Return the authenticated user's profile.",
    annotations: {
      readOnlyHint: true,
      destructiveHint: false,
      openWorldHint: false,
    },
  },
  async (_params, ctx) => {
    if (!ctx.auth) {
      return {
        isError: true,
        content: [{ type: "text", text: "Unauthorized" }],
      };
    }

    const data = {
      userId: ctx.auth.user.userId,
      email: ctx.auth.user.email,
    };
    return {
      content: [{ type: "text", text: JSON.stringify(data) }],
      structuredContent: data,
    };
  },
);

Use ctx.auth only for verified identity from server authentication. Values returned by ctx.client.info(), ctx.client.capabilities(), ctx.client.extension(), and ctx.client.user() are self-reported by the client for the current request. user() normalizes optional OpenAI-specific _meta hints; even its subject, conversation, and organization identifiers are unverified and must never be used for access control. See the Tool context API reference for every ctx method, field, capability check, log level, and return type.

Handle tool failures deliberately

Return { isError: true, content: […] } when the tool ran but the requested operation could not complete. Throw only for unexpected failures that should be treated as server errors.

export const fetchInvoice = server.tool(
  {
    name: "fetch_invoice",
    description: "Fetch one invoice by invoice ID.",
    inputSchema: z.object({ invoiceId: z.string() }),
    annotations: {
      readOnlyHint: true,
      destructiveHint: false,
      openWorldHint: true,
    },
  },
  async ({ invoiceId }) => {
    const invoice = await billing.findInvoice(invoiceId);

    if (!invoice) {
      return {
        isError: true,
        content: [
          { type: "text", text: `Invoice ${invoiceId} was not found.` },
        ],
      };
    }

    return {
      content: [{ type: "text", text: JSON.stringify(invoice) }],
      structuredContent: invoice,
    };
  },
);

Make error messages actionable. Tell the model or user what failed and which input caused the failure.

Test a tool locally

Run the development server and call the tool from the Inspector.

npm run dev

Then open http://localhost:3000/mcp/inspector, select the tool, enter test arguments, and verify both success and failure cases.

Next steps

Tools API reference

Look up tool definitions, callback signatures, inferred types, and return shapes.

Response Helpers

Choose the right helper for text, JSON, errors, resources, media, and widgets.

MCP Apps

Return interactive widgets from tool results.

Authentication

Add verified user identity to protected tools.

Get Started

MCP Server

MCP Apps

MCP Client

MCP Agent

Tooling

Start with a model-friendly tool

Describe inputs with Zod

Add tool annotations

Return the right kind of result

Return views from tools

Use `ctx` for request-aware tools

Handle tool failures deliberately

Test a tool locally

Next steps

Tools API reference

Response Helpers

MCP Apps

Authentication

​Start with a model-friendly tool

​Describe inputs with Zod

​Add tool annotations

​Return the right kind of result

​Return views from tools

​Use ctx for request-aware tools

​Handle tool failures deliberately

​Test a tool locally

​Next steps

Tools API reference

Response Helpers

MCP Apps

Authentication

Start with a model-friendly tool

Describe inputs with Zod

Add tool annotations

Return the right kind of result

Return views from tools

Use `ctx` for request-aware tools

Handle tool failures deliberately

Test a tool locally

Next steps