# Search for tools using a query

**Documentation:** /reference/api-reference/tool-router/postToolRouterSessionBySessionIdSearch

Search for tools matching a given use case query within a tool router session. Returns matching tool slugs, full tool schemas, toolkit connection statuses, and workflow guidance in a predictable format.

---

## POST `/api/v3/tool_router/session/{session_id}/search`

**Endpoint:** `https://backend.composio.dev/api/v3/tool_router/session/{session_id}/search`

**Summary:** Search for tools using a query

Search for tools matching a given use case query within a tool router session. Returns matching tool slugs, full tool schemas, toolkit connection statuses, and workflow guidance in a predictable format.

### Authentication

**ApiKeyAuth** - API Key in `header` header `x-api-key` OR **UserApiKeyAuth** - API Key in `header` header `x-user-api-key`

### Path Parameters

- `session_id` (string (toolRouterSessionId)) *(required)*: Tool router session ID (trs_*)

### Request Body

**Schema:**

- `queries` (array<object>) *(required)*: List of search queries to execute in parallel. Up to 7 queries supported.
  - Array items:
    - `use_case` (string) *(required)*: The task or use case to search tools for. Provide a detailed description to get the best results.
    - `known_fields` (string): Known field hints as key:value pairs (e.g., "channel_name:general, user_email:john@example.com")
- `model` (string): Optional model hint for search/planning behavior (e.g., "gpt-4o"). Ignored if invalid.

**Example:**

```json
{
  "queries": [
    {
      "use_case": "string",
      "known_fields": "string"
    }
  ],
  "model": "string"
}
```

### Responses

#### 200 - Successfully executed the search. Returns matching tool slugs, schemas, connection statuses, and guidance.

**Response Schema:**

- `success` (boolean) *(required)*: Whether all searches completed successfully. False if any query failed.
- `error` (string,null) *(required)*: Error message if any searches failed, null if all succeeded. Format: "X out of Y searches failed, reasons: <details>"
- `results` (array<object>) *(required)*: Per-query search results with tools, reasoning, and memory. One entry per query in request order.
  - Array items:
    - `index` (number) *(required)*: 1-based index of the query in the request
    - `use_case` (string) *(required)*: The use case that was searched
    - `execution_guidance` (string): Guidance message about the search results, particularly when a cached plan is available
    - `difficulty` (string): Task difficulty assessment (e.g., "easy - Simple single-tool operation with known parameters")
    - `recommended_plan_steps` (array<string>): Workflow steps from cached plan (only present when cached plan is available)
    - `known_pitfalls` (array<string>): Common pitfalls and considerations (only present when cached plan is available)
    - `reference_workbench_snippets` (array<object>): Reference Python code snippets for processing tool responses in the workbench (only present when cached plan is available)
      - Array items:
        - `description` (string) *(required)*: Description of what the code snippet does
        - `code` (string) *(required)*: Python code snippet for the workbench
    - `primary_tool_slugs` (array<string>) *(required)*: List of main tool slugs matching the search criteria
    - `related_tool_slugs` (array<string>) *(required)*: List of related tool slugs that might be useful
    - `toolkits` (array<string>) *(required)*: List of unique toolkit slugs used by tools in this query
    - `plan_id` (string): ID of cached plan if available
    - `error` (string,null): Error message if the search for this query failed, null otherwise. Always present for failed queries.
    - `memory` (object): Memory data relevant to this query, grouped by app. Only present for non-cached search results.
      - `[key: string]` (array<string>)
- `toolkit_connection_statuses` (array<object>) *(required)*: Connection status for all toolkits mentioned across all queries, with descriptions merged in.
  - Array items:
    - `toolkit` (string) *(required)*: The toolkit slug identifier (e.g., "gmail", "slack")
    - `description` (string) *(required)*: Description of what the toolkit does and its capabilities
    - `has_active_connection` (boolean) *(required)*: Whether an active connection exists for this toolkit
    - `connection_details` (object): Connection details including auth config and connected account IDs. Only present when has_active_connection is true.
      - `[key: string]` (any)
    - `current_user_info` (object): Information about the currently connected user (email, name, etc.)
      - `[key: string]` (any)
    - `status_message` (string) *(required)*: Human-readable message about the connection status and next steps
- `tool_schemas` (object) *(required)*: Deduplicated tool definitions keyed by tool_slug for O(1) lookup. Each tool appears once even if used in multiple queries.
  - `[key: string]` (object)
    - `toolkit` (string) *(required)*: The slug of the toolkit that provides this tool
    - `tool_slug` (string) *(required)*: The slug of the tool
    - `description` (string): Description of the tool
    - `input_schema` (object): Input schema for the tool (only present when hasFullSchema is true)
      - `[key: string]` (any)
    - `output_schema` (object): Output/response schema for the tool
      - `[key: string]` (any)
    - `hasFullSchema` (boolean): Whether the full input_schema is included in this response
    - `schemaRef` (object): Reference to fetch full schema when hasFullSchema is false
      - `tool` (enum: "COMPOSIO_GET_TOOL_SCHEMAS") *(required)*: Tool to call
      - `args` (object) *(required)*: Arguments to pass to the tool
        - `tool_slugs` (array<string>) *(required)*: Tool slugs to fetch schemas for
      - `message` (string) *(required)*: Instruction message for the LLM
