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

> Tool Server Info: Composio connects 500+ apps—Slack, GitHub, Notion, Google Workspace (Gmail, Sheets, Drive, Calendar...

**Slug:** `COMPOSIO_SEARCH_TOOLS`

**Tags:** important, openWorldHint, readOnlyHint

Discovers the right tools across 500+ apps for a task and returns them with an execution plan, connection status, and the `session_id` that ties the rest of the workflow together.

## When to use it

Call `COMPOSIO_SEARCH_TOOLS` first, at the start of any task that touches an external app or service. Run it again whenever the user pivots to a new use case so you get a fresh `session_id` and a plan scoped to the new work.

> [!NOTE]
>
> Split a request into atomic queries (one query per tool call) and name the app in each query so intent stays scoped. The response tells you which toolkits already have an active connection and which need `COMPOSIO_MANAGE_CONNECTIONS`.

## Input parameters

**queries** `array\<object\>` *required*

Structured English search queries to process in parallel. Split independent app/API actions into separate queries, including hidden prerequisites. Each query returns 4-6 tools.

**properties**

**use\_case** `string` *required*

Provide a normalized English description of the complete use case to enable precise planning. Focus on the specific action and intended outcome. Include any specific apps if mentioned by user in each use\_case. Do NOT include personal identifiers (names, emails, IDs) here — put those in known\_fields.

**known\_fields** `string`

Provide known workflow inputs as a single English string of comma-separated key:value pairs (not an array). Keep 1-2 short, structured items - stable identifiers, names, emails, or settings only. Omit if not relevant. No free-form or long text (messages, notes, descriptions).

**session** `object`

Session context for correlating meta tool calls within a workflow. Always pass this parameter. Use \{generate\_id: true} for new workflows or \{id: "EXISTING\_ID"} to continue existing workflows.

**properties**

**id** `string`

Existing session identifier for the current workflow to reuse across calls.

**generate\_id** `boolean`

Set to true for the first search call of a new usecase/workflow to generate a new session ID. When user pivots to a different task, set this true. If omitted or false with an existing session.id, the provided session ID will be reused.

**model** `string`

Client LLM model name (recommended). Used to optimize planning/search behavior. Ignored if omitted or invalid.

**search\_strategy** `string`

Search path to use. Use auto normally. If the returned plan does not match the current request or an expected tool is missing, retry with tool\_search to bypass cached plans and run direct tool search. Default: `auto`. Possible values: `auto`, `tool_search`.

## Response

**data** `object`

Data from the action execution

**properties**

**results** `array\<object\>`

Per-query search results with tools, reasoning, and memory. One entry per query in request order.

**properties**

**index** `integer`

1-based index of the query in the request

**use\_case** `string`

The use case that was searched

**primary\_tool\_slugs** `array\<string\>`

List of main tool slugs matching the search criteria

**related\_tool\_slugs** `array\<string\>`

List of related tool slugs that might be useful

**toolkits** `array\<string\>`

List of unique toolkit slugs used by tools in this query

**reasoning** `string`

Reasoning for the search results

**task\_difficulty** `string`

Assessment of task difficulty for this specific query

**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)

**properties**

**description** `string`

Description of what the code snippet does

**code** `string`

Python code snippet for the workbench, wrapped in triple backticks

**error** `string`

Error message if the search failed, null otherwise

**tool\_schemas** `object`

Deduplicated tool definitions keyed by tool\_slug for O(1) lookup. Each tool appears once even if used in multiple queries.

**toolkit\_connection\_statuses** `array\<object\>`

Connection status for all toolkits mentioned across all queries, with descriptions merged in

**properties**

**toolkit** `string`

The toolkit slug identifier (e.g., "gmail", "slack")

**description** `string`

Description of what the toolkit does and its capabilities

**has\_active\_connection** `boolean`

Whether an active connection exists for this toolkit

**connection\_details** `object`

Connection details including auth config and connected account IDs

**current\_user\_info** `object`

Information about the currently connected user (email, name, etc.)

**account\_type** `string`

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. Possible values: `PRIVATE`, `SHARED`.

**status\_message** `string`

Human-readable message about the connection status and next steps

**time\_info** `object`

Time information for the query

**properties**

**current\_time\_utc** `string`

Current time in ISO format (UTC)

**current\_time\_utc\_epoch\_seconds** `integer`

Current time as Unix epoch timestamp in seconds

**message** `string`

Important message about time handling and timezone considerations

**session** `object`

Session info for correlating meta tool calls

**properties**

**id** `string`

Session identifier to be passed to subsequent meta tool calls

**generate\_id** `boolean`

Whether a fresh session id was generated in this call

**instructions** `string`

LLM-facing guidance on how to reuse this session id

**next\_steps\_guidance** `array\<string\>`

Combined workflow guidance covering connections, planner, and memory usage. Each element is a step instruction.

**error** `string`

Error if any occurred during the execution. Format: "X out of Y searches failed, reasons: \<details>"

**successful** `boolean`

Whether all searches completed successfully. False if any query failed
