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

# Resolve agent config tools

> Returns configured built-in and custom tools plus missing machine, skill, subagent, and retrieval defaults, including disabled entries. Accepts YAML/JSON source. Source previews validate tool-related fields only; they do not validate whether the config can be saved or launched. Does not resolve contextual integration tools, discover MCP tools, or change any configuration.



## OpenAPI

````yaml /api-reference/openapi.yaml post /orgs/{orgID}/projects/{projectID}/agent-configs/tools
openapi: 3.1.2
info:
  title: Omnara API
  version: 0.1.0
  description: Public HTTP API contract for Omnara.
servers:
  - url: https://api.omnara.com/v1
    description: Hosted Omnara
  - url: /api/v1
    description: Self-hosted Omnara, relative to the deployment origin
security:
  - bearerAuth: []
  - browserSessionCookie: []
tags:
  - name: Agents
    description: >-
      Launch agents, send inputs, manage the input backlog, and work with tool
      calls.
    externalDocs:
      description: Guide
      url: https://docs.omnara.com/agents/overview
  - name: Interactions
    description: List and resolve the approvals and questions that pause an agent.
    externalDocs:
      description: Guide
      url: https://docs.omnara.com/events/interactions
  - name: Actors
    description: Attribute agent inputs and interaction responses to external users.
    externalDocs:
      description: Guide
      url: >-
        https://docs.omnara.com/events/sending-input#who-said-that-actors-and-attribution
  - name: Events
    description: Read or stream the agent timeline, list turns, and download artifacts.
    externalDocs:
      description: Guide
      url: https://docs.omnara.com/events/streaming
  - name: Configs and Profiles
    description: >-
      Create agent configs, manage reusable launch profiles, and set up
      integrations.
    externalDocs:
      description: Guide
      url: https://docs.omnara.com/agents/configuration
  - name: Integrations
    description: >-
      Connect project integrations, route conversations, and manage launch
      settings.
    externalDocs:
      description: Guide
      url: https://docs.omnara.com/integrations/overview
  - name: Models
    description: Configure model providers and models, and grant projects access to them.
    externalDocs:
      description: Guide
      url: https://docs.omnara.com/organization/model-providers
  - name: Machines
    description: Register machines, control project access, and manage daemon tokens.
    externalDocs:
      description: Guide
      url: https://docs.omnara.com/machines/connect
  - name: Machine Pools
    description: Define machine pools and grant projects access to them.
    externalDocs:
      description: Guide
      url: https://docs.omnara.com/machines/pools
  - name: Secrets
    description: >-
      Manage secret ownership and versions, and inspect or grant project
      availability.
    externalDocs:
      description: Guide
      url: https://docs.omnara.com/organization/secrets
  - name: Skills
    description: Manage versioned skill ownership and load skill instructions on demand.
    externalDocs:
      description: Guide
      url: https://docs.omnara.com/tools/skills
  - name: Organizations and Projects
    description: Create organizations and projects and manage membership.
    externalDocs:
      description: Guide
      url: https://docs.omnara.com/organization/members
  - name: Users and API Keys
    description: >-
      The authenticated user, personal and organization API keys, and
      invitations.
    externalDocs:
      description: Guide
      url: https://docs.omnara.com/api/authentication
  - name: Machine Daemon
    description: Routes the Omnara machine daemon uses to connect a machine.
paths:
  /orgs/{orgID}/projects/{projectID}/agent-configs/tools:
    parameters:
      - name: orgID
        in: path
        description: Organization ID (org_...).
        required: true
        schema:
          $ref: '#/components/schemas/OrganizationID'
      - name: projectID
        in: path
        description: Project ID (proj_...).
        required: true
        schema:
          $ref: '#/components/schemas/ProjectID'
    post:
      tags:
        - Configs and Profiles
      summary: Resolve agent config tools
      description: >-
        Returns configured built-in and custom tools plus missing machine,
        skill, subagent, and retrieval defaults, including disabled entries.
        Accepts YAML/JSON source. Source previews validate tool-related fields
        only; they do not validate whether the config can be saved or launched.
        Does not resolve contextual integration tools, discover MCP tools, or
        change any configuration.
      operationId: resolveAgentConfigTools
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResolveAgentConfigToolsRequest'
      responses:
        '200':
          description: Resolved config tools.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResolvedAgentConfigTools'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        4XX:
          $ref: '#/components/responses/ClientError'
      security:
        - bearerAuth: []
        - browserSessionCookie: []
          csrfHeader: []
