MCP Apps Kit - v0.5.0
    Preparing search index...

    Interface ToolDef<TInput, TOutput>

    Single tool definition with Zod schemas

    interface ToolDef<
        TInput extends z.ZodType = z.ZodType,
        TOutput extends z.ZodType = z.ZodType,
    > {
        annotations?: ToolAnnotations;
        description: string;
        fileParams?: string[];
        handler: (
            input: output<TInput>,
            context: ToolContext,
        ) => Promise<
            output<TOutput> & {
                _closeWidget?: boolean;
                _meta?: Record<string, unknown>;
                _text?: string;
            },
        >;
        input: TInput;
        invokedMessage?: string;
        invokingMessage?: string;
        output?: TOutput;
        title?: string;
        ui?: string
        | UIDef;
        visibility?: Visibility;
        widgetAccessible?: boolean;
    }

    Type Parameters

    • TInput extends z.ZodType = z.ZodType
    • TOutput extends z.ZodType = z.ZodType
    Index

    Properties

    annotations? description fileParams? handler input invokedMessage? invokingMessage? output? title? ui? visibility? widgetAccessible?

    Properties

    annotations?: ToolAnnotations

    Behavioral hints for the AI model. Help hosts optimize UX and models understand tool behavior.

    description: string

    Human-readable description for the LLM

    fileParams?: string[]

    Input parameters that accept file references (ChatGPT only).

    List parameter names that should accept uploaded file IDs. ChatGPT will allow users to attach files to these parameters.

    ["imageFile", "documentFile"]
    handler: (
        input: output<TInput>,
        context: ToolContext,
    ) => Promise<
        output<TOutput> & {
            _closeWidget?: boolean;
            _meta?: Record<string, unknown>;
            _text?: string;
        },
    >

    Async handler function with typed input and context

    Type Declaration

      • (
            input: output<TInput>,
            context: ToolContext,
        ): Promise<
            output<TOutput> & {
                _closeWidget?: boolean;
                _meta?: Record<string, unknown>;
                _text?: string;
            },
        >

      • Parameters

        • input: output<TInput>

          Validated input matching the Zod schema

        • context: ToolContext

          Client-provided metadata (locale, location, etc.)

        Returns Promise<
            output<TOutput> & {
                _closeWidget?: boolean;
                _meta?: Record<string, unknown>;
                _text?: string;
            },
        >

        Promise resolving to the output matching the output schema

    handler: async (input, context) => {
      console.log(`Locale: ${context.locale}`);
      return { message: `Hello, ${input.name}!` };
    }
    input: TInput

    Zod schema for input validation

    invokedMessage?: string

    Message shown after tool completes (ChatGPT only)

    invokingMessage?: string

    Message shown while tool is executing (ChatGPT only)

    output?: TOutput

    Zod schema for output validation (optional for type inference)

    title?: string

    Optional display title (defaults to tool name)

    ui?: string | UIDef

    UI resource to render results.

    Can be:

    • A string key referencing a UI defined in createApp's ui config (legacy)
    • A UIDef object for colocated UI definition (recommended)
    const myTool = defineTool({
      ui: defineUI({
        html: "./widget.html",
        prefersBorder: true,
      }),
      // ...
    });

    const myTool = defineTool({
      ui: "my-widget", // References ui config in createApp
      // ...
    });
    visibility?: Visibility

    Who can call this tool

    widgetAccessible?: boolean

    Whether the widget/app can invoke this tool (ChatGPT only)

    Settings

    Member Visibility

    On This Page

    Properties