> ## 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 what references a set of tools

> Returns, for each tool `referenceId`, the agents and skills in the project that hold it. This endpoint is read-only, and you can use it to warn before a delete, because deleting a tool detaches it from everything listed here. `projectId` is required, because the authorization middleware reads it to scope the request.



## OpenAPI

````yaml https://api-trial.cognigy.ai/swagger/openapi.json get /tool-references
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:
  /tool-references:
    get:
      tags:
        - Tool references
      summary: List what references a set of tools
      description: >-
        Returns, for each tool `referenceId`, the agents and skills in the
        project that hold it. This endpoint is read-only, and you can use it to
        warn before a delete, because deleting a tool detaches it from
        everything listed here. `projectId` is required, because the
        authorization middleware reads it to scope the request.
      parameters:
        - description: >-
            A comma-separated list of tool `referenceId` values, with at most
            100 distinct values. Repeated values collapse and don't count
            against the limit.
          in: query
          name: ids
          required: true
          schema:
            type: string
        - description: The unique identifier for the project.
          in: query
          name: projectId
          required: true
          schema:
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/internal_tools.ListToolReferencesResponse'
          description: OK
        '400':
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/github_com_cognigy_ai-agents-v2_internal_middleware.ProblemDetailBadRequest
          description: Missing or over-long ids
        '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.ListToolReferencesResponse:
      properties:
        items:
          items:
            $ref: '#/components/schemas/internal_tools.ToolReferenceEntry'
          type: array
        total:
          description: >-
            Total is the number of DISTINCT holders across every item — how many

            agents and skills a delete of all the requested tools would detach
            them

            from. It is deliberately none of the two things it could easily have
            been:

              - `len(Items)`, which is what it used to be. Every requested id gets an
                entry, so that number is identical to Items' own length and carries no
                information at all, while the `example:"2"` beside it suggested a
                holder count. Redundant and misleading at once.
              - the SUM of each item's holders, which double-counts: one agent holding
                three of the requested tools would make "delete 3 tools, detaching
                from 1 agent" report 3.

            Distinct is the number a delete confirmation wants, and it is
            correct for

            one requested tool and for many. Per-tool counts are already
            available as

            `items[i].holders.length`, so nothing is lost by not summing.
          example: 2
          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.ToolReferenceEntry:
      properties:
        holders:
          description: >-
            Holders is empty rather than null when nothing references the tool:
            a

            caller must be able to tell "no references" from "not asked about",
            and

            every requested id gets an entry.
          items:
            $ref: '#/components/schemas/internal_tools.ToolReferenceHolderResponse'
          type: array
        toolReferenceId:
          description: ToolReferenceId is the tool asked about.
          example: 550e8400-e29b-41d4-a716-446655440000
          type: string
      type: object
    github_com_cognigy_ai-agents-v2_internal_middleware.FieldError:
      properties:
        field:
          type: string
        message:
          type: string
      type: object
    internal_tools.ToolReferenceHolderResponse:
      properties:
        id:
          example: 507f1f77bcf86cd799439011
          type: string
        kind:
          description: Kind is "agent" or "skill".
          enum:
            - agent
            - skill
          example: agent
          type: string
        name:
          example: Support Bot
          type: string
        referenceId:
          description: ReferenceId is the holder's own referenceId, not the tool's.
          example: 550e8400-e29b-41d4-a716-446655440000
          type: string
      type: object
  securitySchemes:
    ApiKey:
      description: '[Production] API key for production authentication'
      in: header
      name: X-API-Key
      type: apiKey

````