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

next
ts 86 lines 6.08 KB
Raw
1 import { resolveToolkitCount } from './toolkit-count';
2
3 /**
4 * Hand-written copy overrides for meta tool reference pages.
5 *
6 * The meta tool JSON (`public/data/meta-tools.json`) and the generated MDX are
7 * generated by `scripts/generate-meta-tools.ts`, so
8 * editing those gets clobbered. This map survives regeneration: it is merged
9 * over the schema snapshot at read time in `lib/meta-tools-data.ts`.
10 *
11 * Each entry provides Modal-voice display copy. The API still owns the input
12 * and response schemas; we only override the prose.
13 */
14
15 export interface MetaToolOverride {
16 /** One confident sentence on what the tool does. Replaces the API description for display. */
17 summary: string;
18 /** When you should reach for this tool in a session. */
19 whenToUse: string;
20 /** Optional short note on usage, ordering, or gotchas. */
21 usageNote?: string;
22 }
23
24 export const META_TOOL_OVERRIDES: Record<string, MetaToolOverride> = {
25 COMPOSIO_PROXY_EXECUTE: {
26 summary:
27 "Sends a raw HTTP request to a connected app's own API, authenticated with your connected account, for endpoints no Composio tool covers.",
28 whenToUse:
29 'Use `COMPOSIO_PROXY_EXECUTE` when no tool from `COMPOSIO_SEARCH_TOOLS` covers the endpoint you need. The toolkit needs an active connection first; call `COMPOSIO_MANAGE_CONNECTIONS` if it has none.',
30 usageNote:
31 'Enable it with `proxyExecute: true` in TypeScript or `proxy_execute=True` in Python. Compared with `session.proxyExecute()`, pass `toolkit_slug` instead of `toolkit`, use `type` instead of `in` for each parameter\'s location, and `method` also accepts `HEAD`. Composio attaches credentials. If the request cannot be sent, the tool returns `successful: false` with an `error`; an upstream non-2xx response returns normally in `data`, with its HTTP `status` and body. Large responses can be offloaded to the sandbox.',
32 },
33 COMPOSIO_SEARCH_TOOLS: {
34 summary:
35 'Discovers the right tools across %TOOLKIT_COUNT% toolkits for a task and returns them with an execution plan, connection status, and the `session_id` that ties the rest of the workflow together.',
36 whenToUse:
37 'Call `COMPOSIO_SEARCH_TOOLS` first, at the start of any task that touches an external app or service. Run it again whenever the user pivots to a new use case so you get a fresh `session_id` and a plan scoped to the new work.',
38 usageNote:
39 'Split a request into atomic queries (one query per tool call) and name the app in each query so intent stays scoped. The response tells you which toolkits already have an active connection and which need `COMPOSIO_MANAGE_CONNECTIONS`.',
40 },
41 COMPOSIO_GET_TOOL_SCHEMAS: {
42 summary:
43 'Returns the full input schema for tools you already know the slug for, so you can build schema-compliant arguments before executing.',
44 whenToUse:
45 'Reach for `COMPOSIO_GET_TOOL_SCHEMAS` when `COMPOSIO_SEARCH_TOOLS` hands you a tool with a `schemaRef` instead of an inline `input_schema`, or when you need the `output_schema` to validate a response in the workbench.',
46 usageNote:
47 'Only pass slugs that `COMPOSIO_SEARCH_TOOLS` returned. Never guess or fabricate a slug. If a slug is not found, the response suggests close matches you can call again with.',
48 },
49 COMPOSIO_MANAGE_CONNECTIONS: {
50 summary:
51 'Checks connection status for a toolkit and returns a branded authentication link when the user needs to connect, covering OAuth, API keys, and every other auth type.',
52 whenToUse:
53 'Call `COMPOSIO_MANAGE_CONNECTIONS` when `COMPOSIO_SEARCH_TOOLS` reports that a toolkit has no active connection. You must have an active connection before you execute any tool from that toolkit.',
54 usageNote:
55 'When the tool returns a `redirect_url`, show it to the user as a formatted markdown link and wait for the connection to go active before executing. Set `reinitiate_all` to force a fresh connection when credentials are stale.',
56 },
57 COMPOSIO_MULTI_EXECUTE_TOOL: {
58 summary:
59 'Executes up to 50 tools in parallel and returns structured outputs ready for immediate analysis.',
60 whenToUse:
61 'Use `COMPOSIO_MULTI_EXECUTE_TOOL` to run tools that `COMPOSIO_SEARCH_TOOLS` discovered. Batch tools into one call only when they are logically independent, with no ordering or output-to-input dependencies between them.',
62 usageNote:
63 'Pass strictly schema-compliant arguments and make sure each toolkit has an active connection first. Set `sync_response_to_workbench` to true when a response may be large or needed for later scripting; otherwise process small responses inline.',
64 },
65 COMPOSIO_REMOTE_WORKBENCH: {
66 summary:
67 'Runs Python in a persistent remote sandbox to process large remote files and script bulk or repeated tool executions.',
68 whenToUse:
69 'Reach for `COMPOSIO_REMOTE_WORKBENCH` when data lives in a remote file rather than inline in the chat, when you need to run a known tool in bulk (for example, label 100 emails), or when you want to call an API via `proxy_execute` because no Composio tool exists for it.',
70 usageNote:
71 'State persists across calls like a Jupyter notebook, and helper functions such as `run_composio_tool` and `invoke_llm` are preloaded. There is a hard 3-minute execution limit per cell, so split work into steps and checkpoint intermediate results to `/mnt/files/`. Do not use it for data you can already see inline.',
72 },
73 COMPOSIO_REMOTE_BASH_TOOL: {
74 summary:
75 'Runs bash commands in a remote sandbox for file operations, data processing, and system tasks.',
76 whenToUse:
77 'Use `COMPOSIO_REMOTE_BASH_TOOL` to work with large tool responses that `COMPOSIO_MULTI_EXECUTE_TOOL` saved to remote files, or to run quick file and shell operations with tools like `jq`, `awk`, `sed`, and `grep`.',
78 usageNote:
79 'Commands run from `/home/user` by default and share the same 3-minute execution limit, so break large tasks into smaller commands.',
80 },
81 };
82
83 export function getMetaToolOverride(slug: string): MetaToolOverride | undefined {
84 const override = META_TOOL_OVERRIDES[slug];
85 return override ? { ...override, summary: resolveToolkitCount(override.summary) } : undefined;
86 }