> ## Documentation Index > Fetch the complete documentation index at: https://guide.omnia-voice.com/llms.txt > Use this file to discover all available pages before exploring further. # Create a tool > Define a tool the agent can invoke. Creating it does not attach it to anything — use `POST /agents/{id}/tools` for that, so one tool can serve many agents. ## OpenAPI ````yaml /openapi.yaml post /agent-tools openapi: 3.0.0 info: title: Omnia Voice API description: > The Omnia Voice API allows you to programmatically manage voice agents, tools, phone numbers, and call logs. ## Authentication All API requests require an API key to be passed in the `X-API-Key` header. ## Rate Limiting API requests are rate limited to 1000 requests per hour per API key. version: 1.0.0 contact: email: support@omnia-voice.com servers: - url: https://api.omnia-voice.com/api/v1 description: Production - url: https://dashboard.omnia-voice.com/api/v1 description: Production (alias — same service) security: - ApiKeyAuth: [] tags: - name: Agents description: Manage voice agents - name: Tools description: Manage agent tools and actions - name: Phone Numbers description: Manage phone number assignments - name: Calls description: Create and manage voice calls - name: Call Logs description: View call history and details - name: Pricing description: Get pricing information and calculate call costs - name: Configuration description: Get configuration options (voices, languages) paths: /agent-tools: post: tags: - Tools summary: Create a tool description: | Define a tool the agent can invoke. Creating it does not attach it to anything — use `POST /agents/{id}/tools` for that, so one tool can serve many agents. operationId: createTool requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateToolRequest' responses: '201': description: Tool created content: application/json: schema: $ref: '#/components/schemas/Tool' '400': description: | Validation failed. Common causes: `modelToolName` not matching `^[a-zA-Z][a-zA-Z0-9_]*$`; a `baseUrlPattern` pointing at an internal address; a parameter name appearing in more than one of the dynamic/automatic/static maps; or an `authTokens` key that is not declared in `httpSecurityOptions`. '409': description: A tool with that `modelToolName` already exists. components: schemas: CreateToolRequest: type: object description: | `type` discriminates the shape. HTTP tools additionally require `httpMethod` and `baseUrlPattern`; client tools take neither. required: - type - name - modelToolName properties: type: type: string enum: - http - client name: type: string minLength: 1 maxLength: 100 description: type: string description: | What the model reads to decide whether to call this tool. The most important field on the object — most "my tool never fires" problems are description problems. modelToolName: type: string pattern: ^[a-zA-Z][a-zA-Z0-9_]*$ description: | Must start with a letter and contain only letters, numbers, and underscores. httpMethod: type: string enum: - GET - POST - PUT - PATCH - DELETE description: Required for `http` tools. baseUrlPattern: type: string format: uri description: | Required for `http` tools. **Internal addresses are rejected** — RFC 1918 ranges, loopback, IPv6 ULA, link-local including the cloud metadata endpoint at 169.254.169.254, and known private DNS names. dynamicParameters: type: object additionalProperties: $ref: '#/components/schemas/DynamicParameter' automaticParameters: type: object additionalProperties: $ref: '#/components/schemas/AutomaticParameter' staticParameters: type: object additionalProperties: $ref: '#/components/schemas/StaticParameter' agentReaction: $ref: '#/components/schemas/AgentReaction' timeout: $ref: '#/components/schemas/ToolTimeout' readOnly: type: boolean default: false httpSecurityOptions: $ref: '#/components/schemas/HttpSecurityOptions' authTokens: type: object additionalProperties: type: string description: | Plaintext credential values keyed by credential name, encrypted before storage and never returned. **Every key must be declared** in `httpSecurityOptions.options[].requirements`, or the request is rejected. This catches typos like `stcokApiKey` that would otherwise persist silently and 401 against your endpoint at call time with nothing useful in the logs. The reverse is not required: you may declare two credentials as alternatives and supply only one. Tool: type: object description: A tool the agent can invoke during a call. properties: id: type: string name: type: string description: type: string nullable: true modelToolName: type: string description: The function name the model sees. type: type: string enum: - http - client httpMethod: type: string enum: - GET - POST - PUT - PATCH - DELETE description: HTTP tools only. baseUrlPattern: type: string description: HTTP tools only. dynamicParameters: type: object additionalProperties: $ref: '#/components/schemas/DynamicParameter' automaticParameters: type: object additionalProperties: $ref: '#/components/schemas/AutomaticParameter' staticParameters: type: object additionalProperties: $ref: '#/components/schemas/StaticParameter' agentReaction: type: string allOf: - $ref: '#/components/schemas/AgentReaction' nullable: true httpSecurityOptions: type: object allOf: - $ref: '#/components/schemas/HttpSecurityOptions' nullable: true setCredentials: type: object additionalProperties: type: boolean description: | Which credential slots hold a stored value. **Credential values are never returned by this API** — this map exists so a UI can render `••••••••` for a set slot and an empty field for an unset one. timeout: type: string allOf: - $ref: '#/components/schemas/ToolTimeout' nullable: true readOnly: type: boolean default: false description: | Attests the tool is side-effect free, letting the runtime run it **eagerly** while the agent is still speaking and discard the result if the conversation turns elsewhere. Set it only on lookups — never on a booking or a payment. agentCount: type: integer description: How many agents this tool is attached to. createdAt: type: string format: date-time updatedAt: type: string format: date-time DynamicParameter: type: object description: The model fills this in from the conversation. required: - schema properties: location: $ref: '#/components/schemas/ParameterLocation' required: type: boolean schema: type: object required: - type properties: type: type: string enum: - string - number - boolean - object - array description: type: string description: | Written for the model, not for a developer. "The customer's order number, usually eight digits" beats "order identifier". enum: type: array items: type: string required: type: boolean AutomaticParameter: type: object description: Injected by the platform at call time. required: - knownValue properties: location: $ref: '#/components/schemas/ParameterLocation' knownValue: type: string description: e.g. `KNOWN_PARAM_CALL_ID` to receive the live call's ID. StaticParameter: type: object description: | Sent on every invocation and **never exposed to the model**. Use for tenant IDs, API versions, feature flags — things your endpoint needs but the agent has no business knowing or inventing. required: - value properties: location: $ref: '#/components/schemas/ParameterLocation' value: description: Any JSON value. AgentReaction: type: string enum: - speaks - listens - speaks-once description: | What the agent does when the tool returns. `speaks` narrates the result (default). `listens` stays silent and waits — right for tools that hand off, like a transfer. `speaks-once` speaks only if it did not already speak just before invoking, which prevents "Checking that for you… here is the result…" double-talk. ToolTimeout: type: string pattern: ^\d+(\.\d+)?s$ description: | Seconds with an `s` suffix, e.g. `"2.5s"` or `"10s"`. Must be greater than 0 and at most **40s**. Defaults to 2.5s when unset. example: 5s HttpSecurityOptions: type: object description: | Declares which credentials the tool needs and how each is sent. The secret values themselves live in `authTokens`. `options` is a list of **acceptable alternatives** — satisfying any one entry is enough, which is how you offer "either an API key or a bearer token". required: - options properties: options: type: array minItems: 1 items: type: object required: - requirements properties: requirements: type: object additionalProperties: $ref: '#/components/schemas/CredentialRequirement' description: Credential name → how it is sent. ParameterLocation: type: string description: | Where the value goes in the HTTP request. Both the short and the canonical long form are accepted on input; the long form is what is sent to the runtime. enum: - header - query - path - body - PARAMETER_LOCATION_HEADER - PARAMETER_LOCATION_QUERY - PARAMETER_LOCATION_PATH - PARAMETER_LOCATION_BODY CredentialRequirement: type: object description: | How one credential is transmitted. Declare **exactly one** of the three. properties: queryApiKey: type: object description: Sent as a query-string parameter. properties: name: type: string headerApiKey: type: object description: Sent as a request header. properties: name: type: string httpAuth: type: object description: Sent via the Authorization header with a scheme. properties: scheme: type: string example: Bearer securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-API-Key description: API key for authentication ````