> ## Documentation Index
> Fetch the complete documentation index at: https://composio-preview.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Search for tools using a query

> Search for tools matching a use case query within an existing tool router session.



## OpenAPI

````yaml /api-reference/openapi.json post /api/v3.1/tool_router/session/{session_id}/search
openapi: 3.1.0
info:
  version: 3.1.0
  title: Composio Platform API v3.1
  description: >-
    Composio v3.1 API — all endpoints available under /api/v3.1/. Tool endpoints
    default to the latest tool version.
  contact:
    name: Composio Support
    url: https://composio.dev/support
    email: support@composio.dev
  license:
    name: Proprietary
    url: https://composio.dev/terms
servers:
  - url: https://backend.composio.dev
    description: Composio production API
security:
  - ApiKeyAuth: []
tags:
  - name: Authentication
    description: Authentication related endpoints
    x-group: Authentication
  - name: Auth Configs
    description: Authentication configuration management
    x-group: Auth Configs
  - name: Connected Accounts
    description: Connected account management
    x-group: Connected Accounts
  - name: Logs
    description: Logging and monitoring
    x-group: Logs
  - name: OpenAPI
    description: OpenAPI specification management
    x-group: OpenAPI
  - name: Organization
    description: Organization management
    x-group: Organization
  - name: API Keys
    description: API key management
    x-group: API Keys
  - name: Webhooks
    description: Webhook configuration
    x-group: Webhooks
  - name: Webhook Endpoints
    description: >-
      Per-OAuth-app webhook ingress endpoints. Inbound URLs the provider posts
      to, plus signing secret storage and verification.
    x-group: Webhook Endpoints
  - name: Webhook Subscriptions
    description: >-
      Webhook delivery subscriptions. Outbound URLs Composio posts trigger
      events to, plus signing secret rotation and event-type filters.
    x-group: Webhook Subscriptions
  - name: Team
    description: Team member management
    x-group: Team
  - name: Consumer Skills
    description: Organization-authored Skill management
    x-group: Consumer Skills
  - name: Toolkits
    description: Toolkit and tool management
    x-group: Toolkits
  - name: Tools
    description: Tool execution endpoints
    x-group: Tools
  - name: Triggers
    description: Trigger management and execution
    x-group: Triggers
  - name: Payments
    description: Payment and subscription management
    x-group: Payments
  - name: Billing
    description: Dashboard billing state — usage, subscription, contract (cookie-auth only)
    x-group: Billing
  - name: Compliance
    description: Organization compliance agreements and acceptance state
    x-group: Compliance
  - name: Files
    description: File management
    x-group: Files
  - name: MCP
    description: MCP server management
    x-group: MCP
  - name: MCP Partner
    description: MCP partner management
    x-group: MCP Partner
  - name: Stripe Projects
    description: Stripe Projects provisioning
    x-group: Stripe Projects
  - name: Tool Router
    description: (Labs) Tool router endpoints
    x-group: Sessions (Prev Tool Router)
  - name: Playground
    description: Dashboard playground chat
    x-group: Playground
  - name: Arena
    description: Arena conversations, messages and terms
    x-group: Arena
  - name: Projects
    description: Projects API endpoints.
    x-group: Projects
  - name: Organization Management
    description: Organization Management API endpoints.
    x-group: Organization Management
  - name: Webhook Events
    description: Events delivered by Composio to your registered webhook endpoints
    x-group: Webhook Events
