> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cognigy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# List tools

> Returns a list of tools with optional filtering, pagination, and sorting.



## OpenAPI

````yaml https://api-trial.cognigy.ai/swagger/openapi.json get /tools
openapi: 3.0.3
info:
  contact:
    email: support@example.com
    name: API Support
  description: API for managing agents and related resources
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  termsOfService: http://swagger.io/terms/
  title: Agents API
  version: '1.0'
servers:
  - url: https://api-trial.cognigy.ai/v1
security:
  - ApiKey: []
tags:
  - name: Agents
  - name: Brand personas
  - name: Tools
  - name: Built-in tools
  - name: Skills
  - name: Built-in skills
  - name: MCP servers
  - name: Tool references
paths:
  /tools:
    get:
      tags:
        - Tools
      summary: List tools
      description: >-
        Returns a list of tools with optional filtering, pagination, and
        sorting.
      parameters:
        - description: The unique identifier for the project to filter by.
          in: query
          name: projectId
          schema:
            type: string
        - description: The string to filter by name. The filter is case-insensitive.
          in: query
          name: filter
          schema:
            type: string
        - description: >-
            The maximum number of items to return, from 1 to 100. The default is
            100.
          in: query
          name: limit
          schema:
            default: 100
            type: integer
        - description: >-
            The number of items to skip before starting to return results. The
            default is 0.
          in: query
          name: skip
          schema:
            default: 0
            type: integer
        - description: >-
            The sort order. Use `asc` or `desc` to sort by `_id`, or
            `<field>:<asc|desc>` to sort by one of `_id`, `name`,
            `lastChangedAt` or `createdAt`. The default is `asc`.
          in: query
          name: sort
          schema:
            default: asc
            type: string
        - description: >-
            The cursor for the next page of results. It is only valid with the
            default `_id` sort. To page through a sorted list, use `skip` and
            `limit`.
          in: query
          name: next
          schema:
            type: string
        - description: >-
            The cursor for the previous page of results. It is only valid with
            the default `_id` sort. To page through a sorted list, use `skip`
            and `limit`.
          in: query
          name: previous
          schema:
            type: string
        - description: >-
            The `referenceId` of an agent. Returns only the tools available to
            this agent, whether attached directly or bundled in a skill it has
            hired. Requires `projectId`. Disabled tools are included.
          in: query
          name: agentReferenceId
          schema:
            type: string
        - description: >-
            A comma-separated list of tool sources to filter by. The allowed
            values are `extension`, `managed`, `builtin` and `mcp`.
          in: query
          name: source
          schema:
            type: string
        - description: >-
            The `referenceId` of an MCP server. Filters MCP tools to that
            server.
          in: query
          name: mcpServerReferenceId
          schema:
            type: string
        - description: >-
            If set to `true`, the response also includes system-managed tools
            that are left out by default: hidden rows and
            `voice-config-defaults` instances, which are managed from Voice
            Studio. The default is `false`.
          in: query
          name: includeHidden
          schema:
            default: false
            type: boolean
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/internal_tools.ListToolsResponse'
          description: OK
        '400':
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/github_com_cognigy_ai-agents-v2_internal_middleware.ProblemDetailBadRequest
          description: Invalid query parameters
        '403':
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/github_com_cognigy_ai-agents-v2_internal_middleware.ProblemDetailForbidden
          description: Access denied
        '500':
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/github_com_cognigy_ai-agents-v2_internal_middleware.ProblemDetailInternalError
          description: Internal server error
