> This page is for Voice APIs.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://dev.hume.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://dev.hume.ai/_mcp/server.

# List tools

GET https://api.hume.ai/v0/evi/tools

Fetches a paginated list of **Tools**.

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.

Reference: https://dev.hume.ai/voice/reference/speech-to-speech-evi/tools/list-tools

## Authentication

- `X-Hume-Api-Key` header (required) — API Key authentication via header

## Request

### Query parameters

- `page_number` (integer, optional, default: 0) — Specifies the page number to retrieve, enabling pagination. This parameter uses zero-based indexing. For example, setting `page_number` to 0 retrieves the first page of results (items 0-9 if `page_size` is 10), setting `page_number` to 1 retrieves the second page (items 10-19), and so on. Defaults to 0, which retrieves the first page.
- `page_size` (integer, optional) — Specifies the maximum number of results to include per page, enabling pagination. The value must be between 1 and 100, inclusive. For example, if `page_size` is set to 10, each page will include up to 10 items. Defaults to 10.
- `restrict_to_most_recent` (boolean, optional) — By default, `restrict_to_most_recent` is set to true, returning only the latest version of each tool. To include all versions of each tool in the list, set `restrict_to_most_recent` to false.
- `name` (string, optional) — Filter to only include tools with name.

## Response

### 200

Success

- `page_number` (integer, required) — The page number of the returned list. This value corresponds to the `page_number` parameter specified in the request. Pagination uses zero-based indexing.
- `page_size` (integer, required) — The maximum number of items returned per page. This value corresponds to the `page_size` parameter specified in the request.
- `tools_page` (list of return_user_defined_tool, required) — List of tools returned for the specified `page_number` and `page_size`.
- `total_pages` (integer, required) — The total number of pages in the collection.

## Types

### return_user_defined_tool

A specific tool version returned from the server

- `created_on` (long, required) — The timestamp when the first version of this tool was created.
- `id` (string, required) — Identifier for a Tool. Formatted as a UUID.
- `modified_on` (long, required) — The timestamp when this version of the tool was created.
- `name` (string, required) — 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](/docs/speech-to-speech-evi/features/tool-use#using-built-in-tools).
- `parameters` (string, required) — 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_type` (enum, required)
  - Allowed values: `BUILTIN`, `FUNCTION`
- `version` (integer, required) — Version number for a Tool. Version numbers should be integers. The combination of configId and version number is unique.
- `version_type` (enum, required)
  - Allowed values: `FIXED`, `LATEST`
- `description` (string, optional, nullable) — An optional description of what the Tool does, used by the supplemental LLM to choose when and how to call the function.
- `fallback_content` (string, optional, nullable) — 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_description` (string, optional, nullable) — An optional description of the Tool version.

## Examples

**Response**

```json
{
  "page_number": 0,
  "page_size": 2,
  "tools_page": [
    {
      "created_on": 1715267200693,
      "id": "d20827af-5d8d-4f66-b6b9-ce2e3e1ea2b2",
      "modified_on": 1715267200693,
      "name": "get_current_location",
      "parameters": "{ \"type\": \"object\", \"properties\": { \"location\": { \"type\": \"string\", \"description\": \"The city and state, e.g. San Francisco, CA\" }}, \"required\": [\"location\"] }",
      "tool_type": "FUNCTION",
      "version": 0,
      "version_type": "FIXED",
      "description": "Fetches user's current location.",
      "fallback_content": "Unable to fetch location.",
      "version_description": "Fetches user's current location."
    },
    {
      "created_on": 1715266126705,
      "id": "4442f3ea-9038-40e3-a2ce-1522b7de770f",
      "modified_on": 1715266126705,
      "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\"] }",
      "tool_type": "FUNCTION",
      "version": 0,
      "version_type": "FIXED",
      "description": "Fetches current weather and uses celsius or fahrenheit based on location of user.",
      "fallback_content": "Unable to fetch location.",
      "version_description": "Fetches current weather and uses celsius or fahrenheit based on location of user."
    }
  ],
  "total_pages": 1
}
```