> ## Documentation Index > Fetch the complete documentation index at: https://docs.tryopencomputer.com/llms.txt > Use this file to discover all available pages before exploring further. # Update Tool > Update the tool's supported metadata or definition. Test the resulting downstream request against a service you control before using it in an agent. ## OpenAPI ````yaml /api-reference/openapi.json put /api/v1/tools/{tool_uuid} openapi: 3.1.0 info: title: Athena API version: 1.0.0 description: >- Hosted Athena customer API. Authenticate backend management and call-trigger requests with X-API-Key. Website embeds and artifact playback use their own scoped tokens. Provider availability, feature settings, and verification limits are described in the guides. servers: - url: https://athena.tryopencomputer.com description: Hosted Athena API security: [] paths: /api/v1/tools/{tool_uuid}: put: tags: - Tools summary: Update Tool description: >- Update the tool's supported metadata or definition. Test the resulting downstream request against a service you control before using it in an agent. operationId: update_tool_api_v1_tools__tool_uuid__put parameters: - name: tool_uuid in: path required: true schema: type: string title: Tool Uuid - name: authorization in: header required: false schema: anyOf: - type: string - type: 'null' title: Authorization - name: X-API-Key in: header required: false schema: anyOf: - type: string - type: 'null' title: X-Api-Key requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateToolRequest' responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/ToolResponse' '400': description: Bad Request '401': description: Authentication is missing or invalid. '404': description: Not found '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' security: - ApiKeyAuth: [] - BearerAuth: [] components: schemas: UpdateToolRequest: properties: name: anyOf: - type: string maxLength: 255 - type: 'null' title: Name description: anyOf: - type: string - type: 'null' title: Description icon: anyOf: - type: string maxLength: 50 - type: 'null' title: Icon icon_color: anyOf: - type: string maxLength: 7 - type: 'null' title: Icon Color definition: anyOf: - oneOf: - $ref: '#/components/schemas/HttpApiToolDefinition' - $ref: '#/components/schemas/EndCallToolDefinition' - $ref: '#/components/schemas/TransferCallToolDefinition' - $ref: '#/components/schemas/TransferAgentToolDefinition' - $ref: '#/components/schemas/CalculatorToolDefinition' - $ref: '#/components/schemas/NativeToolDefinition' - $ref: '#/components/schemas/McpToolDefinition' discriminator: propertyName: type mapping: calculator: '#/components/schemas/CalculatorToolDefinition' end_call: '#/components/schemas/EndCallToolDefinition' http_api: '#/components/schemas/HttpApiToolDefinition' mcp: '#/components/schemas/McpToolDefinition' native: '#/components/schemas/NativeToolDefinition' transfer_agent: '#/components/schemas/TransferAgentToolDefinition' transfer_call: '#/components/schemas/TransferCallToolDefinition' - type: 'null' title: Definition status: anyOf: - type: string - type: 'null' title: Status type: object title: UpdateToolRequest description: Request schema for updating a reusable tool. ToolResponse: properties: id: type: integer title: Id tool_uuid: type: string title: Tool Uuid name: type: string title: Name description: anyOf: - type: string - type: 'null' title: Description category: type: string title: Category icon: anyOf: - type: string - type: 'null' title: Icon icon_color: anyOf: - type: string - type: 'null' title: Icon Color status: type: string title: Status definition: additionalProperties: true type: object title: Definition created_at: type: string format: date-time title: Created At updated_at: anyOf: - type: string format: date-time - type: 'null' title: Updated At created_by: anyOf: - $ref: '#/components/schemas/CreatedByResponse' - type: 'null' type: object required: - id - tool_uuid - name - description - category - icon - icon_color - status - definition - created_at - updated_at title: ToolResponse description: Response schema for a reusable tool. HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError HttpApiToolDefinition: properties: schema_version: type: integer title: Schema Version description: Schema version. default: 1 messages: items: anyOf: - $ref: '#/components/schemas/ToolStartTextMessage' - $ref: '#/components/schemas/ToolStartAudioMessage' - $ref: '#/components/schemas/ToolDelayedTextMessage' - $ref: '#/components/schemas/ToolDelayedAudioMessage' type: array maxItems: 220 title: Messages description: >- Configured speech. An empty list disables announcements. HTTP/MCP choose one start entry and one entry per delayed timing at random. End-call and transfer tools support one start entry only. type: type: string const: http_api title: Type description: Tool type. config: $ref: '#/components/schemas/HttpApiConfig' description: HTTP API configuration. type: object required: - type - config title: HttpApiToolDefinition description: Tool definition for HTTP API tools. EndCallToolDefinition: properties: schema_version: type: integer title: Schema Version description: Schema version. default: 1 messages: items: anyOf: - $ref: '#/components/schemas/ToolStartTextMessage' - $ref: '#/components/schemas/ToolStartAudioMessage' - $ref: '#/components/schemas/ToolDelayedTextMessage' - $ref: '#/components/schemas/ToolDelayedAudioMessage' type: array maxItems: 220 title: Messages description: >- Configured speech. An empty list disables announcements. HTTP/MCP choose one start entry and one entry per delayed timing at random. End-call and transfer tools support one start entry only. type: type: string const: end_call title: Type description: Tool type. config: $ref: '#/components/schemas/EndCallConfig' description: End Call configuration. type: object required: - type - config title: EndCallToolDefinition description: Tool definition for End Call tools. TransferCallToolDefinition: properties: schema_version: type: integer title: Schema Version description: Schema version. default: 1 messages: items: anyOf: - $ref: '#/components/schemas/ToolStartTextMessage' - $ref: '#/components/schemas/ToolStartAudioMessage' - $ref: '#/components/schemas/ToolDelayedTextMessage' - $ref: '#/components/schemas/ToolDelayedAudioMessage' type: array maxItems: 220 title: Messages description: >- Configured speech. An empty list disables announcements. HTTP/MCP choose one start entry and one entry per delayed timing at random. End-call and transfer tools support one start entry only. type: type: string const: transfer_call title: Type description: Tool type. config: $ref: '#/components/schemas/TransferCallConfig' description: Transfer Call configuration. type: object required: - type - config title: TransferCallToolDefinition description: Tool definition for Transfer Call tools. TransferAgentToolDefinition: properties: schema_version: type: integer title: Schema Version description: Schema version. default: 1 messages: items: anyOf: - $ref: '#/components/schemas/ToolStartTextMessage' - $ref: '#/components/schemas/ToolStartAudioMessage' - $ref: '#/components/schemas/ToolDelayedTextMessage' - $ref: '#/components/schemas/ToolDelayedAudioMessage' type: array maxItems: 220 title: Messages description: >- One start text message, with template variables supported. Omit to use the default handover line, or send an empty list for a silent handoff. type: type: string const: transfer_agent title: Type description: Tool type. config: $ref: '#/components/schemas/TransferAgentConfig' description: Transfer Agent configuration. type: object required: - type - config title: TransferAgentToolDefinition description: Tool definition for Transfer Agent tools. CalculatorToolDefinition: properties: schema_version: type: integer title: Schema Version description: Schema version. default: 1 messages: items: anyOf: - $ref: '#/components/schemas/ToolStartTextMessage' - $ref: '#/components/schemas/ToolStartAudioMessage' - $ref: '#/components/schemas/ToolDelayedTextMessage' - $ref: '#/components/schemas/ToolDelayedAudioMessage' type: array maxItems: 220 title: Messages description: >- Configured speech. An empty list disables announcements. HTTP/MCP choose one start entry and one entry per delayed timing at random. End-call and transfer tools support one start entry only. type: type: string const: calculator title: Type description: Tool type. type: object required: - type title: CalculatorToolDefinition description: Tool definition for Calculator tools. NativeToolDefinition: properties: schema_version: type: integer title: Schema Version description: Schema version. default: 1 type: type: string const: native title: Type description: Tool type. config: $ref: '#/components/schemas/NativeToolConfig' description: Native tool configuration. type: object required: - type - config title: NativeToolDefinition description: Tool definition for built-in phone-line tools. McpToolDefinition: properties: schema_version: type: integer title: Schema Version description: Schema version. default: 1 messages: items: anyOf: - $ref: '#/components/schemas/ToolStartTextMessage' - $ref: '#/components/schemas/ToolStartAudioMessage' - $ref: '#/components/schemas/ToolDelayedTextMessage' - $ref: '#/components/schemas/ToolDelayedAudioMessage' type: array maxItems: 220 title: Messages description: >- Configured speech. An empty list disables announcements. HTTP/MCP choose one start entry and one entry per delayed timing at random. End-call and transfer tools support one start entry only. type: type: string const: mcp title: Type description: Tool type. config: $ref: '#/components/schemas/McpToolConfig' description: MCP server configuration. type: object required: - type - config title: McpToolDefinition description: Persisted MCP tool definition. CreatedByResponse: properties: id: type: integer title: Id provider_id: type: string title: Provider Id type: object required: - id - provider_id title: CreatedByResponse description: Response schema for the user who created a tool. ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type input: title: Input ctx: type: object title: Context type: object required: - loc - msg - type title: ValidationError ToolStartTextMessage: properties: type: type: string const: text title: Type text: type: string minLength: 1 title: Text event: type: string const: start title: Event additionalProperties: false type: object required: - type - text - event title: ToolStartTextMessage ToolStartAudioMessage: properties: type: type: string const: audio title: Type recording_id: type: integer exclusiveMinimum: 0 title: Recording Id event: type: string const: start title: Event additionalProperties: false type: object required: - type - recording_id - event title: ToolStartAudioMessage ToolDelayedTextMessage: properties: type: type: string const: text title: Type text: type: string minLength: 1 title: Text event: type: string const: delayed title: Event after_ms: type: integer maximum: 120000 exclusiveMinimum: 0 title: After Ms additionalProperties: false type: object required: - type - text - event - after_ms title: ToolDelayedTextMessage ToolDelayedAudioMessage: properties: type: type: string const: audio title: Type recording_id: type: integer exclusiveMinimum: 0 title: Recording Id event: type: string const: delayed title: Event after_ms: type: integer maximum: 120000 exclusiveMinimum: 0 title: After Ms additionalProperties: false type: object required: - type - recording_id - event - after_ms title: ToolDelayedAudioMessage HttpApiConfig: properties: method: type: string enum: - GET - POST - PUT - PATCH - DELETE title: Method description: HTTP method to use for the request. llm_hint: Use one of GET, POST, PUT, PATCH, DELETE. url: type: string title: Url description: Target HTTP or HTTPS URL. llm_hint: >- Use the final endpoint URL. Authentication belongs in credential_uuid, not embedded in the URL. headers: anyOf: - additionalProperties: type: string type: object - type: 'null' title: Headers description: Static headers to include with every request. llm_hint: >- Do not place secrets here. Store secrets in the UI credential manager and reference them with credential_uuid. credential_uuid: anyOf: - type: string - type: 'null' title: Credential Uuid description: Reference to an external credential for request authentication. llm_hint: >- Use a credential_uuid returned by list_credentials. The MCP flow does not create credential secrets. parameters: anyOf: - items: $ref: '#/components/schemas/ToolParameter' type: array - type: 'null' title: Parameters description: Parameters the model must provide when calling this tool. preset_parameters: anyOf: - items: $ref: '#/components/schemas/PresetToolParameter' type: array - type: 'null' title: Preset Parameters description: >- Parameters injected by Athena from fixed values or workflow context templates. timeout_ms: anyOf: - type: integer minimum: 1 - type: 'null' title: Timeout Ms description: Request timeout in milliseconds. default: 5000 require_approval: anyOf: - type: string enum: - always - never - type: 'null' title: Require Approval description: >- Ask the caller to confirm the exact action before this tool runs: 'always' or 'never'. Unset means 'never' (runs as soon as the agent picks it). llm_hint: >- Use 'always' for actions that change or delete something (cancel, pay, send, delete). body_template: anyOf: - additionalProperties: true type: object - type: 'null' title: Body Template description: Optional JSON body template for POST, PUT, and PATCH requests. llm_hint: >- Use {{parameter_name}} placeholders to position LLM and preset parameters anywhere in the body, including nested objects and arrays; also {{initial_context.*}}. A value that is exactly one placeholder keeps the value's original JSON type. Omit this field to send all parameters as a flat top-level JSON object. Ignored for GET and DELETE. body_format: type: string enum: - json - form title: Body Format description: >- Encoding of the POST, PUT, and PATCH request body: 'json' sends application/json, 'form' sends application/x-www-form-urlencoded. default: json llm_hint: >- Use 'form' only for APIs that accept form-encoded bodies and reject JSON. In form mode, list values repeat the field name once per item and object values are sent as JSON strings. additionalProperties: false type: object required: - method - url title: HttpApiConfig description: Configuration for HTTP API tools. EndCallConfig: properties: endCallReason: type: boolean title: Endcallreason description: >- When enabled, the model must provide a reason for ending the call. The reason is set as call disposition and added to call tags. default: false endCallReasonDescription: anyOf: - type: string - type: 'null' title: Endcallreasondescription description: >- Description shown to the model for the reason parameter. Used only when endCallReason is enabled. additionalProperties: false type: object title: EndCallConfig description: Configuration for End Call tools. TransferCallConfig: properties: introduction_enabled: type: boolean title: Introduction Enabled description: >- Play a generated introduction in the agent's voice to both parties before connecting them. Supported for Twilio calls with a TTS provider. Realtime speech-to-speech agents and synthesis failures skip the introduction. default: false introduction_prompt: type: string maxLength: 2000 title: Introduction Prompt description: Instructions for the transfer introduction, including language. default: >- Briefly introduce this caller to the person receiving the transfer. Include their reason for calling, essential details, and any explicit language preference. Use the caller's preferred language. Keep it to one sentence, at most 25 words. Do not invent details. destination_source: type: string enum: - static - dynamic - context_mapping title: Destination Source description: >- Whether the destination is static/template, resolved by HTTP, or selected by ordered gathered/initial-context mapping rules. default: static destination: type: string title: Destination description: >- Phone number, SIP endpoint, or template to transfer the call to, e.g. +1234567890, PJSIP/1234, or {{initial_context.transfer_destination}}. default: '' timeout: type: integer maximum: 120 minimum: 5 title: Timeout description: Maximum seconds to wait for the destination to answer. default: 30 call_disposition: anyOf: - type: string maxLength: 64 - type: 'null' title: Call Disposition description: >- Optional disposition to record after a successful transfer. When omitted, Athena records its provider-specific transfer default. parameters: anyOf: - items: $ref: '#/components/schemas/ToolParameter' type: array - type: 'null' title: Parameters description: >- Parameters the model may provide when calling this transfer tool, for example state, department, or transfer reason. resolver: anyOf: - $ref: '#/components/schemas/HttpTransferResolverConfig' - type: 'null' description: Optional resolver that determines transfer routing at call time. context_mapping: anyOf: - $ref: '#/components/schemas/ContextDestinationMappingConfig' - type: 'null' description: Optional ordered context-to-destination routing rules. additionalProperties: false type: object title: TransferCallConfig description: Configuration for Transfer Call tools. TransferAgentConfig: properties: workflow_id: type: integer title: Workflow Id description: >- Id of the Athena agent to transfer to. Must be in the same organization, and must not be a speech-to-speech agent. llm_hint: >- Name the tool after this agent, e.g. 'Transfer to Billing', and describe when to use it -- that is what the model routes on. play_greeting: type: boolean title: Play Greeting description: >- Whether the destination agent opens with its Start Call greeting. When false, it skips the greeting and opens with a reply generated from the handover note, continuing the conversation instead of introducing itself. default: true additionalProperties: false type: object required: - workflow_id title: TransferAgentConfig description: >- Configuration for Transfer Agent tools. One tool, one destination. An agent that can hand the caller to several places gets several of these tools, and the model chooses between them the way it chooses between any other tools -- by their names and descriptions. That keeps the routing decision in the one place the model already reasons about, and leaves nothing to configure here but where the call goes. Most of how a handoff sounds is fixed: the caller hears a ringer while the next agent is prepared. The handover line is configurable because it is caller-facing and Athena runs in more than one language, and so is whether the next agent opens with its greeting, because an agent that greets callers on its own number should not re-introduce itself mid-conversation. NativeToolConfig: properties: kind: type: string const: dtmf_send title: Kind description: >- dtmf_send: press phone keypad keys on the call, e.g. to navigate an automated phone menu. Phone calls only. max_digits: type: integer maximum: 32 minimum: 1 title: Max Digits description: Most keys one tool call may press. default: 16 type: object required: - kind title: NativeToolConfig description: Configuration for a built-in phone-line tool. McpToolConfig: properties: transport: type: string const: streamable_http title: Transport description: MCP transport protocol. default: streamable_http url: type: string title: Url description: MCP server URL. Must use http:// or https://. llm_hint: Use the server's streamable HTTP MCP endpoint. credential_uuid: anyOf: - type: string - type: 'null' title: Credential Uuid description: Reference to an external credential for MCP server auth. llm_hint: >- Use a credential_uuid returned by list_credentials. Credentials are created by the user in the UI. tools_filter: items: type: string type: array title: Tools Filter description: Allowlist of MCP tool names to expose. Empty exposes all tools. llm_hint: >- Use exact MCP tool names from the remote server catalog when you need to restrict the exposed tools. require_approval: anyOf: - type: string enum: - always - never - additionalProperties: type: string enum: - always - never type: object - type: 'null' title: Require Approval description: >- Ask the caller to confirm the exact action before a server tool runs: 'always', 'never', or a map {tool_name: 'always'|'never'}. Tools it does not name (or unset) ask only when the server marks them destructive (destructiveHint: true); otherwise they run as soon as the agent picks them. llm_hint: >- Use exact MCP tool names from the server catalog as keys, e.g. {"cancel_order": "always"}. timeout_secs: type: integer minimum: 0 title: Timeout Secs description: Connection timeout in seconds. default: 30 sse_read_timeout_secs: type: integer minimum: 0 title: Sse Read Timeout Secs description: SSE read timeout in seconds. default: 300 discovered_tools: items: additionalProperties: true type: object type: array title: Discovered Tools description: >- Server-managed cache of the MCP server's tool catalog [{name, description}]. Populated best-effort by the backend. llm_hint: Do not author this field; the server fills it. type: object required: - url title: McpToolConfig description: Configuration for a customer MCP server tool definition. ToolParameter: properties: name: type: string title: Name description: Parameter name used as a key in the tool request body. llm_hint: Use a stable snake_case name the agent can naturally fill. type: type: string enum: - string - number - boolean - object - array title: Type description: JSON type for the parameter value. llm_hint: Allowed values are string, number, boolean, object, and array. description: type: string title: Description description: Description shown to the model for this parameter. llm_hint: >- Write this as an instruction to the agent: what value to provide and when. required: type: boolean title: Required description: Whether this parameter is required when the tool is called. default: true type: object required: - name - type - description title: ToolParameter description: A parameter that the tool accepts from the model at call time. PresetToolParameter: properties: name: type: string title: Name description: Parameter name used as a key in the request body. type: type: string enum: - string - number - boolean - object - array title: Type description: JSON type for the resolved value. llm_hint: Allowed values are string, number, boolean, object, and array. value_template: type: string title: Value Template description: Fixed value or template, e.g. {{initial_context.phone_number}}. llm_hint: >- Use {{initial_context.*}} for call-start context and {{gathered_context.*}} for values extracted during the call. required: type: boolean title: Required description: Whether the parameter must resolve to a non-empty value. default: true type: object required: - name - type - value_template title: PresetToolParameter description: A parameter injected by Athena at runtime. HttpTransferResolverConfig: properties: type: type: string const: http title: Type description: Resolver type. default: http url: type: string title: Url description: HTTP or HTTPS endpoint for transfer resolution. headers: anyOf: - additionalProperties: type: string type: object - type: 'null' title: Headers description: Static headers to include with every resolver request. credential_uuid: anyOf: - type: string - type: 'null' title: Credential Uuid description: Reference to an external credential for resolver authentication. timeout_ms: type: integer maximum: 5000 minimum: 500 title: Timeout Ms description: Resolver request timeout in milliseconds. default: 3000 wait_message: anyOf: - type: string - type: 'null' title: Wait Message description: Optional short message played while Athena resolves routing. parameters: anyOf: - items: $ref: '#/components/schemas/ToolParameter' type: array - type: 'null' title: Parameters description: Parameters the model may provide when calling this transfer tool. preset_parameters: anyOf: - items: $ref: '#/components/schemas/PresetToolParameter' type: array - type: 'null' title: Preset Parameters description: >- Parameters injected by Athena from fixed values or workflow context templates. type: object required: - url title: HttpTransferResolverConfig description: HTTP endpoint used to resolve transfer destination at call time. ContextDestinationMappingConfig: properties: rules: anyOf: - items: $ref: '#/components/schemas/ContextDestinationRule' type: array - type: 'null' title: Rules description: Ordered routing rules evaluated top to bottom; first match wins. context_path: anyOf: - type: string - type: 'null' title: Context Path description: >- Deprecated single-rule context path. Use rules instead; accepted for backward compatibility. routes: anyOf: - items: $ref: '#/components/schemas/ContextDestinationRoute' type: array - type: 'null' title: Routes description: >- Deprecated single-rule routes. Use rules instead; accepted for backward compatibility. fallback_destination: anyOf: - type: string maxLength: 255 - type: 'null' title: Fallback Destination description: >- Optional provider-native destination or context template used when no rule matched. type: object title: ContextDestinationMappingConfig description: >- Resolve a transfer destination from gathered or initial context. Rules are evaluated in order. The first rule whose context value matches one of its routes wins; ``fallback_destination`` applies only when no rule matched. Destinations may be provider-native values or context templates. ContextDestinationRule: properties: context_path: type: string maxLength: 255 minLength: 1 title: Context Path description: >- Context path used for routing. An unprefixed path checks gathered context first, then initial context; use initial_context.* or gathered_context.* to select one explicitly. routes: items: $ref: '#/components/schemas/ContextDestinationRoute' type: array maxItems: 100 minItems: 1 title: Routes type: object required: - context_path - routes title: ContextDestinationRule description: One context lookup with its value-to-destination routes. ContextDestinationRoute: properties: context_value: type: string maxLength: 255 minLength: 1 title: Context Value description: Context value that selects this destination. destination: type: string maxLength: 255 minLength: 1 title: Destination description: >- VICIdial in-group, SIP endpoint, E.164 phone number, or context template used when this route matches. type: object required: - context_value - destination title: ContextDestinationRoute description: Map one context value to a transfer destination. securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-API-Key BearerAuth: type: http scheme: bearer ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.