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

# Create tool

> Create a new tool that agents can use to extend their capabilities.

Create a tool to extend an agent's capabilities. Supported tool types include file search, web search, code interpreter, custom tools, agent as tool, and MCP connector. For an overview of all tool types and how they work, see [Tools](/flow/sdk/agents/tools).

## MCP connector

To create an MCP connector tool, set `type` to `mcp_connector` and provide the server URL in `config.URL`. Optionally include `config.CLIENT_ID` and `config.CLIENT_SECRET` if your MCP server requires OAuth without dynamic client registration.

If an OAuth flow is required, the tool is created with a status of `pending_authorization`. Open the `AUTHORIZATION_URL` from the response in a browser and complete the flow. Once authorized, the tool status changes to `active` and it can be linked to an agent. If you don't complete the flow within one hour, the OAuth window expires and the tool moves to `failed` status. To use it again, delete it and create a new one.

For servers that require no authentication, the tool is created with `active` status and can be linked to an agent immediately.

For a full walkthrough including SDK examples, see [MCP connector](/flow/sdk/agents/mcp-connector).

## Agent as tool

To create an agent-as-tool, set `type` to `agent_as_tool` and provide the sub-agent's ID in `config.agent_id`. The sub-agent must already exist before creating the tool.

Each agent can only have one agent-as-tool. If an agent-as-tool already exists for the provided `agent_id`, the request returns an error.

### Errors

* `"Tool already exists: <tool-name>"` — A tool with this name already exists. Tool names must be unique per user.
* `"Tool already exists for given agent: <agent-id>"` — An agent-as-tool already exists for this agent. Each agent can only have one.

For a full walkthrough including SDK examples and constraints, see [Agent as tool](/flow/sdk/agents/agent-as-tool).


## OpenAPI

````yaml post /v1/flow/tools
openapi: 3.1.0
info:
  title: SeekrFlow API
  description: SeekrFlow API Documentation
  termsOfService: http://www.seekr.com/support
  contact:
    name: Seekr API Support
    url: http://www.seekr.com/contact
    email: contact@seekr.com
  version: 5.87.1
servers:
  - url: https://flow.seekr.com
    description: SeekrBuild server base URL
security: []
paths:
  /v1/flow/tools:
    post:
      tags:
        - Tools
      summary: Create tool
      description: Create a new tool that agents can use to extend their capabilities.
      operationId: create_tool_v1_flow_tools_post
      requestBody:
        required: true
        content:
          application/json:
            schema:
              anyOf:
                - $ref: >-
                    #/components/schemas/llm_training__agents__tools__standalone__schemas__CreateFileSearch
                - $ref: >-
                    #/components/schemas/llm_training__agents__tools__standalone__schemas__CreateRunPython
                - $ref: >-
                    #/components/schemas/llm_training__agents__tools__standalone__schemas__CreateWebSearch
                - $ref: '#/components/schemas/CreateAgentAsTool'
                - $ref: '#/components/schemas/CreateMCPConnectorTool'
              title: Request
            examples:
              file_search:
                summary: File search request
                value:
                  name: my file search tool
                  description: 'contains files about '
                  type: file_search
                  config:
                    file_search_index: my-document-index
                    top_k: 10
                    score_threshold: 0.7
              run_python:
                summary: Code interpreter / Custom functions request
                value:
                  name: my python functions tool
                  type: run_python
                  description: Execute Python code for data analysis and calculations
                  config:
                    function_ids:
                      - func-123
                      - func-456
              web_search:
                summary: Web search request
                value:
                  name: my web search tool
                  type: web_search
                  description: Search the web for current information
              agent_as_tool:
                summary: Create agent as a tool request
                value:
                  name: sports history bot
                  description: an expert on the history of sports
                  config:
                    agent_id: agent-00c6a3dc-4d32-4f52-9594-912aa345fffa
              mcp_connector:
                summary: MCP Connector Tool request
                value:
                  name: mcp connector tool
                  description: MCP connector tool with external authorization
                  type: mcp_connector
                  config:
                    url: https://example.com/mcp-connector
      responses:
        '202':
          description: Successful Response
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/FileSearchResponse'
                  - $ref: '#/components/schemas/RunPythonResponse'
                  - $ref: '#/components/schemas/WebSearchResponse'
                  - $ref: '#/components/schemas/AgentAsToolResponse'
                  - $ref: '#/components/schemas/MCPConnectorToolResponse'
                discriminator:
                  propertyName: type
                  mapping:
                    file_search:
                      $ref: '#/components/schemas/FileSearchResponse'
                    run_python:
                      $ref: '#/components/schemas/RunPythonResponse'
                    web_search:
                      $ref: '#/components/schemas/WebSearchResponse'
                    agent_as_tool:
                      $ref: '#/components/schemas/AgentAsToolResponse'
                    mcp_connector:
                      $ref: '#/components/schemas/MCPConnectorToolResponse'
                title: Response Create Tool V1 Flow Tools Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - APIKeyHeader: []
