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: add guidance on when to use latest vs pinned toolkit versions

Zen Agentbcaeab47a3d0
diff --git a/docs/content/changelog/04-08-26-v31-api.mdx b/docs/content/changelog/04-08-26-v31-api.mdx
index 9fa610746..10b03cd20 100644
--- a/docs/content/changelog/04-08-26-v31-api.mdx
+++ b/docs/content/changelog/04-08-26-v31-api.mdx
@@ -40,6 +40,8 @@ Every non-tool endpoint (`/auth_configs`, `/connected_accounts`, `/triggers`, `/
2. If you depend on a specific pinned version, pass it explicitly — `version=00000000_00` for most endpoints, or `toolkit_versions=00000000_00` for `GET /tools` (see table above)
3. If you were already passing `version: "latest"` (or `toolkit_versions: "latest"`), you can drop the parameter entirely on v3.1
+**Which default is right for you?** If your application passes tool outputs to an LLM or AI agent, the v3.1 default (`latest`) is the better fit — agents interpret responses dynamically and benefit from always having the newest tools. If your code parses tool outputs programmatically (e.g., destructuring specific fields or mapping to a database schema), pin to a specific version so schema changes don't silently break your integration. See [Toolkit Versioning](/docs/tools-direct/toolkit-versioning#choosing-between-latest-and-a-pinned-version) for details.
+
**Before (v3):**
```bash
curl "https://backend.composio.dev/api/v3/tools/GMAIL_SEND_EMAIL?version=latest" \
diff --git a/docs/content/docs/common-faq.mdx b/docs/content/docs/common-faq.mdx
index c2f8e7cb4..2cc1aa23c 100644
--- a/docs/content/docs/common-faq.mdx
+++ b/docs/content/docs/common-faq.mdx
@@ -91,6 +91,8 @@ You can request new tools or toolkits on the [tool request board](https://reques
<Accordion title="How do I work with toolkit versions?">
Composio toolkits are versioned using date-based identifiers (e.g., `20251027_00`). You can pin versions at SDK initialization or per tool execution to keep behavior consistent across deployments.
+**When to use `latest` vs a pinned version:** Use `latest` when tool outputs and trigger payloads are consumed by an LLM or AI agent — agents adapt to response changes dynamically and benefit from always having the newest tools. Pin to a specific version when your code parses outputs programmatically (e.g., destructuring fields, mapping to a schema, or feeding into a typed pipeline).
+
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>
diff --git a/docs/content/docs/sessions-vs-direct-execution.mdx b/docs/content/docs/sessions-vs-direct-execution.mdx
index c54c14bf4..2e80b3b30 100644
--- a/docs/content/docs/sessions-vs-direct-execution.mdx
+++ b/docs/content/docs/sessions-vs-direct-execution.mdx
@@ -19,6 +19,7 @@ Use sessions unless you need full control over which tools are available and whe
| **Auth** | [In-chat](/docs/authenticating-users/in-chat-authentication): agent prompts the user to connect when needed. Also supports [manual](/docs/authenticating-users/manually-authenticating) | You build the auth flow with [connect links](/docs/tools-direct/authenticating-tools) |
| **[Workbench](/docs/workbench)** | Built in, large responses offloaded automatically | Not available |
| **Human approval** | You configure approval rules on the session. Harder to intercept individual calls since tools are discovered dynamically | You intercept before each call in your code |
+| **Version management** | Always uses `latest` — ideal for agentic workflows where an LLM interprets outputs | You [choose the version](/docs/tools-direct/toolkit-versioning#choosing-between-latest-and-a-pinned-version): `latest` for agent-consumed outputs, pinned for programmatic parsing |
| **Latency** | Multiple LLM turns (search, then execute) | Single call |
Sessions are configurable. You can [enable or disable specific toolkits](/docs/toolkits/enable-and-disable-toolkits), set [auth configs](/docs/auth-configuration/custom-auth-configs) for white-labeled OAuth, and pin specific [connected accounts](/docs/configuring-sessions#account-selection). See [Configuring Sessions](/docs/configuring-sessions) for the full list.
diff --git a/docs/content/docs/setting-up-triggers/creating-triggers.mdx b/docs/content/docs/setting-up-triggers/creating-triggers.mdx
index f2493fccc..951b38e4c 100644
--- a/docs/content/docs/setting-up-triggers/creating-triggers.mdx
+++ b/docs/content/docs/setting-up-triggers/creating-triggers.mdx
@@ -73,7 +73,7 @@ console.log(`Trigger created: ${trigger.triggerId}`);
</Tabs>
<Callout>
-The trigger instance uses the toolkit version configured during Composio initialization (defaults to `'latest'`). See [Toolkit Versioning](/docs/tools-direct/toolkit-versioning) for details.
+Trigger instances default to `'latest'` toolkit version. This is the recommended setting for most use cases — trigger payloads are typically consumed by an LLM or agent that adapts to response changes dynamically. If your code parses trigger payloads programmatically against a fixed schema, you can pin a specific version at SDK initialization. See [Toolkit Versioning](/docs/tools-direct/toolkit-versioning#choosing-between-latest-and-a-pinned-version) for details.
</Callout>
## Using the dashboard
diff --git a/docs/content/docs/tools-direct/executing-tools.mdx b/docs/content/docs/tools-direct/executing-tools.mdx
index 6d59547e9..acd3e21ad 100644
--- a/docs/content/docs/tools-direct/executing-tools.mdx
+++ b/docs/content/docs/tools-direct/executing-tools.mdx
@@ -246,6 +246,10 @@ console.log('GitHub stargazers:', JSON.stringify(result, null, 2));
The examples above configure toolkit versions at SDK initialization. You can also pass versions per-execution or use environment variables. See [toolkit versioning](/docs/tools-direct/toolkit-versioning) for all configuration options.
</Callout>
+<Callout type="info">
+**Choosing a version strategy:** Use `latest` when tool outputs are consumed by an LLM or AI agent — agents adapt to schema changes dynamically. Pin to a specific version when your code parses outputs programmatically. See [choosing between `latest` and a pinned version](/docs/tools-direct/toolkit-versioning#choosing-between-latest-and-a-pinned-version).
+</Callout>
+
### Proxy Execute
You can proxy requests to any supported toolkit API and let Composio inject the authentication state. This is useful when you need an API endpoint that isn't available as a predefined tool.
diff --git a/docs/content/docs/tools-direct/toolkit-versioning.mdx b/docs/content/docs/tools-direct/toolkit-versioning.mdx
index 3539a3183..144dcc618 100644
--- a/docs/content/docs/tools-direct/toolkit-versioning.mdx
+++ b/docs/content/docs/tools-direct/toolkit-versioning.mdx
@@ -136,17 +136,27 @@ Versions follow the format `YYYYMMDD_NN`:
- `NN`: Sequential release number
```python
-# Production — pin to a specific version
+# Pin to a specific version
toolkit_versions = {"github": "20251027_00"}
-# Development — always use the newest tools
+# Always use the newest tools
toolkit_versions = {"github": "latest"}
```
-<Callout type="warn">
-Never use `latest` in production. It can introduce breaking changes. Pin to a specific version instead.
+## Choosing between `latest` and a pinned version
+
+The right choice depends on how your application consumes tool outputs:
+
+- **Use `latest`** when tool outputs are consumed by an LLM or AI agent. Agents interpret responses dynamically and adapt to changes in output structure. Using `latest` ensures your agent always has access to the newest tools and improvements without manual intervention.
+
+- **Pin a specific version** when tool outputs are consumed programmatically — for example, if your code destructures specific fields from a response, maps outputs to a database schema, or feeds results into a typed pipeline. Schema changes in a new version could silently break these integrations.
+
+<Callout type="info">
+As a rule of thumb: if an LLM reads the output, use `latest`. If your code parses the output, pin the version.
</Callout>
+Most agentic applications — including all [session-based](/docs/configuring-sessions) workflows — use `latest` by default and benefit from always having the most up-to-date tools. If you're building structured data pipelines or integrations with fixed response parsing, pin to a tested version and upgrade on your own schedule.
+
## Version resolution order
1. Per-execution version (highest priority)