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.
Start buildingGet support
DocumentationAPI ReferenceChangelogDiscord
  • Voices
    • POSTCreate voice
    • GETList voices
    • DELDelete voice
  • Text-to-Speech (TTS)
    • WSSStream Input
    • STREAMText-to-Speech (Streamed JSON)
    • POSTText-to-Speech (Streamed File)
    • POSTText-to-Speech (Json)
    • POSTText-to-Speech (File)
    • POSTVoice Conversion (Streamed File)
    • STREAMVoice Conversion (Streamed JSON)
  • Speech-to-speech (EVI)
    • WSSChat
      • POSTCreate tool
      • GETList tools
      • GETList tool versions
      • GETGet tool version
      • POSTCreate tool version
      • PATCHUpdate tool name
      • PATCHUpdate tool description
      • DELDelete tool
      • DELDelete tool version
  • Expression Measurement API
Start buildingGet support
LogoLogo
LogoLogo
Speech-to-speech (EVI)Tools

Create tool

POST
https://api.hume.ai/v0/evi/tools
POST
/v0/evi/tools
$curl -X POST https://api.hume.ai/v0/evi/tools \
>     -H "X-Hume-Api-Key: <apiKey>" \
>     -H "Content-Type: application/json" \
>     -d '{
>  "name": "get_current_weather",
>  "parameters": "{ \"type\": \"object\", \"properties\": { \"location\": { \"type\": \"string\", \"description\": \"The city and state, e.g. San Francisco, CA\" }, \"format\": { \"type\": \"string\", \"enum\": [\"celsius\", \"fahrenheit\"], \"description\": \"The temperature unit to use. Infer this from the users location.\" } }, \"required\": [\"location\", \"format\"] }",
>  "description": "This tool is for getting the current weather.",
>  "fallback_content": "Unable to fetch current weather.",
>  "version_description": "Fetches current weather and uses celsius or fahrenheit based on location of user."
>}'
201Created
1{
2  "created_on": 1715275452390,
3  "id": "aa9b71c4-723c-47ff-9f83-1a1829e74376",
4  "modified_on": 1715275452390,
5  "name": "get_current_weather",
6  "parameters": "{ \"type\": \"object\", \"properties\": { \"location\": { \"type\": \"string\", \"description\": \"The city and state, e.g. San Francisco, CA\" }, \"format\": { \"type\": \"string\", \"enum\": [\"celsius\", \"fahrenheit\"], \"description\": \"The temperature unit to use. Infer this from the users location.\" } }, \"required\": [\"location\", \"format\"] }",
7  "tool_type": "FUNCTION",
8  "version": 0,
9  "version_type": "FIXED",
10  "description": "This tool is for getting the current weather.",
11  "fallback_content": "Unable to fetch current weather.",
12  "version_description": "Fetches current weather and uses celsius or fahrenheit based on location of user."
13}
Creates a **Tool** that can be added to an [EVI configuration](/reference/speech-to-speech-evi/configs/create-config). Refer to our [tool use](/docs/speech-to-speech-evi/features/tool-use#function-calling) guide for comprehensive instructions on defining and integrating tools into EVI.
Was this page helpful?
Previous

List tools

Next
Built with

Creates a Tool that can be added to an EVI configuration.

Refer to our tool use guide for comprehensive instructions on defining and integrating tools into EVI.

Authentication

X-Hume-Api-Keystring
API Key authentication via header

Request

This endpoint expects an object.
namestringRequired

Name of the built-in tool to use. Hume supports the following built-in tools:

  • web_search: enables EVI to search the web for up-to-date information when applicable.
  • hang_up: closes the WebSocket connection when appropriate (e.g., after detecting a farewell in the conversation).

For more information, see our guide on using built-in tools.

parametersstringRequired
Stringified JSON defining the parameters used by this version of the Tool. These parameters define the inputs needed for the Tool's execution, including the expected data type and description for each input field. Structured as a stringified JSON schema, this format ensures the Tool receives data in the expected format.
descriptionstring or nullOptional
An optional description of what the Tool does, used by the supplemental LLM to choose when and how to call the function.
fallback_contentstring or nullOptional
Optional text passed to the supplemental LLM in place of the tool call result. The LLM then uses this text to generate a response back to the user, ensuring continuity in the conversation if the Tool errors.
version_descriptionstring or nullOptional
An optional description of the Tool version.

Response

Created
created_onlong
The timestamp when the first version of this tool was created.
idstring
Identifier for a Tool. Formatted as a UUID.
modified_onlong
The timestamp when this version of the tool was created.
namestring

Name of the built-in tool to use. Hume supports the following built-in tools:

  • web_search: enables EVI to search the web for up-to-date information when applicable.
  • hang_up: closes the WebSocket connection when appropriate (e.g., after detecting a farewell in the conversation).

For more information, see our guide on using built-in tools.

parametersstring
Stringified JSON defining the parameters used by this version of the Tool. These parameters define the inputs needed for the Tool's execution, including the expected data type and description for each input field. Structured as a stringified JSON schema, this format ensures the Tool receives data in the expected format.
tool_typeenum
Allowed values:
versioninteger
Version number for a Tool. Version numbers should be integers. The combination of configId and version number is unique.
version_typeenum
Allowed values:
descriptionstring or null
An optional description of what the Tool does, used by the supplemental LLM to choose when and how to call the function.
fallback_contentstring or null
Optional text passed to the supplemental LLM in place of the tool call result. The LLM then uses this text to generate a response back to the user, ensuring continuity in the conversation if the Tool errors.
version_descriptionstring or null
An optional description of the Tool version.