- `time_info` (object) *(required)*: Time information for the query
  - `current_time_utc` (string) *(required)*: Current time in ISO format (UTC)
  - `current_time_utc_epoch_seconds` (number) *(required)*: Current time as Unix epoch timestamp in seconds
  - `message` (string) *(required)*: Important message about time handling and timezone considerations
- `session` (object) *(required)*: Session info for correlating meta tool calls
  - `id` (string) *(required)*: Session identifier to be passed to subsequent meta tool calls as session_id.
  - `generate_id` (boolean) *(required)*: Whether a fresh session id was generated in this call.
  - `instructions` (string) *(required)*: LLM-facing guidance on how to reuse this session id
- `next_steps_guidance` (array<string>) *(required)*: Combined workflow guidance covering connections, planner, and memory usage. Each element is a step instruction.

**Example Response:**

```json
{
  "success": true,
  "error": null,
  "results": [
    {
      "index": 1,
      "use_case": "string",
      "execution_guidance": "string",
      "difficulty": "string",
      "recommended_plan_steps": [
        "..."
      ],
      "known_pitfalls": [
        "..."
      ],
      "reference_workbench_snippets": [
        "..."
      ],
      "primary_tool_slugs": [
        "..."
      ],
      "related_tool_slugs": [
        "..."
      ],
      "toolkits": [
        "..."
      ],
      "plan_id": "string",
      "error": null,
      "memory": {
        "key": "..."
      }
    }
  ],
  "toolkit_connection_statuses": [
    {
      "toolkit": "string",
      "description": "string",
      "has_active_connection": true,
      "connection_details": {
        "key": "..."
      },
      "current_user_info": {
        "key": "..."
      },
      "status_message": "string"
    }
  ],
  "tool_schemas": {
    "key": {
      "toolkit": "string",
      "tool_slug": "string",
      "description": "string",
      "input_schema": {
        "key": "..."
      },
      "output_schema": {
        "key": "..."
      },
      "hasFullSchema": true,
      "schemaRef": {
        "tool": "...",
        "args": "...",
        "message": "..."
      }
    }
  },
  "time_info": {
    "current_time_utc": "string",
    "current_time_utc_epoch_seconds": 1,
    "message": "string"
  },
  "session": {
    "id": "string",
    "generate_id": true,
    "instructions": "string"
  },
  "next_steps_guidance": [
    "string"
  ]
}
```

#### 400 - Bad request

**Response Schema:**

- `error` (object) *(required)*
  - `message` (string) *(required)*
  - `code` (number) *(required)*
  - `slug` (string) *(required)*
  - `status` (number) *(required)*
  - `request_id` (string)
  - `suggested_fix` (string)
  - `errors` (array<string>)

#### 401 - Unauthorized

**Response Schema:**

- `error` (object) *(required)*
  - `message` (string) *(required)*
  - `code` (number) *(required)*
  - `slug` (string) *(required)*
  - `status` (number) *(required)*
  - `request_id` (string)
  - `suggested_fix` (string)
  - `errors` (array<string>)

#### 403 - Forbidden

**Response Schema:**

- `error` (object) *(required)*
  - `message` (string) *(required)*
  - `code` (number) *(required)*
  - `slug` (string) *(required)*
  - `status` (number) *(required)*
  - `request_id` (string)
  - `suggested_fix` (string)
  - `errors` (array<string>)

#### 404 - Not found

**Response Schema:**

- `error` (object) *(required)*
  - `message` (string) *(required)*
  - `code` (number) *(required)*
  - `slug` (string) *(required)*
  - `status` (number) *(required)*
  - `request_id` (string)
  - `suggested_fix` (string)
  - `errors` (array<string>)

#### 500 - Internal server error

**Response Schema:**

- `error` (object) *(required)*
  - `message` (string) *(required)*
  - `code` (number) *(required)*
  - `slug` (string) *(required)*
  - `status` (number) *(required)*
  - `request_id` (string)
  - `suggested_fix` (string)
  - `errors` (array<string>)

### Example cURL Request

```bash
curl -X POST "https://backend.composio.dev/api/v3/tool_router/session/string/search" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "queries": [
      {
        "use_case": "string",
        "known_fields": "string"
      }
    ],
    "model": "string"
  }'
```