> ## 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. # Push a tool to live agents > Puts the tool's current definition into the published version of every agent that uses it, so live calls get the change without republishing each agent. Drafts and older versions are not touched. An agent whose published version would no longer be valid with the change is skipped and listed in `skipped` with the reason. Needs the publish permission, which organization API keys carry. ## OpenAPI ````yaml api-reference/voice-openapi.json POST /v1/projects/{projectId}/tools/{id}/push 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/{id}/push: parameters: - $ref: '#/components/parameters/ProjectIdPath' - $ref: '#/components/parameters/ToolId' post: tags: - Tools summary: Push a tool to live agents description: >- Puts the tool's current definition into the published version of every agent that uses it, so live calls get the change without republishing each agent. Drafts and older versions are not touched. An agent whose published version would no longer be valid with the change is skipped and listed in `skipped` with the reason. Needs the publish permission, which organization API keys carry. operationId: pushTool responses: '200': description: The agents whose published version was updated, and those skipped. content: application/json: schema: type: object required: - agents - skipped properties: agents: type: array description: Agents whose live calls now use the pushed definition. items: type: object required: - id - name properties: id: type: string name: type: string skipped: type: array description: >- Agents that use the tool but kept their published copy, with why. items: type: object required: - id - name - reason properties: id: type: string name: type: string reason: type: string description: >- Why the change could not be applied to this agent's published version. example: agents: - id: 5c1d9e2f-3a4b-4c5d-9e6f-7a8b9c0d1e2f name: Front desk skipped: - id: 8f7e6d5c-4b3a-4c2d-9e1f-0a9b8c7d6e5f name: Order status line reason: >- Task 'check_order' references tool 'lookup_order_v1', which is not attached '401': $ref: '#/components/responses/Unauthorized' '403': description: >- Your credential lacks the publish permission (`code: PUBLISH_CAPABILITY_REQUIRED`). content: application/json: schema: $ref: '#/components/schemas/Error' example: error: publish_capability_required code: PUBLISH_CAPABILITY_REQUIRED '404': description: The project or the tool does not exist. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: Tool not found components: parameters: ProjectIdPath: name: projectId in: path required: true schema: type: string description: Project id ToolId: name: id in: path required: true schema: type: string description: Tool id 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 schemas: 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). 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.