components:
  schemas:
    llm_training__agents__tools__standalone__schemas__CreateFileSearch:
      properties:
        name:
          type: string
          title: Name
        description:
          type: string
          title: Description
        type:
          type: string
          const: file_search
          title: Type
          default: file_search
        config:
          $ref: '#/components/schemas/FileSearchConfig'
      additionalProperties: false
      type: object
      required:
        - name
        - description
        - config
      title: CreateFileSearch
    llm_training__agents__tools__standalone__schemas__CreateRunPython:
      properties:
        name:
          type: string
          title: Name
        description:
          type: string
          title: Description
        type:
          type: string
          const: run_python
          title: Type
          default: run_python
        config:
          $ref: '#/components/schemas/RunPythonConfig'
          default: {}
      additionalProperties: false
      type: object
      required:
        - name
        - description
      title: CreateRunPython
    llm_training__agents__tools__standalone__schemas__CreateWebSearch:
      properties:
        name:
          type: string
          title: Name
        description:
          type: string
          title: Description
        type:
          type: string
          const: web_search
          title: Type
          default: web_search
        config:
          $ref: '#/components/schemas/ToolConfig'
          default: {}
      additionalProperties: false
      type: object
      required:
        - name
        - description
      title: CreateWebSearch
    CreateAgentAsTool:
      properties:
        name:
          type: string
          title: Name
        description:
          type: string
          title: Description
        type:
          type: string
          const: agent_as_tool
          title: Type
          default: agent_as_tool
        config:
          $ref: '#/components/schemas/AgentAsToolConfig'
      additionalProperties: false
      type: object
      required:
        - name
        - description
        - config
      title: CreateAgentAsTool
    CreateMCPConnectorTool:
      properties:
        name:
          type: string
          title: Name
        description:
          type: string
          title: Description
        type:
          type: string
          const: mcp_connector
          title: Type
          default: mcp_connector
        config:
          $ref: '#/components/schemas/MCPConnectorToolConfig'
      additionalProperties: false
      type: object
      required:
        - name
        - description
        - config
      title: CreateMCPConnectorTool
    FileSearchResponse:
      properties:
        id:
          type: string
          title: Id
        name:
          type: string
          title: Name
        description:
          anyOf:
            - type: string
            - type: 'null'
          title: Description
        type:
          type: string
          const: file_search
          title: Type
          default: file_search
        config:
          $ref: '#/components/schemas/FileSearchConfig'
        user_id:
          type: string
          title: User Id
        team_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Team Id
        status:
          $ref: '#/components/schemas/ToolStatus'
        version:
          type: integer
          title: Version
        created_at:
          type: string
          format: date-time
          title: Created At
        updated_at:
          type: string
          format: date-time
          title: Updated At
      type: object
      required:
        - id
        - name
        - config
        - user_id
        - team_id
        - status
        - version
        - created_at
        - updated_at
      title: FileSearchResponse
    RunPythonResponse:
      properties:
        id:
          type: string
          title: Id
        name:
          type: string
          title: Name
        description:
          anyOf:
            - type: string
            - type: 'null'
          title: Description
        type:
          type: string
          const: run_python
          title: Type
          default: run_python
        config:
          $ref: '#/components/schemas/RunPythonConfig'
          default: {}
        user_id:
          type: string
          title: User Id
        team_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Team Id
        status:
          $ref: '#/components/schemas/ToolStatus'
        version:
          type: integer
          title: Version
        created_at:
          type: string
          format: date-time
          title: Created At
        updated_at:
          type: string
          format: date-time
          title: Updated At
      type: object
      required:
        - id
        - name
        - user_id
        - team_id
        - status
        - version
        - created_at
        - updated_at
      title: RunPythonResponse
    WebSearchResponse:
      properties:
        id:
          type: string
          title: Id
        name:
          type: string
          title: Name
        description:
          anyOf:
            - type: string
            - type: 'null'
          title: Description
        type:
          type: string
          const: web_search
          title: Type
          default: web_search
        user_id:
          type: string
          title: User Id
        team_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Team Id
        status:
          $ref: '#/components/schemas/ToolStatus'
        version:
          type: integer
          title: Version
        created_at:
          type: string
          format: date-time
          title: Created At
        updated_at:
          type: string
          format: date-time
          title: Updated At
      type: object
      required:
        - id
        - name
        - user_id
        - team_id
        - status
        - version
        - created_at
        - updated_at
      title: WebSearchResponse
    AgentAsToolResponse:
      properties:
        id:
          type: string
          title: Id
        name:
          type: string
          title: Name
        description:
          anyOf:
            - type: string
            - type: 'null'
          title: Description
        type:
          type: string
          const: agent_as_tool
          title: Type
          default: agent_as_tool
        config:
          $ref: '#/components/schemas/AgentAsToolConfig'
        user_id:
          type: string
          title: User Id
        team_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Team Id
        status:
          $ref: '#/components/schemas/ToolStatus'
        version:
          type: integer
          title: Version
        created_at:
          type: string
          format: date-time
          title: Created At
        updated_at:
          type: string
          format: date-time
          title: Updated At
      type: object
      required:
        - id
        - name
        - config
        - user_id
        - team_id
        - status
        - version
        - created_at
        - updated_at
      title: AgentAsToolResponse
    MCPConnectorToolResponse:
      properties:
        id:
          type: string
          title: Id
        name:
          type: string
          title: Name
        description:
          anyOf:
            - type: string
            - type: 'null'
          title: Description
        type:
          type: string
          const: mcp_connector
          title: Type
          default: mcp_connector
        config:
          $ref: '#/components/schemas/MCPConnectorToolResponseConfig'
        user_id:
          type: string
          title: User Id
        team_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Team Id
        status:
          $ref: '#/components/schemas/ToolStatus'
        version:
          type: integer
          title: Version
        created_at:
          type: string
          format: date-time
          title: Created At
        updated_at:
          type: string
          format: date-time
          title: Updated At
      type: object
      required:
        - id
        - name
        - config
        - user_id
        - team_id
        - status
        - version
        - created_at
        - updated_at
      title: MCPConnectorToolResponse
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    FileSearchConfig:
      properties:
        FILE_SEARCH_INDEX:
          type: string
          minLength: 1
          title: File Search Index
        EMBEDDING_MODEL:
          anyOf:
            - type: string
            - type: 'null'
          title: Embedding Model
        TOP_K:
          type: integer
          maximum: 100
          minimum: 1
          title: Top K
          description: Top K must be >= 1 and <= 100
          default: 10
        SCORE_THRESHOLD:
          type: number
          exclusiveMaximum: 1
          minimum: 0
          title: Score Threshold
          description: Score must be ≥ 0.0 and < 1.0
          default: 0
      additionalProperties: false
      type: object
      required:
        - FILE_SEARCH_INDEX
      title: FileSearchConfig
    RunPythonConfig:
      properties:
        FUNCTION_IDS:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Function Ids
      additionalProperties: false
      type: object
      title: RunPythonConfig
    ToolConfig:
      properties: {}
      additionalProperties: false
      type: object
      title: ToolConfig
    AgentAsToolConfig:
      properties:
        AGENT_ID:
          type: string
          title: Agent Id
      additionalProperties: false
      type: object
      required:
        - AGENT_ID
      title: AgentAsToolConfig
    MCPConnectorToolConfig:
      properties:
        URL:
          type: string
          minLength: 1
          title: Url
        CLIENT_ID:
          anyOf:
            - type: string
              minLength: 1
            - type: 'null'
          title: Client Id
        CLIENT_SECRET:
          anyOf:
            - type: string
              minLength: 1
            - type: 'null'
          title: Client Secret
      additionalProperties: false
      type: object
      required:
        - URL
      title: MCPConnectorToolConfig
    ToolStatus:
      type: string
      enum:
        - Active
        - Inactive
        - Deprecated
        - Pending_authorization
        - Failed
      title: ToolStatus
    MCPConnectorToolResponseConfig:
      properties:
        URL:
          type: string
          minLength: 1
          title: Url
        TRANSPORT:
          type: string
          enum:
            - sse
            - streamable-http
          title: Transport
          default: streamable-http
        AUTHORIZATION_URL:
          anyOf:
            - type: string
            - type: 'null'
          title: Authorization Url
      additionalProperties: false
      type: object
      required:
        - URL
      title: MCPConnectorToolResponseConfig
    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
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      description: Seekr API Key without 'Bearer' Prefix
      in: header
      name: Authorization

````