How Devices Become Tools

Tool Naming Convention

When a device connects with a list of commands, the agent runtime creates a tool for each command. The tool name follows this pattern:

device:{deviceName}:{commandName}

For example, a device named label-printer with a command print_label becomes the tool:

device:label-printer:print_label

The agent sees this tool alongside its regular skill tools and can invoke it in exactly the same way.

Auto-Generated Tools

The agent runtime automatically generates each device tool with:

Property	Source
Tool name	`device:{deviceName}:{commandName}`
Tool description	The `description` field from `DeviceCommandDefinition`
Input schema	The `inputSchema` field from `DeviceCommandDefinition` (or no parameters if omitted)
Timeout	The `timeoutMs` field (default: 30 seconds)

No lua push or lua deploy is needed. The tools appear the moment the device connects and disappear when it disconnects.

Tips for Good Descriptions

The description field is what the AI agent reads to decide whether to use the tool. Better descriptions lead to better tool selection.

Good Descriptions
Bad Descriptions

commands: [
  {
    name: 'read_temperature',
    description: 'Read the current room temperature in celsius from the wall-mounted sensor',
  },
  {
    name: 'print_label',
    description: 'Print a shipping label. Requires recipient name, address, city, and postal code. Optionally specify number of copies (1-10).',
  },
  {
    name: 'scan_barcode',
    description: 'Activate the barcode scanner and return the scanned code. Takes 2-3 seconds. Returns the barcode value and format (UPC, QR, etc).',
  },
]

These descriptions tell the agent:

What the command does
What it needs as input
What it returns
How long it takes (if relevant)

commands: [
  {
    name: 'read_temperature',
    description: 'temp',
  },
  {
    name: 'print_label',
    description: 'prints stuff',
  },
  {
    name: 'scan_barcode',
    description: 'scanner',
  },
]

These descriptions are too vague. The agent will struggle to know when to use these tools or what parameters to pass.

Persona Tips

Your agent persona can reference devices to guide tool usage. Add instructions in your persona about when and how to use device tools:

const agent = new LuaAgent({
  name: 'warehouse-agent',
  persona: `
    You are a warehouse operations assistant.

    You have access to physical devices in the warehouse:
    - Barcode scanners for inventory lookup
    - Weight scales for package verification
    - Gate controllers for dock access

    When a user asks about inventory, use the barcode scanner to look up items.
    When verifying shipments, use the weight scale to confirm package weight.
    Always confirm before opening or closing gates.

    If a device is offline, tell the user and suggest alternatives.
  `,
  skills: [inventorySkill],
});

Example Conversation

Here is what a conversation looks like when an agent uses device tools:

User: What's the temperature in the server room?

Agent: [internally selects tool: device:server-room-sensor:read_temperature]
       [sends command to device, receives: { temperature: 23.5, unit: 'celsius' }]

       The server room temperature is currently 23.5 degrees celsius.

User: That seems a bit warm. Can you turn up the AC?

Agent: [internally selects tool: device:server-room-hvac:set_target]
       [sends command with payload: { temperature: 21 }]
       [receives: { targetTemperature: 21, heatingOn: false }]

       Done. I've set the target temperature to 21 degrees celsius.
       The cooling system is now active. The temperature should
       come down within the next few minutes.

User: Thanks. Let me know if it goes above 25.

Agent: I'll keep an eye on it. If the temperature exceeds 25 degrees,
       I'll notify you immediately.
       [Note: this would be handled by a device trigger, not polling]

Multiple Devices

An agent can have many devices connected at once. The device name in the tool name disambiguates them:

device:sensor-floor-1:read_temperature
device:sensor-floor-2:read_temperature
device:sensor-floor-3:read_temperature
device:label-printer:print_label
device:gate-controller:open_gate

The agent picks the right device based on the user’s request and the tool descriptions.

Offline Devices

When a device disconnects, its tools are removed from the agent’s tool list. The agent will not be able to use commands from an offline device. If a user asks for something that requires an offline device, the agent should explain that the device is unavailable.

Design your persona to handle this gracefully. The agent does not know about devices that were previously connected but are now offline — it only sees currently connected devices.

Next Steps

Self-Describing Commands

Detailed reference for DeviceCommandDefinition

Triggers

The other direction — devices sending events to the agent

Quickstart

See device tools in action

Examples

Full working examples with multiple devices

Getting Started

Device Client

Agent Integration

Examples

Advanced

CLI Commands

How Devices Become Tools

Tool Naming Convention

Auto-Generated Tools

Tips for Good Descriptions

Persona Tips

Example Conversation

Multiple Devices

Offline Devices

Next Steps

Self-Describing Commands

Triggers

Quickstart

Examples

​Tool Naming Convention

​Auto-Generated Tools

​Tips for Good Descriptions

​Persona Tips

​Example Conversation

​Multiple Devices

​Offline Devices

​Next Steps

Self-Describing Commands

Triggers

Quickstart

Examples

Tool Naming Convention

Auto-Generated Tools

Tips for Good Descriptions

Persona Tips

Example Conversation

Multiple Devices

Offline Devices

Next Steps