@devries-cameron20 / composio Mirror · read-only / commits / 4d2b02b6e
Fork 0

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

Mirrored from https://github.com/Camo67/composio.git

Synced Nov 21, 03:37 UTC

docs: reconcile polling, proxy permissions, and SDK examples (#5476)

> Written by an AI agent for Brendan, following his spec. Brendan has not reviewed the full diff yet. ## Summary Reconcile the four inconsistencies reported in the [November 14 docs audit thread](https://composioworkspace.slack.com/archives/C0BR8LGHJP8/p1794695300065769) against current `origin/next`, the SDK implementations, the live tool catalog, and the backend permission enforcement code. | Item | Already fixed or verified | This PR | | --- | --- | --- | | Polling | #5149 corrected the managed polling minimum; the trigger overview and troubleshooting already say 2 minutes | Use 2 minutes in remaining maintained trigger examples and state the default explicitly | | Proxy permissions | The backend grants the session proxy route through **either** Session tool execution or Proxy execute with write access | Remove the incorrect exclusive-permission claims from guides, the permission reference, and KB; retain Proxy execute as required for the direct route | | GitHub tool slug | Catalog confirms `GITHUB_CREATE_AN_ISSUE`, required `owner`, `repo`, `title`, optional `body` | Correct maintained guides, API overviews, agent instructions, SDK source comments, and regenerated references; existing concrete arguments match the catalog schema | | Local tools | #5215 implemented local names and deprecated aliases; #5213 renamed the docs page but left old options in examples | Use local options and session methods in current examples; explain deprecated aliases once, Python warnings, and rejection of both names together | Designated reviewer: @jkomyno. Please review the full diff before merging. ## Changes - Keep all changelogs unchanged. The March 2026 polling entries, including whether to correct or supersede them, remain Brendan's decision. Historical examples retain their old spellings under this constraint. - Preserve Pi's unrelated `customTools` option and the server-side Custom MCP `customToolkits` API. API wire fields named `custom_tools` also remain unchanged. - Regenerate SDK references with their owning TypeScript/Python generators and API overviews with `generate:api-index`. SDK source edits are docstrings/comments only; no runtime behavior or public API changes, so no changeset. - Checked merged and open PRs. In particular, #5322's per-app trigger table, #5065's SDK docs automation, and #5474's stale semantic artifact repair are separate work and are not duplicated here. <!-- sdk-release-note-exempt: SDK source edits only correct slugs inside docstrings and comments; runtime code and public API behavior are unchanged. --> ## Type of change - [x] Documentation ## How Has This Been Tested? **Primary source for proxy permissions:** [platform catalog at `3c17ab7b`](https://github.com/ComposioHQ/platform/blob/3c17ab7b800a75df7cf3f27f6b625754eae86741/apps/apollo/src/lib/apiKeys/project_api_key_permissions/catalog.ts#L182), [route matching](https://github.com/ComposioHQ/platform/blob/3c17ab7b800a75df7cf3f27f6b625754eae86741/apps/apollo/src/lib/apiKeys/project_api_key_permissions/match.ts#L36), and [enforcement](https://github.com/ComposioHQ/platform/blob/3c17ab7b800a75df7cf3f27f6b625754eae86741/apps/apollo/src/lib/apiKeys/project_api_key_permissions/enforce.ts#L48). I downloaded these source files and executed their actual matching/enforcement functions with one permission at a time. Both API versions returned: | Key permission, write access | Session proxy | Direct proxy | | --- | --- | --- | | `session_tool_execution` | allowed | denied | | `proxy_execute` | allowed | allowed | | `session_management` | denied | denied | | `tool_execution` | denied | denied | This verifies source behavior, not a live request with separately scoped keys. The change that would have made Proxy execute exclusive, [platform#12846](https://github.com/ComposioHQ/platform/pull/12846), was closed without merging. The removed claim about sandbox inheritance was not supported by this API-key check: sandbox helpers use a separate WORKBENCH-authenticated internal route. Existing sandbox configuration guidance is retained. **Local checks:** - `composio execute GITHUB_CREATE_AN_ISSUE --get-schema`: catalog version `20261116_01`; inspected schema and concrete example arguments. No tool executed. - `bun run check:code-examples`, `check:api-snippets`, `check:python-snippets`, `check:typescript-snippets`: pass. - `bun run lint`: passes with existing warnings. `bun run lint:links`: 0 errors. The first link check raced SDK reference regeneration; the rerun after regeneration passed. - `bun run types:check`: pass. - `GITHUB_ACTIONS=true timeout 20m bun run build`: exit 0, including Twoslash. Run in the foreground with no overlapping docs build. - Static suite: `bun run test --timeout 30000` passed all 816 tests, 0 failures. Initial run had 811 pass and 5 five-second timeouts while the build ran; the complete rerun passed. - Compared Python runtime ASTs and TypeScript printed ASTs with comments removed: unchanged for every SDK source file edited. - Independent Claude Sonnet 5.5 docs/evidence review found no blocking correctness issue; fixed its finding about old names in handwritten TS SDK guides. ## Checklist - [x] Read and reviewed the diff, including AI-generated changes - [x] Documentation updated; no runtime changes or new dependencies - [x] Third-party links follow the contribution policy - [x] No new tests needed for these prose/example corrections; existing docs checks exercised - [ ] All GitHub checks green before marking ready ## Additional context NEEDS BRENDAN: leave the March 2026 polling changelogs alone, add a correction note, or publish a new entry? This PR makes none of those choices. No unresolved source question remains for the public proxy API-key permission check. ELI5: Some docs used old names or described a restriction the backend never adopted. This makes current examples match the SDK and backend while leaving release-history decisions to Brendan.

Brendan O'Leary committed Nov 20, 2026 at 05:50 UTC 4d2b02b6ec3b120138e2983b405b1dc84234a3fd
42 files changed +121 -118
docs/agent/instructions/context.ts
+1 -1
@@ -17,7 +17,7 @@ This is your always-on map of Composio's concepts and the canonical page for eac
17
18 - **Apps and toolkits**: an App groups catalog toolkits for comparison. Composio Built toolkits use a product API; Provider MCP toolkits use its hosted MCP server. Each keeps separate tools and connections. Use exact toolkit slugs in session configuration. See [Apps and toolkits](/docs/apps-and-toolkits).
19
20 -- **Toolkit** — a collection of related tools for a service (e.g. \`github\`, \`gmail\`). A **tool** is one action, named \`{TOOLKIT}_{ACTION}\` (e.g. \`GITHUB_CREATE_ISSUE\`). Every toolkit is discoverable by default; restrict with the \`toolkits\` config. → [Configuring sessions](/docs/configuring-sessions)
20 +- **Toolkit** — a collection of related tools for a service (e.g. \`github\`, \`gmail\`). A **tool** is one action, named \`{TOOLKIT}_{ACTION}\` (e.g. \`GITHUB_CREATE_AN_ISSUE\`). Every toolkit is discoverable by default; restrict with the \`toolkits\` config. → [Configuring sessions](/docs/configuring-sessions)
21 - **Meta tools** — the fixed set every session exposes (\`COMPOSIO_SEARCH_TOOLS\`, \`COMPOSIO_GET_TOOL_SCHEMAS\`, \`COMPOSIO_MANAGE_CONNECTIONS\`, \`COMPOSIO_MULTI_EXECUTE_TOOL\`, \`COMPOSIO_REMOTE_WORKBENCH\`, \`COMPOSIO_REMOTE_BASH_TOOL\`). → [Meta tools reference](/toolkits/meta-tools)
22 - **Providers** — adapter packages that format Composio tools for a framework (OpenAI, Anthropic, Vercel AI SDK, LangChain, Mastra, Pi, …). → [Providers](/docs/providers)
23 - **Is a toolkit / integration supported?** Composio has ${TOOLKIT_COUNT_LABEL} toolkits, and \`search_docs\` indexes the catalog. A matching \`/toolkits/<slug>\` result means **yes, it's supported** — answer from the returned content when sufficient, call \`read_doc\` only for more details, and point the user at [the toolkits directory](/toolkits). If nothing matches, it isn't a built-in toolkit; suggest [proxy execute](/docs/extending-sessions/proxy-execute) or a [local tool](/docs/extending-sessions/local-tools-and-toolkits) for an API you already have.
docs/api-overviews/tools.mdx
+1 -1
@@ -1,4 +1,4 @@
1 -Tools are the individual executable actions inside a toolkit, like `GMAIL_SEND_EMAIL` or `GITHUB_CREATE_ISSUE`. Each tool has an input schema describing its parameters and an output schema describing what it returns. Tool slugs are SCREAMING_SNAKE_CASE and follow a `{TOOLKIT}_{ACTION}` pattern.
1 +Tools are the individual executable actions inside a toolkit, like `GMAIL_SEND_EMAIL` or `GITHUB_CREATE_AN_ISSUE`. Each tool has an input schema describing its parameters and an output schema describing what it returns. Tool slugs are SCREAMING_SNAKE_CASE and follow a `{TOOLKIT}_{ACTION}` pattern.
2
3 Reach for these endpoints when you want to:
4
docs/content/docs/authentication/index.mdx
+1 -1
@@ -30,7 +30,7 @@ Already have your own tools or agent framework? Follow [Managed authentication f
30 When users connect through a Connect Link and your agent acts through tools, your application never handles their OAuth tokens. Composio stores each connected account's credentials encrypted at rest and refreshes OAuth tokens before they expire. When your agent calls a tool, your backend sends a user ID or connected account ID plus the tool arguments. Composio adds the credential to the provider request server-side and returns the provider's response. Your application and the model receive tool results, not tokens.
31
32 - **No token export.** Connected-account API responses redact credentials by default, for both Composio-managed and custom auth configs. Reading account state isn't a supported way to retrieve tokens.
33 -- **Raw API access without the token.** For endpoints a tool doesn't cover, [Proxy Execute](/docs/extending-sessions/proxy-execute) sends an authenticated request to the provider and returns the response. It requires its own API key permission.
33 +- **Raw API access without the token.** For endpoints a tool doesn't cover, [Proxy Execute](/docs/extending-sessions/proxy-execute) sends an authenticated request to the provider and returns the response. Session proxy calls accept either the Session tool execution or Proxy execute API key permission with Write only access.
34 - **Least-privilege keys and sessions.** [Scoped API keys](/reference/authenticating-to-composio/project-api-key-permissions) separate session management from tool execution, and [session configuration](/docs/configuring-sessions) limits which toolkits and tools an agent can call.
35 - **Custody you choose.** In the default Composio Cloud deployment, Composio holds the encrypted credentials. Private VPC, self-hosted, and customer-managed key deployments change that boundary. With customer-managed keys, a proxy in your cloud decrypts credentials under your KMS keys, and Composio doesn't hold the key material.
36
docs/content/docs/authentication/managed-auth-for-custom-tools.mdx
+1 -1
@@ -14,7 +14,7 @@ This example connects GitHub and reads the connected account's profile through `
14
15 For a [scoped project API key](/reference/authenticating-to-composio/project-api-key-permissions), enable **Session management → Write only**, **Connected accounts → Read only**, and **Proxy execute (Legacy) → Write only**. Default full-access project keys already include these permissions. Keep the key server-side.
16
17 -Use the exact **Proxy execute (Legacy)** permission label when configuring a scoped key. The same permission also grants the current session proxy route. The label does not require a v3.0 API or a legacy SDK; the examples below use v3.1.
17 +Use the exact **Proxy execute (Legacy)** permission label when configuring a scoped key. It grants both the direct and session proxy routes. For session proxy calls, **Session tool execution → Write only** is another option. The label does not require a v3.0 API or a legacy SDK; the examples below use v3.1.
18
19 The example uses `org_42:user_7` as an illustrative connection owner. In your application, derive this value from the authenticated request after checking workspace membership. Never accept a model-supplied or browser-supplied owner ID as authorization. See [B2B connection ownership](/docs/b2b-agents#choose-the-connection-owner) for member-owned and workspace-owned connections.
20
docs/content/docs/configuring-sessions.mdx
+6 -6
@@ -412,7 +412,7 @@ session = composio.sessions.create(
412 # Only these Gmail tools will be available
413 "gmail": {"enable": ["GMAIL_SEND_EMAIL", "GMAIL_FETCH_EMAILS"]},
414 # Only issue-related GitHub tools
415 - "github": {"enable": ["GITHUB_CREATE_ISSUE", "GITHUB_GET_ISSUE"]}
415 + "github": {"enable": ["GITHUB_CREATE_AN_ISSUE", "GITHUB_GET_ISSUE"]}
416 }
417 )
418 ```
@@ -427,7 +427,7 @@ const session = await composio.create("user_123", {
427 // Only these Gmail tools will be available
428 gmail: { enable: ["GMAIL_SEND_EMAIL", "GMAIL_FETCH_EMAILS"] },
429 // Only issue-related GitHub tools
430 - github: { enable: ["GITHUB_CREATE_ISSUE", "GITHUB_GET_ISSUE"] }
430 + github: { enable: ["GITHUB_CREATE_AN_ISSUE", "GITHUB_GET_ISSUE"] }
431 }
432 });
433 ```
@@ -441,7 +441,7 @@ curl -X POST https://backend.composio.dev/api/v3.1/tool_router/session \
441 "user_id": "user_123",
442 "tools": {
443 "gmail": {"enable": ["GMAIL_SEND_EMAIL", "GMAIL_FETCH_EMAILS"]},
444 - "github": {"enable": ["GITHUB_CREATE_ISSUE", "GITHUB_GET_ISSUE"]}
444 + "github": {"enable": ["GITHUB_CREATE_AN_ISSUE", "GITHUB_GET_ISSUE"]}
445 }
446 }'
447 ```
@@ -457,7 +457,7 @@ session = composio.sessions.create(
457 user_id="user_123",
458 tools={
459 "gmail": ["GMAIL_SEND_EMAIL", "GMAIL_FETCH_EMAILS"],
460 - "github": ["GITHUB_CREATE_ISSUE", "GITHUB_GET_ISSUE"]
460 + "github": ["GITHUB_CREATE_AN_ISSUE", "GITHUB_GET_ISSUE"]
461 }
462 )
463 ```
@@ -470,7 +470,7 @@ const composio = new Composio({ apiKey: 'your_api_key' });
470 const session = await composio.create("user_123", {
471 tools: {
472 gmail: ["GMAIL_SEND_EMAIL", "GMAIL_FETCH_EMAILS"],
473 - github: ["GITHUB_CREATE_ISSUE", "GITHUB_GET_ISSUE"]
473 + github: ["GITHUB_CREATE_AN_ISSUE", "GITHUB_GET_ISSUE"]
474 }
475 });
476 ```
@@ -485,7 +485,7 @@ curl -X POST https://backend.composio.dev/api/v3.1/tool_router/session \
485 "user_id": "user_123",
486 "tools": {
487 "gmail": {"enable": ["GMAIL_SEND_EMAIL", "GMAIL_FETCH_EMAILS"]},
488 - "github": {"enable": ["GITHUB_CREATE_ISSUE", "GITHUB_GET_ISSUE"]}
488 + "github": {"enable": ["GITHUB_CREATE_AN_ISSUE", "GITHUB_GET_ISSUE"]}
489 }
490 }'
491 ```
docs/content/docs/extending-sessions/local-tools-and-toolkits.mdx
+18 -16
@@ -15,7 +15,9 @@ Local tools let you define tools that run in-process alongside remote Composio t
15 - **Extension tools**: wrap a Composio toolkit's API with custom business logic via `extendsToolkit` / `extends_toolkit`, using `ctx.proxyExecute()` / `ctx.proxy_execute()` for authenticated requests.
16 - **Local toolkits**: group related standalone tools under a namespace.
17
18 -Local tools were previously called custom tools. The SDK options keep their names: `customTools` / `custom_tools` and `customToolkits` / `custom_toolkits`.
18 +Pass `experimental.localTools` and `experimental.localToolkits` in TypeScript, or `experimental={"local_tools": ..., "local_toolkits": ...}` in Python, when creating a session. Use the same names without `experimental` when resuming with `composio.use()`.
19 +
20 +The previous `customTools` / `custom_tools` and `customToolkits` / `custom_toolkits` options and session methods still work as deprecated aliases. Python emits `ComposioDeprecationWarning` when you use them. Passing both a new option and its alias throws `ValidationError` in TypeScript or raises `InvalidParams` in Python.
21
22 <IntegrationTabs tabs={[
23 { value: "standalone", label: "Standalone Tool" },
@@ -137,7 +139,7 @@ composio = Composio(api_key="your_api_key")
139 session = composio.create(
140 user_id="user_1",
141 experimental={
140 - "custom_tools": [get_user_profile],
142 + "local_tools": [get_user_profile],
143 },
144 )
145
@@ -155,7 +157,7 @@ const composio = new Composio({ apiKey: "your_api_key" });
157
158 const session = await composio.create("user_1", {
159 experimental: {
158 - customTools: [getUserProfile],
160 + localTools: [getUserProfile],
161 },
162 });
163
@@ -308,7 +310,7 @@ session = composio.create(
310 user_id="user_1",
311 toolkits=["gmail"],
312 experimental={
311 - "custom_tools": [send_promo_email],
313 + "local_tools": [send_promo_email],
314 },
315 )
316
@@ -327,7 +329,7 @@ const composio = new Composio({ apiKey: "your_api_key" });
329 const session = await composio.create("user_1", {
330 toolkits: ["gmail"],
331 experimental: {
330 - customTools: [sendPromoEmail],
332 + localTools: [sendPromoEmail],
333 },
334 });
335
@@ -457,7 +459,7 @@ composio = Composio(api_key="your_api_key")
459 session = composio.create(
460 user_id="user_1",
461 experimental={
460 - "custom_toolkits": [user_management],
462 + "local_toolkits": [user_management],
463 },
464 )
465
@@ -475,7 +477,7 @@ const composio = new Composio({ apiKey: "your_api_key" });
477
478 const session = await composio.create("user_1", {
479 experimental: {
478 - customToolkits: [userManagement],
480 + localToolkits: [userManagement],
481 },
482 });
483
@@ -524,7 +526,7 @@ def get_reply_style_guide(input: ReplyGuideInput, ctx):
526 session = composio.create(
527 user_id="user_1",
528 experimental={
527 - "custom_tools": [get_reply_style_guide],
529 + "local_tools": [get_reply_style_guide],
530 },
531 )
532
@@ -558,7 +560,7 @@ const replyGuide = experimental_createTool("GET_REPLY_STYLE_GUIDE", {
560
561 const session = await composio.create("user_1", {
562 experimental: {
561 - customTools: [replyGuide],
563 + localTools: [replyGuide],
564 },
565 });
566
@@ -617,12 +619,12 @@ See the full API in the SDK reference: [TypeScript](/reference/sdk-reference/typ
619
620 Use these methods to list registered tools and toolkits. Slugs include their final `LOCAL_` prefix, and toolkit-scoped tools also include the toolkit slug.
621
620 -{/* code-example: no-api reason="custom_tools() and custom_toolkits() read the SDK session's local registry" */}
622 +{/* code-example: no-api reason="local_tools() and local_toolkits() read the SDK session's local registry" */}
623 <Tabs groupId="language" items={['Python', 'TypeScript']} persist>
624 <Tab value="Python">
625 ```python
624 -custom_tools = session.custom_tools()
625 -custom_toolkits = session.custom_toolkits()
626 +local_tools = session.local_tools()
627 +local_toolkits = session.local_toolkits()
628 ```
629 </Tab>
630 <Tab value="TypeScript">
@@ -631,8 +633,8 @@ import { Composio } from "@composio/core";
633 const composio = new Composio({ apiKey: "your_api_key" });
634 const session = await composio.create("user_1");
635 // ---cut---
634 -const customTools = session.customTools();
635 -const customToolkits = session.customToolkits();
636 +const localTools = session.localTools();
637 +const localToolkits = session.localToolkits();
638 ```
639 </Tab>
640 </Tabs>
@@ -651,7 +653,7 @@ composio = Composio(api_key="your_api_key")
653
654 session = composio.use(
655 "session_id",
654 - custom_tools=[get_user_profile],
656 + local_tools=[get_user_profile],
657 )
658 ```
659 </Tab>
@@ -665,7 +667,7 @@ const composio = new Composio({ apiKey: "your_api_key" });
667 // ---cut---
668
669 const session = await composio.use("session_id", {
668 - customTools: [getUserProfile],
670 + localTools: [getUserProfile],
671 });
672 ```
673 </Tab>
docs/content/docs/extending-sessions/proxy-execute.mdx
+1 -1
@@ -13,7 +13,7 @@ Proxy execute is a building block, not just a fallback. Use it to build experien
13 For the complete connection-to-request flow in your own backend, follow [Managed authentication for your own tools](/docs/authentication/managed-auth-for-custom-tools). It covers per-user OAuth, connection status, and account-specific proxy requests without an agent framework.
14
15 <Callout title="Use a scoped API key">
16 -Authenticate with a [scoped project API key](/reference/authenticating-to-composio/project-api-key-permissions) that has **Proxy execute** enabled. Session tool execution alone does not cover `session.proxyExecute()` or proxy calls made from that session's sandbox. Default full-access keys already include this permission.
16 +For `session.proxyExecute()`, authenticate with a [scoped project API key](/reference/authenticating-to-composio/project-api-key-permissions) that has **Session tool execution → Write only** or **Proxy execute (Legacy) → Write only**. Either permission grants the session proxy route. The direct `/tools/execute/proxy` route requires **Proxy execute (Legacy)**. Default full-access keys already cover both routes.
17 </Callout>
18
19 ## When to use it
docs/content/docs/how-composio-works.mdx
+1 -1
@@ -102,7 +102,7 @@ For OAuth toolkits, Composio uses [managed apps](/docs/authentication/custom-app
102
103 A **toolkit** is a collection of related tools for a service. The `github` toolkit, for example, contains tools for creating issues, managing pull requests, and starring repositories.
104
105 -A **tool** is an individual action your agent can execute. Each tool has an input schema (its parameters) and an output schema (what it returns), and follows a `{TOOLKIT}_{ACTION}` naming pattern, like `GITHUB_CREATE_ISSUE`.
105 +A **tool** is an individual action your agent can execute. Each tool has an input schema (its parameters) and an output schema (what it returns), and follows a `{TOOLKIT}_{ACTION}` naming pattern, like `GITHUB_CREATE_AN_ISSUE`.
106
107 See [Toolkits](/docs/toolkits) for how tools are grouped, discovered, and used with connected accounts.
108
docs/content/docs/migration-guide/managed-to-own-app.mdx
+1 -1
@@ -283,7 +283,7 @@ curl -s "https://backend.composio.dev/api/v3.1/trigger_instances/active?connecte
283 curl -X POST https://backend.composio.dev/api/v3.1/trigger_instances/GMAIL_NEW_GMAIL_MESSAGE/upsert \
284 -H "x-api-key: $COMPOSIO_API_KEY" \
285 -H "Content-Type: application/json" \
286 - -d '{"user_id": "user_123", "connected_account_id": "ca_new_own_app_account", "trigger_config": {}, "type": "poll", "polling_interval": 15}' \
286 + -d '{"user_id": "user_123", "connected_account_id": "ca_new_own_app_account", "trigger_config": {}, "type": "poll", "polling_interval": 2}' \
287 | jq '{trigger_id, type, polling_interval}'
288
289 # After your event filters use the new trigger_id, disable the old instance
docs/content/docs/migration-guide/mcp-servers-to-sessions.mdx
+3 -3
@@ -283,7 +283,7 @@ For a deterministic, non-agent path, call a tool directly on the session.
283 <Tab value="Python">
284 ```python
285 result = session.execute(
286 - "GITHUB_CREATE_ISSUE",
286 + "GITHUB_CREATE_AN_ISSUE",
287 arguments={"owner": "my-org", "repo": "my-repo", "title": "Fix login bug"},
288 )
289 ```
@@ -294,7 +294,7 @@ import { Composio } from '@composio/core';
294 const composio = new Composio({ apiKey: process.env.COMPOSIO_API_KEY });
295 const session = await composio.create("user-123");
296 // ---cut---
297 -const result = await session.execute("GITHUB_CREATE_ISSUE", {
297 +const result = await session.execute("GITHUB_CREATE_AN_ISSUE", {
298 owner: "my-org",
299 repo: "my-repo",
300 title: "Fix login bug",
@@ -308,7 +308,7 @@ curl -X POST https://backend.composio.dev/api/v3.1/tool_router/session/$SESSION_
308 -H "x-api-key: $COMPOSIO_API_KEY" \
309 -H "Content-Type: application/json" \
310 -d '{
311 - "tool_slug": "GITHUB_CREATE_ISSUE",
311 + "tool_slug": "GITHUB_CREATE_AN_ISSUE",
312 "arguments": {"owner": "my-org", "repo": "my-repo", "title": "Fix login bug"}
313 }'
314 ```
docs/content/docs/migration-guide/new-sdk.mdx
+2 -2
@@ -650,7 +650,7 @@ def get_issue_info(input: GetIssueInfoInput, ctx) -> dict:
650
651 session = composio.create(
652 user_id="default",
653 - experimental={"custom_tools": [get_issue_info]},
653 + experimental={"local_tools": [get_issue_info]},
654 )
655 ```
656 </Tab>
@@ -682,7 +682,7 @@ const getIssueInfo = experimental_createTool("GET_ISSUE_INFO", {
682 });
683
684 const session = await composio.create("default", {
685 - experimental: { customTools: [getIssueInfo] },
685 + experimental: { localTools: [getIssueInfo] },
686 });
687 ```
688 </Tab>
docs/content/docs/migration-guide/toolkit-versioning.mdx
+4 -4
@@ -18,7 +18,7 @@ Manual tool execution now requires explicit version specification. The `tools.ex
18 ```python
19 # Raises ToolVersionRequiredError
20 result = composio.tools.execute(
21 - "GITHUB_CREATE_ISSUE",
21 + "GITHUB_CREATE_AN_ISSUE",
22 arguments={"owner": "composio", "repo": "composio", "title": "Bug report"},
23 user_id="user-123",
24 )
@@ -28,7 +28,7 @@ result = composio.tools.execute(
28 ```typescript
29 // @noErrors
30 // Throws ComposioToolVersionRequiredError
31 -const result = await composio.tools.execute("GITHUB_CREATE_ISSUE", {
31 +const result = await composio.tools.execute("GITHUB_CREATE_AN_ISSUE", {
32 userId: "user-123",
33 arguments: { owner: "composio", repo: "composio", title: "Bug report" }
34 });
@@ -146,7 +146,7 @@ During migration, you can temporarily skip version checks (not recommended for p
146 <Tab value="Python">
147 ```python
148 result = composio.tools.execute(
149 - "GITHUB_CREATE_ISSUE",
149 + "GITHUB_CREATE_AN_ISSUE",
150 arguments={"owner": "composio", "repo": "composio", "title": "Bug report"},
151 user_id="user-123",
152 dangerously_skip_version_check=True,
@@ -156,7 +156,7 @@ result = composio.tools.execute(
156 <Tab value="TypeScript">
157 ```typescript
158 // @noErrors
159 -const result = await composio.tools.execute("GITHUB_CREATE_ISSUE", {
159 +const result = await composio.tools.execute("GITHUB_CREATE_AN_ISSUE", {
160 userId: "user-123",
161 arguments: { owner: "composio", repo: "composio", title: "Bug report" },
162 dangerouslySkipVersionCheck: true
docs/content/docs/session-configs.mdx
+1 -1
@@ -87,7 +87,7 @@ A saved policy uses `enable` and `disable`, the same shape you send on create. `
87
88 ## What you can combine with a config
89
90 -The config owns the session's toolkit, tool, and tag access. On `create()`, you can't pass `sessionConfigId` together with `toolkits`, `tools`, `tags`, `experimental.customTools`, or `experimental.customToolkits`. TypeScript reports the mix at compile time, and the SDK throws `ValidationError` before it sends a request. An empty list such as `toolkits: []` counts as set.
90 +The config owns the session's toolkit, tool, and tag access. On `create()`, you can't pass `sessionConfigId` together with `toolkits`, `tools`, `tags`, `experimental.localTools`, or `experimental.localToolkits`. TypeScript reports the mix at compile time, and the SDK throws `ValidationError` before it sends a request. An empty list such as `toolkits: []` counts as set.
91
92 Per-session settings stay yours: `authConfigs`, `connectedAccounts`, `manageConnections`, `sandbox`, `multiAccount`, `preload`, `sessionPreset`, `mcp`, and `experimental.assistivePrompt`.
93
docs/content/docs/sessions-vs-direct-execution.mdx
+8 -8
@@ -83,12 +83,12 @@ The agent discovers app tools through `COMPOSIO_SEARCH_TOOLS`:
83 User: "Create a GitHub issue for the login bug"
84
85 > Agent calls COMPOSIO_SEARCH_TOOLS({ query: "create github issue" })
86 - Returns: GITHUB_CREATE_ISSUE schema + connection status
86 + Returns: GITHUB_CREATE_AN_ISSUE schema + connection status
87
88 > Agent calls COMPOSIO_MANAGE_CONNECTIONS({ toolkits: ["github"] })
89 Returns: confirms connected (or auth link if not)
90
91 -> Agent calls COMPOSIO_MULTI_EXECUTE_TOOL({ tool: "GITHUB_CREATE_ISSUE", args: {...} })
91 +> Agent calls COMPOSIO_MULTI_EXECUTE_TOOL({ tool: "GITHUB_CREATE_AN_ISSUE", args: {...} })
92 Returns: issue details
93
94 Agent: "Created issue #42 on your-org/your-repo"
@@ -160,7 +160,7 @@ composio = Composio(
160 # Fetch specific tools
161 tools = composio.tools.get(
162 user_id="user_123",
163 - tools=["GITHUB_CREATE_ISSUE", "GITHUB_LIST_ISSUES"]
163 + tools=["GITHUB_CREATE_AN_ISSUE", "GITHUB_LIST_ISSUES"]
164 )
165
166 # Or by toolkit
@@ -172,7 +172,7 @@ tools = composio.tools.get(
172
173 # Execute without an LLM
174 result = composio.tools.execute(
175 - "GITHUB_CREATE_ISSUE",
175 + "GITHUB_CREATE_AN_ISSUE",
176 user_id="user_123",
177 arguments={"owner": "my-org", "repo": "my-repo", "title": "Fix login bug"},
178 dangerously_skip_version_check=True, # required when running "latest"; or pin via version=...
@@ -192,7 +192,7 @@ const composio = new Composio({
192
193 // Fetch specific tools
194 const tools = await composio.tools.get("user_123", {
195 - tools: ["GITHUB_CREATE_ISSUE", "GITHUB_LIST_ISSUES"],
195 + tools: ["GITHUB_CREATE_AN_ISSUE", "GITHUB_LIST_ISSUES"],
196 });
197
198 // Or by toolkit
@@ -202,7 +202,7 @@ const allTools = await composio.tools.get("user_123", {
202 });
203
204 // Execute without an LLM
205 -const result = await composio.tools.execute("GITHUB_CREATE_ISSUE", {
205 +const result = await composio.tools.execute("GITHUB_CREATE_AN_ISSUE", {
206 userId: "user_123",
207 arguments: { owner: "my-org", repo: "my-repo", title: "Fix login bug" },
208 dangerouslySkipVersionCheck: true, // required when running "latest"; or pin via version
@@ -212,7 +212,7 @@ const result = await composio.tools.execute("GITHUB_CREATE_ISSUE", {
212 <Tab value="API">
213 ```bash
214 # Fetch specific tools
215 -curl -X GET "https://backend.composio.dev/api/v3.1/tools?tool_slugs=GITHUB_CREATE_ISSUE,GITHUB_LIST_ISSUES&toolkit_versions=latest" \
215 +curl -X GET "https://backend.composio.dev/api/v3.1/tools?tool_slugs=GITHUB_CREATE_AN_ISSUE,GITHUB_LIST_ISSUES&toolkit_versions=latest" \
216 -H "x-api-key: $COMPOSIO_API_KEY"
217
218 # Or by toolkit
@@ -220,7 +220,7 @@ curl -X GET "https://backend.composio.dev/api/v3.1/tools?toolkit_slug=github&lim
220 -H "x-api-key: $COMPOSIO_API_KEY"
221
222 # Execute without an LLM
223 -curl -X POST https://backend.composio.dev/api/v3.1/tools/execute/GITHUB_CREATE_ISSUE \
223 +curl -X POST https://backend.composio.dev/api/v3.1/tools/execute/GITHUB_CREATE_AN_ISSUE \
224 -H "x-api-key: $COMPOSIO_API_KEY" \
225 -H "Content-Type: application/json" \
226 -d '{
docs/content/docs/setting-up-triggers/creating-triggers.mdx
+4 -4
@@ -151,7 +151,7 @@ trigger = composio.triggers.create(
151 slug="GMAIL_NEW_GMAIL_MESSAGE",
152 user_id="user-id-123435",
153 type="poll",
154 - polling_interval=15,
154 + polling_interval=2,
155 )
156 print(trigger.type, trigger.polling_interval, trigger.fallback_reason)
157 ```
@@ -164,7 +164,7 @@ const composio = new Composio();
164
165 const trigger = await composio.triggers.create('user-id-123435', 'GMAIL_NEW_GMAIL_MESSAGE', {
166 type: 'poll',
167 - pollingInterval: 15,
167 + pollingInterval: 2,
168 });
169 console.log(trigger.type, trigger.pollingInterval, trigger.fallbackReason);
170 ```
@@ -174,14 +174,14 @@ console.log(trigger.type, trigger.pollingInterval, trigger.fallbackReason);
174 curl -X POST https://backend.composio.dev/api/v3.1/trigger_instances/GMAIL_NEW_GMAIL_MESSAGE/upsert \
175 -H "x-api-key: $COMPOSIO_API_KEY" \
176 -H "Content-Type: application/json" \
177 - -d '{"user_id": "user-id-123435", "type": "poll", "polling_interval": 15}'
177 + -d '{"user_id": "user-id-123435", "type": "poll", "polling_interval": 2}'
178 ```
179 </Tab>
180 </Tabs>
181
182 Omit `type` to let Composio choose. The response reports what the instance uses. Composio sets `fallback_reason` when the instance polls because it couldn't set up a webhook, for example when your own OAuth app has no [webhook endpoint](/docs/setting-up-triggers/custom-oauth-webhooks) yet.
183
184 -Leave `polling_interval` out to use the toolkit's default.
184 +Leave `polling_interval` out to use the default of 2 minutes.
185
186 ## Next
187
docs/content/docs/tools-direct/fetching-tools.mdx
+5 -5
@@ -149,12 +149,12 @@ Fetch specific tools when you know their names.
149 # Fetch specific tools by name
150 tools = composio.tools.get(
151 user_id,
152 - tools=["GITHUB_CREATE_ISSUE", "GITHUB_CREATE_PULL_REQUEST"]
152 + tools=["GITHUB_CREATE_AN_ISSUE", "GITHUB_CREATE_PULL_REQUEST"]
153 )
154
155 # Get schemas without user_id
156 raw_tools = composio.tools.get_raw_composio_tools(
157 - tools=["GITHUB_CREATE_ISSUE", "GITHUB_CREATE_PULL_REQUEST"]
157 + tools=["GITHUB_CREATE_AN_ISSUE", "GITHUB_CREATE_PULL_REQUEST"]
158 )
159 ```
160 </Tab>
@@ -166,19 +166,19 @@ const userId = 'user_123';
166 // ---cut---
167 // Fetch specific tools by name
168 const specificTools = await composio.tools.get(userId, {
169 - tools: ["GITHUB_CREATE_ISSUE", "GITHUB_CREATE_PULL_REQUEST"]
169 + tools: ["GITHUB_CREATE_AN_ISSUE", "GITHUB_CREATE_PULL_REQUEST"]
170 });
171
172 // Get schemas without userId
173 const specificRawTools = await composio.tools.getRawComposioTools({
174 - tools: ["GITHUB_CREATE_ISSUE", "GITHUB_CREATE_PULL_REQUEST"]
174 + tools: ["GITHUB_CREATE_AN_ISSUE", "GITHUB_CREATE_PULL_REQUEST"]
175 });
176 ```
177 </Tab>
178 <Tab value="API">
179 ```bash
180 # Fetch specific tools by name
181 -curl -X GET "https://backend.composio.dev/api/v3.1/tools?tool_slugs=GITHUB_CREATE_ISSUE,GITHUB_CREATE_PULL_REQUEST" \
181 +curl -X GET "https://backend.composio.dev/api/v3.1/tools?tool_slugs=GITHUB_CREATE_AN_ISSUE,GITHUB_CREATE_PULL_REQUEST" \
182 -H "x-api-key: $COMPOSIO_API_KEY"
183 ```
184 </Tab>
docs/content/examples/custom-tools.mdx
+2 -2
@@ -75,7 +75,7 @@ session = composio.create(
75 session_preset=SESSION_PRESET_DIRECT_TOOLS,
76 toolkits=["hackernews"],
77 tools={"hackernews": {"enable": ["HACKERNEWS_GET_USER"]}},
78 - experimental={"custom_toolkits": [research]},
78 + experimental={"local_toolkits": [research]},
79 )
80 try:
81 tools = session.tools()
@@ -134,7 +134,7 @@ const session = await composio.create('custom-tools-demo', {
134 sessionPreset: SessionPreset.DIRECT_TOOLS,
135 toolkits: ['hackernews'],
136 tools: { hackernews: { enable: ['HACKERNEWS_GET_USER'] } },
137 - experimental: { customToolkits: [research] },
137 + experimental: { localToolkits: [research] },
138 });
139 try {
140 const tools = await session.tools();
docs/content/examples/imessage-agent.mdx
+1 -1
@@ -107,7 +107,7 @@ The provider is what makes `session.tools()` return eve-native tools instead of
107
108 ### Register the local toolkit
109
110 -Pass the local toolkit through `experimental.customToolkits`, and the local iMessage tools join the catalog on the same session.
110 +Pass the local toolkit through `experimental.localToolkits`, and the local iMessage tools join the catalog on the same session.
111
112 <FileBuildup name="wiring" step={3} />
113
docs/content/examples/restrict-gmail-domain.mdx
+1 -1
@@ -31,7 +31,7 @@ export COMPOSIO_API_KEY="your-composio-api-key"
31 export COMPOSIO_USER_ID="domain-check-demo"
32 ```
33
34 -In your application, derive the user ID from your authenticated session. Keep the API key and this code on the server. If you use a scoped project key, enable [Proxy execute](/reference/authenticating-to-composio/project-api-key-permissions).
34 +In your application, derive the user ID from your authenticated session. Keep the API key and this code on the server. If you use a scoped project key, enable [Proxy execute (Legacy) → Write only](/reference/authenticating-to-composio/project-api-key-permissions#proxy-execute-legacy). These scripts call the direct proxy route, which Session tool execution does not grant.
35
36 The script calls Gmail's [`users.getProfile`](https://developers.google.com/workspace/gmail/api/reference/rest/v1/users/getProfile) endpoint with `me`, which selects the authenticated mailbox. It reads the returned `emailAddress`. The endpoint requires a Gmail scope such as `https://www.googleapis.com/auth/gmail.readonly`; `openid` and `email` alone don't grant this access. Ensure your Gmail auth config requests `gmail.readonly` if the agent will also read messages. See [Controlling scopes](/docs/authentication/controlling-scopes) to configure scopes and reconnect after changing them.
37
docs/content/reference/api-reference/tools/index.mdx
+1 -1
@@ -5,7 +5,7 @@ description: "Tool execution endpoints"
5
6 {/* Auto-generated from OpenAPI spec. Edit the overview at api-overviews/tools.mdx, not this file. */}
7
8 -Tools are the individual executable actions inside a toolkit, like `GMAIL_SEND_EMAIL` or `GITHUB_CREATE_ISSUE`. Each tool has an input schema describing its parameters and an output schema describing what it returns. Tool slugs are SCREAMING_SNAKE_CASE and follow a `{TOOLKIT}_{ACTION}` pattern.
8 +Tools are the individual executable actions inside a toolkit, like `GMAIL_SEND_EMAIL` or `GITHUB_CREATE_AN_ISSUE`. Each tool has an input schema describing its parameters and an output schema describing what it returns. Tool slugs are SCREAMING_SNAKE_CASE and follow a `{TOOLKIT}_{ACTION}` pattern.
9
10 Reach for these endpoints when you want to:
11
docs/content/reference/authenticating-to-composio/project-api-key-permissions.mdx
+3 -2
@@ -143,13 +143,14 @@ The Session config read routes below are experimental and require Session config
143
144 ## Session tool execution
145
146 -Search and execute tools through sessions and session-linked MCP servers. Session proxy execution is not included; grant [Proxy execute](#proxy-execute-legacy) for that.
146 +Search and execute tools through sessions and session-linked MCP servers, including session proxy requests. The session proxy route also accepts [Proxy execute](#proxy-execute-legacy) with Write only access. Either permission grants that route.
147
148 | Access | Method | Route |
149 | ------ | ------ | ------------------------------------------------ |
150 | Write | `POST` | `/tool_router/session/{session_id}/execute` |
151 | Write | `POST` | `/tool_router/session/{session_id}/execute_meta` |
152 | Write | `POST` | `/tool_router/session/{session_id}/search` |
153 +| Write | `POST` | `/tool_router/session/{session_id}/proxy_execute` |
154
155 For [session-linked MCP access](/docs/sessions-via-mcp), use `session.mcp.url` and `session.mcp.headers` unchanged. `POST` requests require Session tool execution with Write only access. The transport does not support `GET` (SSE) or `DELETE`; granting additional permissions does not enable those methods.
156
@@ -252,7 +253,7 @@ Execute predefined Composio tools.
253
254 Execute raw proxy requests against connected accounts.
255
255 -Proxy execute is separate from tool execution and from Session tool execution. It is the only permission that grants the session proxy route below, whether the call comes from `session.proxyExecute()` or from code running in that session's sandbox. Grant it only when your application needs to call a connected account API through the raw proxy path.
256 +Proxy execute grants the direct and session proxy routes below. The session proxy route also accepts **Session tool execution → Write only**. The direct `/tools/execute/proxy` route requires **Proxy execute**. Grant this permission when your application needs direct proxy access or session proxy access without session tool execution.
257
258 | Access | Method | Route |
259 | ------ | ------ | ------------------------------------------------- |
docs/content/reference/glossary.mdx
+2 -2
@@ -116,11 +116,11 @@ The unique identifier for a session. Meta tools use it internally to share conte
116 </GlossaryTerm>
117
118 <GlossaryTerm name="Tool">
119 -An individual action an agent can execute. It has an input schema and an output schema, and is named `{TOOLKIT}_{ACTION}` (for example, `GITHUB_CREATE_ISSUE`).
119 +An individual action an agent can execute. It has an input schema and an output schema, and is named `{TOOLKIT}_{ACTION}` (for example, `GITHUB_CREATE_AN_ISSUE`).
120 </GlossaryTerm>
121
122 <GlossaryTerm name="Tool Slug">
123 -A tool's unique identifier, in the `{TOOLKIT}_{ACTION}` pattern (for example, `GITHUB_CREATE_ISSUE`).
123 +A tool's unique identifier, in the `{TOOLKIT}_{ACTION}` pattern (for example, `GITHUB_CREATE_AN_ISSUE`).
124 </GlossaryTerm>
125
126 <GlossaryTerm name="Toolkit">
docs/content/reference/sdk-reference/python/mcp.mdx
+4 -4
@@ -46,7 +46,7 @@ def create(name: str, toolkits: List[Union[ConfigToolkit, str]], manually_manage
46 ... 'auth_config_id': 'ac_abc',
47 ... },
48 ... ],
49 -... allowed_tools=['GITHUB_CREATE_ISSUE', 'GITHUB_LIST_REPOS', 'SLACK_SEND_MESSAGE'],
49 +... allowed_tools=['GITHUB_CREATE_AN_ISSUE', 'GITHUB_LIST_REPOS', 'SLACK_SEND_MESSAGE'],
50 ... manually_manage_connections=False
51 ... )
52 >>>
@@ -129,7 +129,7 @@ def get(server_id: str)
129 >>> server = composio.experimental.mcp.get('mcp_12345')
130 >>>
131 >>> print(server['name']) # "My Personal MCP Server"
132 ->>> print(server['allowed_tools']) # ["GITHUB_CREATE_ISSUE", "SLACK_SEND_MESSAGE"]
132 +>>> print(server['allowed_tools']) # ["GITHUB_CREATE_AN_ISSUE", "SLACK_SEND_MESSAGE"]
133 >>> print(server['toolkits']) # ["github", "slack"]
134 >>> print(server['server_instance_count']) # 3
135 ```
@@ -167,7 +167,7 @@ def update(server_id: str, name: str | None = ..., toolkits: List[Union[ConfigTo
167 >>> server_with_new_tools = composio.experimental.mcp.update(
168 ... 'mcp_12345',
169 ... toolkits=['github', 'slack'],
170 -... allowed_tools=['GITHUB_CREATE_ISSUE', 'SLACK_SEND_MESSAGE']
170 +... allowed_tools=['GITHUB_CREATE_AN_ISSUE', 'SLACK_SEND_MESSAGE']
171 ... )
172 >>>
173 >>> # Update with auth configs
@@ -177,7 +177,7 @@ def update(server_id: str, name: str | None = ..., toolkits: List[Union[ConfigTo
177 ... {'toolkit': 'github', 'auth_config_id': 'auth_abc123'},
178 ... {'toolkit': 'slack', 'auth_config_id': 'auth_def456'}
179 ... ],
180 -... allowed_tools=['GITHUB_CREATE_ISSUE', 'SLACK_SEND_MESSAGE'],
180 +... allowed_tools=['GITHUB_CREATE_AN_ISSUE', 'SLACK_SEND_MESSAGE'],
181 ... manually_manage_connections=False
182 ... )
183 ```
docs/content/reference/sdk-reference/typescript/mcp.mdx
+2 -2
@@ -175,7 +175,7 @@ async get(serverId: string, requestOptions?: ComposioRequestOptions): Promise<MC
175 const server = await composio.experimental.mcp.get("mcp_12345");
176
177 console.log(server.name); // "My Personal MCP Server"
178 -console.log(server.allowedTools); // ["GITHUB_CREATE_ISSUE", "SLACK_SEND_MESSAGE"]
178 +console.log(server.allowedTools); // ["GITHUB_CREATE_AN_ISSUE", "SLACK_SEND_MESSAGE"]
179 console.log(server.toolkits); // ["github", "slack"]
180 console.log(server.serverInstanceCount); // 3
181
@@ -268,7 +268,7 @@ const serverWithNewTools = await composio.experimental.mcp.update("mcp_12345", {
268 {
269 toolkit: "github",
270 authConfigId: "auth_abc123",
271 - allowedTools: ["GITHUB_CREATE_ISSUE", "GITHUB_LIST_REPOS"]
271 + allowedTools: ["GITHUB_CREATE_AN_ISSUE", "GITHUB_LIST_REPOS"]
272 },
273 {
274 toolkit: "slack",
docs/content/reference/sdk-reference/typescript/tools.mdx
+2 -2
@@ -208,7 +208,7 @@ async getInput(slug: string, body: ToolGetInputParams, requestOptions?: Composio
208 **Example**
209
210 ```typescript
211 -const { arguments: args, error } = await composio.tools.getInput('GITHUB_CREATE_ISSUE', {
211 +const { arguments: args, error } = await composio.tools.getInput('GITHUB_CREATE_AN_ISSUE', {
212 text: 'Open an issue in composiohq/composio titled "Docs typo" describing the broken link',
213 version: '20250909_00',
214 });
@@ -270,7 +270,7 @@ const customizedTool = await composio.tools.getRawComposioToolBySlug(
270 );
271
272 // Access tool properties
273 -const githubTool = await composio.tools.getRawComposioToolBySlug('GITHUB_CREATE_ISSUE');
273 +const githubTool = await composio.tools.getRawComposioToolBySlug('GITHUB_CREATE_AN_ISSUE');
274 console.log({
275 slug: githubTool.slug,
276 name: githubTool.name,
docs/content/reference/v3/api-reference/tools/index.mdx
+1 -1
@@ -5,7 +5,7 @@ description: "Tool execution endpoints"
5
6 {/* Auto-generated from OpenAPI spec. Edit the overview at api-overviews/tools.mdx, not this file. */}
7
8 -Tools are the individual executable actions inside a toolkit, like `GMAIL_SEND_EMAIL` or `GITHUB_CREATE_ISSUE`. Each tool has an input schema describing its parameters and an output schema describing what it returns. Tool slugs are SCREAMING_SNAKE_CASE and follow a `{TOOLKIT}_{ACTION}` pattern.
8 +Tools are the individual executable actions inside a toolkit, like `GMAIL_SEND_EMAIL` or `GITHUB_CREATE_AN_ISSUE`. Each tool has an input schema describing its parameters and an output schema describing what it returns. Tool slugs are SCREAMING_SNAKE_CASE and follow a `{TOOLKIT}_{ACTION}` pattern.
9
10 Reach for these endpoints when you want to:
11
docs/kb/articles/platform-project-api-key-permissions.md
+1 -1
@@ -21,4 +21,4 @@ Create a correctly scoped Project API key or use an appropriate full-access Proj
21
22 ## Session tool execution requires write access
23
24 -Set **Session tool execution** to Write to search and execute tools through a session or its MCP server. This permission allows the key to invoke any tool exposed by the session-linked MCP server. It does not cover session proxy requests; those need **Proxy execute**.
24 +Set **Session tool execution** to Write to search and execute tools through a session or its MCP server, including session proxy requests. **Proxy execute (Legacy)** with Write access also grants the session proxy route. Either permission is sufficient for that route. The direct `/tools/execute/proxy` route requires **Proxy execute (Legacy)**.
docs/lib/llm-guardrails/direct-execution.ts
+6 -6
@@ -70,10 +70,10 @@ A toolkit version is **required** for direct execution — \`tools.execute()\` w
70 from composio import Composio
71
72 composio = Composio(toolkit_versions={"github": "latest"})
73 -tools = composio.tools.get("user_123", tools=["GITHUB_CREATE_ISSUE"])
73 +tools = composio.tools.get("user_123", tools=["GITHUB_CREATE_AN_ISSUE"])
74
75 result = composio.tools.execute(
76 - "GITHUB_CREATE_ISSUE",
76 + "GITHUB_CREATE_AN_ISSUE",
77 {"owner": "org", "repo": "repo", "title": "Bug report"},
78 user_id="user_123",
79 dangerously_skip_version_check=True, # required when running "latest"
@@ -86,9 +86,9 @@ result = composio.tools.execute(
86 import { Composio } from "@composio/core";
87
88 const composio = new Composio({ toolkitVersions: { github: "latest" } });
89 -const tools = await composio.tools.get("user_123", { tools: ["GITHUB_CREATE_ISSUE"] });
89 +const tools = await composio.tools.get("user_123", { tools: ["GITHUB_CREATE_AN_ISSUE"] });
90
91 -const result = await composio.tools.execute("GITHUB_CREATE_ISSUE", {
91 +const result = await composio.tools.execute("GITHUB_CREATE_AN_ISSUE", {
92 userId: "user_123",
93 arguments: { owner: "org", repo: "repo", title: "Bug report" },
94 dangerouslySkipVersionCheck: true, // required when running "latest"
@@ -103,8 +103,8 @@ The deliberate \`latest\` choice matches the SDK examples' explicit version-chec
103 set -euo pipefail
104 curl --fail-with-body -s --get https://backend.composio.dev/api/v3.1/tools \\
105 -H "x-api-key: $COMPOSIO_API_KEY" \\
106 - --data-urlencode 'tool_slugs=GITHUB_CREATE_ISSUE' --data-urlencode 'toolkit_versions=latest'
107 -curl --fail-with-body -s -X POST https://backend.composio.dev/api/v3.1/tools/execute/GITHUB_CREATE_ISSUE \\
106 + --data-urlencode 'tool_slugs=GITHUB_CREATE_AN_ISSUE' --data-urlencode 'toolkit_versions=latest'
107 +curl --fail-with-body -s -X POST https://backend.composio.dev/api/v3.1/tools/execute/GITHUB_CREATE_AN_ISSUE \\
108 -H "x-api-key: $COMPOSIO_API_KEY" -H "Content-Type: application/json" \\
109 -d '{"user_id":"user_123","version":"latest","arguments":{"owner":"org","repo":"repo","title":"Bug report"}}'
110 \`\`\`
docs/lib/llm-guardrails/terminology.ts
+1 -1
@@ -14,7 +14,7 @@ If you encounter these terms in error messages, old documentation, or user promp
14 | Old term (v1/v2) | Current term (v3) | In code |
15 |---|---|---|
16 | entity ID | user ID | \`user_id\` parameter |
17 -| actions | tools | e.g., \`GITHUB_CREATE_ISSUE\` is a *tool* |
17 +| actions | tools | e.g., \`GITHUB_CREATE_AN_ISSUE\` is a *tool* |
18 | apps / appType (legacy v1/v2 API field) | toolkits | e.g., \`github\` is a *toolkit*. The current word **App** is *not* legacy: it names a catalog grouping of sibling toolkits (the Notion app groups \`notion\` and \`notion_mcp\`); do not translate it |
19 | integration / integration ID | auth config / auth config ID | \`auth_config_id\` parameter |
20 | connection | connected account | \`connected_accounts\` namespace |
docs/tests/static/kb-query-analytics.test.ts
+2 -2
@@ -197,7 +197,7 @@ describe('knowledge search analytics', () => {
197
198 test('builds an anonymous PostHog event with a lightly redacted query', () => {
199 const capture = buildKnowledgeSearchCapture({
200 - query: 'GITHUB_CREATE_ISSUE failed token=sk-secretvalue123456',
200 + query: 'GITHUB_CREATE_AN_ISSUE failed token=sk-secretvalue123456',
201 filter: 'kb',
202 retrievalMode: 'keyword',
203 resultCount: 2,
@@ -222,7 +222,7 @@ describe('knowledge search analytics', () => {
222 properties: {
223 distinct_id: 'public-kb-search',
224 '$process_person_profile': false,
225 - query: 'GITHUB_CREATE_ISSUE failed token=[REDACTED]',
225 + query: 'GITHUB_CREATE_AN_ISSUE failed token=[REDACTED]',
226 filter: 'kb',
227 retrieval_mode: 'keyword',
228 result_count: 2,
python/composio/core/models/mcp.py
+4 -4
@@ -176,7 +176,7 @@ class MCP(Resource):
176 ... 'auth_config_id': 'ac_abc',
177 ... },
178 ... ],
179 - ... allowed_tools=['GITHUB_CREATE_ISSUE', 'GITHUB_LIST_REPOS', 'SLACK_SEND_MESSAGE'],
179 + ... allowed_tools=['GITHUB_CREATE_AN_ISSUE', 'GITHUB_LIST_REPOS', 'SLACK_SEND_MESSAGE'],
180 ... manually_manage_connections=False
181 ... )
182 >>>
@@ -319,7 +319,7 @@ class MCP(Resource):
319 >>> server = composio.experimental.mcp.get('mcp_12345')
320 >>>
321 >>> print(server['name']) # "My Personal MCP Server"
322 - >>> print(server['allowed_tools']) # ["GITHUB_CREATE_ISSUE", "SLACK_SEND_MESSAGE"]
322 + >>> print(server['allowed_tools']) # ["GITHUB_CREATE_AN_ISSUE", "SLACK_SEND_MESSAGE"]
323 >>> print(server['toolkits']) # ["github", "slack"]
324 >>> print(server['server_instance_count']) # 3
325 """
@@ -360,7 +360,7 @@ class MCP(Resource):
360 >>> server_with_new_tools = composio.experimental.mcp.update(
361 ... 'mcp_12345',
362 ... toolkits=['github', 'slack'],
363 - ... allowed_tools=['GITHUB_CREATE_ISSUE', 'SLACK_SEND_MESSAGE']
363 + ... allowed_tools=['GITHUB_CREATE_AN_ISSUE', 'SLACK_SEND_MESSAGE']
364 ... )
365 >>>
366 >>> # Update with auth configs
@@ -370,7 +370,7 @@ class MCP(Resource):
370 ... {'toolkit': 'github', 'auth_config_id': 'auth_abc123'},
371 ... {'toolkit': 'slack', 'auth_config_id': 'auth_def456'}
372 ... ],
373 - ... allowed_tools=['GITHUB_CREATE_ISSUE', 'SLACK_SEND_MESSAGE'],
373 + ... allowed_tools=['GITHUB_CREATE_AN_ISSUE', 'SLACK_SEND_MESSAGE'],
374 ... manually_manage_connections=False
375 ... )
376 """
python/composio/core/models/tool_router.py
+2 -2
@@ -913,7 +913,7 @@ class ToolRouter(Resource, t.Generic[TTool, TToolCollection]):
913 Example: {'tags': {'enable': ['readOnlyHint'], 'disable': ['destructiveHint']}}
914 Example: {
915 'gmail': ['GMAIL_SEND_EMAIL', 'GMAIL_SEARCH'],
916 - 'github': {'enable': ['GITHUB_CREATE_ISSUE']},
916 + 'github': {'enable': ['GITHUB_CREATE_AN_ISSUE']},
917 'slack': {'disable': ['SLACK_DELETE_MESSAGE']},
918 'linear': {'tags': ['readOnlyHint']}
919 }
@@ -1063,7 +1063,7 @@ class ToolRouter(Resource, t.Generic[TTool, TToolCollection]):
1063 user_id='user_123',
1064 tools={
1065 'gmail': ['GMAIL_SEND_EMAIL', 'GMAIL_SEARCH'], # List shorthand
1066 - 'github': {'enable': ['GITHUB_CREATE_ISSUE']}, # Explicit enable
1066 + 'github': {'enable': ['GITHUB_CREATE_AN_ISSUE']}, # Explicit enable
1067 'slack': {'disable': ['SLACK_DELETE_MESSAGE']}, # Explicit disable
1068 }
1069 )
python/docs/tool-router.md
+1 -1
@@ -135,7 +135,7 @@ session = composio.tool_router.create(
135 'gmail': ['GMAIL_FETCH_EMAILS', 'GMAIL_SEND_EMAIL'],
136
137 # Explicit enable configuration
138 - 'github': {'enable': ['GITHUB_CREATE_ISSUE', 'GITHUB_LIST_ISSUES']},
138 + 'github': {'enable': ['GITHUB_CREATE_AN_ISSUE', 'GITHUB_LIST_ISSUES']},
139
140 # Explicit disable configuration
141 'slack': {'disable': ['SLACK_DELETE_MESSAGE']},
ts/docs/api/experimental-mcp.md
+7 -7
@@ -31,7 +31,7 @@ const composio = new Composio({
31 // 1. Create MCP configuration
32 const mcpConfig = await composio.mcp.create('my-server-name', {
33 toolkits: [{ toolkit: 'github', authConfigId: 'ac_233434343' }],
34 - allowedTools: ['GITHUB_CREATE_ISSUE', 'GITHUB_LIST_REPOS'],
34 + allowedTools: ['GITHUB_CREATE_AN_ISSUE', 'GITHUB_LIST_REPOS'],
35 manuallyManageConnections: false,
36 });
37
@@ -63,7 +63,7 @@ const mcpConfig = await composio.mcp.create('gmail-assistant', {
63 // Alternative with string toolkit names
64 const mcpConfig = await composio.mcp.create('simple-server', {
65 toolkits: ['github', 'slack'],
66 - allowedTools: ['GITHUB_CREATE_ISSUE', 'SLACK_SEND_MESSAGE'],
66 + allowedTools: ['GITHUB_CREATE_AN_ISSUE', 'SLACK_SEND_MESSAGE'],
67 manuallyManageConnections: false,
68 });
69 ```
@@ -163,7 +163,7 @@ Retrieves detailed information about a specific MCP server.
163 const server = await composio.mcp.get("mcp_12345");
164
165 console.log(server.name); // "My Personal MCP Server"
166 -console.log(server.allowedTools); // ["GITHUB_CREATE_ISSUE", "SLACK_SEND_MESSAGE"]
166 +console.log(server.allowedTools); // ["GITHUB_CREATE_AN_ISSUE", "SLACK_SEND_MESSAGE"]
167 console.log(server.toolkits); // ["github", "slack"]
168 console.log(server.serverInstanceCount); // 3
169
@@ -201,7 +201,7 @@ const serverWithNewTools = await composio.mcp.update("mcp_12345", {
201 authConfigId: "auth_xyz789"
202 }
203 ],
204 - allowedTools: ["GITHUB_CREATE_ISSUE", "GITHUB_LIST_REPOS", "SLACK_SEND_MESSAGE"]
204 + allowedTools: ["GITHUB_CREATE_AN_ISSUE", "GITHUB_LIST_REPOS", "SLACK_SEND_MESSAGE"]
205 });
206 ```
207
@@ -288,7 +288,7 @@ const mcpConfig = await composio.mcp.create('multi-toolkit-assistant', {
288 allowedTools: [
289 'GMAIL_FETCH_EMAILS',
290 'GMAIL_SEND_EMAIL',
291 - 'GITHUB_CREATE_ISSUE',
291 + 'GITHUB_CREATE_AN_ISSUE',
292 'GITHUB_LIST_REPOS'
293 ],
294 manuallyManageConnections: false,
@@ -345,7 +345,7 @@ const workConfig = await composio.mcp.create('work-assistant', {
345 { toolkit: 'github', authConfigId: 'ac_work_github' },
346 { toolkit: 'slack', authConfigId: 'ac_work_slack' },
347 ],
348 - allowedTools: ['GITHUB_CREATE_ISSUE', 'SLACK_SEND_MESSAGE'],
348 + allowedTools: ['GITHUB_CREATE_AN_ISSUE', 'SLACK_SEND_MESSAGE'],
349 manuallyManageConnections: false,
350 });
351
@@ -477,7 +477,7 @@ You can configure toolkits in multiple ways:
477 // Using string array (requires default auth configs)
478 const simpleConfig = await composio.mcp.create('simple-server', {
479 toolkits: ['github', 'slack'],
480 - allowedTools: ['GITHUB_CREATE_ISSUE', 'SLACK_SEND_MESSAGE'],
480 + allowedTools: ['GITHUB_CREATE_AN_ISSUE', 'SLACK_SEND_MESSAGE'],
481 manuallyManageConnections: false,
482 });
483
ts/docs/api/mcp.md
+4 -4
@@ -76,7 +76,7 @@ const server = await composio.mcp.create('personal-mcp-server', {
76 {
77 toolkit: 'github',
78 authConfigId: 'ac_xyz',
79 - allowedTools: ['GITHUB_CREATE_ISSUE', 'GITHUB_LIST_REPOS'],
79 + allowedTools: ['GITHUB_CREATE_AN_ISSUE', 'GITHUB_LIST_REPOS'],
80 },
81 {
82 toolkit: 'slack',
@@ -145,7 +145,7 @@ Retrieves detailed information about a specific MCP server/config.
145 const server = await composio.mcp.get('mcp_12345');
146
147 console.log(server.name); // "My Personal MCP Server"
148 -console.log(server.allowedTools); // ["GITHUB_CREATE_ISSUE", "SLACK_SEND_MESSAGE"]
148 +console.log(server.allowedTools); // ["GITHUB_CREATE_AN_ISSUE", "SLACK_SEND_MESSAGE"]
149 console.log(server.toolkits); // ["github", "slack"]
150 console.log(server.serverInstanceCount); // 3
151
@@ -183,7 +183,7 @@ const serverWithNewTools = await composio.mcp.update('mcp_12345', {
183 {
184 toolkit: 'github',
185 authConfigId: 'auth_abc123',
186 - allowedTools: ['GITHUB_CREATE_ISSUE', 'GITHUB_LIST_REPOS'],
186 + allowedTools: ['GITHUB_CREATE_AN_ISSUE', 'GITHUB_LIST_REPOS'],
187 },
188 {
189 toolkit: 'slack',
@@ -351,7 +351,7 @@ Be specific about allowed tools to maintain security:
351 // Specific tools (recommended)
352 {
353 toolkit: "github",
354 - allowedTools: ["GITHUB_CREATE_ISSUE", "GITHUB_LIST_REPOS"]
354 + allowedTools: ["GITHUB_CREATE_AN_ISSUE", "GITHUB_LIST_REPOS"]
355 }
356
357 // Avoid allowing all tools unless necessary
ts/docs/api/tool-router.md
+7 -7
@@ -290,7 +290,7 @@ Define your own tools that run in-process alongside Composio's remote tools. Cus
290
291 There are three ways to define custom tools:
292
293 -**1. Standalone tool** — no auth needed, passed in `customTools`:
293 +**1. Standalone tool** — no auth needed, passed in `localTools`:
294
295 ```typescript
296 import { experimental_createTool } from '@composio/core';
@@ -304,7 +304,7 @@ const grep = experimental_createTool('GREP', {
304 });
305 ```
306
307 -**2. Extension tool** — extends a Composio toolkit, inherits its auth. Passed in `customTools` with `extendsToolkit`:
307 +**2. Extension tool** — extends a Composio toolkit, inherits its auth. Passed in `localTools` with `extendsToolkit`:
308
309 ```typescript
310 const getImportant = experimental_createTool('GET_IMPORTANT_EMAILS', {
@@ -320,7 +320,7 @@ const getImportant = experimental_createTool('GET_IMPORTANT_EMAILS', {
320 });
321 ```
322
323 -**3. Custom toolkit** — groups related no-auth tools. Passed in `customToolkits`:
323 +**3. Custom toolkit** — groups related no-auth tools. Passed in `localToolkits`:
324
325 ```typescript
326 import { experimental_createToolkit } from '@composio/core';
@@ -345,8 +345,8 @@ const devTools = experimental_createToolkit('DEV_TOOLS', {
345 const session = await composio.create('user_123', {
346 toolkits: ['gmail'],
347 experimental: {
348 - customTools: [grep, getImportant],
349 - customToolkits: [devTools],
348 + localTools: [grep, getImportant],
349 + localToolkits: [devTools],
350 },
351 });
352 ```
@@ -955,8 +955,8 @@ interface ToolRouterCreateSessionConfig {
955 assistivePrompt?: {
956 userTimezone?: string; // IANA timezone identifier for timezone-aware assistive prompts
957 };
958 - customTools?: CustomTool[]; // Standalone or extension tools (from experimental_createTool)
959 - customToolkits?: CustomToolkit[]; // Grouped no-auth tools (from experimental_createToolkit)
958 + localTools?: LocalTool[]; // Standalone or extension tools (from experimental_createTool)
959 + localToolkits?: LocalToolkit[]; // Grouped no-auth tools (from experimental_createToolkit)
960 };
961 }
962 ```
ts/docs/api/tools.md
+1 -1
@@ -256,7 +256,7 @@ const customizedTool = await composio.tools.getRawComposioToolBySlug(
256 );
257
258 // Access tool properties
259 -const githubTool = await composio.tools.getRawComposioToolBySlug('GITHUB_CREATE_ISSUE');
259 +const githubTool = await composio.tools.getRawComposioToolBySlug('GITHUB_CREATE_AN_ISSUE');
260 console.log({
261 slug: githubTool.slug,
262 name: githubTool.name,
ts/docs/core-concepts.md
+2 -2
@@ -402,7 +402,7 @@ Use direct execution when:
402
403 ## Custom Tools
404
405 -Custom Tools allow you to attach your own local tools to Tool Router sessions. Define them with `experimental_createTool`, then pass them to `composio.create()` under `experimental.customTools`.
405 +Custom Tools allow you to attach your own local tools to Tool Router sessions. Define them with `experimental_createTool`, then pass them to `composio.create()` under `experimental.localTools`.
406
407 ```typescript
408 import { Composio, experimental_createTool } from '@composio/core';
@@ -423,7 +423,7 @@ const customTool = experimental_createTool('MY_CUSTOM_TOOL', {
423 });
424
425 const session = await composio.create('default', {
426 - experimental: { customTools: [customTool] },
426 + experimental: { localTools: [customTool] },
427 });
428
429 const result = await session.execute('MY_CUSTOM_TOOL', {
ts/docs/getting-started.md
+1 -1
@@ -310,7 +310,7 @@ const customTool = experimental_createTool('WEATHER_FORECAST', {
310 });
311
312 const session = await composio.create('default', {
313 - experimental: { customTools: [customTool] },
313 + experimental: { localTools: [customTool] },
314 });
315
316 const result = await session.execute('WEATHER_FORECAST', {
ts/packages/core/src/models/MCP.ts
+2 -2
@@ -249,7 +249,7 @@ export class MCP {
249 * const server = await composio.experimental.mcp.get("mcp_12345");
250 *
251 * console.log(server.name); // "My Personal MCP Server"
252 - * console.log(server.allowedTools); // ["GITHUB_CREATE_ISSUE", "SLACK_SEND_MESSAGE"]
252 + * console.log(server.allowedTools); // ["GITHUB_CREATE_AN_ISSUE", "SLACK_SEND_MESSAGE"]
253 * console.log(server.toolkits); // ["github", "slack"]
254 * console.log(server.serverInstanceCount); // 3
255 *
@@ -343,7 +343,7 @@ export class MCP {
343 * {
344 * toolkit: "github",
345 * authConfigId: "auth_abc123",
346 - * allowedTools: ["GITHUB_CREATE_ISSUE", "GITHUB_LIST_REPOS"]
346 + * allowedTools: ["GITHUB_CREATE_AN_ISSUE", "GITHUB_LIST_REPOS"]
347 * },
348 * {
349 * toolkit: "slack",
ts/packages/core/src/models/Tools.ts
+2 -2
@@ -844,7 +844,7 @@ export class Tools<
844 * );
845 *
846 * // Access tool properties
847 - * const githubTool = await composio.tools.getRawComposioToolBySlug('GITHUB_CREATE_ISSUE');
847 + * const githubTool = await composio.tools.getRawComposioToolBySlug('GITHUB_CREATE_AN_ISSUE');
848 * console.log({
849 * slug: githubTool.slug,
850 * name: githubTool.name,
@@ -1544,7 +1544,7 @@ export class Tools<
1544 *
1545 * @example
1546 * ```typescript
1547 - * const { arguments: args, error } = await composio.tools.getInput('GITHUB_CREATE_ISSUE', {
1547 + * const { arguments: args, error } = await composio.tools.getInput('GITHUB_CREATE_AN_ISSUE', {
1548 * text: 'Open an issue in composiohq/composio titled "Docs typo" describing the broken link',
1549 * version: '20250909_00',
1550 * });
ts/packages/core/src/types/tool.types.ts
+1 -1
@@ -459,7 +459,7 @@ export type ToolRetrievalOptions = {
459 *
460 * @example Override with specific version
461 * ```typescript
462 - * const tool = await tools.getRawComposioToolBySlug('GITHUB_CREATE_ISSUE', {
462 + * const tool = await tools.getRawComposioToolBySlug('GITHUB_CREATE_AN_ISSUE', {
463 * version: '20250909_00'
464 * });
465 * ```