Tools

Meloqui provides a ToolRegistry for managing functions that LLMs can call.

ToolRegistry

Registry for managing user-defined tools.

import { ToolRegistry } from 'meloqui';

const tools = new ToolRegistry();

tools.registerTool(
  'get_weather',
  async ({ location }: { location: string }) => {
    return { temp: 72, condition: 'sunny' };
  },
  {
    description: 'Get current weather for a location',
    parameters: {
      type: 'object',
      properties: {
        location: { type: 'string', description: 'City name' }
      },
      required: ['location']
    }
  }
);

Methods

registerTool

Register a new tool function.

registerTool(
  name: string,
  func: ToolFunction,
  metadata: ToolMetadata
): void

Parameter	Type	Description
name	string	Unique tool name
func	ToolFunction	Async function to execute
metadata	ToolMetadata	Description and parameters

Throws Error if a tool with the same name already exists.

executeTool

Execute a registered tool by name.

executeTool(name: string, params?: any): Promise<any>

Throws Error if tool not found.

getTools

Get all registered tools.

getTools(): RegisteredTool[]

clear

Remove all registered tools.

clear(): void

toVercelTools

Convert to Vercel AI SDK format (used internally).

toVercelTools(): Record<string, Tool>

Types

ToolFunction

Tool function signature.

type ToolFunction<T = any> = (params: T) => Promise<any>;

Tools receive a single object parameter containing all arguments.

ToolMetadata

Metadata for a registered tool.

interface ToolMetadata {
  /** Human-readable description */
  description: string;
  /** Parameter schema (JSON Schema format) */
  parameters?: Record<string, any>;
}

RegisteredTool

Internal representation of a registered tool.

interface RegisteredTool {
  /** Tool name */
  name: string;
  /** The function to execute */
  func: ToolFunction;
  /** Tool metadata */
  metadata: ToolMetadata;
}

Using with ChatClient

import { ChatClient, ToolRegistry } from 'meloqui';

const tools = new ToolRegistry();

tools.registerTool(
  'calculate',
  async ({ expression }: { expression: string }) => {
    return eval(expression); // Use a safe math parser in production
  },
  {
    description: 'Evaluate a math expression',
    parameters: {
      type: 'object',
      properties: {
        expression: { type: 'string' }
      },
      required: ['expression']
    }
  }
);

const client = new ChatClient({
  provider: 'openai',
  model: 'gpt-4o',
  tools
});

const response = await client.chat('What is 25 * 4?');
// LLM calls calculate tool, returns "100"

Agentic Mode

Enable multi-step tool execution for complex tasks:

const client = new ChatClient({
  provider: 'openai',
  model: 'gpt-4o',
  tools,
  agenticMode: true,
  maxToolRounds: 10 // default: 10 for agentic, 5 for simple
});

In agentic mode, the LLM can make multiple tool calls in sequence to complete complex tasks.

JSON Schema Parameters

Tool parameters use JSON Schema format:

tools.registerTool(
  'search_products',
  async ({ query, category, maxPrice }) => { /* ... */ },
  {
    description: 'Search for products',
    parameters: {
      type: 'object',
      properties: {
        query: {
          type: 'string',
          description: 'Search query'
        },
        category: {
          type: 'string',
          enum: ['electronics', 'clothing', 'books'],
          description: 'Product category'
        },
        maxPrice: {
          type: 'number',
          description: 'Maximum price filter'
        }
      },
      required: ['query']
    }
  }
);