Lava Tools

Harness the dual power of Lava and Rock to build robust, custom functionality with ease. Whether you prefer using high-level entity commands or diving into raw SQL for complex data retrieval, the choice is yours. Beyond just reading data, you can utilize Entity Commands to enable seamless updates. While our examples prioritize SQL for its straightforward approach, remember that the full breadth of Lava is at your fingertips.

A Lava tool has four parts. The Name and Description tell the agent what the tool does and when to call it. Write these carefully, because the model uses them to decide which tool to reach for. The Prompt is the Lava template that runs when the tool is invoked. Parameters define what the agent must pass in. In this example, groupIdKey is a required String parameter. The first line of the Prompt converts it: {% assign groupId = groupIdKey | FromIdHash %}. This is the correct pattern — accept an IdKey, convert it inside the tool, and never expose raw integer Ids to the model.  

Tool Types

There are two types of lava tools you can create:

AI Prompt - A shortcut name for a prompt.When used, it tells the AI: “follow these instructions instead,” using whatever is stored in that prompt.

Execute Lava - Runs the Lava, then formats the results with special filters and returns them to the agent.

AI Prompt Tools

Execute Lava Tools

Return Data to the Agent

When building tools, the response needs to follow a clear, consistent structure. This helps the AI tell the difference between a successful result, an error, and a case where no data was returned. To make that easier, we created a set of Lava filters that format tool responses into the expected shape.

Status Values

Every response must include a status:

• Success— the operation completed successfully and may include a payload. If the payload is missing or an empty list then a NoData result will be generated.
• Error— the operation failed, with an error message describing why.

Filters

These filters shape how the tool sends results back to the agent.

Examples

// Return an error
{% assign result = 'Error' | AgentToolResult:'The value for the startDate parameter was not valid.' %}

// Return a success message
{% assign result = 'Success' | AgentToolResult:'Operation completed successfully.' %}

// Return a list of items
{% assign items = '[]' | FromJSON %}
{% assign result = 'Success' | AgentToolResult:items | AgentToolMetadata:'HasMoreItems',false %}
{% assign result = result | AgentToolInstructions:'The list of items may contain duplicates, these should be removed.' %}

Agent Context Merge Fields

In addition to the standard merge fields, you can access these useful properties available on the AgentContext merge field. Please note that these are only available on the Execute Lava tool.

Ex: {{ AgentContext.AgentType }}

More on Lava Tools