Skip to main content

​
Special Tool Response Types

For most tools, the response will include data you want the model to use (e.g. the results of a lookup). However, Ultravox has support for special tool actions that can end the call, change the call stage, change which tools are available, or communicate with another thread. These tool actions require setting a special response type. How you set the response type depends on your tool implementation. HTTP tools set the response type via the X-Ultravox-Response-Type header. Client and data connection tools should set the responseType field in their tool result message.

​
Updating Tools

An update-tools response changes the tools available to the thread that invoked the tool. Some ways to use it:
  • Large toolsets → Start with a few broad tools and add the specific tools for whatever the caller needs, so the model isn’t distracted by dozens of tools that don’t matter yet.
  • Gated actions → Add account tools only once a verifyIdentity tool succeeds, so the model can’t use them before the caller is verified.
  • Thread-only tools → Give a background thread tools the main conversation never sees. See Giving a background thread its own tools.
If a call stage starts with no tools at all, the model may not reliably call tools added later, because it hasn’t been shown how to call tools. Give the stage at least one tool, such as the tool that adds the others.
The response body sets the tools to remove and add:
​
string[]
Names of tools to remove, as the model sees them (nameOverride if set, otherwise modelToolName). Each must be a tool the thread can currently use. May not be set together with removeAll.
​
boolean
If true, removes all of the thread’s current tools. May not be set together with remove.
​
object[]
Tools to add, in the same format as selectedTools when creating a call. Removals are applied first. An added tool may not reuse the name of a tool the thread keeps, so to replace a tool, remove it and add the new one in the same response.
​
string
default:"OK"
The text the model sees as this tool call’s result.
How you send it depends on the tool type:
  • For HTTP tools, return the body as JSON and set the X-Ultravox-Response-Type header to update-tools.
  • For client and data connection tools, set responseType to update-tools and send the body as the JSON-encoded result.
Things to know about updated tools:
  • They apply only to the invoking thread. Other threads keep their own tools. Threads spawned afterward start from their parent’s current tools.
  • They last until the stage ends. A new call stage starts with that stage’s original tools.
  • Invalid updates change nothing. If the update can’t be applied (for example, an unknown tool, a name collision, or a tool that fails validation), the model gets an error tool result, and the tool message’s errorDetails explains why.
  • They’re listed with the stage’s tools. List Call Stage Tools includes tools added this way when you pass includeRevealed=true, with revealedForThreadId identifying the thread they were added to. A tool’s revealedForThreadId will be UI if the tool was added to the main thread.
To give a new thread different tools from its parent, use toolOverrides when spawning the thread.