Skip to content

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

docs: 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.mdx
index 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_00
This 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.mdx
index 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.mdx
index 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](/toolkit
Starting 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 methods
Configure 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 version
toolkit_versions = {"github": "20251027_00"}
-# Development
+# Development — always use the newest tools
toolkit_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 order
diff --git a/docs/content/docs/troubleshooting/index.mdx b/docs/content/docs/troubleshooting/index.mdx
index 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 Tr
See [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 links
diff --git a/docs/content/docs/troubleshooting/tools.mdx b/docs/content/docs/troubleshooting/tools.mdx
index 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 requirements
diff --git a/docs/scripts/fetch-openapi.mjs b/docs/scripts/fetch-openapi.mjs
index 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 properties
let unionNormalizedCount = 0;