> ## Documentation Index
> Fetch the complete documentation index at: https://developer.watson-orchestrate.ibm.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create A Tool



## OpenAPI

````yaml post /v1/tools
openapi: 3.1.0
info:
  title: WxO Server API
  summary: API for the next gen watsonx Orchestrate stack
  description: >+

    The watsonx Orchestrate Server provides a set of APIs to power the watsonx
    Orchestrate AI assistant. This includes the following core services:


    * Orchestrate Assistant - a built-in AI assistant that powers the
    Orchestrate end-user experience.

    * Custom Assistants - a service layer for interacting with existing AI
    assistatns (such as those in watsonx Assistant).

    * Message Threads - a chat history and async message tracking store.

    * Document Store - manage collections of documents in nearly any format
    including text, pdf, html and many more.

    * Information Extraction - automatically extract clean text and images from
    any document in the Document Store.  Also extract other useful metadata like
    questions answered, keywords, and named entities.

    * Embedding - generate vector embeddings for text and images in the Document
    Store.

    * Vector Index and Retrieval - automatically index documents with rich
    metadata for vector search or hybrid search.

    * Search Engine - create a Gen AI powered search engine that works like Bing
    or Google.

    * Query Engine - configure your own RAG (Retrieval Augmented Generation)
    engine supporting advanced retrieval patterns and automated data management.

    * Model Proxy - create your own LLM model endpoints for chat completions and
    embeddings.  Supports IBM watsonx.ai, IBM BAM, OpenAI, MistralAI, or Ollama
    for local models.


    WxO API Server utilizes the following open source projects:


    * [PostgreSQL](https://www.postgresql.org/)

    * [PGVector](https://github.com/pgvector/pgvector)

    * [LlamaIndex](https://docs.llamaindex.ai/en/stable/)

    * [LangChain](https://python.langchain.com/docs/get_started/introduction)

    * [FastAPI](https://fastapi.tiangolo.com/)

    * [Unstructured](https://unstructured.io/)

    * [Celery](https://docs.celeryproject.org/en/stable/)

  version: 0.1.0
servers:
  - url: https://{api_endpoint}
    description: version
security: []
paths:
  /v1/tools:
    post:
      tags:
        - Tools
      summary: Create A Tool
      operationId: Create_a_Tool_v1_tools_post
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTool'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Create A Tool V1 Tools Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - HTTPBearer: []
components:
  schemas:
    CreateTool:
      properties:
        name:
          anyOf:
            - type: string
            - type: 'null'
          title: Name
          description: Name of the tool
        display_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Display Name
          description: Display name of the tool
        description:
          type: string
          title: Description
        permission:
          $ref: '#/components/schemas/ToolPermission'
        input_schema:
          anyOf:
            - $ref: '#/components/schemas/ToolRequestBody-Input'
            - type: 'null'
        output_schema:
          anyOf:
            - $ref: '#/components/schemas/ToolResponseBody-Input'
            - type: 'null'
        binding:
          anyOf:
            - $ref: '#/components/schemas/ToolBinding-Input'
            - type: 'null'
        tags:
          anyOf:
            - items: {}
              type: array
            - type: 'null'
          title: Tags
        is_async:
          type: boolean
          title: Is Async
          description: Whether the tool execution is asynchronous
          default: false
        restrictions:
          type: string
          title: Restrictions
          description: Whether the tool can be edited
          default: editable
        bundled_agent_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Bundled Agent Id
          description: Base agent id
      type: object
      required:
        - description
        - permission
      title: CreateTool
      description: A specification for a tool that can be used in an agent.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ToolPermission:
      type: string
      enum:
        - read_only
        - write_only
        - read_write
        - admin
      title: ToolPermission
      description: The permission level required to use this tool.
    ToolRequestBody-Input:
      properties:
        type:
          type: string
          enum:
            - object
            - string
          title: Type
          default: object
        properties:
          additionalProperties:
            $ref: '#/components/schemas/FlexibleProperty-Input'
          type: object
          title: Properties
        required:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Required
          default: []
      type: object
      title: ToolRequestBody
      description: A request body for a tool.
    ToolResponseBody-Input:
      properties:
        type:
          type: string
          enum:
            - object
            - string
            - number
            - integer
            - boolean
            - array
            - 'null'
          title: Type
          default: object
        description:
          anyOf:
            - type: string
            - type: 'null'
          title: Description
        properties:
          anyOf:
            - additionalProperties:
                $ref: '#/components/schemas/FlexibleProperty-Input'
              type: object
            - type: 'null'
          title: Properties
        items:
          anyOf:
            - $ref: '#/components/schemas/JsonSchemaObject-Input'
            - type: 'null'
        required:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Required
          default: []
        format:
          anyOf:
            - type: string
            - type: 'null'
          title: Format
        anyOf:
          anyOf:
            - items:
                $ref: '#/components/schemas/JsonSchemaObject-Input'
              type: array
            - type: 'null'
          title: Anyof
        oneOf:
          anyOf:
            - items:
                $ref: '#/components/schemas/JsonSchemaObject-Input'
              type: array
            - type: 'null'
          title: Oneof
        allOf:
          anyOf:
            - items:
                $ref: '#/components/schemas/JsonSchemaObject-Input'
              type: array
            - type: 'null'
          title: Allof
      type: object
      title: ToolResponseBody
      description: A response body for a tool.
    ToolBinding-Input:
      properties:
        openapi:
          anyOf:
            - $ref: '#/components/schemas/OpenApiToolBinding-Input'
            - type: 'null'
        python:
          anyOf:
            - $ref: '#/components/schemas/PythonToolBinding'
            - type: 'null'
        wxflows:
          anyOf:
            - $ref: '#/components/schemas/WxFlowsToolBinding'
            - type: 'null'
        skill:
          anyOf:
            - $ref: '#/components/schemas/SkillToolBinding'
            - type: 'null'
        client_side:
          anyOf:
            - $ref: '#/components/schemas/ClientSideToolBinding'
            - type: 'null'
        conversational_search:
          anyOf:
            - $ref: '#/components/schemas/ConversationalSearchToolBinding'
            - type: 'null'
        mcp:
          anyOf:
            - $ref: '#/components/schemas/MCPToolBinding'
            - type: 'null'
        flow:
          anyOf:
            - $ref: '#/components/schemas/FlowToolBinding-Input'
            - type: 'null'
        langflow:
          anyOf:
            - $ref: '#/components/schemas/LangflowToolBinding'
            - type: 'null'
      type: object
      title: ToolBinding
      description: >-
        A binding of the tool to a specific runtime environment such as an
        OpenAPI endpoint or local Python function.
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
    FlexibleProperty-Input:
      anyOf:
        - $ref: '#/components/schemas/JsonSchemaObject-Input'
        - additionalProperties: true
          type: object
      title: FlexibleProperty
    JsonSchemaObject-Input:
      properties:
        type:
          type: string
          enum:
            - object
            - string
            - number
            - integer
            - boolean
            - array
            - 'null'
          title: Type
          default: string
        title:
          anyOf:
            - type: string
            - type: 'null'
          title: Title
        description:
          anyOf:
            - type: string
            - type: 'null'
          title: Description
        properties:
          anyOf:
            - additionalProperties:
                $ref: '#/components/schemas/JsonSchemaObject-Input'
              type: object
            - type: 'null'
          title: Properties
        required:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Required
        items:
          anyOf:
            - $ref: '#/components/schemas/JsonSchemaObject-Input'
            - type: 'null'
        default:
          anyOf:
            - {}
            - type: 'null'
          title: Default
        enum:
          anyOf:
            - items: {}
              type: array
            - type: 'null'
          title: Enum
        minimum:
          anyOf:
            - type: number
            - type: 'null'
          title: Minimum
        maximum:
          anyOf:
            - type: number
            - type: 'null'
          title: Maximum
        minLength:
          anyOf:
            - type: integer
            - type: 'null'
          title: Minlength
        maxLength:
          anyOf:
            - type: integer
            - type: 'null'
          title: Maxlength
        pattern:
          anyOf:
            - type: string
            - type: 'null'
          title: Pattern
        format:
          anyOf:
            - type: string
            - type: 'null'
          title: Format
        in:
          anyOf:
            - type: string
              enum:
                - query
                - header
                - path
                - body
            - type: 'null'
          title: In
        aliasName:
          anyOf:
            - type: string
            - type: 'null'
          title: Aliasname
        anyOf:
          anyOf:
            - items:
                $ref: '#/components/schemas/JsonSchemaObject-Input'
              type: array
            - type: 'null'
          title: Anyof
        oneOf:
          anyOf:
            - items:
                $ref: '#/components/schemas/JsonSchemaObject-Input'
              type: array
            - type: 'null'
          title: Oneof
        allOf:
          anyOf:
            - items:
                $ref: '#/components/schemas/JsonSchemaObject-Input'
              type: array
            - type: 'null'
          title: Allof
      type: object
      title: JsonSchemaObject
      description: >-
        A JSON Schema object that defines the structure and validation rules for
        JSON data.
    OpenApiToolBinding-Input:
      properties:
        http_method:
          type: string
          enum:
            - GET
            - POST
            - PUT
            - PATCH
            - DELETE
          title: Http Method
        http_path:
          type: string
          title: Http Path
        security:
          items:
            $ref: '#/components/schemas/OpenApiSecurityScheme'
          type: array
          title: Security
          default: []
        servers:
          items:
            type: string
          type: array
          title: Servers
          default: []
        connection_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Connection Id
        callback:
          anyOf:
            - $ref: '#/components/schemas/CallbackBinding-Input'
            - type: 'null'
        acknowledgement:
          anyOf:
            - $ref: '#/components/schemas/AcknowledgementResponseBody-Input'
            - type: 'null'
      type: object
      required:
        - http_method
        - http_path
      title: OpenApiToolBinding
      description: A binding for a tool that uses an OpenAPI endpoint.
    PythonToolBinding:
      properties:
        function:
          type: string
          title: Function
          description: The fully qualified name of the Python function to call.
        requirements:
          items:
            type: string
          type: array
          title: Requirements
          description: details of any requirements that are to be installed along with tool
        connections:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Connections
          description: details of the credential connections of the Python tool
      type: object
      required:
        - function
      title: PythonToolBinding
      description: A binding for a tool that uses a Python function.
    WxFlowsToolBinding:
      properties:
        endpoint:
          type: string
          title: Endpoint
          description: The wxflows endpoint.
        flow_name:
          type: string
          title: Flow Name
          description: The name of the flow to call.
        security:
          $ref: '#/components/schemas/OpenApiSecurityScheme'
          default: []
      type: object
      required:
        - endpoint
        - flow_name
      title: WxFlowsToolBinding
      description: A binding for a tool that uses a watsonx.ai Flows agent.
    SkillToolBinding:
      properties:
        skillset_id:
          type: string
          title: Skillset Id
          description: The ID of the skillset containing the skill to call.
        skill_id:
          type: string
          title: Skill Id
          description: The ID of the skill to call.
        skill_operation_path:
          type: string
          title: Skill Operation Path
          description: The path to the skill operation to call.
        http_method:
          type: string
          enum:
            - GET
            - POST
            - PUT
            - PATCH
            - DELETE
          title: Http Method
      type: object
      required:
        - skillset_id
        - skill_id
        - skill_operation_path
        - http_method
      title: SkillToolBinding
      description: A binding for a tool that uses a watsonx Orchestrate Skill.
    ClientSideToolBinding:
      properties: {}
      type: object
      title: ClientSideToolBinding
      description: A binding for a tool that is executed on the client side.
    ConversationalSearchToolBinding:
      properties:
        conversational_search_config:
          additionalProperties: true
          type: object
          title: Conversational Search Config
        connections:
          items: {}
          type: array
          title: Connections
        version:
          type: string
          title: Version
          default: 0.0.1
      type: object
      title: ConversationalSearchToolBinding
    MCPToolBinding:
      properties:
        server_url:
          anyOf:
            - type: string
            - type: 'null'
          title: Server Url
          description: mcp server url to connect to
        source:
          anyOf:
            - type: string
              enum:
                - public-registry
                - files
            - type: 'null'
          title: Source
        env:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Env
          description: details of the envs to be set
        command:
          anyOf:
            - type: string
            - type: 'null'
          title: Command
          description: command to start the mcp server
        args:
          items:
            type: string
          type: array
          title: Args
          description: arguments to start the mcp server
        transport:
          anyOf:
            - type: string
            - type: 'null'
          title: Transport
          description: transport protocol of remote mcp
        connections:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Connections
          description: details of the credential connections of the Python tool
      type: object
      title: MCPToolBinding
      description: A binding for a tool that from MCP server.
    FlowToolBinding-Input:
      properties:
        http_method:
          anyOf:
            - type: string
              enum:
                - GET
                - POST
                - PUT
                - PATCH
                - DELETE
            - type: 'null'
          title: Http Method
        http_path:
          anyOf:
            - type: string
            - type: 'null'
          title: Http Path
        security:
          items:
            $ref: '#/components/schemas/OpenApiSecurityScheme'
          type: array
          title: Security
          default: []
        servers:
          items:
            type: string
          type: array
          title: Servers
          default: []
        connection_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Connection Id
        callback:
          anyOf:
            - $ref: '#/components/schemas/CallbackBinding-Input'
            - type: 'null'
        acknowledgement:
          anyOf:
            - $ref: '#/components/schemas/AcknowledgementResponseBody-Input'
            - type: 'null'
        flow_id:
          type: string
          title: Flow Id
          description: The ID of the flow to call.
          default: ''
        version:
          type: string
          title: Version
          description: The version of the flow to call.
          default: TIP
        dependencies:
          anyOf:
            - $ref: '#/components/schemas/FlowDependencies'
            - type: 'null'
          description: The dependencies of the flow.
        model:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Model
          description: >-
            The flow model to be used to generate an OpenAPI spec. This won't be
            stored.
      type: object
      title: FlowToolBinding
      description: |-
        A binding for a tool that uses a flow.
        A flow tool is called as an OpenAPI tool.
    LangflowToolBinding:
      properties:
        langflow_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Langflow Id
          description: The ID of langflow that is binded
        project_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Project Id
          description: The ID of project in which Langflow is created
        langflow_version:
          anyOf:
            - type: string
            - type: 'null'
          title: Langflow Version
          description: The version of the Langflow tool binded
        connections:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Connections
          description: details of the credential connections of the Langflow tool
      type: object
      title: LangflowToolBinding
      description: A binding for a tool that uses Langflow.
    OpenApiSecurityScheme:
      properties:
        type:
          anyOf:
            - type: string
              enum:
                - apiKey
                - http
                - oauth2
                - openIdConnect
            - type: 'null'
          title: Type
        scheme:
          anyOf:
            - type: string
              enum:
                - basic
                - bearer
                - oauth
            - type: 'null'
          title: Scheme
        in:
          anyOf:
            - type: string
              enum:
                - query
                - header
                - cookie
            - type: 'null'
          title: In
        name:
          anyOf:
            - type: string
            - type: 'null'
          title: Name
        description:
          anyOf:
            - type: string
            - type: 'null'
          title: Description
        open_id_connect_url:
          anyOf:
            - type: string
            - type: 'null'
          title: Open Id Connect Url
          default: openIdConnectUrl
        flows:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Flows
      type: object
      title: OpenApiSecurityScheme
      description: A security scheme for an OpenAPI endpoint.
    CallbackBinding-Input:
      properties:
        callback_url:
          type: string
          title: Callback Url
          description: The URL to send the callback to
        method:
          $ref: '#/components/schemas/HTTP_METHOD'
          description: The HTTP method to use for the callback
        input_schema:
          anyOf:
            - $ref: '#/components/schemas/ToolRequestBody-Input'
            - type: 'null'
          description: The schema for the callback request body
        output_schema:
          $ref: '#/components/schemas/ToolResponseBody-Input'
          description: The schema for the callback response body
      type: object
      required:
        - callback_url
        - method
        - output_schema
      title: CallbackBinding
      description: A binding for a tool that uses a callback URL.
    AcknowledgementResponseBody-Input:
      properties:
        output_schema:
          $ref: '#/components/schemas/ToolResponseBody-Input'
          description: The schema of the original response from the callback.
      type: object
      required:
        - output_schema
      title: AcknowledgementResponseBody
      description: An acknowledgment for the tools that are async
    FlowDependencies:
      properties:
        tools:
          items:
            type: string
          type: array
          title: Tools
          default: []
        agents:
          items:
            type: string
          type: array
          title: Agents
          default: []
      type: object
      title: FlowDependencies
      description: Tools and agents dependencies of a flow tool
    HTTP_METHOD:
      type: string
      enum:
        - GET
        - POST
        - PUT
        - PATCH
        - DELETE
      title: HTTP_METHOD
      description: HTTP methods supported for callbacks.
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer

````