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: 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.mdxindex 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):**```bashcurl "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.mdxindex 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.mdxindex 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.mdxindex 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 dashboarddiff --git a/docs/content/docs/tools-direct/executing-tools.mdx b/docs/content/docs/tools-direct/executing-tools.mdxindex 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 ExecuteYou 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.mdxindex 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 versiontoolkit_versions = {"github": "20251027_00"}-# Development — always use the newest tools+# Always use the newest toolstoolkit_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 order1. Per-execution version (highest priority)