# List available tools

**Documentation:** /reference/api-reference/tools/getTools

Retrieve a paginated list of available tools with comprehensive filtering, sorting and search capabilities. Use query parameters to narrow down results by toolkit, tags, or search terms.

---

## GET `/api/v3/tools`

**Endpoint:** `https://backend.composio.dev/api/v3/tools`

**Summary:** List available tools

Retrieve a paginated list of available tools with comprehensive filtering, sorting and search capabilities. Use query parameters to narrow down results by toolkit, tags, or search terms.

### Authentication

**ApiKeyAuth** - API Key in `header` header `x-api-key` OR **UserApiKeyAuth** - API Key in `header` header `x-user-api-key`

### Query Parameters

- `toolkit_slug` (string): The slug of the toolkit to filter by
- `tool_slugs` (string): Comma-separated list of specific tool slugs to retrieve (overrides other filters)
- `auth_config_ids` (any): Comma-separated list of auth config IDs to filter tools by
- `important` (enum: "true" | "false"): Filter to only show important/featured tools (set to "true" to enable)
- `tags` (array<string>): Filter tools by one or more tags (can be specified multiple times)
- `scopes` (array,null): Array of scopes to filter tools by)
- `query` (string): Full-text search query to filter tools by name, slug, or description. Applied as a soft filter on top of other filters.
- `search` (string): Deprecated: use "query" instead. Free-text search query to find tools by name, description, or functionality.
- `include_deprecated` (boolean): Include deprecated tools in the response
- `toolkit_versions` (any): Toolkit version specification. Use "latest" for latest versions or bracket notation for specific versions per toolkit.
- `limit` (number,null): Number of items per page, max allowed is 1000
- `cursor` (string): Cursor for pagination. The cursor is a base64 encoded string of the page and limit. The page is the page number and the limit is the number of items per page. The cursor is used to paginate through the items. The cursor is not required for the first page.

### Responses

#### 200 - Successfully retrieved tools list with pagination information

**Response Schema:**

- `items` (array<object>) *(required)*
  - Array items:
    - `slug` (string) *(required)*: Unique identifier for the tool
    - `name` (string) *(required)*: Human-readable display name of the tool
    - `description` (string) *(required)*: Detailed explanation of the tool's functionality and purpose
    - `toolkit` (object) *(required)*
      - `slug` (string) *(required)*: Unique identifier of the parent toolkit
      - `name` (string) *(required)*: Human-readable name of the parent toolkit
      - `logo` (string) *(required)*: URL to the toolkit logo image
    - `input_parameters` (object) *(required)*: Schema definition of required input parameters for the tool
      - `[key: string]` (any)
    - `no_auth` (boolean) *(required)*: Indicates if the tool can be used without authentication
    - `available_versions` (array<string>) *(required)*: List of all available versions for this tool
    - `version` (string) *(required)*: Current version of the tool
    - `output_parameters` (object) *(required)*: Schema definition of return values from the tool
      - `[key: string]` (any)
    - `scopes` (array<string>) *(required)*: List of scopes associated with the tool
    - `tags` (array<string>) *(required)*: List of tags associated with the tool for categorization and filtering
    - `human_description` (string): Human-friendly description of the tool, if available
    - `is_deprecated` (boolean) *(required)*: Indicates if this tool is deprecated and may be removed in the future
    - `deprecated` (object) *(required)*
      - `displayName` (string) *(required)*: The display name of the tool
      - `version` (string) *(required)*: Current version identifier of the tool
      - `available_versions` (array<string>) *(required)*: List of all available versions for this tool
      - `is_deprecated` (boolean) *(required)*: Indicates if this tool is deprecated and may be removed in the future
      - `toolkit` (object) *(required)*
        - `logo` (string) *(required)*: URL to the toolkit logo image
- `next_cursor` (string,null)
- `total_pages` (number) *(required)*
- `current_page` (number) *(required)*
- `total_items` (number) *(required)*

**Example Response:**

```json
{
  "items": [
    {
      "slug": "string",
      "name": "string",
      "description": "string",
      "toolkit": {
        "slug": "...",
        "name": "...",
        "logo": "..."
      },
      "input_parameters": {
        "key": "..."
      },
      "no_auth": true,
      "available_versions": [
        "..."
      ],
      "version": "string",
      "output_parameters": {
        "key": "..."
      },
      "scopes": [
        "..."
      ],
      "tags": [
        "..."
      ],
      "human_description": "string",
      "is_deprecated": true,
      "deprecated": {
        "displayName": "...",
        "version": "...",
        "available_versions": "...",
        "is_deprecated": "...",
        "toolkit": "..."
      }
    }
  ],
  "next_cursor": null,
  "total_pages": 1,
  "current_page": 1,
  "total_items": 1
}
```

#### 400 - Bad request - Invalid query parameters

**Response Schema:**

- `error` (object) *(required)*
  - `message` (string) *(required)*
  - `code` (number) *(required)*
  - `slug` (string) *(required)*
  - `status` (number) *(required)*
  - `request_id` (string)
  - `suggested_fix` (string)
  - `errors` (array<string>)

#### 401 - Unauthorized - Authentication credentials are missing or invalid

**Response Schema:**

- `error` (object) *(required)*
  - `message` (string) *(required)*
  - `code` (number) *(required)*
  - `slug` (string) *(required)*
  - `status` (number) *(required)*
  - `request_id` (string)
  - `suggested_fix` (string)
  - `errors` (array<string>)

#### 403 - Forbidden - User does not have permission to access tools

**Response Schema:**

- `error` (object) *(required)*
  - `message` (string) *(required)*
  - `code` (number) *(required)*
  - `slug` (string) *(required)*
  - `status` (number) *(required)*
  - `request_id` (string)
  - `suggested_fix` (string)
  - `errors` (array<string>)

#### 404 - Not found - The requested resource was not found

**Response Schema:**

- `error` (object) *(required)*
  - `message` (string) *(required)*
  - `code` (number) *(required)*
  - `slug` (string) *(required)*
  - `status` (number) *(required)*
  - `request_id` (string)
  - `suggested_fix` (string)
  - `errors` (array<string>)

#### 429 - Too many requests - Rate limit exceeded

**Response Schema:**

- `error` (object) *(required)*
  - `message` (string) *(required)*
  - `code` (number) *(required)*
  - `slug` (string) *(required)*
  - `status` (number) *(required)*
  - `request_id` (string)
  - `suggested_fix` (string)
  - `errors` (array<string>)

#### 500 - Internal server error - Something went wrong on the server

**Response Schema:**

- `error` (object) *(required)*
  - `message` (string) *(required)*
  - `code` (number) *(required)*
  - `slug` (string) *(required)*
  - `status` (number) *(required)*
  - `request_id` (string)
  - `suggested_fix` (string)
  - `errors` (array<string>)

### Example cURL Request

```bash
curl -X GET "https://backend.composio.dev/api/v3/tools" \
  -H "x-api-key: YOUR_API_KEY"
```