Tools API

defineTool()

function defineTool<
  TArgs = unknown,
  TResult = unknown,
  const TName extends string = string,
>(
  tool: ToolDefinition<TArgs, TResult, TName>,
): ToolDefinition<TArgs, TResult, TName>

Returns the provided definition unchanged while preserving TypeScript generics and literal name types.

const updateCounter = defineTool<
  { delta: number },
  { value: number }
>({
  name: "update_counter",
  description: "Update the visible counter by delta.",
  argsSchema: {
    type: "object",
    properties: {
      delta: { type: "integer" },
    },
    required: ["delta"],
  },
  handler: ({ delta }) => ({ value: counter.add(delta) }),
});

defineTool() itself does not perform validation. Session creation normalizes and validates the tool list.

ToolDefinition

type ToolDefinition<
  TArgs = unknown,
  TResult = unknown,
  TName extends string = string,
> = {
  name: TName;
  description: string;
  argsSchema: ToolArgsSchema;
  timeoutMs?: number;
  handler?: ToolSpecificHandler<TArgs, TResult>;
};

Field	Required	Description
name	Yes	Agent-facing name. Must start with a letter and contain only letters, digits, _, ., -.
description	Yes	Non-empty explanation of behavior, side effects, and selection criteria.
argsSchema	Yes	Pedelec Tool Args Schema. Root must be an object.
timeoutMs	No	Positive integer runtime wait limit. Core default is currently 60 seconds.
handler	No	Inline browser handler retained by the SDK and not sent to Core.

Names must be unique within a skills manifest.

ToolSpecificHandler

type ToolSpecificHandler<TArgs = unknown, TResult = unknown> = (
  args: TArgs,
  ctx: ToolCallContext,
) => TResult | Promise<TResult>;

The handler executes in browser page context. Type parameters are compile-time only; validate runtime args.

Return values must be compatible with the bridge’s JSON data model.

SkillsInput

type SkillsInput<
  TTools extends readonly ToolDefinition[] = readonly ToolDefinition[],
> = {
  guidance: string;
  tools: TTools;
};

const tools = [getCurrentPage, updateCounter] as const;

const skills = {
  guidance: "Read current state before making changes.",
  tools,
} satisfies SkillsInput<typeof tools>;

guidance must be a string. tools must be an array.

ToolNameOf

type ToolNameOf<TTools extends readonly ToolDefinition[]> = Extract<
  TTools[number]["name"],
  string
>;

Extracts the union of tool names from a readonly definitions array.

const tools = [readPage, updateCounter] as const;
type AppToolName = ToolNameOf<typeof tools>;
// "get_current_page" | "update_counter"

createSession() uses this type to narrow named session.onTool() calls.

SerializableToolManifest

type SerializableToolManifest = {
  name: string;
  description: string;
  argsSchema: ToolArgsSchema;
  timeoutMs?: number;
};

This is the tool shape sent to Core. It deliberately excludes handler.

SerializableSkillsManifest

type SerializableSkillsManifest = {
  guidance: string;
  tools: SerializableToolManifest[];
};

This is the normalized skills payload sent through the bridge.

Inline handler normalization

During createSession():

1. tool entries are checked;
2. argsSchema is cloned through JSON serialization;
3. inline handlers are stored in a browser-side map by name;
4. serializable definitions are sent to Core.

A duplicate tool name rejects with INVALID_INPUT.

Legacy input shorthand is rejected. Use argsSchema.

Handler resolution

For an incoming tool call:

1. named handler registered on the session;
2. inline handler from the original tool definition;
3. generic fallback handler;
4. SDK-created TOOL_HANDLER_NOT_FOUND result.

Handler exceptions become TOOL_HANDLER_ERROR results. Failure to deliver the result emits SUBMIT_TOOL_RESULT_FAILED.

Tool Args Schema entry types

The root alias:

type ToolArgsSchema = ToolArgsObjectSchema;

Node union:

type ToolArgsSchemaNode =
  | ToolArgsStringSchema
  | ToolArgsNumberSchema
  | ToolArgsIntegerSchema
  | ToolArgsBooleanSchema
  | ToolArgsArraySchema
  | ToolArgsObjectSchema
  | ToolArgsOneOfSchema;

See Types for every field and Tool Args Schema for usage guidance.