> ## Documentation Index > Fetch the complete documentation index at: https://docs.support.onclarity.com/llms.txt > Use this file to discover all available pages before exploring further. # List tools > Returns the project's tools. Without `agent_id` the list holds both the project-wide tools and every agent's private tools. Pass `agent_id=null` for the project-wide tools only, or an agent id for that agent's private tools only. To see which tools an agent uses, list that agent's tools instead. ## OpenAPI ````yaml api-reference/voice-openapi.json GET /v1/projects/{projectId}/tools openapi: 3.0.3 info: title: Clarity Voice API version: '1.0' description: >- Voice agents and their tools, outbound calls, conversations, campaigns, telephony, and evals. servers: - url: https://voice-api.onclarity.com security: - organizationApiKey: [] tags: - name: Projects description: >- The projects your organization owns. Every other resource lives in a project. - name: Agents description: Create, configure, version and publish voice agents. - name: Outbound calls description: Have a published agent phone a number now. - name: Conversations description: >- One record per call session, with its calls, recordings, transcripts and artifacts. - name: Calls description: The calls of a project, with their status, direction, timing and outcome. - name: Campaigns description: Outbound calling campaigns that phone a list of numbers on a schedule. - name: Eval suites description: >- Reusable sets of eval scenarios and test cases to measure an agent against. - name: Eval judges description: The LLM judges that score eval calls against your test cases. - name: Eval scenarios description: The simulated-caller scenarios of your eval suites. - name: Eval test cases description: The checks a judge applies to each eval call. - name: Eval submissions description: Run an eval suite against an agent and read the verdicts. - name: Phone numbers description: >- The phone numbers of a project, where their calls come from, and how agents call out from them. - name: Inbound SIP trunks description: Bring calls from your own SIP infrastructure to Clarity agents. - name: Outbound SIP trunks description: >- The SIP endpoints Clarity dials through for outbound calls from your numbers. - name: Tools description: The tools agents call during a conversation, and which agents use them. paths: /v1/projects/{projectId}/tools: parameters: - $ref: '#/components/parameters/ProjectIdPath' get: tags: - Tools summary: List tools description: >- Returns the project's tools. Without `agent_id` the list holds both the project-wide tools and every agent's private tools. Pass `agent_id=null` for the project-wide tools only, or an agent id for that agent's private tools only. To see which tools an agent uses, list that agent's tools instead. operationId: listTools parameters: - name: agent_id in: query required: false schema: type: string description: >- The literal string `null` returns project-wide tools only. An agent id returns that agent's private tools only, not the project-wide tools it uses. Omitted or empty applies no filter. responses: '200': description: The tools. Each one carries `used_by_count`. content: application/json: schema: $ref: '#/components/schemas/ToolsListResponse' example: tools: - id: 6e2a4c8d-1b3f-4a5c-9d7e-0f1a2b3c4d5e project_id: 3f6c1a52-8d0e-4b8f-9a51-2c7d4e0b9f13 agent_id: null name: lookup_order description: Look up an order by its number and return its status. type: http configs: url: https://api.example.com/orders method: GET query_params: - name: number value: '{{order_number}}' authentication: type: bearer token: vault:orders_api_token parameters: type: object required: - order_number properties: order_number: type: string description: The order number the caller reads out. parameter_mapping: null hold_message: One moment while I check that order. hold_messages: null async_config: null session: null updated_at: 1794393600000 library_tool_id: null library_revision: null library_channels: null used_by_count: 2 '401': $ref: '#/components/responses/Unauthorized' '404': description: The project does not exist or your key cannot reach it. content: application/json: schema: $ref: '#/components/schemas/Error' components: parameters: ProjectIdPath: name: projectId in: path required: true schema: type: string description: Project id schemas: ToolsListResponse: type: object required: - tools properties: tools: type: array items: $ref: '#/components/schemas/Tool' Error: type: object required: - error additionalProperties: true properties: error: type: string description: Error message code: type: string description: >- A stable machine-readable reason, present on the refusals a client may branch on. Among them: `PUBLISH_CAPABILITY_REQUIRED` (403, the credential may not change what is live), `AGENT_NOT_PUBLISHED` (409, the agent has no published version yet), `AGENT_TYPE_NOT_DISPATCHABLE` (422, a Voice Assist agent named where an agent must place a call or answer one itself — a campaign, an outbound caller ID, a dispatched call, an eval; a number's inbound dispatch rule accepts one; the body carries `agent_type` and `agent_id`), `ASSIST_FLEET_NOT_CONFIGURED` (422 on a dispatch rule naming a Voice Assist agent in a project whose LiveKit has no Voice Assist listener), `NOT_APPLICABLE_TO_AGENT_TYPE` (422, a voice-only setting written on a Voice Assist agent), `AGENT_TYPE_BOUNDARY` (409), `AGENT_TYPE_NOT_SUPPORTED` (400), `INVALID_CUSTOMER_TIMEZONE` (400, `customer_timezone` is not a time zone name; the body carries the value), `VOICE_ASSISTANT_REQUIRED` (403, the organization is not licensed for Voice Assist), `ORGANIZATION_UNAVAILABLE` (503), `REGION_PROFILE_CONFLICT` (503), `LLM_SERVICE_TIER_UNAVAILABLE` (422, an agent's processing speed is not offered by its model or not enabled for the organization; `reason` says which) and `AUTH_UPSTREAM_UNAVAILABLE` (503 on any endpoint, with `Retry-After`: the credential could not be checked right now; it was not rejected and the request was not carried out). Tool: type: object description: >- A tool an agent can call during a conversation. Project-wide tools (`agent_id: null`) can be attached to any agent of the project; a private tool belongs to one agent. required: - id - project_id - agent_id - name - description - type - configs - parameters - parameter_mapping - hold_message - hold_messages - async_config - session - updated_at properties: id: type: string description: Tool id. project_id: type: string agent_id: type: string nullable: true description: The agent the tool is private to, or `null` for a project-wide tool. name: type: string description: The name the model calls the tool by. description: type: string description: What the tool does and when to use it, as the model reads it. type: type: string description: >- What the tool does, which decides the shape of `configs`: `http`, `knowledgebase`, `code`, `builtin`, `workflow`, `messaging`, `handoff` or `ticket`. configs: type: object additionalProperties: true description: >- The tool's configuration, in the shape of its `type` (see `configs` in Create a tool). It can also carry values Clarity fills in on save, such as a workflow's `url` or a knowledge base's search target. parameters: type: object additionalProperties: true description: >- JSON Schema of the arguments the model passes when it calls the tool. parameter_mapping: type: object nullable: true additionalProperties: type: string description: >- Renames arguments before the request is built, `{argument: request_field}`. `null` when none. hold_message: type: string nullable: true description: What the agent says while the tool runs, or `null` for nothing. hold_messages: type: object nullable: true additionalProperties: type: string description: >- The hold message per language of a multilingual agent, keyed by language label. async_config: type: object nullable: true additionalProperties: true description: >- Settings that let the conversation go on while the tool runs, in the shape of `async_config` in Create a tool. `null` means the agent waits for the result. session: $ref: '#/components/schemas/ToolSession' updated_at: type: integer format: int64 nullable: true description: >- When the tool was last changed, in milliseconds since the Unix epoch. `null` for a tool not changed since this field was added. library_tool_id: type: string nullable: true description: >- The organization tool library entry this tool comes from, or `null` for a tool that belongs to this project only. library_revision: type: integer nullable: true description: The library entry's revision this tool holds, or `null`. library_channels: type: array nullable: true items: type: string description: >- Which kinds of agents (`chat`, `voice`) can use the library entry, or `null`. used_by_count: type: integer description: >- How many agents of the project have the tool attached. A published agent keeps calling the tool it was published with until it is published again, whatever this count says. Present on reads and lists. used_by_agents: type: array description: >- The agents the tool is attached to. Returned when you get one tool, not in lists. items: type: object required: - id - name properties: id: type: string name: type: string ToolSession: type: object nullable: true additionalProperties: false description: >- The tool's part in the call-scoped caller authentication session. Null means the tool takes no part. A non-null `verification` makes it a verification tool and carries the verification policy; caller authentication is on for an agent exactly when an attached tool verifies the caller or requires a verified caller. On PATCH, an absent key keeps the stored value and an explicit null clears it. properties: requires_verified_caller: type: boolean description: >- The runtime refuses the tool until a verification tool verified the caller. stores: type: array maxItems: 20 items: type: object additionalProperties: false required: - from - as - visibility properties: from: type: string description: Dot path into the JSON response. as: type: string pattern: ^[a-z][a-z0-9_]{0,63}$ description: Session name, referenced as {{session.}}. visibility: type: string enum: - private - visible verification: type: object nullable: true additionalProperties: false properties: success: type: object additionalProperties: false properties: status_in: type: array items: type: integer minimum: 100 maximum: 599 field: type: string equals: oneOf: - type: string - type: number - type: boolean ttl_from: type: string max_attempts: type: integer minimum: 1 maximum: 10 description: >- Failed verifications allowed per call (default 3). With several verifiers on an agent, the smallest wins. on_exhausted: type: string enum: - end_call - transfer - continue description: >- What happens when the attempts run out (default end_call). Taken from the verifier with the smallest max_attempts. `transfer` needs a connect_to_human tool attached to the agent. unreachable_counts_as_failure: type: boolean description: >- Count a timeout / connection error / 5xx as a failed attempt (default false; true on any verifier wins). default_ttl_s: type: integer nullable: true minimum: 60 maximum: 86400 description: >- Session lifetime when the response gives none (null - until the call ends). The smallest non-null value wins. responses: Unauthorized: description: >- No credential was sent, or the API key is invalid or revoked. A key that could not be checked at all answers 503 `AUTH_UPSTREAM_UNAVAILABLE` instead (see Errors). content: application/json: schema: $ref: '#/components/schemas/Error' example: error: Invalid or revoked token securitySchemes: organizationApiKey: type: http scheme: bearer description: >- Your organization API key (it starts with `anek_org_`). The same key works on the Voice API and the Support API. See [Authentication](/authentication). ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.