paths:
  /api/v3.1/tool_router/session/{session_id}/search:
    post:
      tags:
        - Tool Router
      summary: Search for tools using a query
      description: >-
        Search for tools matching a use case query within an existing tool
        router session.
      operationId: postToolRouterSessionBySessionIdSearch
      parameters:
        - schema:
            type: string
            format: toolRouterSessionId
            description: Tool router session ID (trs_*)
            example: trs_LX9uJKBinWWr
          required: true
          description: Tool router session ID (trs_*)
          name: session_id
          in: path
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                queries:
                  type: array
                  items:
                    type: object
                    properties:
                      use_case:
                        type: string
                        minLength: 1
                        maxLength: 1024
                        description: >-
                          The task or use case to search tools for. Provide a
                          detailed description to get the best results. Max 1024
                          characters.
                        example: >-
                          Send an email to john@example.com with a summary of my
                          last 5 slack messages
                      known_fields:
                        type: string
                        maxLength: 500
                        description: >-
                          Known field hints as key:value pairs (e.g.,
                          "channel_name:general, user_email:john@example.com").
                          Max 500 characters.
                        example: channel_name:general
                    required:
                      - use_case
                  minItems: 1
                  maxItems: 7
                  description: List of search queries to execute in parallel.
                  example:
                    - use_case: Send a slack message to a channel
                model:
                  type: string
                  description: >-
                    Optional model hint for search/planning behavior (e.g.,
                    "gpt-4o").
                  example: gpt-4o
                search_strategy:
                  type: string
                  enum:
                    - auto
                    - tool_search
                  description: >-
                    Search path to use. Defaults to auto. Use tool_search to
                    bypass cached plans and run direct tool search.
                  example: tool_search
                experimental:
                  type: object
                  properties:
                    custom_toolkits:
                      type: array
                      items:
                        type: object
                        properties:
                          slug:
                            type: string
                            minLength: 1
                            pattern: ^[a-zA-Z0-9_-]+$
                            description: >-
                              Unique slug for the toolkit. Must not conflict
                              with existing Composio toolkit slugs.
                              Alphanumeric, underscores, and hyphens only.
                            example: ecommerce
                          name:
                            type: string
                            minLength: 1
                            maxLength: 128
                            description: >-
                              Display name shown to the LLM and in search
                              results.
                            example: E-Commerce API
                          description:
                            type: string
                            minLength: 1
                            maxLength: 2048
                            description: >-
                              Used for BM25 search matching and shown in toolkit
                              connection statuses.
                            example: >-
                              Internal e-commerce API for order management and
                              fulfillment
                          preload:
                            type: boolean
                            description: >-
                              SDK hint for direct custom-tool exposure. Not
                              stored in session config; echoed in create/attach
                              responses for inline custom definitions.
                          tools:
                            type: array
                            items:
                              type: object
                              properties:
                                slug:
                                  type: string
                                  minLength: 1
                                  pattern: ^[a-zA-Z0-9_-]+$
                                  description: >-
                                    Tool slug. Combined with toolkit slug to
                                    form LOCAL_<TOOLKIT>_<TOOL> (max 60 chars
                                    total).
                                  example: GET_CUSTOMER_ORDERS
                                name:
                                  type: string
                                  minLength: 1
                                  maxLength: 128
                                  description: Human-readable display name
                                  example: Get Customer Orders
                                description:
                                  type: string
                                  minLength: 1
                                  maxLength: 5120
                                  description: >-
                                    Used for BM25 search matching and shown to
                                    the LLM.
                                  example: >-
                                    Fetch recent orders for a customer by their
                                    email address
                                input_schema:
                                  type: object
                                  additionalProperties: {}
                                  description: >-
                                    Must have type: "object" and a properties
                                    field.
                                  example:
                                    type: object
                                    properties:
                                      email:
                                        type: string
                                        description: Customer email
                                    required:
                                      - email
                                output_schema:
                                  type: object
                                  additionalProperties: {}
                                  description: >-
                                    Optional output schema for the tool
                                    response.
                                preload:
                                  type: boolean
                                  description: >-
                                    SDK hint for direct custom-tool exposure.
                                    Not stored in session config; echoed in
                                    create/attach responses for inline custom
                                    definitions.
                              required:
                                - slug
                                - name
                                - description
                                - input_schema
                            minItems: 1
                            maxItems: 100
                            description: Tools in this custom toolkit
                        required:
                          - slug
                          - name
                          - description
                          - tools
                      description: >-
                        Custom toolkits with grouped tools. Toolkit slugs must
                        not conflict with existing Composio toolkits. All tools
                        are no-auth.
                    custom_tools:
                      type: array
                      items:
                        type: object
                        properties:
                          slug:
                            type: string
                            minLength: 1
                            pattern: ^[a-zA-Z0-9_-]+$
                            description: >-
                              Tool slug. Forms LOCAL_<TOOL> (standalone) or
                              LOCAL_<TOOLKIT>_<TOOL> (extending). Max 60 chars
                              total.
                            example: GET_IMPORTANT_EMAILS
                          name:
                            type: string
                            minLength: 1
                            maxLength: 128
                            description: Human-readable display name
                            example: Get Important Emails
                          description:
                            type: string
                            minLength: 1
                            maxLength: 5120
                            description: >-
                              Used for BM25 search matching and shown to the
                              LLM.
                            example: >-
                              Fetch emails marked as important from the last 24
                              hours
                          input_schema:
                            type: object
                            additionalProperties: {}
                            description: 'Must have type: "object" and a properties field.'
                            example:
                              type: object
                              properties:
                                limit:
                                  type: number
                                  description: Max results to return
                          output_schema:
                            type: object
                            additionalProperties: {}
                            description: JSON Schema describing tool output (optional)
                          extends_toolkit:
                            type: string
                            minLength: 1
                            description: >-
                              If set, must be a valid Composio toolkit slug. The
                              tool inherits that toolkit's auth/connection
                              status. If omitted, the tool is standalone
                              (no-auth).
                            example: gmail
                          preload:
                            type: boolean
                            description: >-
                              SDK hint for direct custom-tool exposure. Not
                              stored in session config; echoed in create/attach
                              responses for inline custom definitions.
                        required:
                          - slug
                          - name
                          - description
                          - input_schema
                      description: >-
                        Custom tools to include in search. Standalone tools need
                        no auth. Tools with extends_toolkit inherit the Composio
                        toolkit's connection.
                  additionalProperties: false
                  description: >-
                    Inline custom tools and toolkits for this request. v3.1
                    sessions do not persist customs — pass them on every request
                    that needs them.
              required:
                - queries
      responses:
        '200':
          description: >-
            Successfully executed the search. Returns matching tool slugs,
            schemas, connection statuses, and guidance.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    description: >-
                      Whether all searches completed successfully. False if any
                      query failed.
                  error:
                    type:
                      - string
                      - 'null'
                    description: >-
                      Error message if any searches failed, null if all
                      succeeded. Format: "X out of Y searches failed, reasons:
                      <details>"
                  results:
                    type: array
                    items:
                      type: object
                      properties:
                        index:
                          type: number
                          description: 1-based index of the query in the request
                        use_case:
                          type: string
                          description: The use case that was searched
                        execution_guidance:
                          type: string
                          description: >-
                            Guidance message about the search results,
                            particularly when a cached plan is available
                        difficulty:
                          type: string
                          description: >-
                            Task difficulty assessment (e.g., "easy - Simple
                            single-tool operation with known parameters")
                        recommended_plan_steps:
                          type: array
                          items:
                            type: string
                          description: >-
                            Workflow steps from cached plan (only present when
                            cached plan is available)
                        known_pitfalls:
                          type: array
                          items:
                            type: string
                          description: >-
                            Common pitfalls and considerations (only present
                            when cached plan is available)
                        reference_workbench_snippets:
                          type: array
                          items:
                            type: object
                            properties:
                              description:
                                type: string
                                description: Description of what the code snippet does
                              code:
                                type: string
                                description: Python code snippet for the workbench
                            required:
                              - description
                              - code
                          description: >-
                            Reference Python code snippets for processing tool
                            responses in the workbench (only present when cached
                            plan is available)
                        primary_tool_slugs:
                          type: array
                          items:
                            type: string
                          description: List of main tool slugs matching the search criteria
                        related_tool_slugs:
                          type: array
                          items:
                            type: string
                          description: List of related tool slugs that might be useful
                        toolkits:
                          type: array
                          items:
                            type: string
                          description: >-
                            List of unique toolkit slugs used by tools in this
                            query
                        plan_id:
                          type: string
                          description: ID of cached plan if available
                        cached_plan_usecase:
                          type: string
                          description: >-
                            Use case the cached plan was originally built for,
                            if a cached plan is available. May differ from
                            `use_case` when the cached plan was matched from a
                            similar query.
                        error:
                          type:
                            - string
                            - 'null'
                          description: >-
                            Error message if the search for this query failed,
                            null otherwise. Always present for failed queries.
                        memory:
                          type: object
                          additionalProperties:
                            type: array
                            items:
                              type: string
                          description: >-
                            Memory data relevant to this query, grouped by app.
                            Only present for non-cached search results.
                      required:
                        - index
                        - use_case
                        - primary_tool_slugs
                        - related_tool_slugs
                        - toolkits
                    description: >-
                      Per-query search results with tools, reasoning, and
                      memory. One entry per query in request order.
                  toolkit_connection_statuses:
                    type: array
                    items:
                      type: object
                      properties:
                        toolkit:
                          type: string
                          description: The toolkit slug identifier (e.g., "gmail", "slack")
                        description:
                          type: string
                          description: >-
                            Description of what the toolkit does and its
                            capabilities
                        has_active_connection:
                          type: boolean
                          description: Whether an active connection exists for this toolkit
                        connection_details:
                          type: object
                          additionalProperties: {}
                          description: >-
                            Connection details including auth config and
                            connected account IDs. Only present when
                            has_active_connection is true.
                        current_user_info:
                          type: object
                          additionalProperties: {}
                          description: >-
                            Information about the currently connected user
                            (email, name, etc.)
                        account_type:
                          type: string
                          enum:
                            - PRIVATE
                            - SHARED
                          description: >-
                            Sharing model for the connected account when
                            has_active_connection is true. PRIVATE is
                            owner-only; SHARED is reachable only when explicitly
                            pinned to the session.
                        accounts:
                          type: array
                          items:
                            type: object
                            properties:
                              id:
                                type: string
                                description: Unique identifier for this account
                              alias:
                                type: string
                                description: User-assigned alias for this account
                              user_info:
                                type: object
                                additionalProperties: {}
                                description: >-
                                  Information about the connected user (email,
                                  name, etc.)
                              status:
                                type: string
                                description: Connection status (e.g., "active")
                              created_at:
                                type: string
                                description: >-
                                  ISO 8601 timestamp of when the account was
                                  connected
                              is_default:
                                type: boolean
                                description: >-
                                  Whether this is the default account for the
                                  toolkit
                              account_type:
                                type: string
                                enum:
                                  - PRIVATE
                                  - SHARED
                                description: >-
                                  Sharing model for this connected account.
                                  PRIVATE is owner-only; SHARED is reachable
                                  from a tool-router session only when
                                  explicitly pinned.
                            required:
                              - id
                              - status
                              - created_at
                              - is_default
                          description: >-
                            List of connected accounts for this toolkit. Present
                            when multi-account is enabled.
                        account_selection:
                          type: string
                          enum:
                            - required
                          description: >-
                            When "required", the agent must specify which
                            account to use. Present only when multiple accounts
                            exist.
                        instant_account:
                          type: object
                          properties:
                            allowed_tool_slugs:
                              type: array
                              items:
                                type: string
                              description: >-
                                Tools of this toolkit that run on the Composio
                                instant account
                            prices:
                              type: object
                              additionalProperties:
                                $ref: '#/components/schemas/ToolPricing'
                              description: Price of each tool, keyed by tool slug.
                          required:
                            - allowed_tool_slugs
                          description: >-
                            Present when the toolkit is connected through the
                            Composio instant account rather than a connected
                            account of the user.
                        status_message:
                          type: string
                          description: >-
                            Human-readable message about the connection status
                            and next steps
                      required:
                        - toolkit
                        - description
                        - has_active_connection
                        - status_message
                    description: >-
                      Connection status for all toolkits mentioned across all
                      queries, with descriptions merged in.
                  tool_schemas:
                    type: object
                    additionalProperties:
                      type: object
                      properties:
                        toolkit:
                          type: string
                          description: The slug of the toolkit that provides this tool
                        tool_slug:
                          type: string
                          description: The slug of the tool
                        description:
                          type: string
                          description: Description of the tool
                        input_schema:
                          type: object
                          additionalProperties: {}
                          description: >-
                            Input schema for the tool (only present when
                            hasFullSchema is true)
                        output_schema:
                          type: object
                          additionalProperties: {}
                          description: >-
                            Output/response schema for the tool. Only included
                            when include_output_schemas is true.
                        hasFullSchema:
                          type: boolean
                          description: >-
                            Whether the full input_schema is included in this
                            response
                        schemaRef:
                          type: object
                          properties:
                            tool:
                              type: string
                              enum:
                                - COMPOSIO_GET_TOOL_SCHEMAS
                              description: Tool to call
                            args:
                              type: object
                              properties:
                                tool_slugs:
                                  type: array
                                  items:
                                    type: string
                                  description: Tool slugs to fetch schemas for
                              required:
                                - tool_slugs
                              description: Arguments to pass to the tool
                            message:
                              type: string
                              description: Instruction message for the LLM
                          required:
                            - tool
                            - args
                          description: >-
                            Reference to fetch full schema when hasFullSchema is
                            false
                      required:
                        - toolkit
                        - tool_slug
                    description: >-
                      Deduplicated tool definitions keyed by tool_slug for O(1)
                      lookup. Each tool appears once even if used in multiple
                      queries.
                  time_info:
                    type: object
                    properties:
                      current_time_utc:
                        type: string
                        description: Current time in ISO format (UTC)
                      current_time_utc_epoch_seconds:
                        type: number
                        description: Current time as Unix epoch timestamp in seconds
                      message:
                        type: string
                        description: >-
                          Important message about time handling and timezone
                          considerations
                    required:
                      - current_time_utc
                      - current_time_utc_epoch_seconds
                      - message
                    description: Time information for the query
                  session:
                    type: object
                    properties:
                      id:
                        type: string
                        description: >-
                          Session identifier to be passed to subsequent meta
                          tool calls as session_id.
                      generate_id:
                        type: boolean
                        description: Whether a fresh session id was generated in this call.
                      instructions:
                        type: string
                        description: LLM-facing guidance on how to reuse this session id
                    required:
                      - id
                      - generate_id
                      - instructions
                    description: Session info for correlating meta tool calls
                  next_steps_guidance:
                    type: array
                    items:
                      type: string
                    description: >-
                      Combined workflow guidance covering connections, planner,
                      and memory usage. Each element is a step instruction.
                required:
                  - success
                  - error
                  - results
                  - toolkit_connection_statuses
                  - tool_schemas
                  - time_info
                  - session
                  - next_steps_guidance
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '402':
          description: Payment required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '410':
          description: Gone
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '413':
          description: Payload too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Too many requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '502':
          description: Bad gateway
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - ApiKeyAuth: []
components:
  schemas:
    ToolPricing:
      type: object
      properties:
        description:
          type: string
          description: Human-readable pricing description.
        discount:
          type:
            - string
            - 'null'
          description: Discount on top of provider charges.
      description: Published pricing for the tool
      additionalProperties: false
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            message:
              type: string
            code:
              type: number
            slug:
              type: string
            status:
              type: number
            request_id:
              type: string
            suggested_fix:
              type: string
            errors:
              type: array
              items:
                type: string
          required:
            - message
            - code
            - slug
            - status
      required:
        - error
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: >-
        Your Composio project API key. Create or copy it from the Composio
        dashboard.
      x-default: your-project-api-key

````