Skip to content

Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

docs: improve how-composio-works page from review feedback

Sushmitha Malleshafb9c0c937e1
diff --git a/docs/content/docs/how-composio-works.mdx b/docs/content/docs/how-composio-works.mdx
index 1cd0295d1..c88bf0306 100644
--- a/docs/content/docs/how-composio-works.mdx
+++ b/docs/content/docs/how-composio-works.mdx
@@ -85,12 +85,18 @@ graph TD
classDef annotation stroke-dasharray: 5 5
```
-`SEARCH_TOOLS` discovers the right toolkit tools for the task. `MULTI_EXECUTE_TOOL` runs them against the external API with the user's credentials. If the user isn't authenticated yet, `MANAGE_CONNECTIONS` handles that in between.
+`COMPOSIO_SEARCH_TOOLS` discovers the right toolkit tools for the task. `COMPOSIO_MULTI_EXECUTE_TOOL` runs them against the external API with the user's credentials. If the user isn't authenticated yet, `COMPOSIO_MANAGE_CONNECTIONS` handles that in between.
For large responses or bulk operations (labeling hundreds of emails, processing CSVs), the agent uses `COMPOSIO_REMOTE_WORKBENCH` to run Python with helper functions like `invoke_llm` and `run_composio_tool`.
<Card icon={<BookOpen />} title="Tools and toolkits" href="/docs/tools-and-toolkits" description="Meta tools, context management, and execution" />
+## Tool discovery
+
+When the agent calls `COMPOSIO_SEARCH_TOOLS`, Composio runs a Vector + BM25 hybrid search across all available toolkits to find the right tools for a given use-case query. The search returns matching tool schemas, connection statuses, and related tools in a single call.
+
+Composio also surfaces **learned plans** from past executions. These are step-by-step workflows that have worked before for similar tasks, guiding the LLM to better perform an operation without starting from scratch.
+
## Authentication
When a tool requires authentication and the user hasn't connected yet, the agent uses `COMPOSIO_MANAGE_CONNECTIONS` to generate a **Connect Link**, a hosted page where the user authorizes access.
@@ -122,6 +128,19 @@ When the agent calls `COMPOSIO_MULTI_EXECUTE_TOOL`, Composio resolves the sessio
Your agent doesn't touch API credentials or handle token refresh. Composio resolves credentials from the session and connected account, makes the authenticated call, and returns the result.
+## Remote workbench
+
+Large responses from `COMPOSIO_MULTI_EXECUTE_TOOL` are automatically synced to a secure remote workbench. Instead of stuffing thousands of lines into the context window, the agent can work with the data inside the workbench:
+
+- **Reading** files and tool responses
+- **Searching** across large outputs
+- **Writing and executing** Python code to transform, filter, or aggregate data
+- **Calling Composio tools** via the `run_composio_tool` helper for bulk orchestration
+
+This keeps the agent's context window lean while still letting it handle operations like labeling hundreds of emails, processing CSV exports, or summarizing long API responses.
+
+<Card icon={<BookOpen />} title="Workbench" href="/docs/workbench" description="Persistent Python sandbox for large-context operations" />
+
## Direct tool execution
If you know exactly which tools you need, you can skip the meta tool pattern and execute tools directly: