Register tools

Overview

Tools let your AI agent do more than just answer questions. By registering tools, you give the agent the ability to perform actions on your website — add items to a cart, navigate to a page, look up account details, or anything else you can do with JavaScript. When a visitor asks something that requires an action, the agent automatically picks the right tool, passes the correct parameters, and returns the result in the conversation.

Register a tool

Use the registerTool method on your Zephlo instance:

import Zephlo from "zephlo";

const zephlo = Zephlo.initialize({
  key: "flk_your_api_key",
  chatbotId: "YOUR_AGENT_ID",
});

zephlo.registerTool({
  name: "add_to_cart",
  description: "Add a product to the shopping cart",
  inputSchema: {
    type: "object",
    properties: {
      item: { type: "string", description: "Product name or SKU" },
      quantity: { type: "integer", description: "Number of items to add" },
    },
    required: ["item"],
  },
  execute: async (params) => {
    const res = await fetch("/api/cart", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify(params),
    });
    const data = await res.json();
    return `Added ${params.quantity || 1}x ${params.item} to cart. Total: $${data.total}`;
  },
});

Tool definition

Each tool has four fields:

Field	Type	Description
`name`	`string`	Unique identifier in `snake_case`. The agent uses this internally
`description`	`string`	Plain-English explanation of what the tool does. The agent reads this to decide when to use it
`inputSchema`	`object`	A JSON Schema describing the parameters the tool accepts
`execute`	`function`	The function that runs when the agent calls the tool. Receives the parameters and must return a `string`

Writing good descriptions

The description field is what the agent sees when deciding which tool to use. Be specific about when and why the tool should be called:

// Too vague -- agent won't know when to use it
description: "Does something with products"

// Good -- agent understands the trigger and purpose
description: "Add a product to the visitor's shopping cart when they want to buy something"

Input schema

The inputSchema follows JSON Schema format. Here are the supported types:

JSON Schema type	Description	Example
`string`	Text values	Names, emails, URLs
`integer`	Whole numbers	Quantities, IDs
`number`	Decimal numbers	Prices, percentages
`boolean`	True / false	Toggles, flags
`array`	Lists	Tags, selected items
`object`	Nested objects	Address, preferences

Example schema with all features

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "Search keywords"
    },
    "category": {
      "type": "string",
      "description": "Product category to filter by",
      "enum": ["electronics", "clothing", "books"]
    },
    "max_price": {
      "type": "number",
      "description": "Maximum price in USD"
    },
    "in_stock": {
      "type": "boolean",
      "description": "Only show items currently in stock"
    }
  },
  "required": ["query"]
}

Add a description to every property. The agent uses these to understand what values to pass.

The execute function

The execute function runs in the browser when the agent calls the tool. It has full access to the DOM, localStorage, fetch, and any other browser API. Rules:

Must return a string (or Promise<string>)
Can be synchronous or asynchronous
The returned string is sent back to the agent as the tool’s result

// Synchronous
execute: (params) => {
  return `Current page: ${document.title}`;
}

// Asynchronous
execute: async (params) => {
  const res = await fetch(`/api/orders/${params.orderId}`);
  const order = await res.json();
  return `Order ${order.id}: ${order.status}, shipped ${order.shipped_at}`;
}

Never return sensitive data (passwords, tokens, PII) from a tool. The result is sent to the AI agent and may appear in the chat.

Examples

Navigate to a page

zephlo.registerTool({
  name: "navigate",
  description: "Navigate the visitor to a specific page on the website",
  inputSchema: {
    type: "object",
    properties: {
      url: { type: "string", description: "Relative URL path like /pricing or /docs" },
    },
    required: ["url"],
  },
  execute: (params) => {
    window.location.href = params.url as string;
    return `Navigating to ${params.url}`;
  },
});

Search products

zephlo.registerTool({
  name: "search_products",
  description: "Search the product catalog and return matching results",
  inputSchema: {
    type: "object",
    properties: {
      query: { type: "string", description: "Search keywords" },
      limit: { type: "integer", description: "Max results to return" },
    },
    required: ["query"],
  },
  execute: async (params) => {
    const res = await fetch(`/api/products?q=${encodeURIComponent(params.query as string)}&limit=${params.limit || 5}`);
    const products = await res.json();
    return products.map((p: any) => `${p.name} - $${p.price}`).join("\n");
  },
});

Toggle dark mode

zephlo.registerTool({
  name: "toggle_dark_mode",
  description: "Switch between light and dark mode on the website",
  inputSchema: {
    type: "object",
    properties: {
      mode: {
        type: "string",
        description: "The theme to switch to",
        enum: ["light", "dark"],
      },
    },
    required: ["mode"],
  },
  execute: (params) => {
    document.documentElement.setAttribute("data-theme", params.mode as string);
    return `Switched to ${params.mode} mode`;
  },
});

Get page context

zephlo.registerTool({
  name: "get_page_info",
  description: "Get information about the page the visitor is currently viewing",
  inputSchema: {
    type: "object",
    properties: {},
  },
  execute: () => {
    return JSON.stringify({
      title: document.title,
      url: window.location.href,
      referrer: document.referrer,
    });
  },
});

Listening for tool results

You can listen for tool results to update your UI or trigger side effects:

const unsubscribe = zephlo.onToolResult((results) => {
  for (const result of results) {
    console.log(`Tool: ${result.tool_name}`);
    console.log(`Result: ${result.content}`);
    console.log(`Meta:`, result.meta);
  }
});

// Stop listening
unsubscribe();

Listing registered tools

Retrieve all registered tools and their schemas:

const tools = zephlo.webMcpTools();

for (const tool of tools) {
  console.log(tool.name, tool.description);
}

WebMCP browser integration

Zephlo implements the emerging WebMCP browser standard. When you register a tool, it’s also published to navigator.modelContext if the browser (or an agentic extension) supports it. Conversely, any tools other scripts have registered on navigator.modelContext are automatically discovered and made available to your agent. This means your tools can be shared with the visitor’s own AI assistant, and tools provided by other parts of your page work with Zephlo — no extra wiring. The standard API works everywhere regardless of browser support, so you don’t need to feature-detect it.

Getting started

Widget

Register tools

Overview

Register a tool

Tool definition

Writing good descriptions

Input schema

Example schema with all features

The execute function

Examples

Navigate to a page

Search products

Toggle dark mode

Get page context

Listening for tool results

Listing registered tools

WebMCP browser integration

Next steps

Form tools

Widget integration

​Overview

​Register a tool

​Tool definition

​Writing good descriptions

​Input schema

​Example schema with all features

​The execute function

​Examples

​Navigate to a page

​Search products

​Toggle dark mode

​Get page context

​Listening for tool results

​Listing registered tools

​WebMCP browser integration

​Next steps

Form tools

Widget integration

Overview

Register a tool

Tool definition

Writing good descriptions

Input schema

Example schema with all features

The execute function

Examples

Navigate to a page

Search products

Toggle dark mode

Get page context

Listening for tool results

Listing registered tools

WebMCP browser integration

Next steps