---
title: "Search for tools using a query"
method: POST
path: "/api/v3/tool_router/session/{session_id}/search"
tags: ["Tool Router"]
---

# Search for tools using a query

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

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.

## Path parameters

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

## Request body

- object
  - `queries` object[], required — List of search queries to execute in parallel. Up to 7 queries supported.
    - `use_case` string, required — The task or use case to search tools for. Provide a detailed description to get the best results. Max 1024 characters.
    - `known_fields` string — Known field hints as key:value pairs (e.g., "channel_name:general, user_email:john@example.com"). Max 500 characters.
  - `model` string — Optional model hint for search/planning behavior (e.g., "gpt-4o"). Ignored if invalid.
  - `search_strategy` 'auto' | 'tool_search' — Search path to use. Defaults to auto. Use tool_search to bypass cached plans and run direct tool search.

## Response `200`

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

- object
  - `success` boolean, required — Whether all searches completed successfully. False if any query failed.
  - `error` string, nullable, required — Error message if any searches failed, null if all succeeded. Format: "X out of Y searches failed, reasons: <details>"
  - `results` object[], required — Per-query search results with tools, reasoning, and memory. One entry per query in request order.
    - `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` string[] — Workflow steps from cached plan (only present when cached plan is available)
    - `known_pitfalls` string[] — Common pitfalls and considerations (only present when cached plan is available)
    - `reference_workbench_snippets` object[] — Reference Python code snippets for processing tool responses in the workbench (only present when cached plan is available)
      - `description` string, required — Description of what the code snippet does
      - `code` string, required — Python code snippet for the workbench
    - `primary_tool_slugs` string[], required — List of main tool slugs matching the search criteria
    - `related_tool_slugs` string[], required — List of related tool slugs that might be useful
    - `toolkits` string[], required — List of unique toolkit slugs used by tools in this query
    - `plan_id` string — ID of cached plan if available
    - `error` string, nullable — 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.
  - `toolkit_connection_statuses` object[], required — Connection status for all toolkits mentioned across all queries, with descriptions merged in.
    - `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.
    - `current_user_info` object — Information about the currently connected user (email, name, etc.)
    - `account_type` 'PRIVATE' | 'SHARED' — 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` object[] — List of connected accounts for this toolkit. Present when multi-account is enabled.
      - `id` string, required — Unique identifier for this account
      - `alias` string — User-assigned alias for this account
      - `user_info` object — Information about the connected user (email, name, etc.)
      - `status` string, required — Connection status (e.g., "active")
      - `created_at` string, required — ISO 8601 timestamp of when the account was connected
      - `is_default` boolean, required — Whether this is the default account for the toolkit
      - `account_type` 'PRIVATE' | 'SHARED' — Sharing model for this connected account. PRIVATE is owner-only; SHARED is reachable from a tool-router session only when explicitly pinned.
    - `account_selection` 'required' — When "required", the agent must specify which account to use. Present only when multiple accounts exist.
    - `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.
  - `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` string[], required — Combined workflow guidance covering connections, planner, and memory usage. Each element is a step instruction.

## Other responses

- `400` — Bad request
- `401` — Unauthorized
- `403` — Forbidden
- `404` — Not found
- `413` — Payload too large
- `429` — Too many requests
- `500` — Internal server error
- `502` — Bad gateway

## Changes

- **2026-08-19** `a2d171c9d84a` — 1 info
  - added the new optional request property `search_strategy`

[Change history](https://skmtc.dev/composiohq/apis/composio-platform-api/changes/api/v3/tool_router/session/:session_id/search/post.md)

---

[API](https://skmtc.dev/composiohq/apis/composio-platform-api.md) · [All operations](https://skmtc.dev/composiohq/apis/composio-platform-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/composiohq/composio-platform-api/revisions/368fb7851f42/schema)