Skip to main content

​
The Simple Way: registerTool()

For most use cases, use registerTool() to add tools one at a time: 
const registration = navigator.modelContext.registerTool({
  name: "add_to_cart",
  description: "Add a product to the shopping cart",
  inputSchema: {
    type: "object",
    properties: {
      productId: { type: "string" },
      quantity: { type: "number" }
    }
  },
  async execute({ productId, quantity }) {
    await addToCart(productId, quantity);
    return {
      content: [{ type: "text", text: `Added ${quantity} items` }]
    };
  }
});

// Optional: Unregister later if needed
registration.unregister();
Why registerTool() is the default:
  • ✅ Works everywhere (React, Vue, vanilla JS)
  • ✅ Automatic cleanup when unregistered
  • ✅ Perfect for component-scoped tools
  • ✅ Simple and intuitive
Only use provideContext() when you need to set application-level base tools all at once:
navigator.modelContext.provideContext({
  tools: [/* array of tool definitions */]
});
When to use:
  • Defining core application tools at startup
  • Setting up a foundation tool set
Important: This replaces all base tools each time it’s called. For most use cases, stick with registerTool() instead.See Advanced Patterns for detailed guidance.

​
Tool Lifecycle

​
React Component Example

​
Vanilla JavaScript Example

​
Tool Definition Structure

A complete tool definition includes: 
interface ToolDefinition {
  name: string;              // Unique tool identifier (e.g., "add_to_cart")
  description: string;       // Clear description for AI understanding
  inputSchema: JSONSchema;   // JSON Schema for input validation
  execute: (args) => Promise<ToolResult>;  // Handler function
  annotations?: {            // Optional hints for AI
    idempotentHint?: boolean;
    readOnlyHint?: boolean;
    destructiveHint?: boolean;
  };
}

​
Registration Best Practices

Don’t repeatedly register and unregister tools. Register when the component/feature becomes available, unregister when it’s removed.
// ✅ Good - register once in useEffect
useEffect(() => {
  const reg = navigator.modelContext.registerTool({...});
  return () => reg.unregister();
}, []);

// ❌ Bad - registering on every render
const reg = navigator.modelContext.registerTool({...});
Avoid registering too many tools (>50) on a single page. This can overwhelm AI agents and slow down tool discovery.Consider:
  • Registering context-specific tools dynamically
  • Grouping related operations into single tools with parameters
  • Using tool annotations to guide AI selection
Always unregister tools when they’re no longer available:
// React - use cleanup function
useEffect(() => {
  const reg = navigator.modelContext.registerTool({...});
  return () => reg.unregister();
}, []);

// Vanilla JS - cleanup on page unload
const registration = navigator.modelContext.registerTool({...});
window.addEventListener('beforeunload', () => {
  registration.unregister();
});
Help AI agents understand when and how to use your tools:
// ✅ Good
{
  name: "shopping_cart_add_item",
  description: "Add a product to the user's shopping cart by product ID and quantity. Returns updated cart total."
}

// ❌ Bad
{
  name: "addItem",
  description: "Adds item"
}

Tool Schemas

Learn about input validation and schema definition

Tool Design Patterns

Best practices for designing effective tools

React WebMCP

React hooks for WebMCP tool registration

Performance

Performance considerations for tool registration