Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
TypeScript agentic-aiagentsaiai-agentsaiagentsdeveloper-toolsfunction-callinggpt-4javascriptjsllmllmopsmcppythonremote-mcp-serverssetypescript
docs: add Meta Tools reference section
Sushmitha Mallesh788255f03003
diff --git a/.github/workflows/docs-update-data.yml b/.github/workflows/docs-update-data.ymlindex 96ce02f90..806815b5f 100644--- a/.github/workflows/docs-update-data.yml+++ b/.github/workflows/docs-update-data.yml@@ -49,18 +49,21 @@ jobs:- name: Generate API index pagesrun: bun run generate:api-index+ - name: Generate meta tools reference+ run: bun run generate:meta-tools+- name: Check for changesid: changesrun: |cd ..- git add -N docs/public/data/ docs/public/openapi.json docs/content/reference/api-reference/ 2>/dev/null || true- if git diff --quiet docs/public/data/ docs/public/openapi.json docs/content/reference/api-reference/ 2>/dev/null; then+ git add -N docs/public/data/ docs/public/openapi.json docs/content/reference/api-reference/ docs/content/reference/meta-tools/ 2>/dev/null || true+ if git diff --quiet docs/public/data/ docs/public/openapi.json docs/content/reference/api-reference/ docs/content/reference/meta-tools/ 2>/dev/null; thenecho "has_changes=false" >> $GITHUB_OUTPUTecho "No changes detected"elseecho "has_changes=true" >> $GITHUB_OUTPUTecho "Changes detected:"- git diff --stat docs/public/data/ docs/public/openapi.json docs/content/reference/api-reference/ 2>/dev/null || true+ git diff --stat docs/public/data/ docs/public/openapi.json docs/content/reference/api-reference/ docs/content/reference/meta-tools/ 2>/dev/null || truefi- name: Create Pull Request@@ -77,6 +80,8 @@ jobs:- `docs/public/data/toolkits-list.json` - Light toolkit list- `docs/public/openapi.json` - OpenAPI specification- `docs/content/reference/api-reference/*.mdx` - API index pages+ - `docs/public/data/meta-tools.json` - Meta tools schemas+ - `docs/content/reference/meta-tools/*.mdx` - Meta tools reference pages${{ github.event_name == 'repository_dispatch' && format('Hermes commit: {0}', github.event.client_payload.hermes_commit) || '' }}branch: docs/auto-update-data@@ -85,3 +90,4 @@ jobs:docs/public/data/docs/public/openapi.jsondocs/content/reference/api-reference/+ docs/content/reference/meta-tools/diff --git a/docs/.claude/context/pipelines.md b/docs/.claude/context/pipelines.mdindex 770eabf5f..59b87fc6d 100644--- a/docs/.claude/context/pipelines.md+++ b/docs/.claude/context/pipelines.md@@ -6,7 +6,7 @@ Reference for all GitHub Actions workflows related to docs.| Workflow | File | Trigger | What it does ||---|---|---|---|-| **Update Data** | `docs-update-data.yml` | Cron (every 5h), `repository_dispatch` (Apollo deploy), manual | Fetches toolkits data, OpenAPI spec, and API index pages. Creates PR via `peter-evans/create-pull-request` targeting `next`. |+| **Update Data** | `docs-update-data.yml` | Cron (every 5h), `repository_dispatch` (Apollo deploy), manual | Fetches toolkits data, OpenAPI spec, API index pages, and meta tools reference. Creates PR via `peter-evans/create-pull-request` targeting `next`. || **Sync Connect Clients** | `docs.sync-connect-clients.yml` | Cron (daily 8 AM UTC), manual | Claude Code action syncs client definitions from `ComposioHQ/composio_dashboard` to `composio-connect.mdx`. Creates PR targeting `next`. Agent instructions: `docs/.claude/agents/connect-clients-sync.md`. || **Changelog → Docs** | `docs.changelog-to-docs.yml` | Push to `next` (changelog files) | Codex action reads new changelog entries and updates docs pages. Creates PR targeting `next`. Agent instructions: `docs/.claude/agents/changelog-docs-updater.md`. || **Check Links** | `docs-check-links.yml` | PR changes to `docs/` | Runs `bun run scripts/validate-links.ts` to catch broken internal links. |diff --git a/docs/CLAUDE.md b/docs/CLAUDE.mdindex 51003af8b..898ea74f2 100644--- a/docs/CLAUDE.md+++ b/docs/CLAUDE.md@@ -65,11 +65,13 @@ Detailed documentation for Claude is organized in `.claude/`:5. **Toolkits data** - `public/data/toolkits.json` must exist; errors are thrown, not ignored.-6. **Test on mobile** - Fumadocs nav differs on mobile. Avoid assumptions about horizontal layout.+6. **Meta tools data** - `public/data/meta-tools.json` and `content/reference/meta-tools/` are auto-generated by `bun run generate:meta-tools` (fetches from Tool Router API). Updated by CI alongside toolkits data. The `MetaToolDetailServer` component reads from the JSON at build time — do NOT register it in `mdx-components.tsx` (causes `fs` to leak into client bundle).-7. **Toolkit FAQ files** - FAQ snippets live in `content/toolkits/faq/{slug}.md`. They're plain markdown (no frontmatter) embedded in toolkit pages at build time, not standalone Fumadocs pages. They're excluded from the toolkits Fumadocs source via `files: ['**/*', '!faq/**']` in `source.config.ts` but still scanned by the link checker.+7. **Test on mobile** - Fumadocs nav differs on mobile. Avoid assumptions about horizontal layout.-8. **Link checker** - `scripts/validate-links.ts` validates all internal links. It needs `bunfig.toml` (Bun preload for fumadocs-mdx) to run. Key details:+8. **Toolkit FAQ files** - FAQ snippets live in `content/toolkits/faq/{slug}.md`. They're plain markdown (no frontmatter) embedded in toolkit pages at build time, not standalone Fumadocs pages. They're excluded from the toolkits Fumadocs source via `files: ['**/*', '!faq/**']` in `source.config.ts` but still scanned by the link checker.++9. **Link checker** - `scripts/validate-links.ts` validates all internal links. It needs `bunfig.toml` (Bun preload for fumadocs-mdx) to run. Key details:- Populate keys use `(home)/` prefix to match the `app/(home)/` route group- Fragment validation falls back to parsing raw markdown headings (since `data.toc` is unavailable outside Next.js)- Dynamic toolkit pages are validated against slugs from `public/data/toolkits.json`diff --git a/docs/app/llms.mdx/[[...slug]]/route.ts b/docs/app/llms.mdx/[[...slug]]/route.tsindex 865787f37..4ed671e9f 100644--- a/docs/app/llms.mdx/[[...slug]]/route.ts+++ b/docs/app/llms.mdx/[[...slug]]/route.ts@@ -14,6 +14,8 @@ import { notFound } from 'next/navigation';import { readFile } from 'fs/promises';import { join } from 'path';import { getAllToolkits, getToolkitBySlug } from '@/lib/toolkit-data';+import { getAllMetaTools, getMetaToolBySlug } from '@/lib/meta-tools-data';+import type { MetaTool, MetaToolParameter } from '@/lib/meta-tools-data';import type { Toolkit, Tool, Trigger, ParameterSchema } from '@/types/toolkit';import { processSchema, toolFromApi } from '@/lib/toolkit-schema';@@ -742,6 +744,94 @@ async function generateToolkitsIndex(): Promise<string> {return lines.join('\n');}+const LLM_FOOTER = '\n\n---\n\n📚 **More documentation:** [View all docs](https://docs.composio.dev/llms.txt) | [Glossary](https://docs.composio.dev/llms.mdx/docs/glossary) | [Cookbooks](https://docs.composio.dev/llms.mdx/cookbooks) | [API Reference](https://docs.composio.dev/llms.mdx/reference)';++// Render meta tool parameters as markdown+function renderMetaToolParams(properties: Record<string, MetaToolParameter>, indent = 0): string[] {+ const lines: string[] = [];+ const prefix = ' '.repeat(indent);++ for (const [name, param] of Object.entries(properties)) {+ const typeStr = param.type === 'array' && param.items && typeof param.items === 'object' && (param.items as Record<string, unknown>).type+ ? `array<${(param.items as Record<string, unknown>).type}>`+ : param.type;+ const reqMark = param.required ? ' *(required)*' : '';+ const desc = param.description+ ? `: ${param.description.replace(/\*\*/g, '').replace(/__/g, '').replace(/\n+/g, ' ').trim()}`+ : '';+ const defaultStr = param.default !== undefined && param.default !== null && param.default !== ''+ ? ` (default: \`${String(param.default)}\`)`+ : '';+ const enumStr = param.enum && param.enum.length > 0+ ? ` — values: ${param.enum.map(v => `\`${v}\``).join(', ')}`+ : '';++ lines.push(`${prefix}- \`${name}\` (${typeStr})${reqMark}${desc}${defaultStr}${enumStr}`);++ if (param.properties && Object.keys(param.properties).length > 0) {+ lines.push(...renderMetaToolParams(param.properties, indent + 1));+ }++ const items = param.items && typeof param.items === 'object' ? param.items as Record<string, unknown> : null;+ if (items?.properties && typeof items.properties === 'object' && Object.keys(items.properties as object).length > 0) {+ lines.push(`${prefix} - Array items:`);+ lines.push(...renderMetaToolParams(items.properties as Record<string, MetaToolParameter>, indent + 2));+ }+ }++ return lines;+}++// Generate markdown for a single meta tool+function metaToolToMarkdown(tool: MetaTool): string {+ const lines: string[] = [+ `# ${tool.displayName}`,+ '',+ `**Slug:** \`${tool.slug}\``,+ ];++ if (tool.tags.length > 0) {+ lines.push(`**Tags:** ${tool.tags.join(', ')}`);+ }++ lines.push('');++ const inputProps = tool.inputParameters?.properties || {};+ if (Object.keys(inputProps).length > 0) {+ lines.push('## Input Parameters', '');+ lines.push(...renderMetaToolParams(inputProps));+ lines.push('');+ }++ const responseProps = tool.responseSchema?.properties || {};+ if (Object.keys(responseProps).length > 0) {+ lines.push('## Response', '');+ lines.push(...renderMetaToolParams(responseProps));+ lines.push('');+ }++ return lines.join('\n') + LLM_FOOTER;+}++// Generate markdown index for all meta tools+function metaToolsIndexToMarkdown(tools: MetaTool[]): string {+ const lines: string[] = [+ '# Meta Tools',+ '',+ 'Meta tools are system-level tools available in sessions. They handle tool discovery, execution, authentication, and sandboxing.',+ '',+ '| Tool | Tags |',+ '|------|------|',+ ];++ for (const tool of tools) {+ const tags = tool.tags.length > 0 ? tool.tags.join(', ') : '—';+ lines.push(`| [\`${tool.slug}\`](/reference/meta-tools/${tool.slug.toLowerCase().replace('composio_', '')}.md) | ${tags} |`);+ }++ return lines.join('\n') + LLM_FOOTER;+}+export async function GET(_req: Request,{ params }: { params: Promise<{ slug?: string[] }> }@@ -790,6 +880,27 @@ export async function GET(notFound();}+ // Special handling for meta tools - /reference/meta-tools and /reference/meta-tools/{slug}+ if (prefix === 'reference' && rest[0] === 'meta-tools') {+ if (rest.length === 1) {+ // Index page+ const tools = await getAllMetaTools();+ return new Response(metaToolsIndexToMarkdown(tools), {+ headers: { 'Content-Type': 'text/markdown; charset=utf-8' },+ });+ }+ if (rest.length === 2) {+ // Individual tool page — match by page slug (e.g., "search_tools")+ const tools = await getAllMetaTools();+ const tool = tools.find(t => t.slug.toLowerCase().replace('composio_', '') === rest[1]);+ if (tool) {+ return new Response(metaToolToMarkdown(tool), {+ headers: { 'Content-Type': 'text/markdown; charset=utf-8' },+ });+ }+ }+ }+// Handle 'reference' specially - uses async getReferenceSource() for OpenAPI pages// eslint-disable-next-line @typescript-eslint/no-explicit-anylet pageSource: any;diff --git a/docs/components/meta-tools/meta-tool-detail.tsx b/docs/components/meta-tools/meta-tool-detail.tsxnew file mode 100644index 000000000..ab9dc39c4--- /dev/null+++ b/docs/components/meta-tools/meta-tool-detail.tsx@@ -0,0 +1,172 @@+'use client';++import { useState } from 'react';+import type { MetaTool, MetaToolParameter } from '@/lib/meta-tools-data';+import {+ Collapsible,+ CollapsibleContent,+ CollapsibleTrigger,+} from 'fumadocs-ui/components/ui/collapsible';+import { cn } from '@/lib/utils';+import { ChevronDown, ChevronRight } from 'lucide-react';++const TAG_LABELS: Record<string, { label: string; className: string }> = {+ readOnlyHint: {+ label: 'Read-only',+ className: 'bg-emerald-500/10 text-emerald-700 dark:text-emerald-400 border-emerald-500/20',+ },+ destructiveHint: {+ label: 'Destructive',+ className: 'bg-red-500/10 text-red-700 dark:text-red-400 border-red-500/20',+ },+ idempotentHint: {+ label: 'Idempotent',+ className: 'bg-blue-500/10 text-blue-700 dark:text-blue-400 border-blue-500/20',+ },+ openWorldHint: {+ label: 'External',+ className: 'bg-purple-500/10 text-purple-700 dark:text-purple-400 border-purple-500/20',+ },+ important: {+ label: 'Important',+ className: 'bg-amber-500/10 text-amber-700 dark:text-amber-400 border-amber-500/20',+ },+};++function TagBadge({ tag }: { tag: string }) {+ const info = TAG_LABELS[tag];+ if (!info) return null;+ return (+ <span className={cn('inline-flex items-center rounded-md border px-2 py-0.5 text-xs font-medium', info.className)}>+ {info.label}+ </span>+ );+}++function ParameterRow({ name, param, isLast, showRequired = true }: { name: string; param: MetaToolParameter; isLast: boolean; showRequired?: boolean }) {+ const hasNested = param.properties && Object.keys(param.properties).length > 0;+ const items = param.items && typeof param.items === 'object' ? param.items as Record<string, unknown> : null;+ const itemsHaveProperties = items && typeof items.properties === 'object' && Object.keys(items.properties as object).length > 0;+ const [isOpen, setIsOpen] = useState(false);++ // Show array<itemType> for simple item types+ const typeLabel = param.type === 'array' && items?.type && !itemsHaveProperties+ ? `array<${items.type}>`+ : param.type;++ return (+ <div className={cn(!isLast && 'border-b border-fd-border')}>+ <div className="py-3">+ <div className="flex flex-wrap items-center gap-2">+ <code className="text-sm font-semibold font-mono text-fd-foreground">{name}</code>+ <span className="text-xs font-mono text-fd-muted-foreground">{typeLabel}</span>+ {showRequired && param.required && (+ <span className="text-xs font-medium text-red-500 dark:text-red-400">Required</span>+ )}+ {param.default !== undefined && param.default !== null && param.default !== '' && (+ <span className="text-xs text-fd-muted-foreground">+ Default: <code className="rounded border border-fd-border px-1 py-0.5 text-xs">{String(param.default)}</code>+ </span>+ )}+ </div>+ {param.description && (+ <p className="mt-1.5 text-sm text-fd-muted-foreground leading-relaxed">+ {param.description.replace(/\*\*/g, '').replace(/__/g, '').replace(/\n+/g, ' ').trim()}+ </p>+ )}+ {param.enum && param.enum.length > 0 && (+ <div className="mt-2">+ <span className="text-xs text-fd-muted-foreground">Possible values: </span>+ <span className="inline-flex flex-wrap gap-1 mt-0.5">+ {param.enum.map((v) => (+ <code key={v} className="rounded border border-fd-border px-1.5 py-0.5 text-xs font-mono text-fd-muted-foreground">+ {v}+ </code>+ ))}+ </span>+ </div>+ )}+ {param.examples && param.examples.length > 0 && (+ <div className="mt-2">+ <span className="text-xs text-fd-muted-foreground">Example: </span>+ <span className="inline-flex flex-wrap gap-1 mt-0.5">+ {param.examples.map((ex, i) => (+ <code key={i} className="rounded border border-fd-border px-1.5 py-0.5 text-xs font-mono text-fd-muted-foreground">+ {typeof ex === 'string' ? ex : JSON.stringify(ex)}+ </code>+ ))}+ </span>+ </div>+ )}+ {(hasNested || itemsHaveProperties) && (+ <Collapsible open={isOpen} onOpenChange={setIsOpen} className="mt-2">+ <CollapsibleTrigger className="flex items-center gap-1 text-xs text-fd-muted-foreground hover:text-fd-foreground font-medium transition-colors">+ {isOpen ? <ChevronDown className="h-3 w-3" /> : <ChevronRight className="h-3 w-3" />}+ {hasNested+ ? `Show ${Object.keys(param.properties!).length} properties`+ : `Show ${Object.keys((items!.properties as object)).length} item properties`}+ </CollapsibleTrigger>+ <CollapsibleContent>+ <div className="mt-2 pl-3 border-l-2 border-fd-border">+ <ParameterList parameters={(hasNested ? param.properties! : items!.properties) as Record<string, MetaToolParameter>} showRequired={showRequired} />+ </div>+ </CollapsibleContent>+ </Collapsible>+ )}+ </div>+ </div>+ );+}++function ParameterList({ parameters, showRequired = true }: { parameters: Record<string, MetaToolParameter>; showRequired?: boolean }) {+ const entries = Object.entries(parameters);+ return (+ <div>+ {entries.map(([name, param], idx) => (+ <ParameterRow key={name} name={name} param={param} isLast={idx === entries.length - 1} showRequired={showRequired} />+ ))}+ </div>+ );+}++function SchemaSection({ title, schema, showRequired = true }: { title: string; schema: { type: string; properties: Record<string, MetaToolParameter> }; showRequired?: boolean }) {+ const properties = schema.properties || {};+ const entries = Object.entries(properties);++ if (entries.length === 0) return null;++ return (+ <div>+ <h3 className="text-base font-semibold text-fd-foreground mb-3">{title}</h3>+ <div className="rounded-lg border border-fd-border bg-fd-card">+ <div className="px-4">+ <ParameterList parameters={properties} showRequired={showRequired} />+ </div>+ </div>+ </div>+ );+}++export function MetaToolDetail({ tool }: { tool: MetaTool }) {+ return (+ <div className="space-y-6">+ {/* Header */}+ <div>+ {tool.tags.length > 0 && (+ <div className="flex flex-wrap items-center gap-2 mb-3">+ {tool.tags.map((tag) => (+ <TagBadge key={tag} tag={tag} />+ ))}+ </div>+ )}+ <code className="text-sm font-mono text-fd-muted-foreground">{tool.slug}</code>+ </div>++ {/* Input Parameters */}+ <SchemaSection title="Input Parameters" schema={tool.inputParameters} />++ {/* Response */}+ <SchemaSection title="Response" schema={tool.responseSchema} showRequired={false} />+ </div>+ );+}diff --git a/docs/components/meta-tools/meta-tool-page.tsx b/docs/components/meta-tools/meta-tool-page.tsxnew file mode 100644index 000000000..29539bd1f--- /dev/null+++ b/docs/components/meta-tools/meta-tool-page.tsx@@ -0,0 +1,8 @@+import { getMetaToolBySlug } from '@/lib/meta-tools-data';+import { MetaToolDetail } from './meta-tool-detail';++export async function MetaToolDetailServer({ slug }: { slug: string }) {+ const tool = await getMetaToolBySlug(slug);+ if (!tool) return <p>Meta tool not found: {slug}</p>;+ return <MetaToolDetail tool={tool} />;+}diff --git a/docs/content/docs/glossary.mdx b/docs/content/docs/glossary.mdxindex 2ca5a80d7..862a51293 100644--- a/docs/content/docs/glossary.mdx+++ b/docs/content/docs/glossary.mdx@@ -56,7 +56,7 @@ Authenticating users from your own code using `session.authorize()` or `connecte</GlossaryTerm><GlossaryTerm name="Meta Tools">-A set of tools included in every session, including `COMPOSIO_SEARCH_TOOLS`, `COMPOSIO_MANAGE_CONNECTIONS`, `COMPOSIO_MULTI_EXECUTE_TOOL`, `COMPOSIO_REMOTE_WORKBENCH`, and `COMPOSIO_REMOTE_BASH_TOOL`. They let the agent discover tools, manage auth, execute in parallel, and run code without loading hundreds of tool definitions upfront. See [Tools and toolkits](/docs/tools-and-toolkits#meta-tools).+A set of tools included in every session, including `COMPOSIO_SEARCH_TOOLS`, `COMPOSIO_GET_TOOL_SCHEMAS`, `COMPOSIO_MANAGE_CONNECTIONS`, `COMPOSIO_MULTI_EXECUTE_TOOL`, `COMPOSIO_REMOTE_WORKBENCH`, and `COMPOSIO_REMOTE_BASH_TOOL`. They let the agent discover tools, manage auth, execute in parallel, and run code without loading hundreds of tool definitions upfront. See [Meta Tools Reference](/reference/meta-tools).</GlossaryTerm><GlossaryTerm name="Modifiers">diff --git a/docs/content/docs/how-composio-works.mdx b/docs/content/docs/how-composio-works.mdxindex f6aaf770d..8537d929c 100644--- a/docs/content/docs/how-composio-works.mdx+++ b/docs/content/docs/how-composio-works.mdx@@ -44,28 +44,30 @@ Sessions are immutable. Their configuration is fixed at creation. If the context## Meta tools-Rather than loading hundreds of tool definitions into your agent's context, a session provides 5 meta tools:+Rather than loading hundreds of tool definitions into your agent's context, a session provides [meta tools](/docs/tools-and-toolkits#meta-tools):```mermaidgraph LRA["Your agent"] --> B["Session"]B --> C["Meta tools"]C --> D["COMPOSIO_SEARCH_TOOLS"]- C --> E["COMPOSIO_MANAGE_CONNECTIONS"]- C --> F["COMPOSIO_MULTI_EXECUTE_TOOL"]- C --> G["COMPOSIO_REMOTE_WORKBENCH"]- C --> H["COMPOSIO_REMOTE_BASH_TOOL"]+ C --> E["COMPOSIO_GET_TOOL_SCHEMAS"]+ C --> F["COMPOSIO_MANAGE_CONNECTIONS"]+ C --> G["COMPOSIO_MULTI_EXECUTE_TOOL"]+ C --> H["COMPOSIO_REMOTE_WORKBENCH"]+ C --> I["COMPOSIO_REMOTE_BASH_TOOL"]D -.- D1["Discover tools by use case"]:::annotation- E -.- E1["Handle OAuth and API keys"]:::annotation- F -.- F1["Run tools with user credentials"]:::annotation- G -.- G1["Persistent Python sandbox"]:::annotation- H -.- H1["File operations and data processing"]:::annotation+ E -.- E1["Retrieve input schemas for tools"]:::annotation+ F -.- F1["Handle OAuth and API keys"]:::annotation+ G -.- G1["Run tools with user credentials"]:::annotation+ H -.- H1["Persistent Python sandbox"]:::annotation+ I -.- I1["File operations and data processing"]:::annotationclassDef annotation stroke-dasharray: 5 5```-The agent searches for relevant tools, authenticates if needed, and executes them, all through these 5 meta tools. For large responses or bulk operations, the agent offloads work to the workbench sandbox. Meta tool calls share context through a `session_id`, so the agent can search in one call and execute in the next without losing state.+The agent searches for relevant tools, authenticates if needed, and executes them, all through these meta tools. For large responses or bulk operations, the agent offloads work to the workbench sandbox. Meta tool calls share context through a `session_id`, so the agent can search in one call and execute in the next without losing state.Composio also surfaces **learned plans** from past executions: step-by-step workflows that have worked before for similar tasks, guiding the agent without starting from scratch.diff --git a/docs/content/docs/toolkits/fetching-tools-and-toolkits.mdx b/docs/content/docs/toolkits/fetching-tools-and-toolkits.mdxindex 82aeafd9d..d0af50402 100644--- a/docs/content/docs/toolkits/fetching-tools-and-toolkits.mdx+++ b/docs/content/docs/toolkits/fetching-tools-and-toolkits.mdx@@ -93,7 +93,7 @@ do {### Get meta tools-`session.tools()` returns the 5 meta tools formatted for your configured provider (OpenAI, Anthropic, etc.):+`session.tools()` returns the [meta tools](/reference/meta-tools) formatted for your configured provider (OpenAI, Anthropic, etc.):<Tabs groupId="language" items={['Python', 'TypeScript']} persist><Tab value="Python">diff --git a/docs/content/docs/tools-and-toolkits.mdx b/docs/content/docs/tools-and-toolkits.mdxindex 4897fdafd..ff71dee55 100644--- a/docs/content/docs/tools-and-toolkits.mdx+++ b/docs/content/docs/tools-and-toolkits.mdx@@ -4,20 +4,23 @@ description: Understand how tools and toolkits work in Composiokeywords: [tools, toolkits, meta tools, context management]----Composio offers 1000+ toolkits, but loading all the tools into context would overwhelm your agent. Instead, your agent has access to 5 meta tools that discover, authenticate, and execute the right tools at runtime.+Composio offers 1000+ toolkits, but loading all the tools into context would overwhelm your agent. Instead, your agent has access to meta tools that discover, authenticate, and execute the right tools at runtime.## Meta tools-When you create a session, your agent gets these 5 meta tools:+When you create a session, your agent gets these meta tools:| Meta tool | What it does ||-----------|--------------|-| `COMPOSIO_SEARCH_TOOLS` | Discover relevant tools across 1000+ apps |-| `COMPOSIO_MANAGE_CONNECTIONS` | Handle OAuth and API key authentication |-| `COMPOSIO_MULTI_EXECUTE_TOOL` | Execute up to 20 tools in parallel |+| `COMPOSIO_SEARCH_TOOLS` | Discover relevant tools across 500+ apps with execution plans |+| `COMPOSIO_GET_TOOL_SCHEMAS` | Retrieve complete input schemas for specific tools |+| `COMPOSIO_MULTI_EXECUTE_TOOL` | Execute up to 50 tools in parallel |+| `COMPOSIO_MANAGE_CONNECTIONS` | Handle OAuth, API key, and other authentication methods || `COMPOSIO_REMOTE_WORKBENCH` | Run Python code in a [persistent sandbox](/docs/workbench) || `COMPOSIO_REMOTE_BASH_TOOL` | Execute bash commands for file and data processing |+See the [Meta Tools Reference](/reference/meta-tools) for complete input/output schemas and details.+Meta tool calls in a session are correlated using a `session_id`, allowing them to share context. The tools can also store useful information (like IDs and relationships discovered during execution) in memory for subsequent calls.### How it worksdiff --git a/docs/content/reference/meta-tools/get_tool_schemas.mdx b/docs/content/reference/meta-tools/get_tool_schemas.mdxnew file mode 100644index 000000000..e73e990fc--- /dev/null+++ b/docs/content/reference/meta-tools/get_tool_schemas.mdx@@ -0,0 +1,11 @@+---+title: Get Tool Schemas+description: "Retrieve complete input schemas for tools by their slug"+keywords: [COMPOSIO_GET_TOOL_SCHEMAS, meta tool]+---++{/* Auto-generated by scripts/generate-meta-tools.ts — do not edit manually */}++import { MetaToolDetailServer } from '@/components/meta-tools/meta-tool-page';++<MetaToolDetailServer slug="COMPOSIO_GET_TOOL_SCHEMAS" />diff --git a/docs/content/reference/meta-tools/index.mdx b/docs/content/reference/meta-tools/index.mdxnew file mode 100644index 000000000..16399e73e--- /dev/null+++ b/docs/content/reference/meta-tools/index.mdx@@ -0,0 +1,24 @@+---+title: Meta Tools+description: Complete reference for all Composio meta tools available in sessions.+keywords: [meta tools, session]+---++{/* Auto-generated by scripts/generate-meta-tools.ts — do not edit manually */}++import { Callout } from 'fumadocs-ui/components/callout';++<Callout type="warn">+Meta tool schemas are for reference only. We do not guarantee backward compatibility for parameter names or response shapes. Do not rely on them for structured type definitions in your code.+</Callout>++Meta tools are system-level tools available in [sessions](/docs/tools-and-toolkits). They handle tool discovery, execution, authentication, and sandboxing.++| Tool | Description |+|------|-------------|+| [`COMPOSIO_GET_TOOL_SCHEMAS`](/reference/meta-tools/get_tool_schemas) | Retrieve complete input schemas for tools by their slug |+| [`COMPOSIO_MANAGE_CONNECTIONS`](/reference/meta-tools/manage_connections) | Create or manage OAuth, API key, and other auth connections |+| [`COMPOSIO_MULTI_EXECUTE_TOOL`](/reference/meta-tools/multi_execute_tool) | Execute up to 50 tools in parallel with workflow memory |+| [`COMPOSIO_REMOTE_BASH_TOOL`](/reference/meta-tools/remote_bash_tool) | Execute bash commands in a remote sandbox for file and data processing |+| [`COMPOSIO_REMOTE_WORKBENCH`](/reference/meta-tools/remote_workbench) | Run Python code in a persistent Jupyter sandbox with built-in helpers |+| [`COMPOSIO_SEARCH_TOOLS`](/reference/meta-tools/search_tools) | Discover relevant tools across 500+ apps with execution plans and connection status |diff --git a/docs/content/reference/meta-tools/manage_connections.mdx b/docs/content/reference/meta-tools/manage_connections.mdxnew file mode 100644index 000000000..9dda6d40f--- /dev/null+++ b/docs/content/reference/meta-tools/manage_connections.mdx@@ -0,0 +1,11 @@+---+title: Manage Connections+description: "Create or manage OAuth, API key, and other auth connections"+keywords: [COMPOSIO_MANAGE_CONNECTIONS, meta tool]+---++{/* Auto-generated by scripts/generate-meta-tools.ts — do not edit manually */}++import { MetaToolDetailServer } from '@/components/meta-tools/meta-tool-page';++<MetaToolDetailServer slug="COMPOSIO_MANAGE_CONNECTIONS" />diff --git a/docs/content/reference/meta-tools/meta.json b/docs/content/reference/meta-tools/meta.jsonnew file mode 100644index 000000000..405ddd827--- /dev/null+++ b/docs/content/reference/meta-tools/meta.json@@ -0,0 +1,12 @@+{+ "title": "Meta Tools",+ "defaultOpen": true,+ "pages": [+ "get_tool_schemas",+ "search_tools",+ "multi_execute_tool",+ "manage_connections",+ "remote_bash_tool",+ "remote_workbench"+ ]+}diff --git a/docs/content/reference/meta-tools/multi_execute_tool.mdx b/docs/content/reference/meta-tools/multi_execute_tool.mdxnew file mode 100644index 000000000..dc931253b--- /dev/null+++ b/docs/content/reference/meta-tools/multi_execute_tool.mdx@@ -0,0 +1,11 @@+---+title: Multi Execute Tool+description: "Execute up to 50 tools in parallel with workflow memory"+keywords: [COMPOSIO_MULTI_EXECUTE_TOOL, meta tool]+---++{/* Auto-generated by scripts/generate-meta-tools.ts — do not edit manually */}++import { MetaToolDetailServer } from '@/components/meta-tools/meta-tool-page';++<MetaToolDetailServer slug="COMPOSIO_MULTI_EXECUTE_TOOL" />diff --git a/docs/content/reference/meta-tools/remote_bash_tool.mdx b/docs/content/reference/meta-tools/remote_bash_tool.mdxnew file mode 100644index 000000000..35a86d33e--- /dev/null+++ b/docs/content/reference/meta-tools/remote_bash_tool.mdx@@ -0,0 +1,11 @@+---+title: Remote Bash Tool+description: "Execute bash commands in a remote sandbox for file and data processing"+keywords: [COMPOSIO_REMOTE_BASH_TOOL, meta tool]+---++{/* Auto-generated by scripts/generate-meta-tools.ts — do not edit manually */}++import { MetaToolDetailServer } from '@/components/meta-tools/meta-tool-page';++<MetaToolDetailServer slug="COMPOSIO_REMOTE_BASH_TOOL" />diff --git a/docs/content/reference/meta-tools/remote_workbench.mdx b/docs/content/reference/meta-tools/remote_workbench.mdxnew file mode 100644index 000000000..7c50ba143--- /dev/null+++ b/docs/content/reference/meta-tools/remote_workbench.mdx@@ -0,0 +1,11 @@+---+title: Remote Workbench+description: "Run Python code in a persistent Jupyter sandbox with built-in helpers"+keywords: [COMPOSIO_REMOTE_WORKBENCH, meta tool]+---++{/* Auto-generated by scripts/generate-meta-tools.ts — do not edit manually */}++import { MetaToolDetailServer } from '@/components/meta-tools/meta-tool-page';++<MetaToolDetailServer slug="COMPOSIO_REMOTE_WORKBENCH" />diff --git a/docs/content/reference/meta-tools/search_tools.mdx b/docs/content/reference/meta-tools/search_tools.mdxnew file mode 100644index 000000000..19f868052--- /dev/null+++ b/docs/content/reference/meta-tools/search_tools.mdx@@ -0,0 +1,11 @@+---+title: Search Tools+description: "Discover relevant tools across 500+ apps with execution plans and connection status"+keywords: [COMPOSIO_SEARCH_TOOLS, meta tool]+---++{/* Auto-generated by scripts/generate-meta-tools.ts — do not edit manually */}++import { MetaToolDetailServer } from '@/components/meta-tools/meta-tool-page';++<MetaToolDetailServer slug="COMPOSIO_SEARCH_TOOLS" />diff --git a/docs/content/reference/meta.json b/docs/content/reference/meta.jsonindex 7faf27f68..2c971b067 100644--- a/docs/content/reference/meta.json+++ b/docs/content/reference/meta.json@@ -6,6 +6,7 @@"rate-limits","errors","api-reference",+ "meta-tools","sdk-reference"]}diff --git a/docs/lib/meta-tools-data.ts b/docs/lib/meta-tools-data.tsnew file mode 100644index 000000000..bb0619273--- /dev/null+++ b/docs/lib/meta-tools-data.ts@@ -0,0 +1,70 @@+import { readFile } from 'fs/promises';+import { readFileSync } from 'fs';+import { join } from 'path';++export interface MetaToolParameter {+ type: string;+ description: string;+ required?: boolean;+ default?: unknown;+ enum?: string[];+ examples?: unknown[];+ items?: Record<string, unknown>;+ properties?: Record<string, MetaToolParameter>;+}++export interface MetaTool {+ slug: string;+ name: string;+ displayName: string;+ description: string;+ tags: string[];+ inputParameters: {+ type: string;+ properties: Record<string, MetaToolParameter>;+ };+ responseSchema: {+ type: string;+ properties: Record<string, MetaToolParameter>;+ };+}++const META_TOOLS_PATH = join(process.cwd(), 'public/data/meta-tools.json');++let cached: { list: MetaTool[]; bySlug: Map<string, MetaTool> } | null = null;++function buildCache(tools: MetaTool[]) {+ cached = {+ list: tools,+ bySlug: new Map(tools.map(t => [t.slug, t])),+ };+ return cached;+}++function parse(data: string): MetaTool[] {+ const tools = JSON.parse(data) as MetaTool[];++ if (!Array.isArray(tools)) {+ throw new Error('meta-tools.json must contain an array');+ }++ return tools;+}++export async function getAllMetaTools(): Promise<MetaTool[]> {+ if (cached) return cached.list;+ const data = await readFile(META_TOOLS_PATH, 'utf-8');+ return buildCache(parse(data)).list;+}++export async function getMetaToolBySlug(slug: string): Promise<MetaTool | null> {+ if (cached) return cached.bySlug.get(slug) ?? null;+ const data = await readFile(META_TOOLS_PATH, 'utf-8');+ return buildCache(parse(data)).bySlug.get(slug) ?? null;+}++export function getAllMetaToolsSync(): MetaTool[] {+ if (cached) return cached.list;+ const data = readFileSync(META_TOOLS_PATH, 'utf-8');+ return buildCache(parse(data)).list;+}diff --git a/docs/lib/source.ts b/docs/lib/source.tsindex f80b94a48..50a0a075b 100644--- a/docs/lib/source.ts+++ b/docs/lib/source.ts@@ -12,7 +12,7 @@ import { getGuardrails } from './llm-guardrails';const defaultOpenTransformer = {folder(node: { name: string; defaultOpen?: boolean }, folderPath: string) {// Set defaultOpen for API Reference and SDK Reference folders- if (folderPath === 'api-reference' || folderPath === 'sdk-reference') {+ if (folderPath === 'api-reference' || folderPath === 'sdk-reference' || folderPath === 'meta-tools') {return { ...node, defaultOpen: true };}return node;diff --git a/docs/package.json b/docs/package.jsonindex 99f89b28d..8bf769b5f 100644--- a/docs/package.json+++ b/docs/package.json@@ -11,6 +11,7 @@"lint": "eslint","lint:links": "bun scripts/validate-links.ts","generate:toolkits": "bun scripts/generate-toolkits.ts",+ "generate:meta-tools": "bun scripts/generate-meta-tools.ts","generate:api-index": "bun scripts/generate-api-index.ts","test": "bun test tests/static/","test:integration": "bun test tests/integration/ --timeout 30000"diff --git a/docs/public/data/meta-tools.json b/docs/public/data/meta-tools.jsonnew file mode 100644index 000000000..259f5f0da--- /dev/null+++ b/docs/public/data/meta-tools.json@@ -0,0 +1,1280 @@+[+ {+ "slug": "COMPOSIO_GET_TOOL_SCHEMAS",+ "name": "get_tool_schemas",+ "displayName": "Get Tool Schemas",+ "description": "Retrieve input schemas for tools by slug. Returns complete parameter definitions required to execute each tool. Make sure to call this tool whenever the response of COMPOSIO_SEARCH_TOOLS does not provide a complete schema for a tool - you must never invent or guess any input parameters.",+ "category": "discovery",+ "categoryLabel": "Discovery & Planning",+ "tags": [+ "readOnlyHint"+ ],+ "toolkit": {+ "slug": "COMPOSIO",+ "name": "composio",+ "logo": "https://cdn.jsdelivr.net/gh/ComposioHQ/open-logos@master/composio-logo.png"+ },+ "inputParameters": {+ "properties": {+ "tool_slugs": {+ "description": "List of tool slugs to retrieve schemas for. Each slug MUST be a valid tool slug previously returned by COMPOSIO_SEARCH_TOOLS.",+ "examples": [+ [+ "GMAIL_SEND_EMAIL"+ ],+ [+ "GMAIL_SEND_EMAIL",+ "SLACK_SEND_MESSAGE"+ ]+ ],+ "type": "array",+ "items": {+ "type": "string",+ "minLength": 1+ },+ "title": "Tool Slugs"+ },+ "session_id": {+ "description": "ALWAYS pass the session_id that was provided in the SEARCH_TOOLS response.",+ "title": "Session ID",+ "type": "string"+ }+ },+ "required": [+ "tool_slugs"+ ],+ "title": "GetToolSchemasRequest",+ "type": "object"+ },+ "responseSchema": {+ "properties": {+ "data": {+ "additionalProperties": false,+ "description": "Data from the action execution",+ "properties": {+ "success": {+ "description": "Whether all requested tool schemas were found",+ "type": "boolean"+ },+ "tool_schemas": {+ "description": "Tool definitions keyed by tool_slug for O(1) lookup. Same format as tool_schemas in search response.",+ "type": "object",+ "additionalProperties": {+ "type": "object",+ "properties": {+ "toolkit": {+ "type": "string",+ "description": "The slug of the toolkit that provides this tool"+ },+ "tool_slug": {+ "type": "string",+ "description": "The slug of the tool"+ },+ "description": {+ "type": "string",+ "description": "Description of the tool"+ },+ "input_schema": {+ "type": "object",+ "description": "Input schema for the tool"+ }+ },+ "required": [+ "toolkit",+ "tool_slug"+ ]+ }+ },+ "not_found": {+ "description": "Tool slugs that were not found",+ "type": "array",+ "items": {+ "type": "string"+ }+ },+ "session": {+ "additionalProperties": false,+ "description": "Session info echoed back to reinforce reuse: { id: string, instructions: string }",+ "properties": {+ "id": {+ "type": "string"+ },+ "instructions": {+ "type": "string"+ }+ },+ "required": [+ "id",+ "instructions"+ ],+ "title": "Session",+ "type": "object"+ }+ },+ "required": [+ "success",+ "tool_schemas"+ ],+ "title": "Data",+ "type": "object"+ },+ "error": {+ "default": null,+ "description": "Error if any occurred during the execution of the action",+ "nullable": true,+ "title": "Error",+ "type": "string"+ },+ "successful": {+ "description": "Whether or not the action execution was successful or not",+ "title": "Successful",+ "type": "boolean"+ }+ },+ "required": [+ "data",+ "successful"+ ],+ "title": "GetToolSchemasResponseWrapper",+ "type": "object"+ }+ },+ {+ "slug": "COMPOSIO_SEARCH_TOOLS",+ "name": "search_tools",+ "displayName": "Search Tools",+ "description": "\n MCP Server Info: COMPOSIO MCP connects 500+ apps—Slack, GitHub, Notion, Google Workspace (Gmail, Sheets, Drive, Calendar), Microsoft (Outlook, Teams), X/Twitter, Figma, Web Search / Deep research, Browser tool (scrape URLs, browser automation), Meta apps (Instagram, Meta Ads), TikTok, AI tools like Nano Banana & Veo3, and more—for seamless cross-app automation.\n Use this MCP server to discover the right tools and the recommended step-by-step plan to execute reliably.\n ALWAYS call this tool first whenever a user mentions or implies an external app, service, or workflow—never say \"I don't have access to X/Y app\" before calling it.\n\n Tool Info: Extremely fast discovery tool that returns relevant MCP-callable tools along with a recommended execution plan and common pitfalls for reliable execution.\n\nUsage guidelines:\n - Use this tool whenever kicking off a task. Re-run it when you need additional tools/plans due to missing details, errors, or a changed use case.\n - If the user pivots to a different use case in same chat, you MUST call this tool again with the new use case and generate a new session_id.\n - Specify the use_case with a normalized description of the problem, query, or task. Be clear and precise. Queries can be simple single-app actions or multiple linked queries for complex cross-app workflows.\n - Pass known_fields along with use_case as a string of key–value hints (for example, \"channel_name: general\") to help the search resolve missing details such as IDs.\n \n\nSplitting guidelines (Important):\n 1. Atomic queries: 1 query = 1 tool call. Include hidden prerequisites (e.g., add \"get Linear issue\" before \"update Linear issue\").\n 2. Include app names: If user names a toolkit, include it in every sub query so intent stays scoped (e.g., \"fetch Gmail emails\", \"reply to Gmail email\").\n 3. English input: Translate non-English prompts while preserving intent and identifiers.\n\n Example:\n User query: \"send an email to John welcoming him and create a meeting invite for tomorrow\"\n Search call: queries: [\n {use_case: \"send an email to someone\", known_fields: \"recipient_name: John\"},\n {use_case: \"create a meeting invite\", known_fields: \"meeting_date: tomorrow\"}\n ]\n\nPlan review checklist (Important):\n - The response includes a detailed execution plan and common pitfalls. You MUST review this plan carefully, adapt it to your current context, and generate your own final step-by-step plan before execution. Execute the steps in order to ensure reliable and accurate execution. Skipping or ignoring required steps can lead to unexpected failures.\n - Check the plan and pitfalls for input parameter nuances (required fields, IDs, formats, limits). Before executing any tool, you MUST review its COMPLETE input schema and provide STRICTLY schema-compliant arguments to avoid invalid-input errors.\n - Determine whether pagination is needed; if a response returns a pagination token and completeness is implied, paginate until exhaustion and do not return partial results.\n\nResponse:\n - Tools & Input Schemas: The response lists toolkits (apps) and tools suitable for the task, along with their tool_slug, description, input schema / schemaRef, and related tools for prerequisites, alternatives, or next steps.\n - NOTE: Tools with schemaRef instead of input_schema require you to call COMPOSIO_GET_TOOL_SCHEMAS first to load their full input_schema before use.\n - Connection Info: If a toolkit has an active connection, the response includes it along with any available current user information. If no active connection exists, you MUST initiate a new connection via COMPOSIO_MANAGE_CONNECTIONS with the correct toolkit name. DO NOT execute any toolkit tool without an ACTIVE connection.\n - Time Info: The response includes the current UTC time for reference. You can reference UTC time from the response if needed.\n - The tools returned to you through this are to be called via COMPOSIO_MULTI_EXECUTE_TOOL. Ensure each tool execution specifies the correct tool_slug and arguments exactly as defined by the tool's input schema.\n \nSESSION: ALWAYS set this parameter, first for any workflow. Pass session: {generate_id: true} for new workflows OR session: {id: \"EXISTING_ID\"} to continue. ALWAYS use the returned session_id in ALL subsequent meta tool calls.\n ",+ "category": "discovery",+ "categoryLabel": "Discovery & Planning",+ "tags": [+ "important",+ "openWorldHint",+ "readOnlyHint"+ ],+ "toolkit": {+ "slug": "COMPOSIO",+ "name": "composio",+ "logo": "https://cdn.jsdelivr.net/gh/ComposioHQ/open-logos@master/composio-logo.png"+ },+ "inputParameters": {+ "properties": {+ "queries": {+ "type": "array",+ "description": "List of structured search queries (in English) to process in parallel. Each query represents a specific use case or task. For multi-app or complex workflows, split them into smaller single-app, API-level actions for best accuracy, including implicit prerequisites (e.g., fetch the resource before updating it). Each query returns 5-10 tools.",+ "items": {+ "type": "object",+ "properties": {+ "use_case": {+ "description": "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.",+ "examples": [+ "send an email to someone",+ "search issues with label in jira toolkit",+ "put issue details in a google sheet",+ "post a formatted message to slack channel"+ ],+ "title": "Use Case",+ "type": "string"+ },+ "known_fields": {+ "type": "string",+ "description": "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).",+ "examples": [+ "channel_name:pod-sdk",+ "channel_id:123",+ "invitee_names:John,Maria, timezone:Asia/Kolkata"+ ]+ }+ },+ "required": [+ "use_case"+ ]+ },+ "minItems": 1,+ "title": "Queries"+ },+ "session": {+ "type": "object",+ "description": "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": {+ "type": "string",+ "description": "Existing session identifier for the current workflow to reuse across calls.",+ "title": "Session ID"+ },+ "generate_id": {+ "type": "boolean",+ "description": "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.",+ "title": "Generate ID"+ }+ }+ },+ "model": {+ "type": "string",+ "description": "Client LLM model name (recommended). Used to optimize planning/search behavior. Ignored if omitted or invalid.",+ "examples": [+ "gpt-5.2",+ "claude-4.5-sonnet"+ ],+ "title": "Model"+ }+ },+ "required": [+ "queries"+ ],+ "title": "SearchToolsRequest",+ "type": "object"+ },+ "responseSchema": {+ "properties": {+ "data": {+ "additionalProperties": false,+ "description": "Data from the action execution",+ "properties": {+ "results": {+ "type": "array",+ "description": "Per-query search results with tools, reasoning, and memory. One entry per query in request order.",+ "items": {+ "type": "object",+ "properties": {+ "index": {+ "type": "integer",+ "description": "1-based index of the query in the request"+ },+ "use_case": {+ "type": "string",+ "description": "The use case that was searched"+ },+ "primary_tool_slugs": {+ "type": "array",+ "description": "List of main tool slugs matching the search criteria",+ "items": {+ "type": "string"+ }+ },+ "related_tool_slugs": {+ "type": "array",+ "description": "List of related tool slugs that might be useful",+ "items": {+ "type": "string"+ }+ },+ "toolkits": {+ "type": "array",+ "description": "List of unique toolkit slugs used by tools in this query",+ "items": {+ "type": "string"+ }+ },+ "reasoning": {+ "type": "string",+ "description": "Reasoning for the search results"+ },+ "task_difficulty": {+ "type": "string",+ "description": "Assessment of task difficulty for this specific query"+ },+ "recommended_plan_steps": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "description": "Workflow steps from cached plan (only present when cached plan is available)"+ },+ "known_pitfalls": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "description": "Common pitfalls and considerations (only present when cached plan is available)"+ },+ "reference_workbench_snippets": {+ "type": "array",+ "description": "Reference Python code snippets for processing tool responses in the workbench (only present when cached plan is available)",+ "items": {+ "type": "object",+ "properties": {+ "description": {+ "type": "string",+ "description": "Description of what the code snippet does"+ },+ "code": {+ "type": "string",+ "description": "Python code snippet for the workbench, wrapped in triple backticks"+ }+ },+ "required": [+ "description",+ "code"+ ]+ }+ },+ "error": {+ "type": "string",+ "nullable": true,+ "description": "Error message if the search failed, null otherwise"+ }+ },+ "required": [+ "index",+ "use_case",+ "primary_tool_slugs",+ "related_tool_slugs",+ "toolkits",+ "reasoning",+ "task_difficulty"+ ]+ }+ },+ "tool_schemas": {+ "type": "object",+ "description": "Deduplicated tool definitions keyed by tool_slug for O(1) lookup. Each tool appears once even if used in multiple queries.",+ "additionalProperties": {+ "type": "object",+ "properties": {+ "tool_slug": {+ "type": "string",+ "description": "The slug of the tool"+ },+ "toolkit": {+ "type": "string",+ "description": "The slug of the toolkit that provides this tool"+ },+ "description": {+ "type": "string",+ "nullable": true,+ "description": "Description of the tool"+ },+ "input_schema": {+ "type": "object",+ "nullable": true,+ "description": "Input schema for the tool",+ "additionalProperties": true+ },+ "usage_guidelines": {+ "type": "string",+ "nullable": true,+ "description": "Practical usage notes and examples for the tool"+ }+ }+ }+ },+ "toolkit_connection_statuses": {+ "type": "array",+ "description": "Connection status for all toolkits mentioned across all queries, with descriptions merged in",+ "items": {+ "type": "object",+ "properties": {+ "toolkit": {+ "type": "string",+ "description": "The toolkit slug identifier (e.g., \"gmail\", \"slack\")"+ },+ "description": {+ "type": "string",+ "description": "Description of what the toolkit does and its capabilities"+ },+ "has_active_connection": {+ "type": "boolean",+ "description": "Whether an active connection exists for this toolkit"+ },+ "connection_details": {+ "type": "object",+ "description": "Connection details including auth config and connected account IDs",+ "additionalProperties": true+ },+ "current_user_info": {+ "type": "object",+ "nullable": true,+ "description": "Information about the currently connected user (email, name, etc.)",+ "additionalProperties": true+ },+ "status_message": {+ "type": "string",+ "description": "Human-readable message about the connection status and next steps"+ }+ },+ "required": [+ "toolkit",+ "description",+ "has_active_connection",+ "connection_details",+ "status_message"+ ]+ }+ },+ "time_info": {+ "type": "object",+ "description": "Time information for the query",+ "properties": {+ "current_time_utc": {+ "type": "string",+ "description": "Current time in ISO format (UTC)"+ },+ "current_time_utc_epoch_seconds": {+ "type": "integer",+ "description": "Current time as Unix epoch timestamp in seconds"+ },+ "message": {+ "type": "string",+ "description": "Important message about time handling and timezone considerations"+ }+ },+ "required": [+ "current_time_utc",+ "current_time_utc_epoch_seconds",+ "message"+ ]+ },+ "session": {+ "type": "object",+ "description": "Session info for correlating meta tool calls",+ "properties": {+ "id": {+ "type": "string",+ "description": "Session identifier to be passed to subsequent meta tool calls"+ },+ "generate_id": {+ "type": "boolean",+ "description": "Whether a fresh session id was generated in this call"+ },+ "instructions": {+ "type": "string",+ "description": "LLM-facing guidance on how to reuse this session id"+ }+ },+ "required": [+ "id",+ "generate_id",+ "instructions"+ ]+ },+ "next_steps_guidance": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "description": "Combined workflow guidance covering connections, planner, and memory usage. Each element is a step instruction."+ }+ },+ "required": [+ "results",+ "tool_schemas",+ "toolkit_connection_statuses",+ "time_info",+ "session",+ "next_steps_guidance"+ ],+ "title": "Data",+ "type": "object"+ },+ "error": {+ "default": null,+ "description": "Error if any occurred during the execution. Format: \"X out of Y searches failed, reasons: <details>\"",+ "nullable": true,+ "title": "Error",+ "type": "string"+ },+ "successful": {+ "description": "Whether all searches completed successfully. False if any query failed",+ "title": "Successful",+ "type": "boolean"+ }+ },+ "required": [+ "data",+ "successful"+ ],+ "title": "SearchToolsResponseWrapper",+ "type": "object"+ }+ },+ {+ "slug": "COMPOSIO_MULTI_EXECUTE_TOOL",+ "name": "multi_execute_tool",+ "displayName": "Multi Execute Tool",+ "description": "\n Fast and parallel tool executor for tools and recipes discovered through COMPOSIO_SEARCH_TOOLS. Use this tool to execute up to 50 tools in parallel across apps. Response contains structured outputs ready for immediate analysis - avoid reprocessing them via remote bash/workbench tools.\n\nPrerequisites:\n- Always use valid tool slugs and their arguments discovered through COMPOSIO_SEARCH_TOOLS. NEVER invent tool slugs or argument fields. ALWAYS pass STRICTLY schema-compliant arguments with each tool execution.\n- Ensure an ACTIVE connection exists for the toolkits that are going to be executed. If none exists, MUST initiate one via COMPOSIO_MANAGE_CONNECTIONS before execution.\n- Only batch tools that are logically independent - no required ordering or dependencies between tools or their outputs. DO NOT pass dummy or placeholder values; always resolve required inputs using appropriate tools first.\n\nUsage guidelines:\n- Use this whenever a tool is discovered and has to be called, either as part of a multi-step workflow or as a standalone tool.\n- If COMPOSIO_SEARCH_TOOLS returns a tool that can perform the task, prefer calling it via this executor. Do not write custom API calls or ad-hoc scripts for tasks that can be completed by available Composio tools.\n- Prefer parallel execution: group independent tools into a single multi-execute call where possible.\n- Predictively set sync_response_to_workbench=true if the response may be large or needed for later scripting. It still shows response inline; if the actual response data turns out small and easy to handle, keep everything inline and SKIP workbench usage.\n- Responses contain structured outputs for each tool. RULE: Small data - process yourself inline; large data - process in the workbench.\n- ALWAYS include inline references/links to sources in MARKDOWN format directly next to the relevant text. Eg provide slack thread links alongside with summary, render document links instead of raw IDs.\n\nRestrictions: Some tools or toolkits may be disabled in this environment. If the response indicates a restriction, inform the user and STOP execution immediately. Do NOT attempt workarounds or speculative actions.\n\n\n",+ "category": "execution",+ "categoryLabel": "Execution",+ "tags": [+ "openWorldHint",+ "destructiveHint",+ "important"+ ],+ "toolkit": {+ "slug": "COMPOSIO",+ "name": "composio",+ "logo": "https://cdn.jsdelivr.net/gh/ComposioHQ/open-logos@master/composio-logo.png"+ },+ "inputParameters": {+ "properties": {+ "tools": {+ "description": "List of tools to execute in parallel.",+ "items": {+ "properties": {+ "tool_slug": {+ "description": "The slug of the tool to execute - must be a valid slug from SEARCH_TOOLS response.",+ "examples": [+ "GMAIL_SEND_EMAIL",+ "SLACK_SEND_MESSAGE",+ "GITHUB_CREATE_ISSUE"+ ],+ "minLength": 1,+ "title": "Tool Slug",+ "type": "string"+ },+ "arguments": {+ "additionalProperties": true,+ "description": "The arguments to pass to the tool. The argument schema is defined in the SEARCH_TOOLS response. Use exact field names and types; do not diverge from returned schemas.",+ "examples": [+ {+ "body": "This is a test",+ "subject": "Hello",+ "to": "[email protected]"+ },+ {+ "channel": "#general",+ "text": "Hello from Composio!"+ },+ {+ "body": "Description of the issue",+ "labels": [+ "bug"+ ],+ "title": "Bug Report"+ }+ ],+ "title": "Arguments",+ "type": "object"+ }+ },+ "required": [+ "tool_slug",+ "arguments"+ ],+ "title": "MultiExecuteToolItem",+ "type": "object"+ },+ "maxItems": 50,+ "minItems": 1,+ "title": "Tools",+ "type": "array"+ },+ "thought": {+ "description": "One-sentence, concise, high-level rationale (no step-by-step).",+ "title": "Thought",+ "type": "string"+ },+ "sync_response_to_workbench": {+ "description": "Syncs the response to the remote workbench (for later scripting/processing) while still viewable inline. Predictively set true if the output may be large or need scripting; if it turns out small/manageable, skip workbench and use inline only. Default: false",+ "title": "Sync Response To Workbench",+ "type": "boolean"+ },+ "session_id": {+ "description": "ALWAYS pass the session_id that was provided in the SEARCH_TOOLS response.",+ "title": "Session ID",+ "type": "string"+ },+ "current_step": {+ "description": "Short enum for current step of the workflow execution. Eg FETCHING_EMAILS, GENERATING_REPLIES. Always include to keep execution aligned with the workflow.",+ "title": "Current Step",+ "type": "string"+ },+ "current_step_metric": {+ "description": "Progress metrics for the current step - use to track how far execution has advanced. Format as a string \"done/total units\" - example \"10/100 emails\", \"0/n messages\", \"3/10 pages\".",+ "title": "Current Step Metric",+ "type": "string"+ }+ },+ "required": [+ "tools",+ "sync_response_to_workbench"+ ],+ "title": "MultiExecuteToolRequest",+ "type": "object"+ },+ "responseSchema": {+ "properties": {+ "data": {+ "additionalProperties": false,+ "description": "Data from the action execution",+ "properties": {+ "error_count": {+ "description": "Number of failed tool executions",+ "title": "Error Count",+ "type": "integer"+ },+ "results": {+ "description": "List of responses from executing the tools. Order matches the input order.",+ "examples": [+ [+ {+ "error": null,+ "index": 0,+ "response": {+ "data": {+ "response": {+ "data": {+ "id": "123",+ "title": "Issue created",+ "url": "https://github.com/org/repo/issues/123"+ }+ }+ },+ "error": null,+ "log_id": "log_XYZ789",+ "successful": true+ },+ "tool_slug": "GITHUB_CREATE_ISSUE"+ },+ {+ "error": "No active connected account found for toolkit: gmail",+ "index": 1,+ "response": null,+ "tool_slug": "GMAIL_SEND_EMAIL"+ }+ ]+ ],+ "items": {+ "properties": {+ "error": {+ "default": null,+ "description": "Error message if the tool execution failed",+ "nullable": true,+ "title": "Error",+ "type": "string"+ },+ "index": {+ "description": "Original index of the tool in the request",+ "title": "Index",+ "type": "integer"+ },+ "response": {+ "additionalProperties": true,+ "default": null,+ "description": "The response from executing the tool if successful",+ "nullable": true,+ "title": "Response",+ "type": "object"+ },+ "tool_slug": {+ "description": "The slug of the tool that was executed",+ "title": "Tool Slug",+ "type": "string"+ }+ },+ "required": [+ "tool_slug",+ "index"+ ],+ "title": "MultiExecuteToolItemResponse",+ "type": "object"+ },+ "title": "Results",+ "type": "array"+ },+ "success_count": {+ "description": "Number of successful tool executions",+ "title": "Success Count",+ "type": "integer"+ },+ "total_count": {+ "description": "Total number of tools executed",+ "title": "Total Count",+ "type": "integer"+ },+ "session": {+ "additionalProperties": false,+ "default": null,+ "description": "Session info echoed back to reinforce reuse: { id: string, instructions: string }",+ "nullable": true,+ "properties": {+ "id": {+ "type": "string"+ },+ "instructions": {+ "type": "string"+ }+ },+ "title": "Session",+ "type": "object"+ },+ "remote_file_info": {+ "additionalProperties": true,+ "default": null,+ "description": "Information about the complete response saved to a remote file when response is too large or when sync_response_to_workbench is true",+ "nullable": true,+ "title": "Remote File Info",+ "type": "object"+ },+ "next_steps": {+ "default": null,+ "description": "Next steps for the caller",+ "nullable": true,+ "title": "Next Steps",+ "type": "string"+ }+ },+ "required": [+ "results",+ "total_count",+ "success_count",+ "error_count"+ ],+ "title": "Data",+ "type": "object"+ },+ "error": {+ "default": null,+ "description": "Error if any occurred during the execution of the action",+ "nullable": true,+ "title": "Error",+ "type": "string"+ },+ "successful": {+ "description": "Whether or not the action execution was successful or not",+ "title": "Successful",+ "type": "boolean"+ }+ },+ "required": [+ "data",+ "successful"+ ],+ "title": "MultiExecuteActionResponseWrapper",+ "type": "object"+ }+ },+ {+ "slug": "COMPOSIO_MANAGE_CONNECTIONS",+ "name": "manage_connections",+ "displayName": "Manage Connections",+ "description": "\nCreate or manage connections to user's apps. Returns a branded authentication link that works for OAuth, API keys, and all other auth types.\n\nCall policy:\n- First call COMPOSIO_SEARCH_TOOLS for the user's query.\n- If COMPOSIO_SEARCH_TOOLS indicates there is no active connection for a toolkit, call COMPOSIO_MANAGE_CONNECTIONS with the exact toolkit name(s) returned.\n- Do not call COMPOSIO_MANAGE_CONNECTIONS if COMPOSIO_SEARCH_TOOLS returns no main tools and no related tools.\n- Toolkit names in toolkits must exactly match toolkit identifiers returned by COMPOSIO_SEARCH_TOOLS; never invent names.\n- NEVER execute any toolkit tool without an ACTIVE connection.\n\nTool Behavior:\n- If a connection is Active, the tool returns the connection details. Always use this to verify connection status and fetch metadata.\n- If a connection is not Active, returns a authentication link (redirect_url) to create new connection.\n- If reinitiate_all is true, the tool forces reconnections for all toolkits, even if they already have active connections.\n\nWorkflow after initiating connection:\n- Always show the returned redirect_url as a FORMATTED MARKDOWN LINK to the user, and ask them to click on the link to finish authentication.\n- Begin executing tools only after the connection for that toolkit is confirmed Active.\n ",+ "category": "authentication",+ "categoryLabel": "Authentication",+ "tags": [+ "openWorldHint"+ ],+ "toolkit": {+ "slug": "COMPOSIO",+ "name": "composio",+ "logo": "https://cdn.jsdelivr.net/gh/ComposioHQ/open-logos@master/composio-logo.png"+ },+ "inputParameters": {+ "properties": {+ "toolkits": {+ "description": "List of toolkits to check or connect. Should be a valid toolkit returned by SEARCH_TOOLS (never invent one). If a toolkit is not connected, will initiate connection. Example: ['gmail', 'exa', 'github', 'outlook', 'reddit', 'googlesheets', 'one_drive']",+ "items": {+ "properties": {},+ "type": "string"+ },+ "title": "Toolkits",+ "type": "array"+ },+ "reinitiate_all": {+ "default": false,+ "description": "Force reconnection for ALL toolkits in the toolkits list, even if they already have Active connections.\n WHEN TO USE:\n - You suspect existing connections are stale or broken.\n - You want to refresh all connections with new credentials or settings.\n - You're troubleshooting connection issues across multiple toolkits.\n BEHAVIOR:\n - Overrides any existing active connections for all specified toolkits and initiates new link-based authentication flows.\n DEFAULT: false (preserve existing active connections)",+ "title": "Reinitiate All",+ "type": "boolean"+ },+ "session_id": {+ "description": "ALWAYS pass the session_id that was provided in the SEARCH_TOOLS response.",+ "title": "Session ID",+ "type": "string"+ }+ },+ "required": [+ "toolkits"+ ],+ "title": "ManageConnectionsRequest",+ "type": "object"+ },+ "responseSchema": {+ "properties": {+ "data": {+ "additionalProperties": false,+ "description": "Data from the action execution",+ "properties": {+ "message": {+ "description": "Overall status message",+ "title": "Message",+ "type": "string"+ },+ "results": {+ "additionalProperties": {+ "description": "Result for a single toolkit connection attempt",+ "properties": {+ "has_active_connection": {+ "description": "Whether an active connection exists",+ "title": "Has Active Connection",+ "type": "boolean"+ },+ "auth_config_id": {+ "anyOf": [+ {+ "type": "string"+ },+ {+ "type": "null"+ }+ ],+ "default": null,+ "description": "Auth config ID when a new auth config is created or used",+ "title": "Auth Config Id"+ },+ "connected_account_id": {+ "anyOf": [+ {+ "type": "string"+ },+ {+ "type": "null"+ }+ ],+ "default": null,+ "description": "Connected account ID if available",+ "title": "Connected Account Id"+ },+ "created_at": {+ "anyOf": [+ {+ "type": "string"+ },+ {+ "type": "null"+ }+ ],+ "default": null,+ "description": "Creation time (ISO 8601) for the connection if available",+ "title": "Created At"+ },+ "current_user_info": {+ "additionalProperties": true,+ "default": null,+ "description": "Information about the currently connected user (email, name, etc.)",+ "nullable": true,+ "title": "Current User Info",+ "type": "object"+ },+ "error_message": {+ "anyOf": [+ {+ "type": "string"+ },+ {+ "type": "null"+ }+ ],+ "default": null,+ "description": "Error message if status is 'failed'",+ "title": "Error Message"+ },+ "instruction": {+ "anyOf": [+ {+ "type": "string"+ },+ {+ "type": "null"+ }+ ],+ "default": null,+ "description": "Instructions for user if status is 'initiated'",+ "title": "Instruction"+ },+ "redirect_url": {+ "anyOf": [+ {+ "type": "string"+ },+ {+ "type": "null"+ }+ ],+ "default": null,+ "description": "Authentication link URL if status is 'initiated'. Always show this as a formatted markdown link to the user.",+ "title": "Redirect Url"+ },+ "status": {+ "description": "Status of the connection attempt",+ "enum": [+ "active",+ "initiated",+ "failed"+ ],+ "title": "Status",+ "type": "string"+ },+ "toolkit": {+ "description": "Name of the toolkit",+ "title": "Toolkit",+ "type": "string"+ },+ "was_reinitiated": {+ "anyOf": [+ {+ "type": "boolean"+ },+ {+ "type": "null"+ }+ ],+ "default": null,+ "description": "Whether this connection was reinitiated (vs newly created)",+ "title": "Was Reinitiated"+ }+ },+ "required": [+ "toolkit",+ "status"+ ],+ "title": "ToolkitConnectionResult",+ "type": "object"+ },+ "description": "Connection results for each toolkit",+ "title": "Results",+ "type": "object"+ },+ "summary": {+ "additionalProperties": false,+ "description": "Summary of results by status type",+ "properties": {+ "total_toolkits": {+ "type": "integer"+ },+ "active_connections": {+ "type": "integer"+ },+ "initiated_connections": {+ "type": "integer"+ },+ "failed_connections": {+ "type": "integer"+ }+ },+ "required": [],+ "title": "Summary",+ "type": "object"+ },+ "session": {+ "additionalProperties": false,+ "description": "Session info echoed back to reinforce reuse: { id: string, instructions: string }",+ "properties": {+ "id": {+ "type": "string"+ },+ "instructions": {+ "type": "string"+ }+ },+ "required": [+ "id",+ "instructions"+ ],+ "title": "Session",+ "type": "object"+ }+ },+ "required": [+ "message",+ "results",+ "summary"+ ],+ "title": "Data",+ "type": "object"+ },+ "error": {+ "default": null,+ "description": "Error if any occurred during the execution of the action",+ "nullable": true,+ "title": "Error",+ "type": "string"+ },+ "successful": {+ "description": "Whether or not the action execution was successful or not",+ "title": "Successful",+ "type": "boolean"+ }+ },+ "required": [+ "data",+ "successful"+ ],+ "title": "ManageConnectionResponseWrapper",+ "type": "object"+ }+ },+ {+ "slug": "COMPOSIO_REMOTE_BASH_TOOL",+ "name": "remote_bash_tool",+ "displayName": "Remote Bash Tool",+ "description": "\n Execute bash commands in a REMOTE sandbox for file operations, data processing, and system tasks. Essential for handling large tool responses saved to remote files.\n PRIMARY USE CASES:\n- Process large tool responses saved by COMPOSIO_MULTI_EXECUTE_TOOL to remote sandbox\n- File system operations, extract specific information from JSON with shell tools like jq, awk, sed, grep, etc.\n- Commands run from /home/user directory by default\n ",+ "category": "sandbox",+ "categoryLabel": "Sandbox",+ "tags": [+ "destructiveHint",+ "openWorldHint"+ ],+ "toolkit": {+ "slug": "COMPOSIO",+ "name": "composio",+ "logo": "https://cdn.jsdelivr.net/gh/ComposioHQ/open-logos@master/composio-logo.png"+ },+ "inputParameters": {+ "properties": {+ "command": {+ "description": "The bash command to execute",+ "title": "Command",+ "type": "string"+ },+ "session_id": {+ "description": "ALWAYS pass the session_id that was provided in the SEARCH_TOOLS response.",+ "title": "Session ID",+ "type": "string"+ }+ },+ "required": [+ "command"+ ],+ "title": "RemoteBashToolInput",+ "type": "object"+ },+ "responseSchema": {+ "properties": {+ "data": {+ "additionalProperties": false,+ "description": "Data from the action execution",+ "properties": {+ "session": {+ "description": "Session info echoed back to reinforce reuse: { id: string, instructions: string }",+ "additionalProperties": false,+ "properties": {+ "id": {+ "type": "string"+ },+ "instructions": {+ "type": "string"+ }+ },+ "required": [+ "id",+ "instructions"+ ],+ "title": "Session",+ "type": "object"+ },+ "stderr": {+ "description": "The standard error output from the command, possibly truncated for brevity.",+ "title": "Stderr",+ "type": "string"+ },+ "stderrLines": {+ "description": "Total number of lines in original stderr, even if truncated",+ "title": "Stderr Lines",+ "type": "integer"+ },+ "stderr_file_path": {+ "description": "Path to file containing full stderr if output was truncated",+ "title": "Stderr File Path",+ "type": "string"+ },+ "stdout": {+ "description": "The standard output from the command, possibly truncated for brevity.",+ "title": "Stdout",+ "type": "string"+ },+ "stdoutLines": {+ "description": "Total number of lines in original stdout, even if truncated",+ "title": "Stdout Lines",+ "type": "integer"+ },+ "stdout_file_path": {+ "description": "Path to file containing full stdout if output was truncated",+ "title": "Stdout File Path",+ "type": "string"+ },+ "sandbox_id_suffix": {+ "description": "Last 4 digits of the sandbox ID for easier reference",+ "title": "Sandbox ID Suffix",+ "type": "string"+ }+ },+ "required": [+ "stdout",+ "stdoutLines",+ "stderr",+ "stderrLines"+ ],+ "title": "Data",+ "type": "object"+ },+ "error": {+ "default": null,+ "description": "Error if any occurred during the execution of the action",+ "nullable": true,+ "title": "Error",+ "type": "string"+ },+ "successful": {+ "description": "Whether or not the action execution was successful or not",+ "title": "Successful",+ "type": "boolean"+ }+ },+ "required": [+ "data",+ "successful"+ ],+ "title": "RemoteBashToolOutputWrapper",+ "type": "object"+ }+ },+ {+ "slug": "COMPOSIO_REMOTE_WORKBENCH",+ "name": "remote_workbench",+ "displayName": "Remote Workbench",+ "description": "\n Process **REMOTE FILES** or script BULK TOOL EXECUTIONS using Python code IN A REMOTE SANDBOX. If you can see the data in chat, DON'T USE THIS TOOL.\n**ONLY** use this when processing **data stored in a remote file** or when scripting bulk tool executions.\n\nDO NOT USE\n- When the complete response is already inline/in-memory, or you only need quick parsing, summarization, or basic math.\n\nUSE IF\n- To parse/analyze tool outputs saved to a remote file in the sandbox or to script multi-tool chains there.\n- For bulk or repeated executions of known Composio tools (e.g., add a label to 100 emails).\n- To call APIs via proxy_execute when no Composio tool exists for that API.\n\n\nOUTPUTS\n- Returns a compact result or, if too long, artifacts under `/home/user/.code_out`.\n\nIMPORTANT CODING RULES:\n 1. Stepwise Execution: Split work into small steps. Save intermediate outputs in variables or temporary file in `/tmp/`. Call COMPOSIO_REMOTE_WORKBENCH again for the next step. This improves composability and avoids timeouts.\n 2. Notebook Persistence: This is a persistent Jupyter notebook cell: variables, functions, imports, and in-memory state from previous and future code executions are preserved in the notebook's history and available for reuse. You also have a few helper functions available.\n 3. Parallelism & Timeout (CRITICAL): There is a hard timeout of 4 minutes so complete the code within that. Prioritize PARALLEL execution using ThreadPoolExecutor with suitable concurrency for bulk operations - e.g., call run_composio_tool or invoke_llm parallelly across rows to maximize efficiency.\n 3.1 If the data is large, split into smaller batches and call the workbench multiple times to avoid timeouts.\n 4. Checkpoints: Implement checkpoints (in memory or files) so that long runs can be resumed from the last completed step.\n 5. Schema Safety: Never assume the response schema for run_composio_tool if not known already from previous tools. To inspect schema, either run a simple request **outside** the workbench via COMPOSIO_MULTI_EXECUTE_TOOL or use invoke_llm helper.\n 6. LLM Helpers: Always use invoke_llm helper for summary, analysis, or field extraction on results. This is a smart LLM that will give much better results than any adhoc filtering.\n 7. Avoid Meta Loops: Do not use run_composio_tool to call COMPOSIO_MULTI_EXECUTE_TOOL or other COMPOSIO_* meta tools to avoid cycles. Only use it for app tools.\n 8. Pagination: Use when data spans multiple pages. Continue fetching pages with the returned next_page_token or cursor until none remains. Parallelize fetching pages if tool supports page_number.\n 9. No Hardcoding: Never hardcode data in code. Always load it from files or tool responses, iterating to construct intermediate or final inputs/outputs.\n 10. If the final output is in a workbench file, use upload_local_file to download it - never expose the raw workbench file path to the user. Prefer to download useful artifacts after task is complete.\n\n\nENV & HELPERS:\n- Home directory: `/home/user`.\n- NOTE: Helper functions already initialized in the workbench - DO NOT import or redeclare them:\n - \n`run_composio_tool(tool_slug: str, arguments: dict) -> tuple[Dict[str, Any], str]`: Execute a known Composio **app** tool (from COMPOSIO_SEARCH_TOOLS). Do not invent names; match the tool's input schema. Suited for loops/parallel/bulk over datasets.\n i) run_composio_tool returns JSON with top-level \"data\". Parse carefully—structure may be nested.\n \n - \n`invoke_llm(query: str) -> tuple[str, str]`: Invoke an LLM for semantic tasks. Pass MAX 200k characters in input.\n i) NOTE Prompting guidance: When building prompts for invoke_llm, prefer f-strings (or concatenation) so literal braces stay intact. If using str.format, escape braces by doubling them ({{ }}).\n ii) Define the exact JSON schema you want and batch items into smaller groups to stay within token limit.\n\n - `upload_local_file(*file_paths) -> tuple[Dict[str, Any], str]`: Upload files in workbench to Composio S3/R2 storage. Use this to download any generated files/artifacts from the workbench.\n - `proxy_execute(method, endpoint, toolkit, query_params=None, body=None, headers=None) -> tuple[Any, str]`: Call a toolkit API directly when no Composio tool exists. Only one toolkit can be invoked with proxy_execute per workbench call\n - `web_search(query: str) -> tuple[str, str]`: Search the web for information.\n - `smart_file_extract(sandbox_file_path: str, show_preview: bool = True) -> tuple[str, str]`: Extracts text from files in the sandbox (e.g., PDF, image).\n - Workbench comes with comprehensive Image Processing (PIL/Pillow, OpenCV, scikit-image), PyTorch ML libraries, Document and Report handling tools (pandoc, python-docx, pdfplumber, reportlab), and standard Data Analysis tools (pandas, numpy, matplotlib) for advanced visual, analytical, and AI tasks.\n All helper functions return a tuple (result, error). Always check error before using result.\n\n## Python Helper Functions for LLM Scripting\n\n\n### run_composio_tool(tool_slug, arguments)\nExecutes a known Composio tool via backend API. Do NOT call COMPOSIO_* meta tools to avoid cyclic calls.\n\n def run_composio_tool(tool_slug: str, arguments: Dict[str, Any]) -> tuple[Dict[str, Any], str]\n # Returns: (tool_response_dict, error_message)\n # Success: ({\"data\": {actual_data}}, \"\") - Note the top-level data\n # Error: ({}, \"error_message\") or (response_data, \"error_message\")\n\n result, error = run_composio_tool(\"GMAIL_FETCH_EMAILS\", {\"max_results\": 1, \"user_id\": \"me\"})\n if error:\n print(\"GMAIL_FETCH_EMAILS error:\", error); return\n email_data = result.get(\"data\", {})\n print(\"Fetched:\", email_data)\n \n\n\n### invoke_llm(query)\nCalls LLM for reasoning, analysis, and semantic tasks. Pass MAX 200k characters input.\n\n def invoke_llm(query: str) -> tuple[str, str]\n # Returns: (llm_response, error_message)\n\n resp, error = invoke_llm(\"Summarize the key points from this data\")\n if not error:\n print(\"LLM:\", resp)\n\n # Example: analyze tool response with LLM\n tool_resp, err = run_composio_tool(\"GMAIL_FETCH_EMAILS\", {\"max_results\": 5, \"user_id\": \"me\"})\n if not err:\n parsed = tool_resp.get(\"data\", {})\n resp, err2 = invoke_llm(f\"Analyze these emails and summarize: {parsed}\")\n if not err2:\n print(\"LLM Gmail Summary:\", resp)\n # TIP: batch prompts to reduce LLM calls.\n \n\n\n### upload_local_file(*file_paths)\nUploads sandbox files to Composio S3/R2 storage. Single files upload directly, multiple files are auto-zipped.\nUse this when you need to upload/download any generated artifacts from the sandbox.\n\n def upload_local_file(*file_paths) -> tuple[Dict[str, Any], str]\n # Returns: (result_dict, error_string)\n # Success: ({\"s3_url\": str, \"uploaded_file\": str, \"type\": str, \"id\": str, \"s3key\": str, \"message\": str}, \"\")\n # Error: ({}, \"error_message\")\n\n # Single file\n result, error = upload_local_file(\"/path/to/report.pdf\")\n\n # Multiple files (auto-zipped)\n result, error = upload_local_file(\"/home/user/doc1.txt\", \"/home/user/doc2.txt\")\n\n if not error:\n print(\"Uploaded:\", result[\"s3_url\"])\n\n\n### proxy_execute(method, endpoint, toolkit, query_params=None, body=None, headers=None)\nDirect API call to a connected toolkit service.\n\n def proxy_execute(\n method: Literal[\"GET\",\"POST\",\"PUT\",\"DELETE\",\"PATCH\"],\n endpoint: str,\n toolkit: str,\n query_params: Optional[Dict[str, str]] = None,\n body: Optional[object] = None,\n headers: Optional[Dict[str, str]] = None,\n ) -> tuple[Any, str]\n # Returns: (response_data, error_message)\n\n # Example: GET request with query parameters\n query_params = {\"q\": \"is:unread\", \"maxResults\": \"10\"}\n data, error = proxy_execute(\"GET\", \"/gmail/v1/users/me/messages\", \"gmail\", query_params=query_params)\n if not error:\n print(\"Success:\", data)\n\n\n### web_search(query)\nSearches the web via Exa AI.\n\n def web_search(query: str) -> tuple[str, str]\n # Returns: (search_results_text, error_message)\n\n results, error = web_search(\"latest developments in AI\")\n if not error:\n print(\"Results:\", results)\n\n## Best Practices\n\n\n### Error-first pattern and Defensive parsing (print keys while narrowing)\n res, err = run_composio_tool(\"GMAIL_FETCH_EMAILS\", {\"max_results\": 5})\n if err:\n print(\"error:\", err); return\n if isinstance(res, dict):\n print(\"res keys:\", list(res.keys()))\n data = res.get(\"data\") or {}\n print(\"data keys:\", list(data.keys()))\n msgs = data.get(\"messages\") or []\n print(\"messages count:\", len(msgs))\n for m in msgs:\n print(\"subject:\", m.get(\"subject\", \"<missing>\"))\n\n### Parallelize (4-min sandbox timeout)\nAdjust concurrency so all tasks finish within 4 minutes.\n\n import concurrent.futures\n\n MAX_CONCURRENCY = 10 # Adjust as needed\n\n def send_bulk_emails(email_list):\n def send_single(email):\n result, error = run_composio_tool(\"GMAIL_SEND_EMAIL\", {\n \"to\": email[\"recipient\"], \"subject\": email[\"subject\"], \"body\": email[\"body\"]\n })\n if error:\n print(f\"Failed {email['recipient']}: {error}\")\n return {\"status\": \"failed\", \"error\": error}\n return {\"status\": \"sent\", \"data\": result}\n\n results = []\n with concurrent.futures.ThreadPoolExecutor(max_workers=MAX_CONCURRENCY) as ex:\n futures = [ex.submit(send_single, e) for e in email_list]\n for f in concurrent.futures.as_completed(futures):\n results.append(f.result())\n return results\n\n email_list = [{\"recipient\": f\"user{i}@example.com\", \"subject\": \"Test\", \"body\": \"Hello\"} for i in range(1000)]\n results = send_bulk_emails(email_list)\n \n\n ",+ "category": "sandbox",+ "categoryLabel": "Sandbox",+ "tags": [+ "destructiveHint",+ "openWorldHint"+ ],+ "toolkit": {+ "slug": "COMPOSIO",+ "name": "composio",+ "logo": "https://cdn.jsdelivr.net/gh/ComposioHQ/open-logos@master/composio-logo.png"+ },+ "inputParameters": {+ "description": "Remote Workbench — run analysis/orchestration in a persistent remote sandbox.\nUse only when working with remote artifacts or when you must script multiple Composio tool calls.\nAvoid if the needed data is already inline in the chat/context.",+ "properties": {+ "code_to_execute": {+ "description": "Python to run inside the persistent **remote Jupyter sandbox**. State (imports, variables, files) is preserved across executions. Keep code concise to minimize tool call latency. Avoid unnecessary comments.",+ "examples": [+ "import json, glob\npaths = glob.glob(file_path)\n...",+ "result, error = run_composio_tool(tool_slug='SLACK_SEARCH_MESSAGES', arguments={'query': 'Rube'})\nif error: return\nmessages = result.get('data', {}).get('messages', [])"+ ],+ "title": "Code To Execute",+ "type": "string"+ },+ "thought": {+ "description": "Concise objective and high-level plan (no private chain-of-thought). 1 sentence describing what the cell should achieve and why the sandbox is needed.",+ "title": "Thought",+ "type": "string"+ },+ "session_id": {+ "description": "ALWAYS pass the session_id that was provided in the SEARCH_TOOLS response.",+ "title": "Session ID",+ "type": "string"+ },+ "current_step": {+ "description": "Short enum for current step of the workflow execution. Eg FETCHING_EMAILS, GENERATING_REPLIES. Always include to keep execution aligned with the workflow.",+ "title": "Current Step",+ "type": "string"+ },+ "current_step_metric": {+ "description": "Progress metrics for the current step - use to track how far execution has advanced. Format as a string \"done/total units\" - example \"10/100 emails\", \"0/n messages\", \"3/10 pages\".",+ "title": "Current Step Metric",+ "type": "string"+ }+ },+ "required": [+ "code_to_execute"+ ],+ "title": "RemoteWorkbenchRequest",+ "type": "object"+ },+ "responseSchema": {+ "properties": {+ "data": {+ "additionalProperties": false,+ "description": "Data from the action execution",+ "properties": {+ "error": {+ "default": "",+ "description": "Error message if any",+ "title": "Error",+ "type": "string"+ },+ "results": {+ "description": "The results of the code execution",+ "title": "Results",+ "type": "string"+ },+ "results_file_path": {+ "description": "Path to file containing full results if output was truncated",+ "title": "Results File Path",+ "type": "string"+ },+ "session": {+ "description": "Session info echoed back to reinforce reuse: { id: string, instructions: string }",+ "additionalProperties": false,+ "properties": {+ "id": {+ "type": "string"+ },+ "instructions": {+ "type": "string"+ }+ },+ "required": [+ "id",+ "instructions"+ ],+ "title": "Session",+ "type": "object"+ },+ "stderr": {+ "description": "The standard error output from the command",+ "title": "Stderr",+ "type": "string"+ },+ "stderr_file_path": {+ "description": "Path to file containing full stderr if output was truncated",+ "title": "Stderr File Path",+ "type": "string"+ },+ "stdout": {+ "description": "The standard output from the command",+ "title": "Stdout",+ "type": "string"+ },+ "stdout_file_path": {+ "description": "Path to file containing full stdout if output was truncated",+ "title": "Stdout File Path",+ "type": "string"+ },+ "sandbox_id_suffix": {+ "description": "Last 4 digits of the sandbox ID for easier reference",+ "title": "Sandbox ID Suffix",+ "type": "string"+ }+ },+ "required": [+ "results",+ "stdout",+ "stderr"+ ],+ "title": "Data",+ "type": "object"+ },+ "error": {+ "default": null,+ "description": "Error if any occurred during the execution of the action",+ "nullable": true,+ "title": "Error",+ "type": "string"+ },+ "successful": {+ "description": "Whether or not the action execution was successful or not",+ "title": "Successful",+ "type": "boolean"+ }+ },+ "required": [+ "data",+ "successful"+ ],+ "title": "RemoteWorkbenchResponseWrapper",+ "type": "object"+ }+ }+]\ No newline at end of filediff --git a/docs/scripts/generate-meta-tools.ts b/docs/scripts/generate-meta-tools.tsnew file mode 100644index 000000000..93f58a6bc--- /dev/null+++ b/docs/scripts/generate-meta-tools.ts@@ -0,0 +1,233 @@+/**+ * Meta Tools Generator Script+ *+ * Fetches meta tool definitions from the Composio Tool Router API and generates:+ * - /public/data/meta-tools.json (complete meta tool schemas from API)+ * - /content/reference/meta-tools/meta.json (sidebar navigation)+ * - /content/reference/meta-tools/index.mdx (overview page)+ * - /content/reference/meta-tools/{name}.mdx (individual tool pages)+ *+ * All output is derived from the API response — no hardcoded tool definitions.+ *+ * Run: bun run generate:meta-tools+ *+ * Environment variables:+ * - COMPOSIO_API_KEY (required)+ * - COMPOSIO_API_BASE (optional, defaults to https://backend.composio.dev/api/v3)+ */++import { writeFile, mkdir, readdir, unlink } from 'fs/promises';+import { join } from 'path';++const API_BASE = process.env.COMPOSIO_API_BASE || 'https://backend.composio.dev/api/v3';+const API_KEY = process.env.COMPOSIO_API_KEY;++if (!API_KEY) {+ console.error('Error: COMPOSIO_API_KEY environment variable is required');+ process.exit(1);+}++const DATA_DIR = join(process.cwd(), 'public/data');+const CONTENT_DIR = join(process.cwd(), 'content/reference/meta-tools');++async function createSession(): Promise<string> {+ console.log('Creating session...');++ const response = await fetch(`${API_BASE}/tool_router/session`, {+ method: 'POST',+ headers: {+ 'Content-Type': 'application/json',+ 'x-api-key': API_KEY!,+ },+ body: JSON.stringify({+ user_id: 'default',+ config: {+ autoManageConnections: true,+ recipesEnabled: true,+ enableWaitForConnections: true,+ },+ }),+ });++ if (!response.ok) {+ const body = await response.text();+ throw new Error(`Failed to create session: ${response.status} ${response.statusText}\n${body}`);+ }++ const data = await response.json();+ const sessionId = data.session_id;++ if (!sessionId) {+ throw new Error('No session_id in response');+ }++ console.log(` Session created: ${sessionId}`);+ console.log(` Tools available: ${(data.tool_router_tools || []).join(', ')}`);+ return sessionId;+}++async function fetchMetaTools(sessionId: string): Promise<any[]> {+ console.log('Fetching meta tools with schemas...');++ const response = await fetch(`${API_BASE}/tool_router/session/${sessionId}/tools`, {+ headers: {+ 'x-api-key': API_KEY!,+ },+ });++ if (!response.ok) {+ const body = await response.text();+ throw new Error(`Failed to fetch meta tools: ${response.status} ${response.statusText}\n${body}`);+ }++ const data = await response.json();+ const tools = data.items || data;++ if (!Array.isArray(tools)) {+ throw new Error('Expected array of tools in response');+ }++ console.log(` Found ${tools.length} meta tools`);+ return tools;+}++function transformTool(raw: any) {+ const slug: string = raw.slug || '';++ return {+ slug,+ name: raw.name || '',+ displayName: raw.name?.replace(/_/g, ' ').replace(/\b\w/g, (c: string) => c.toUpperCase()) || slug,+ description: raw.description || '',+ tags: raw.tags || [],+ toolkit: raw.toolkit || null,+ inputParameters: raw.input_parameters || {},+ responseSchema: raw.output_parameters || {},+ };+}++/** Derive a short page slug from the tool slug: COMPOSIO_SEARCH_TOOLS -> search_tools */+function pageSlug(toolSlug: string): string {+ return toolSlug.toLowerCase().replace('composio_', '');+}++/** Truncate description to first sentence for index table */+function briefDescription(description: string): string {+ // Strip markdown and leading whitespace+ const cleaned = description.replace(/\*\*/g, '').replace(/__/g, '').replace(/\n+/g, ' ').trim();+ const firstSentence = cleaned.split(/\.(\s|$)/)[0];+ if (firstSentence.length > 120) {+ return firstSentence.slice(0, 117) + '...';+ }+ return firstSentence;+}++/** Generate the index.mdx overview page — flat table of all tools */+function generateIndexMdx(tools: any[]): string {+ let content = `---+title: Meta Tools+description: Complete reference for all Composio meta tools available in sessions.+keywords: [meta tools, session]+---++{/* Auto-generated by scripts/generate-meta-tools.ts — do not edit manually */}++import { Callout } from 'fumadocs-ui/components/callout';++<Callout type="warn">+Meta tool schemas are for reference only. We do not guarantee backward compatibility for parameter names or response shapes. Do not rely on them for structured type definitions in your code.+</Callout>++Meta tools are system-level tools available in [sessions](/docs/tools-and-toolkits). They handle tool discovery, execution, authentication, and sandboxing.++| Tool | Description |+|------|-------------|+`;++ for (const tool of tools) {+ content += `| [\`${tool.slug}\`](/reference/meta-tools/${pageSlug(tool.slug)}) | ${briefDescription(tool.description)} |\n`;+ }++ return content;+}++/** Generate an individual tool MDX page */+function generateToolMdx(tool: any): string {+ const desc = briefDescription(tool.description).replace(/"/g, '\\"');++ return `---+title: ${tool.displayName}+description: "${desc}"+keywords: [${tool.slug}, meta tool]+---++{/* Auto-generated by scripts/generate-meta-tools.ts — do not edit manually */}++import { MetaToolDetailServer } from '@/components/meta-tools/meta-tool-page';++<MetaToolDetailServer slug="${tool.slug}" />+`;+}++/** Generate meta.json for sidebar navigation — index.mdx is the folder page */+function generateMetaJson(tools: any[]): string {+ const pages = tools.map(t => pageSlug(t.slug));+ return JSON.stringify({ title: 'Meta Tools', defaultOpen: true, pages }, null, 2) + '\n';+}++async function cleanGeneratedMdx() {+ try {+ const files = await readdir(CONTENT_DIR);+ for (const file of files) {+ if (file.endsWith('.mdx') || file === 'meta.json') {+ await unlink(join(CONTENT_DIR, file));+ }+ }+ } catch {+ // Directory doesn't exist yet, that's fine+ }+}++async function main() {+ console.log('Starting meta tools generation...\n');++ await mkdir(DATA_DIR, { recursive: true });+ await mkdir(CONTENT_DIR, { recursive: true });++ const sessionId = await createSession();+ const rawTools = await fetchMetaTools(sessionId);+ const metaTools = rawTools.map(transformTool);++ // Sort alphabetically by slug+ metaTools.sort((a, b) => a.slug.localeCompare(b.slug));++ // 1. Write JSON data+ await writeFile(join(DATA_DIR, 'meta-tools.json'), JSON.stringify(metaTools, null, 2));+ console.log(`\nWrote public/data/meta-tools.json (~${Math.round(JSON.stringify(metaTools).length / 1024)}KB)`);++ // 2. Clean old generated MDX files and regenerate+ await cleanGeneratedMdx();++ // 3. Write meta.json+ await writeFile(join(CONTENT_DIR, 'meta.json'), generateMetaJson(metaTools));+ console.log('Wrote content/reference/meta-tools/meta.json');++ // 4. Write index.mdx+ await writeFile(join(CONTENT_DIR, 'index.mdx'), generateIndexMdx(metaTools));+ console.log('Wrote content/reference/meta-tools/index.mdx');++ // 5. Write individual tool pages+ for (const tool of metaTools) {+ const filename = `${pageSlug(tool.slug)}.mdx`;+ await writeFile(join(CONTENT_DIR, filename), generateToolMdx(tool));+ console.log(`Wrote content/reference/meta-tools/${filename}`);+ }++ console.log(`\nGeneration complete! ${metaTools.length} meta tools.`);+ console.log(`Tools: ${metaTools.map(t => t.slug).join(', ')}`);+}++main().catch((error) => {+ console.error('Fatal error:', error);+ process.exit(1);+});