components:
  schemas:
    OrganizationID:
      type: string
      pattern: ^org_[a-z2-7]{26}$
    ProjectID:
      description: Project ID (proj_...).
      type: string
      pattern: ^proj_[a-z2-7]{26}$
    ResolveAgentConfigToolsRequest:
      type: object
      additionalProperties: false
      required:
        - source
        - source_format
      properties:
        source:
          description: >-
            Agent config source as YAML or JSON text, or, with source_format
            json, as a JSON object. Only the fields that determine tools are
            read.
          anyOf:
            - type: string
              minLength: 1
            - $ref: '#/components/schemas/AgentConfigToolsDefinition'
          x-go-type: json.RawMessage
        source_format:
          type: string
          enum:
            - yaml
            - json
    ResolvedAgentConfigTools:
      type: object
      additionalProperties: false
      required:
        - tools
      properties:
        tools:
          type: array
          items:
            $ref: '#/components/schemas/ResolvedAgentConfigTool'
    AgentConfigToolsDefinition:
      description: >-
        The parts of an agent config definition that determine its effective
        tools. Other fields are ignored.
      type: object
      additionalProperties: true
      properties:
        git_credentials:
          $ref: '#/components/schemas/AgentConfigDefinitionGitCredentials'
        interaction_handlers:
          $ref: '#/components/schemas/AgentConfigDefinitionInteractionHandlers'
        machine_sources:
          $ref: '#/components/schemas/AgentConfigDefinitionMachineSources'
        mcp:
          $ref: '#/components/schemas/AgentConfigDefinitionMCPServers'
        memory_stores:
          $ref: '#/components/schemas/AgentConfigDefinitionMemoryStores'
        skills:
          $ref: '#/components/schemas/AgentConfigDefinitionSkills'
        subagents:
          $ref: '#/components/schemas/AgentConfigDefinitionSubagents'
        tools:
          $ref: '#/components/schemas/AgentConfigDefinitionTools'
      x-go-type: json.RawMessage
    ResolvedAgentConfigTool:
      type: object
      additionalProperties: false
      required:
        - name
        - enabled
        - permission
      properties:
        name:
          type: string
        enabled:
          type: boolean
        permission:
          $ref: '#/components/schemas/ToolPermissionSelection'
    Error:
      type: object
      additionalProperties: false
      required:
        - error
        - code
      properties:
        error:
          type: string
          description: Human-readable error message. Do not match on it programmatically.
        current_digest:
          type: string
          pattern: ^sha256:[0-9a-f]{64}$
          description: >-
            Current file digest for file_content_conflict or
            expected_digest_required; absent if the file no longer exists. A
            replacement must be confirmed before retrying with this digest.
        issues:
          type: array
          description: >-
            Field-level problems when a submitted document (such as an agent
            config source) failed validation. Absent for errors that are not
            about a specific field.
          items:
            $ref: '#/components/schemas/AgentConfigErrorIssue'
        code:
          type: string
          description: Stable error code for programmatic handling.
          x-go-type: ErrorCode
          x-extensible-enum:
            - invalid_request
            - unauthorized
            - forbidden
            - not_found
            - conflict
            - file_content_conflict
            - file_read_only
            - expected_digest_required
            - not_a_file
            - gone
            - request_too_large
            - unsupported_media_type
            - unprocessable
            - upstream_unavailable
            - rate_limited
            - internal_error
            - service_unavailable
            - idempotency_key_conflict
            - agent_backlog_full
            - state_transition_conflict
            - managed_work_admission_denied
            - pending_work
            - not_wake_capable
            - daemon_runtime_unregistered
            - validation_failed
            - csrf_check_failed
            - authentication_unavailable
    ClientErrorCode:
      type: string
      description: >-
        Stable error code carried by 4XX statuses. Subset of the Error code enum
        whose statuses are client errors.
      x-extensible-enum:
        - invalid_request
        - validation_failed
        - unauthorized
        - forbidden
        - csrf_check_failed
        - not_found
        - conflict
        - file_content_conflict
        - file_read_only
        - expected_digest_required
        - not_a_file
        - idempotency_key_conflict
        - agent_backlog_full
        - state_transition_conflict
        - pending_work
        - not_wake_capable
        - gone
        - daemon_runtime_unregistered
        - request_too_large
        - unsupported_media_type
        - unprocessable
        - upstream_unavailable
        - rate_limited
    AgentConfigDefinitionGitCredentials:
      description: Integration whose git credentials the agent's machines use.
      type: object
      additionalProperties: false
      required:
        - integration
      properties:
        integration:
          type: string
          pattern: ^[a-zA-Z][a-zA-Z0-9-]{0,31}$
      x-go-type: json.RawMessage
    AgentConfigDefinitionInteractionHandlers:
      description: Interaction handlers keyed by integration name.
      anyOf:
        - type: object
          additionalProperties:
            $ref: '#/components/schemas/AgentConfigDefinitionInteractionHandler'
          propertyNames:
            type: string
            pattern: ^[a-zA-Z][a-zA-Z0-9-]{0,31}$
        - type: 'null'
      x-go-type: json.RawMessage
    AgentConfigDefinitionMachineSources:
      anyOf:
        - type: array
          items:
            $ref: '#/components/schemas/AgentConfigDefinitionMachineSource'
        - type: 'null'
      x-go-type: json.RawMessage
    AgentConfigDefinitionMCPServers:
      anyOf:
        - type: object
          additionalProperties:
            $ref: '#/components/schemas/AgentConfigDefinitionMCPServer'
          propertyNames:
            type: string
            pattern: ^[a-zA-Z][a-zA-Z0-9-]{0,31}$
        - type: 'null'
      x-go-type: json.RawMessage
    AgentConfigDefinitionMemoryStores:
      anyOf:
        - type: array
          items:
            $ref: '#/components/schemas/AgentConfigDefinitionMemoryStore'
        - type: 'null'
      x-go-type: json.RawMessage
    AgentConfigDefinitionSkills:
      anyOf:
        - type: array
          uniqueItems: true
          items:
            type: string
            pattern: ^skl_[a-z2-7]{26}$
        - type: 'null'
      x-go-type: json.RawMessage
    AgentConfigDefinitionSubagents:
      anyOf:
        - type: object
          additionalProperties:
            $ref: '#/components/schemas/AgentConfigDefinitionSubagent'
          propertyNames:
            type: string
            pattern: ^[A-Za-z_][A-Za-z0-9_]{0,63}$
        - type: 'null'
      x-go-type: json.RawMessage
    AgentConfigDefinitionTools:
      anyOf:
        - type: object
          additionalProperties:
            $ref: '#/components/schemas/AgentConfigDefinitionTool'
          propertyNames:
            allOf:
              - anyOf:
                  - type: string
                    pattern: ^[A-Za-z_][A-Za-z0-9_]{0,63}$
                  - type: string
                    maxLength: 64
                    pattern: ^int__[a-zA-Z][a-zA-Z0-9-]{0,31}__[a-zA-Z][a-zA-Z0-9_-]*$
              - not:
                  type: string
                  pattern: ^mcp__
        - type: 'null'
      x-go-type: json.RawMessage
    ToolPermissionSelection:
      type: object
      additionalProperties: false
      required:
        - mode
        - parameters
      properties:
        mode:
          type: string
        parameters:
          type: object
          additionalProperties: true
    AgentConfigErrorIssue:
      type: object
      additionalProperties: false
      required:
        - path
        - message
      properties:
        path:
          type: string
          description: >-
            JSON Pointer (RFC 6901) to the offending field in the submitted
            document. An empty string refers to the whole document.
        message:
          type: string
          description: Human-readable description of the problem with this field.
        line:
          type: integer
          minimum: 1
          description: >-
            1-based line of the offending field in the submitted source, when it
            can be located.
        column:
          type: integer
          minimum: 1
          description: >-
            1-based column of the offending field in the submitted source, when
            it can be located.
    AgentConfigDefinitionInteractionHandler:
      description: Enables an integration's interaction handler. Takes no settings.
      type: object
      additionalProperties: false
      x-go-type: agentconfig.AgentConfigIntegrationCapabilitySource
      x-go-type-import:
        path: github.com/omnara-ai/omnara/internal/agentconfig
    AgentConfigDefinitionMachineSource:
      type: object
      additionalProperties: false
      properties:
        cwd:
          type: string
          maxLength: 4096
        delete_after_idle_minutes:
          anyOf:
            - const: 0
            - type: integer
              minimum: 5
              maximum: 2147483647
        description:
          type: string
          maxLength: 4096
        env_overlay:
          anyOf:
            - type: object
              additionalProperties:
                anyOf:
                  - type: string
                  - type: 'null'
              propertyNames:
                $ref: '#/components/schemas/EnvironmentVariableName'
            - type: 'null'
        initial_num_machines:
          type: integer
          minimum: 0
        machine_cpu:
          type: integer
          minimum: 1
          maximum: 2147483647
        machine_memory_mb:
          type: integer
          minimum: 1
          maximum: 2147483647
        machine_name:
          $ref: '#/components/schemas/ResourceNameReference'
        machine_pool_name:
          $ref: '#/components/schemas/ResourceNameReference'
        machine_provider_options_overlay:
          anyOf:
            - type: object
            - type: 'null'
        max_machines:
          type: integer
          minimum: 0
        secret_env_overlay:
          anyOf:
            - type: object
              additionalProperties:
                anyOf:
                  - type: string
                    pattern: ^sec_[a-z2-7]{26}$
                  - type: 'null'
              propertyNames:
                $ref: '#/components/schemas/EnvironmentVariableName'
            - type: 'null'
      oneOf:
        - type: object
          required:
            - machine_name
        - type: object
          required:
            - machine_pool_name
      x-go-type: json.RawMessage
    AgentConfigDefinitionMCPServer:
      type: object
      additionalProperties: false
      required:
        - url
      properties:
        auth:
          $ref: '#/components/schemas/AgentConfigDefinitionMCPAuth'
        default_enabled:
          anyOf:
            - type: boolean
            - type: 'null'
        deferred:
          type: boolean
        permission:
          $ref: '#/components/schemas/AgentConfigDefinitionToolPermission'
        tools:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/AgentConfigDefinitionMCPTool'
          propertyNames:
            type: string
            pattern: ^[a-zA-Z][a-zA-Z0-9_-]{0,63}$
        url:
          type: string
          minLength: 1
      x-go-type: json.RawMessage
    AgentConfigDefinitionMemoryStore:
      type: object
      additionalProperties: false
      required:
        - name
        - access
      properties:
        name:
          $ref: '#/components/schemas/MemoryStoreName'
        access:
          type: string
          enum:
            - read
            - read_write
      x-go-type: json.RawMessage
    AgentConfigDefinitionSubagent:
      type: object
      additionalProperties: false
      required:
        - type
      properties:
        archive_after_idle_minutes:
          type: integer
          minimum: 1
          maximum: 2147483647
        description:
          type: string
        instruction:
          $ref: '#/components/schemas/AgentConfigDefinitionSubagentInstruction'
        max_instances:
          type: integer
          minimum: 1
          maximum: 2147483647
        model:
          $ref: '#/components/schemas/AgentConfigDefinitionSubagentModel'
        profile:
          $ref: '#/components/schemas/ResourceNameReference'
        type:
          enum:
            - profile
            - self
      if:
        type: object
        required:
          - type
        properties:
          type:
            const: profile
      then:
        required:
          - profile
      else:
        not:
          type: object
          required:
            - profile
      x-go-type: json.RawMessage
    AgentConfigDefinitionTool:
      type: object
      additionalProperties: false
      properties:
        deferred:
          type: boolean
        description:
          type: string
          minLength: 1
        enabled:
          anyOf:
            - type: boolean
            - type: 'null'
        input_schema:
          $ref: '#/components/schemas/AgentConfigDefinitionToolInputSchema'
        permission:
          $ref: '#/components/schemas/AgentConfigDefinitionToolPermission'
        type:
          enum:
            - built_in
            - custom
      if:
        type: object
        required:
          - type
        properties:
          type:
            const: custom
      then:
        required:
          - description
          - input_schema
      else:
        not:
          anyOf:
            - type: object
              required:
                - description
            - type: object
              required:
                - input_schema
      x-go-type: agentconfig.AgentConfigToolSource
      x-go-type-import:
        path: github.com/omnara-ai/omnara/internal/agentconfig
    ResourceNameReference:
      description: Name of an existing resource, resolved when the config is compiled.
      type: string
      minLength: 1
      maxLength: 64
      pattern: ^\S(?:.*\S)?$
    AgentConfigDefinitionMCPAuth:
      type: object
      additionalProperties: false
      required:
        - type
        - secret_id
      properties:
        region:
          type: string
          minLength: 1
        secret_id:
          type: string
          minLength: 1
          pattern: ^sec_[a-z2-7]{26}$
        service:
          type: string
          minLength: 1
        type:
          enum:
            - bearer
            - oauth
            - sigv4
      x-go-type: json.RawMessage
    AgentConfigDefinitionToolPermission:
      type: object
      additionalProperties: false
      required:
        - mode
      properties:
        mode:
          type: string
          minLength: 1
          pattern: \S
        parameters:
          type: object
      x-go-type: json.RawMessage
    AgentConfigDefinitionMCPTool:
      type: object
      additionalProperties: false
      properties:
        deferred:
          anyOf:
            - type: boolean
            - type: 'null'
        enabled:
          anyOf:
            - type: boolean
            - type: 'null'
        permission:
          $ref: '#/components/schemas/AgentConfigDefinitionToolPermission'
      x-go-type: json.RawMessage
    MemoryStoreName:
      type: string
      minLength: 1
      maxLength: 64
      pattern: ^[a-z0-9]+(?:-[a-z0-9]+)*$
      description: >-
        Machine-readable memory store identifier consisting of lowercase ASCII
        segments separated by single hyphens.
    AgentConfigDefinitionSubagentInstruction:
      type: object
      additionalProperties: false
      properties:
        append:
          type: string
      x-go-type: json.RawMessage
    AgentConfigDefinitionSubagentModel:
      type: object
      additionalProperties: false
      dependentRequired:
        name:
          - provider_config
        provider_config:
          - name
      properties:
        cache_retention:
          enum:
            - none
            - short
            - long
        context_window_tokens:
          type: integer
          minimum: 2
          maximum: 2147483647
          description: >-
            Context budget for input and output tokens. Triggers compaction when
            estimated input exceeds the remaining budget after output and safety
            reserves. The turn fails if compaction cannot make it fit.
        default_max_output_tokens:
          type: integer
          minimum: 1
        name:
          $ref: '#/components/schemas/ResourceNameReference'
        provider_config:
          $ref: '#/components/schemas/ResourceNameReference'
        reasoning:
          type: object
          additionalProperties: false
          required:
            - effort
          properties:
            effort:
              type: string
              minLength: 1
              pattern: \S
      x-go-type: json.RawMessage
    AgentConfigDefinitionToolInputSchema:
      description: >-
        A JSON Schema for the tool's input. Keywords beyond those listed, such
        as additionalProperties or description, are allowed.
      type: object
      additionalProperties: true
      required:
        - type
      properties:
        properties:
          type: object
          additionalProperties:
            type: object
        required:
          type: array
          items:
            type: string
            minLength: 1
        type:
          const: object
      x-go-type: json.RawMessage
  responses:
    BadRequest:
      description: The request was invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Authentication is required or invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: The authenticated principal is not authorized.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: The requested resource was not found or is not visible.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ServiceUnavailable:
      description: The service dependency required to satisfy the request is unavailable.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ClientError:
      description: >-
        Any other client error. The body carries the shared Error envelope
        restricted to client error codes; statuses with a dedicated response
        above are documented precisely.
      content:
        application/json:
          schema:
            type: object
            additionalProperties: false
            required:
              - error
              - code
            properties:
              error:
                type: string
                description: >-
                  Human-readable error message. Do not match on it
                  programmatically.
              code:
                $ref: '#/components/schemas/ClientErrorCode'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: Omnara personal or organization access token
      description: An opaque Omnara personal or organization bearer token.
    browserSessionCookie:
      type: apiKey
      in: cookie
      name: __Host-omnara_session
      description: >-
        Browser session cookie. HTTPS deployments use __Host-omnara_session;
        local HTTP development uses omnara_session.
    csrfHeader:
      type: apiKey
      in: header
      name: X-Omnara-Csrf
      description: >-
        CSRF token header required for browser-session mutations. The value must
        match the session's CSRF cookie.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.