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

# Search for tools using a query

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

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

## 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.
    - `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").
  - `experimental` object — Inline custom tools and toolkits for this request. v3.1 sessions do not persist customs — pass them on every request that needs them.
    - `custom_toolkits` object[] — Custom toolkits with grouped tools. Toolkit slugs must not conflict with existing Composio toolkits. All tools are no-auth.
      - `slug` string, required — Unique slug for the toolkit. Must not conflict with existing Composio toolkit slugs. Alphanumeric, underscores, and hyphens only.
      - `name` string, required — Display name shown to the LLM and in search results.
      - `description` string, required — Used for BM25 search matching and shown in toolkit connection statuses.
      - `preload` boolean — SDK hint for direct custom-tool exposure. Not stored in session config; echoed in create/attach responses for inline custom definitions.
      - `tools` object[], required — Tools in this custom toolkit
        - `slug` string, required — Tool slug. Combined with toolkit slug to form LOCAL_<TOOLKIT>_<TOOL> (max 60 chars total).
        - `name` string, required — Human-readable display name
        - `description` string, required — Used for BM25 search matching and shown to the LLM.
        - `input_schema` object, required — Must have type: "object" and a properties field.
        - `output_schema` object — Optional output schema for the tool response.
        - `preload` boolean — SDK hint for direct custom-tool exposure. Not stored in session config; echoed in create/attach responses for inline custom definitions.
    - `custom_tools` object[] — Custom tools to include in search. Standalone tools need no auth. Tools with extends_toolkit inherit the Composio toolkit's connection.
      - `slug` string, required — Tool slug. Forms LOCAL_<TOOL> (standalone) or LOCAL_<TOOLKIT>_<TOOL> (extending). Max 60 chars total.
      - `name` string, required — Human-readable display name
      - `description` string, required — Used for BM25 search matching and shown to the LLM.
      - `input_schema` object, required — Must have type: "object" and a properties field.
      - `output_schema` object — JSON Schema describing tool output (optional)
      - `extends_toolkit` string — 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).
      - `preload` boolean — SDK hint for direct custom-tool exposure. Not stored in session config; echoed in create/attach responses for inline custom definitions.

## 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

---

[API](https://skmtc.net/composiohq/apis/composio-platform-api-v3-1.md) · [All operations](https://skmtc.net/composiohq/apis/composio-platform-api-v3-1/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/composiohq/composio-platform-api-v3-1/versions/4239836857f8/schema)