components:
  schemas:
    internal_tools.ListToolsResponse:
      properties:
        items:
          items:
            $ref: '#/components/schemas/internal_tools.ToolItem'
          type: array
        nextCursor:
          example: 507f1f77bcf86cd799439011
          type: string
        previousCursor:
          example: 507f1f77bcf86cd799439017
          type: string
        total:
          example: 1
          type: integer
      type: object
    github_com_cognigy_ai-agents-v2_internal_middleware.ProblemDetailBadRequest:
      properties:
        detail:
          example: request body validation failed
          type: string
        errors:
          items:
            $ref: >-
              #/components/schemas/github_com_cognigy_ai-agents-v2_internal_middleware.FieldError
          type: array
        instance:
          example: /v1/{resource}
          type: string
        status:
          example: 400
          type: integer
        title:
          example: Bad Request
          type: string
        traceId:
          example: api--a4d2f126-bec4-4544-a049-7c0cf08524ed
          type: string
        type:
          example: about:blank
          type: string
      type: object
    github_com_cognigy_ai-agents-v2_internal_middleware.ProblemDetailForbidden:
      properties:
        detail:
          example: 'access denied: insufficient permissions'
          type: string
        instance:
          example: /v1/{resource}/{id}
          type: string
        status:
          example: 403
          type: integer
        title:
          example: Forbidden
          type: string
        traceId:
          example: api--a4d2f126-bec4-4544-a049-7c0cf08524ed
          type: string
        type:
          example: about:blank
          type: string
      type: object
    github_com_cognigy_ai-agents-v2_internal_middleware.ProblemDetailInternalError:
      properties:
        detail:
          example: internal server error
          type: string
        instance:
          example: /v1/{resource}
          type: string
        status:
          example: 500
          type: integer
        title:
          example: Internal Server Error
          type: string
        traceId:
          example: api--a4d2f126-bec4-4544-a049-7c0cf08524ed
          type: string
        type:
          example: about:blank
          type: string
      type: object
    internal_tools.ToolItem:
      properties:
        builtinSlug:
          example: my-tool-slug
          type: string
        bundledOnly:
          description: >-
            BundledOnly mirrors the catalog's bundledOnly flag for builtin
            tools:

            true means the catalog only allows this slug to be instantiated as

            part of a skill bundle, so CreateToolUseCase.execute rejects any

            direct POST /tools for it (including a frontend "Clone" action on

            this row). Tagged omitempty: the key is present only when true —

            omitted (not sent as `false`) for non-builtin sources and for

            builtin tools that aren't bundle-restricted.
          example: true
          type: boolean
        createdAt:
          example: 1694518620
          type: integer
        createdBy:
          example: ^[a-z0-9]{24}$
          type: string
        description:
          example: A tool that performs an action
          type: string
        extension:
          example: my-extension
          type: string
        id:
          example: ^[a-z0-9]{24}$
          type: string
        lastChangedAt:
          example: 1694518620
          type: integer
        lastChangedBy:
          example: ^[a-z0-9]{24}$
          type: string
        mcp:
          allOf:
            - $ref: '#/components/schemas/internal_tools.MCPBindingItem'
          description: MCP is present only for source "mcp". List shape — no inputSchema.
        name:
          example: My Tool
          type: string
        organisationId:
          example: ^[a-z0-9]{24}$
          type: string
        parameters:
          items:
            $ref: '#/components/schemas/internal_tools.ToolParameterResponse'
          type: array
        projectId:
          example: ^[a-z0-9]{24}$
          type: string
        referenceId:
          example: 550e8400-e29b-41d4-a716-446655440000
          type: string
        source:
          example: extension
          type: string
        type:
          example: action
          type: string
      type: object
    github_com_cognigy_ai-agents-v2_internal_middleware.FieldError:
      properties:
        field:
          type: string
        message:
          type: string
      type: object
    internal_tools.MCPBindingItem:
      properties:
        serverReferenceId:
          example: 550e8400-e29b-41d4-a716-446655440000
          type: string
        toolName:
          description: >-
            ToolName is the tool's name on the remote server. Always equal to
            the

            row's own `name`; given here because it is the join key from a list
            row to

            a discovery result.
          example: search_issues
          type: string
      type: object
    internal_tools.ToolParameterResponse:
      properties:
        connectionTypes:
          example:
            - http_basic
            - http_oauth2
          items:
            type: string
          type: array
        description:
          example: The input parameter
          type: string
        key:
          example: input
          type: string
        mode:
          example: dynamic
          type: string
        name:
          example: input
          type: string
        type:
          example: string
          type: string
        value: {}
      type: object
  securitySchemes:
    ApiKey:
      description: '[Production] API key for production authentication'
      in: header
      name: X-API-Key
      type: apiKey

````