> ## Documentation Index > Fetch the complete documentation index at: https://docs.cartesia.ai/llms.txt > Use this file to discover all available pages before exploring further. # Get Tool > Returns one shared tool. Expand `agents` to include agents that currently reference it. ## OpenAPI ````yaml latest.yml GET /v1/agents/tools/{tool_id} openapi: 3.0.1 info: title: Cartesia API version: 0.0.1 servers: - url: https://api.cartesia.ai description: Production security: [] paths: /v1/agents/tools/{tool_id}: get: tags: - Agent Tools summary: Get a tool description: >- Returns one shared tool. Expand `agents` to include agents that currently reference it. operationId: getV1AgentsToolsByTool_id parameters: - name: tool_id in: path description: Unique identifier for the tool. required: true schema: description: Unique identifier for the tool. type: string minLength: 1 - name: expand[] in: query schema: type: array items: type: string enum: - agents - $ref: '#/components/parameters/CartesiaVersionHeader' responses: '200': description: Get a tool content: application/json: schema: $ref: '#/components/schemas/ManagedToolV1' '404': description: Not found content: application/json: schema: $ref: '#/components/schemas/PublicErrorResponse' security: - APIKeyAuth: [] components: parameters: CartesiaVersionHeader: name: Cartesia-Version in: header description: API version header. required: true schema: type: string format: date example: '2026-08-14' default: '2026-08-14' enum: - '2026-08-14' schemas: ManagedToolV1: type: object discriminator: propertyName: type mapping: webhook: $ref: '#/components/schemas/ManagedWebhookToolV1' client: $ref: '#/components/schemas/ManagedClientToolV1' oneOf: - $ref: '#/components/schemas/ManagedWebhookToolV1' - $ref: '#/components/schemas/ManagedClientToolV1' title: ManagedTool PublicErrorResponse: type: object properties: doc_url: description: URL to relevant documentation for the error type: string nullable: true error_code: description: Machine-readable error code type: string nullable: true message: description: Detailed human-readable error message type: string request_id: description: >- Unique identifier for this request. Include this when contacting support. type: string title: description: Short human-readable error summary, like "File too large" type: string required: - request_id - message - title title: PublicErrorResponse ManagedWebhookToolV1: type: object properties: agents: description: >- Agents that currently use this tool. Included when `expand[]=agents` is requested. type: array items: $ref: '#/components/schemas/ManagedAgentSummaryV1' api_schema: $ref: '#/components/schemas/ManagedWebhookApiSchemaV1Response' created_at: description: >- An RFC 3339 / ISO 8601 date-time string with timezone (e.g. `2025-04-16T12:34:56.789Z`). type: string format: date-time description: description: What the tool does and when the agent should use it. type: string maxLength: 2000 minLength: 1 execution_mode: description: >- Controls how the tool runs relative to the conversation. `immediate` runs in the current turn and can be interrupted by the caller, while `async` lets the turn finish while the tool runs. type: string enum: - immediate - async id: description: Unique identifier for the tool. type: string minLength: 1 name: description: Name the agent uses to call the tool. Names are case-sensitive. type: string pattern: ^[a-zA-Z][a-zA-Z0-9_-]{0,63}$ pre_tool_speech: description: >- Controls whether the agent speaks before using the tool. `auto` lets the agent decide, while `force` asks the agent to speak first. type: string enum: - auto - force response_timeout_secs: description: >- Maximum time to wait for the endpoint to respond. Defaults to 20 seconds. type: integer default: 20 maximum: 120 minimum: 1 type: description: Runs an HTTP request from Cartesia's servers. type: string enum: - webhook updated_at: description: >- An RFC 3339 / ISO 8601 date-time string with timezone (e.g. `2025-04-16T12:34:56.789Z`). type: string format: date-time required: - name - description - pre_tool_speech - execution_mode - type - response_timeout_secs - api_schema - id - created_at - updated_at title: Webhook tool ManagedClientToolV1: type: object properties: agents: description: >- Agents that currently use this tool. Included when `expand[]=agents` is requested. type: array items: $ref: '#/components/schemas/ManagedAgentSummaryV1' created_at: description: >- An RFC 3339 / ISO 8601 date-time string with timezone (e.g. `2025-04-16T12:34:56.789Z`). type: string format: date-time description: description: What the tool does and when the agent should use it. type: string maxLength: 2000 minLength: 1 execution_mode: description: >- Controls how the tool runs relative to the conversation. `immediate` runs in the current turn and can be interrupted by the caller, while `async` lets the turn finish while the tool runs. type: string enum: - immediate - async expects_response: description: >- Whether the client application must return a result. When `false`, the tool call is dispatched without waiting for a result. type: boolean id: description: Unique identifier for the tool. type: string minLength: 1 name: description: Name the agent uses to call the tool. Names are case-sensitive. type: string pattern: ^[a-zA-Z][a-zA-Z0-9_-]{0,63}$ parameters: $ref: '#/components/schemas/ManagedClientToolParametersV1' description: Parameters the agent can pass to the client function. pre_tool_speech: description: >- Controls whether the agent speaks before using the tool. `auto` lets the agent decide, while `force` asks the agent to speak first. type: string enum: - auto - force response_timeout_secs: description: >- Maximum time to wait for the client application to return a result. Defaults to 20 seconds. Applies only when `expects_response` is `true`. type: integer default: 20 maximum: 120 minimum: 1 type: description: Runs a function in the connected client application. type: string enum: - client updated_at: description: >- An RFC 3339 / ISO 8601 date-time string with timezone (e.g. `2025-04-16T12:34:56.789Z`). type: string format: date-time required: - name - description - pre_tool_speech - execution_mode - type - response_timeout_secs - expects_response - parameters - id - created_at - updated_at title: Client tool ManagedAgentSummaryV1: type: object properties: created_at: description: >- An RFC 3339 / ISO 8601 date-time string with timezone (e.g. `2025-04-16T12:34:56.789Z`). type: string format: date-time description: description: Description of the agent. nullable: true type: string id: description: Unique identifier for the agent. type: string minLength: 1 name: description: Name shown for the agent. type: string updated_at: description: >- An RFC 3339 / ISO 8601 date-time string with timezone (e.g. `2025-04-16T12:34:56.789Z`). type: string format: date-time version_id: description: Unique identifier for an immutable agent configuration version. type: string minLength: 1 required: - id - name - description - created_at - updated_at - version_id title: ManagedAgentSummary ManagedWebhookApiSchemaV1Response: type: object properties: authentication: $ref: '#/components/schemas/WebhookAuthenticationResponse' method: description: The HTTP method. type: string enum: - GET - POST - PUT - PATCH - DELETE path_params_schema: description: Path parameters keyed by placeholder name. type: object additionalProperties: $ref: '#/components/schemas/WebhookPathParam' query_params_schema: $ref: '#/components/schemas/WebhookQuerySchema' request_body_schema: $ref: '#/components/schemas/WebhookBodyParam' description: >- The schema for the JSON request body. The root must be an `object`. Only `POST`, `PUT`, and `PATCH` requests can include a body. request_headers: description: Headers sent with every request. type: object additionalProperties: anyOf: - type: string description: A literal header value. Use the secret object for credentials. - $ref: '#/components/schemas/WebhookSecretResponse' description: >- A plain-text header value or a stored secret. The secret value is not returned. url: description: >- The HTTPS endpoint to call. Use `{name}` for path parameters defined in `path_params_schema`. type: string maxLength: 2048 minLength: 1 required: - url - method title: ManagedWebhookApiSchemaResponse ManagedClientToolParametersV1: type: object additionalProperties: false properties: properties: description: Parameters keyed by name. type: object additionalProperties: $ref: '#/components/schemas/ClientToolParam' required: description: >- Names of parameters the agent must provide. Other parameters are optional. type: array items: type: string minLength: 1 maxItems: 64 uniqueItems: true type: description: The parameters schema type. Always `object`. type: string enum: - object required: - type title: ManagedClientToolParameters WebhookAuthenticationResponse: description: Authentication sent in the `Authorization` header. type: object oneOf: - type: object properties: mode: type: string enum: - basic_auth password: $ref: '#/components/schemas/WebhookSecretResponse' username: description: The username. It cannot contain a colon. type: string maxLength: 512 minLength: 1 required: - mode - username - password description: Sends an `Authorization` header using HTTP Basic authentication. - type: object properties: mode: type: string enum: - bearer token: $ref: '#/components/schemas/WebhookSecretResponse' required: - mode - token description: Sends an `Authorization` header using a bearer token. title: WebhookAuthenticationResponse WebhookPathParam: description: A value inserted into a URL path placeholder. type: object properties: constant_value: description: >- A fixed value sent on every request. It must match the parameter's `type`. The agent does not see or set it. anyOf: - type: string - type: number - type: boolean description: description: What value the agent should provide. type: string maxLength: 1000 enum: description: Allowed values. type: array items: anyOf: - type: string maxLength: 1000 - type: number - type: boolean maxItems: 64 minItems: 1 type: type: string enum: - string - integer - number required: - type title: WebhookPathParam WebhookQuerySchema: description: Parameters sent in the request query string. type: object properties: properties: description: Query parameters keyed by name. type: object additionalProperties: $ref: '#/components/schemas/WebhookQueryParam' required: description: >- Parameter names the agent must provide. Other agent-provided parameters are optional; parameters with `constant_value` are always sent. type: array items: type: string minLength: 1 maxItems: 64 required: - properties title: WebhookQuerySchema WebhookBodyParam: description: A value sent in the JSON request body. type: object properties: constant_value: description: >- A fixed value sent on every request. It must match the parameter's `type`. The agent does not see or set it. anyOf: - type: string - type: number - type: boolean description: description: What value the agent should provide. type: string maxLength: 1000 enum: description: Allowed values. type: array items: anyOf: - type: string maxLength: 1000 - type: number - type: boolean maxItems: 64 minItems: 1 items: $ref: '#/components/schemas/WebhookBodyParam' description: The array item schema. Required when `type` is `array`. properties: description: Object properties keyed by name. type: object additionalProperties: $ref: '#/components/schemas/WebhookBodyParam' required: description: >- Property names the agent must provide. Other agent-provided properties are optional; properties with `constant_value` are always sent. type: array items: type: string minLength: 1 maxItems: 64 type: type: string enum: - string - integer - number - boolean - object - array required: - type title: WebhookBodyParam WebhookSecretResponse: description: A stored credential. `secret_value` is not returned. type: object properties: secret_description: description: >- A label for this credential. Do not include the secret itself because this field is stored as plain text. type: string maxLength: 200 minLength: 1 type: type: string enum: - secret required: - type title: WebhookSecretResponse ClientToolParam: description: One argument passed to your function. type: object properties: description: description: What value the agent should provide. type: string maxLength: 1000 enum: description: Allowed string values. type: array items: type: string maxLength: 1000 maxItems: 64 minItems: 1 uniqueItems: true items: description: The array item type. Required when `type` is `array`. type: object properties: type: type: string enum: - string - integer - number - boolean required: - type type: description: The parameter's JSON type. type: string enum: - string - integer - number - boolean - array required: - type title: ClientToolParam WebhookQueryParam: description: A value sent in the query string. type: object properties: constant_value: description: >- A fixed value sent on every request. It must match the parameter's `type`. The agent does not see or set it. anyOf: - type: string - type: number - type: boolean description: description: What value the agent should provide. type: string maxLength: 1000 enum: description: Allowed values. type: array items: anyOf: - type: string maxLength: 1000 - type: number - type: boolean maxItems: 64 minItems: 1 items: description: The array item type. Required when `type` is `array`. type: object properties: type: type: string enum: - string - integer - number - boolean required: - type type: type: string enum: - string - integer - number - boolean - array required: - type title: WebhookQueryParam securitySchemes: APIKeyAuth: type: http scheme: bearer bearerFormat: API Key description: >- Cartesia API key (`sk_car_...`). Get one at [play.cartesia.ai/keys](https://play.cartesia.ai/keys). x-default: $CARTESIA_API_KEY ````