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: clarify toolkit_versions default behavior in Get Tools API
Devin AIcadbd463fddb
diff --git a/docs/content/docs/common-faq.mdx b/docs/content/docs/common-faq.mdxindex 10cd10448..731cb39c5 100644--- a/docs/content/docs/common-faq.mdx+++ b/docs/content/docs/common-faq.mdx@@ -90,6 +90,19 @@ Composio toolkits are versioned using date-based identifiers (e.g., `20251027_00This applies to direct tool execution only. Sessions with meta tools always use the latest version. See [Toolkit versioning](/docs/tools-direct/toolkit-versioning).</Accordion>+<Accordion title="Why does the API return fewer tools than the platform UI?">+When calling the Get Tools API (`GET /api/v3/tools`) without specifying a `toolkit_versions` parameter, the API defaults to the base version (`00000000_00`), which only includes tools from the initial release. The platform UI shows tools from the latest version.++To get all available tools, pass `toolkit_versions=latest`:++```bash+curl 'https://backend.composio.dev/api/v3/tools?toolkit_slug=googledrive&toolkit_versions=latest' \+ -H 'x-api-key: YOUR_API_KEY'+```++For production use, pin to a specific version instead of `latest` to avoid breaking changes. See [Toolkit versioning](/docs/tools-direct/toolkit-versioning).+</Accordion>+<Accordion title="Can a user connect multiple accounts for the same app?">Yes. For example, a user can connect both a personal and work Gmail account. Call `session.authorize()` multiple times for the same toolkit. Each session uses the most recently connected account by default, but you can pin a specific account when creating the session.diff --git a/docs/content/docs/tools-direct/fetching-tools.mdx b/docs/content/docs/tools-direct/fetching-tools.mdxindex 61138a376..d327fcdf8 100644--- a/docs/content/docs/tools-direct/fetching-tools.mdx+++ b/docs/content/docs/tools-direct/fetching-tools.mdx@@ -238,6 +238,6 @@ const toolkitSearchRaw = await composio.tools.getRawComposioTools({</Tab></Tabs>-<Callout type="info">-Use specific toolkit versions in production to prevent breaking changes. See [toolkit versioning](/docs/tools-direct/toolkit-versioning).+<Callout type="warn">+When no toolkit version is specified, the API returns tools from the base version (`00000000_00`), which may be fewer than what's available. Pass `toolkit_versions="latest"` or a specific version to get all tools. Never use `latest` in production. See [toolkit versioning](/docs/tools-direct/toolkit-versioning).</Callout>diff --git a/docs/content/docs/tools-direct/toolkit-versioning.mdx b/docs/content/docs/tools-direct/toolkit-versioning.mdxindex 89ea3e72e..2cbb161bc 100644--- a/docs/content/docs/tools-direct/toolkit-versioning.mdx+++ b/docs/content/docs/tools-direct/toolkit-versioning.mdx@@ -21,6 +21,24 @@ You can also find the latest version for each toolkit on the [Toolkits](/toolkitStarting from Python SDK v0.9.0 and TypeScript SDK v0.2.0, specifying versions is required for manual tool execution.</Callout>+## Default version behavior++<Callout type="warn">+When no version is specified, the API defaults to the base version (`00000000_00`), **not** the latest version. This means the response may contain fewer tools than what's shown on the [platform UI](https://platform.composio.dev). To get all available tools including ones added in newer versions, explicitly set `toolkit_versions` to `"latest"` or a specific version.+</Callout>++This applies to both the SDK and direct REST API calls:++```bash+# Without version — returns only tools from the base version+curl 'https://backend.composio.dev/api/v3/tools?toolkit_slug=googledrive' \+ -H 'x-api-key: YOUR_API_KEY'++# With version=latest — returns all tools including newer ones+curl 'https://backend.composio.dev/api/v3/tools?toolkit_slug=googledrive&toolkit_versions=latest' \+ -H 'x-api-key: YOUR_API_KEY'+```+## Configuration methodsConfigure toolkit versions using one of three methods:@@ -118,15 +136,19 @@ Versions follow the format `YYYYMMDD_NN`:- `NN`: Sequential release number```python-# Production+# Production — pin to a specific versiontoolkit_versions = {"github": "20251027_00"}-# Development+# Development — always use the newest toolstoolkit_versions = {"github": "latest"}```<Callout type="warn">-Never use `latest` in production. It can introduce breaking changes.+Never use `latest` in production. It can introduce breaking changes. Pin to a specific version instead.+</Callout>++<Callout type="info">+If you omit `toolkit_versions` entirely, the API uses the base version (`00000000_00`). This is the oldest version and may not include all tools available for a toolkit. Always specify a version explicitly.</Callout>## Version resolution orderdiff --git a/docs/content/docs/troubleshooting/index.mdx b/docs/content/docs/troubleshooting/index.mdxindex 7d19da366..bf85d6b85 100644--- a/docs/content/docs/troubleshooting/index.mdx+++ b/docs/content/docs/troubleshooting/index.mdx@@ -47,6 +47,12 @@ Go to the [dashboard](https://platform.composio.dev) and navigate to **Active TrSee [Troubleshooting triggers](/docs/troubleshooting/triggers#reporting-issues) for a screenshot.</Accordion>+<Accordion title="Why does the API return fewer tools than the platform UI?">+The Get Tools API defaults to the base toolkit version (`00000000_00`) when `toolkit_versions` is not specified. Pass `toolkit_versions=latest` to get all available tools.++See [Troubleshooting tools](/docs/troubleshooting/tools#api-returning-fewer-tools-than-expected) for details.+</Accordion>+</Accordions>## Quick linksdiff --git a/docs/content/docs/troubleshooting/tools.mdx b/docs/content/docs/troubleshooting/tools.mdxindex b6d9bc535..eddd42eb7 100644--- a/docs/content/docs/troubleshooting/tools.mdx+++ b/docs/content/docs/troubleshooting/tools.mdx@@ -31,6 +31,21 @@ Verify the connected account has necessary permissions:- **Paid accounts**: Certain toolkits need paid subscriptions- Example: MS Teams requires Microsoft 365 account + Azure AD tenant+## API returning fewer tools than expected++If the Get Tools API (`GET /api/v3/tools`) returns fewer tools than what's shown on the [platform UI](https://platform.composio.dev), you likely need to specify a toolkit version.++When `toolkit_versions` is not provided, the API defaults to the base version (`00000000_00`), which only includes tools from the initial release. Tools added in later versions won't appear.++To get all available tools, pass `toolkit_versions=latest`:++```bash+curl 'https://backend.composio.dev/api/v3/tools?toolkit_slug=googledrive&toolkit_versions=latest' \+ -H 'x-api-key: YOUR_API_KEY'+```++For production use, pin to a specific version instead of `latest`. See [Toolkit versioning](/docs/tools-direct/toolkit-versioning).+## Tool not working- Check [tool-specific documentation](/toolkits) for requirementsdiff --git a/docs/scripts/fetch-openapi.mjs b/docs/scripts/fetch-openapi.mjsindex 13d427357..867138b7c 100644--- a/docs/scripts/fetch-openapi.mjs+++ b/docs/scripts/fetch-openapi.mjs@@ -117,6 +117,19 @@ async function fetchAndFilterSpec() {console.log(`Removed ${removedCount} endpoints/operations`);console.log(`Final spec has ${Object.keys(filteredPaths).length} paths`);+ // Enhance toolkit_versions parameter description for clarity+ for (const methods of Object.values(spec.paths)) {+ for (const operation of Object.values(methods)) {+ if (operation.parameters) {+ for (const param of operation.parameters) {+ if (param.name === 'toolkit_versions') {+ param.description = 'Toolkit version specification. **When not specified, defaults to the base version (`00000000_00`), which may return fewer tools than the latest version.** Use `"latest"` to get all available tools, or use bracket notation for specific versions per toolkit (e.g., `toolkit_versions[gmail]=20250930_00`). For production, pin to a specific version instead of `"latest"` to avoid breaking changes.';+ }+ }+ }+ }+ }+// Normalize overly complex anyOf/oneOf schemas (e.g., connection_data with 68 object variants)// Merges similar object schemas into a single object with all propertieslet unionNormalizedCount = 0;