> ## Documentation Index > Fetch the complete documentation index at: https://docs.iwy.ai/llms.txt > Use this file to discover all available pages before exploring further. # Create a new tool > Creates a new custom tool that agents can use. Tools are defined by their parameters schema (JSON Schema format) and the webhook endpoint they call. ## OpenAPI ````yaml post /tool openapi: 3.0.3 info: title: iwy API description: > API for managing AI agents and custom tools. Create conversational AI agents with custom capabilities, manage tool integrations, and embed AI avatars in your applications. ## Authentication All endpoints require authentication using a Bearer token (IWY_SERVICE_API_KEY). You can find your API key at [app.iwy.ai/settings](https://app.iwy.ai/settings). ## Base URL ``` https://api.iwy.ai/v1 ``` version: 1.0.0 contact: name: iwy Support url: https://www.iwy.ai/contact servers: - url: https://api.iwy.ai/v1 description: Production server security: - bearerAuth: [] tags: - name: Ephemeral Agents description: Create one-time use agents with automatic expiration - name: Agents description: Manage AI agents and their configurations - name: Tools description: Manage custom tools and functions for agents - name: Sessions description: Start and manage agent video call sessions paths: /tool: post: tags: - Tools summary: Create a new tool description: > Creates a new custom tool that agents can use. Tools are defined by their parameters schema (JSON Schema format) and the webhook endpoint they call. operationId: createTool requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateToolRequest' example: name: get_weather description: Fetches the current weather for a given city server_url: https://webhook.example.com/weather parameters_schema: type: object required: - city properties: city: type: string description: The name of the city (e.g., 'Paris' or 'New York') additionalProperties: false method: POST headers: Content-Type: application/json x-api-key: your-webhook-api-key timeout_seconds: 15 is_async: false strict_params: true responses: '201': description: Tool created successfully content: application/json: schema: $ref: '#/components/schemas/Tool' '400': $ref: '#/components/responses/BadRequestError' '401': $ref: '#/components/responses/UnauthorizedError' '500': $ref: '#/components/responses/InternalServerError' components: schemas: CreateToolRequest: type: object required: - name - description - server_url - parameters_schema properties: name: type: string description: Function name (snake_case) example: get_weather description: type: string description: Clear explanation of what the tool does example: Fetches the current weather for a given city server_url: type: string format: uri description: Webhook endpoint URL parameters_schema: type: object description: JSON Schema defining the tool's parameters method: type: string enum: - POST - GET - PUT - PATCH - DELETE default: POST headers: type: object additionalProperties: true timeout_seconds: type: integer default: 20 minimum: 1 maximum: 300 is_async: type: boolean default: false strict_params: type: boolean default: true auth_config: type: object nullable: true tags: type: array items: type: string Tool: type: object description: Complete tool configuration required: - id - user_id - name - description - server_url - parameters_schema - method properties: id: type: string format: uuid description: Unique identifier for the tool user_id: type: string format: uuid description: ID of the user who owns this tool name: type: string description: Function name (snake_case) example: get_weather description: type: string description: Clear explanation of what the tool does example: Fetches the current weather for a given city server_url: type: string format: uri description: Webhook endpoint URL example: https://webhook.example.com/weather parameters_schema: type: object description: JSON Schema defining the tool's parameters example: type: object required: - city properties: city: type: string description: The name of the city additionalProperties: false method: type: string enum: - POST - GET - PUT - PATCH - DELETE description: HTTP method default: POST headers: type: object description: Custom HTTP headers additionalProperties: true example: Content-Type: application/json x-api-key: your-key timeout_seconds: type: integer description: Request timeout in seconds default: 20 minimum: 1 maximum: 300 is_async: type: boolean description: Whether the tool runs asynchronously default: false strict_params: type: boolean description: Whether to strictly validate parameters default: true auth_config: type: object description: Authentication configuration nullable: true tags: type: array description: Tags for organization items: type: string Error: type: object required: - success - error properties: success: type: boolean example: false error: type: string description: Error message example: Parameter validation failed details: description: Additional error details oneOf: - type: string - type: object execution_time_ms: type: integer description: Execution time before error occurred responses: BadRequestError: description: Invalid request - validation failed content: application/json: schema: $ref: '#/components/schemas/Error' example: success: false error: Bad request details: 'Missing required field: name' UnauthorizedError: description: Authentication failed - invalid or missing API key content: application/json: schema: $ref: '#/components/schemas/Error' example: success: false error: Unauthorized details: Invalid or missing API key InternalServerError: description: Internal server error content: application/json: schema: $ref: '#/components/schemas/Error' example: success: false error: Internal server error details: An unexpected error occurred securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: > Your iwy Service API Key. Find it at [app.iwy.ai/settings](https://app.iwy.ai/settings). Include it in the Authorization header: ``` Authorization: Bearer YOUR_API_KEY ``` ````