For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
Log inSign up
Support
GuidesReference
GuidesReference
    • Core
      • Overview
    • Agents
      • Overview
      • AgentBase
      • AgentServer
      • Configuration
      • ContextBuilder
      • DataMap
      • FunctionResult
      • Helper Functions & Utilities
      • LiveWire
        • Agent
        • AgentSession
        • Infrastructure
        • Plugins
        • runApp
        • RunContext
        • Signals
        • tool / FunctionTool
      • PomBuilder
      • Prefabs
      • SkillBase
      • SkillManager
      • SkillRegistry
      • Skills
      • SwaigFunction
      • SwmlBuilder
      • SWMLService
    • RELAY
      • Overview
      • Actions
      • Call
      • Constants
      • Events
      • Message
      • RelayClient
      • RelayError
    • REST Client
      • Overview
      • Addresses
      • Calling
      • ChatResource
      • Compat
      • Datasphere
      • Fabric
      • ImportedNumbersResource
      • Logs
      • LookupResource
      • MFA
      • Number Groups
      • Phone Numbers
      • Project
      • PubSubResource
      • Queues
      • Recordings
      • Registry
      • RestClient
      • RestError
      • Short Codes
      • SIP Profile
      • Verified Callers
      • Video
LogoLogoSignalWire Docs
Log inSign up
Support
On this page
  • tool
  • Parameters
  • Returns
  • Examples
  • FunctionTool Interface
AgentsLiveWire

tool / FunctionTool

|View as Markdown|Open in Claude|
Was this page helpful?
Edit this page
Previous

PomBuilder

Next
Built with

tool

1function tool<P = any>(options: {
2  description: string;
3  parameters?: any;
4  execute: (params: P, context: { ctx: RunContext }) => any;
5}): FunctionTool

Creates a FunctionTool definition that can be passed into an Agent’s tools map. The tool() function mirrors llm.tool() from @livekit/agents-js.

When the underlying SignalWire agent is built, each tool is registered as a SWAIG function via defineTool().

Parameters

description
stringRequired

A description of what the tool does. This is sent to the LLM so it knows when to invoke the tool.

parameters
any

JSON Schema describing the tool’s parameters, or a Zod schema object. If omitted, the tool accepts no parameters.

execute
(params: P, context: { ctx: RunContext }) => anyRequired

The function to run when the tool is invoked. Receives the parsed parameters and a context object containing the RunContext. Can return a string, an object (serialized to JSON), or a FunctionResult.

Returns

FunctionTool — A tool definition object. The name field is empty and gets filled in when the tool is assigned to a key in Agent.tools.

Examples

1import { tool } from '@signalwire/sdk/livewire';
2
3const getWeather = tool({
4  description: 'Get the current weather for a city.',
5  parameters: {
6    city: { type: 'string', description: 'The city name' },
7  },
8  execute: (params) => {
9    return `It is sunny in ${params.city}.`;
10  },
11});

FunctionTool Interface

The FunctionTool interface represents a tool definition that can be registered on an Agent.

1interface FunctionTool {
2  name: string;
3  description: string;
4  parameters?: Record<string, unknown>;
5  execute: (params: any, context: { ctx: RunContext }) => any;
6}
name
string

The tool name. When created via tool(), this is initially empty and is set automatically when the tool is added to an Agent’s tools map (the map key becomes the name).

description
string

A description of what the tool does.

parameters
Record<string, unknown> | undefined

JSON Schema or Zod schema describing the tool’s accepted parameters.

execute
(params: any, context: { ctx: RunContext }) => any

The handler function invoked when the LLM calls this tool.