---
type: api
title: Get a tool by id
description: **Spaces method and path for this operation:**
url: https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/kibana-serverless/operation/operation-get-agent-builder-tools-toolid
resource: https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/kibana-serverless/operation/operation-get-agent-builder-tools-toolid
products:
  - Kibana
---

# Get a tool by id

- Server: `https://{kibana_url}`

## Paths

- `GET` `/api/agent_builder/tools/{toolId}`
- `GET` `/s/{space_id}/api/agent_builder/tools/{toolId}`

- [Api key auth](/elastic/docs-builder/docs/4371/api/doc/kibana-serverless/authentication#apikeyauth)

#### Path Parameters

- `toolId` (string)
  The unique identifier of the tool to retrieve.

## Description

Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.

Get a specific tool by ID. Use this endpoint to retrieve the complete tool definition including its schema and configuration requirements. To learn more about Agent Builder tools, refer to the [tools documentation](https://www.elastic.co/docs/explore-analyze/ai-features/agent-builder/tools).<br/><br/>[Required authorization] Route required privileges: agentBuilder:read.

## Response

Indicates a successful response

## Code Examples

#### Console

```console
GET kbn:/api/agent_builder/tools/{toolId}
```

#### curl

```curl
curl \
  -X GET "https://${KIBANA_URL}/api/agent_builder/tools/{toolId}" \
  -H "Authorization: ApiKey ${API_KEY}"
```

## Response Examples

#### Get builtin tool

Example response returning built-in platform.core.search tool

```json
{
  "configuration": {},
  "description": "A powerful tool for searching and analyzing data within your Elasticsearch cluster.\nIt supports both full-text relevance searches and structured analytical queries.\n\nUse this tool for any query that involves finding documents, counting, aggregating, or summarizing data from a known index.\n\nExamples of queries:\n- \u0022find articles about serverless architecture\u0022\n- \u0022search for support tickets mentioning \u0027billing issue\u0027 or \u0027refund request\u0027\u0022\n- \u0022what is our policy on parental leave?\u0022\n- \u0022list all products where the category is \u0027electronics\u0027\u0022\n- \u0022show me the last 5 documents from that index\u0022\n- \u0022show me the sales over the last year break down by month\u0022\n\nNote:\n- The \u0027index\u0027 parameter can be used to specify which index to search against.\n If not provided, the tool will decide itself which is the best index to use.\n- It is perfectly fine not to specify the \u0027index\u0027 parameter. It should only be specified when you already\n know about the index and fields you want to search on, e.g. if the user explicitly specified it.",
  "id": "platform.core.search",
  "readonly": true,
  "schema": {
    "$schema": "http://json-schema.org/draft-07/schema#",
    "additionalProperties": false,
    "type": "object",
    "properties": {
      "index": {
        "description": "(optional) Index to search against. If not provided, will automatically select the best index to use based on the query.",
        "type": "string"
      },
      "query": {
        "description": "A natural language query expressing the search request",
        "type": "string"
      }
    },
    "required": [
      "query"
    ]
  },
  "tags": [],
  "type": "builtin"
}
```

#### Get ES|QL tool

Example response returning custom example-esql-tool tool

```json
{
  "configuration": {
    "params": {
      "limit": {
        "description": "Maximum number of results to return",
        "type": "integer"
      },
      "startTime": {
        "description": "Start time for the analysis in ISO format",
        "type": "date"
      }
    },
    "query": "FROM financial_trades | WHERE execution_timestamp \u003E= ?startTime | STATS trade_count=COUNT(*), avg_price=AVG(execution_price) BY symbol | SORT trade_count DESC | LIMIT ?limit"
  },
  "description": "Example ES|QL query tool for analyzing financial trades with time filtering",
  "id": "example-esql-tool",
  "readonly": false,
  "schema": {
    "$schema": "http://json-schema.org/draft-07/schema#",
    "additionalProperties": false,
    "description": "Parameters needed to execute the query",
    "type": "object",
    "properties": {
      "limit": {
        "description": "Maximum number of results to return",
        "type": "integer"
      },
      "startTime": {
        "description": "Start time for the analysis in ISO format",
        "format": "date-time",
        "type": "string"
      }
    },
    "required": [
      "startTime",
      "limit"
    ]
  },
  "tags": [
    "analytics",
    "finance"
  ],
  "type": "esql"
}
```

#### Get index search tool

Example response returning custom example-index-search-tool tool

```json
{
  "configuration": {
    "pattern": "financial_*"
  },
  "description": "Search tool specifically for financial data analysis and reporting",
  "id": "example-index-search-tool",
  "readonly": false,
  "schema": {
    "$schema": "http://json-schema.org/draft-07/schema#",
    "additionalProperties": false,
    "type": "object",
    "properties": {
      "nlQuery": {
        "description": "A natural language query expressing the search request",
        "type": "string"
      }
    },
    "required": [
      "nlQuery"
    ]
  },
  "tags": [
    "search",
    "finance"
  ],
  "type": "index_search"
}
```