WebToolError

An error to throw from a tool's execute to pick the code the agent gets.

An error to throw from a tool’s execute to pick the code the agent gets. Without it, a thrown error is coded failed; with it the agent can tell bad input from a missing page from a person who must decide.

Import

import { WebToolError } from "@webmcp-agents/core";

Example

A lookup that tells the agent its input was wrong, so it can fix the reference and retry.

import { defineWebTool, WebToolError } from "@webmcp-agents/core";
import { z } from "zod";

const bookings = new Map([["SK-7F3K2Q", "LHR to JFK, 9 Dec, 08:15"]]);

export const getBooking = defineWebTool({
  id: "get_booking",
  title: "Look up a booking",
  description:
    "Look up a confirmed booking's itinerary by its reference " +
    "(SK-…). Use after booking, from any page.",
  inputSchema: z.object({
    reference: z.string().describe("e.g. SK-7F3K2Q"),
  }),
  readOnly: true,
  execute: ({ reference }) => {
    const found = bookings.get(reference.toUpperCase());
    if (!found)
      throw new WebToolError(
        "invalid_input",
        `No booking ${reference.toUpperCase()}. Check the reference.`,
      );
    return found;
  },
});

The agent gets Error [invalid_input]: No booking SK-0000. Check the reference., with structuredContent.error set to { code: "invalid_input", retryable: true }.

Options

new WebToolError(code, message).

Name	Type	Default	Description
`code`	`ToolErrorCode`	required	Why the call failed: `cancelled`, `interrupted`, `timeout`, `unavailable`, `invalid_input`, `needs_user` or `failed`. See the table under `toolError`. Readable afterwards as `error.code`.
`message`	`string`	required	What the agent reads. Say what to do next: “No booking SK-0000. Check the reference.” beats “Not found”.

Returns

An Error subclass with name "WebToolError" and the readonly property code: ToolErrorCode.

Notes

errorResult uses the error’s code over its own default, so the code survives toModelContextTool and reaches the agent.
useWebTool and defineWebTool’s invoke reject with a WebToolError carrying the agent’s code, so your own UI can branch on error.code.
An abort (AbortError) is never wrapped: a cancelled call stays a cancellation.