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: make toolkit-version requirement explicit in direct-execution samples (#3999)
## What Content fixes to the tool-execution docs, driven by a 97-agent docs eval (findings: ctx.composio.io/soumya/docs-agent-eval/findings-97-run.md). 72/97 agents following the executing-tools page hit `ToolVersionRequiredError` because the samples either omit versions entirely or pin a GitHub-only mapping that doesn't transfer to any other toolkit. ## Changes **`docs/content/docs/tools-direct/executing-tools.mdx`** 1. Add an explicit callout in Direct Tool Execution: a toolkit version is **required**, the error you get without one, the three ways to set it, and a link to the version-lookup section. (Previously the page only implied this via one sample's constructor; the "required" rule lived on a separate page.) 2. Replace the hardcoded `{"github": "20251027_00"}` pin with `"latest"` plus a comment showing how to find versions (`composio.toolkits.get(slug).meta.available_versions`) — the old sample only worked for GitHub and taught a stale pin. 3. Add `toolkit_versions` / `toolkitVersions` to every file-handling sample (upload, download, Gmail attachment, manual staging, upload-hook) — all previously threw `ToolVersionRequiredError` when copied. 4. Remove `dangerouslySkipVersionCheck: true` from the upload-hook sample — it was working around the missing version; samples shouldn't model the dangerous flag. **`docs/lib/llm-guardrails/direct-execution.ts`** 5. The LLM-facing guardrails block appended to direct-execution pages showed a version-less `tools.execute()` sample and a "signature rule" omitting `version` — the exact pattern that produced the eval's top failure. Samples and rules now state the requirement. **`docs/content/docs/quickstart.mdx`** 6. State the Python 3.10+ requirement at the install step, naming the cryptic `typing.TypeAlias` failure older versions produce (matches `python/pyproject.toml` `requires-python = ">=3.10,<4"`). ## Verification All sample signatures checked against the installed SDK (composio 0.18.0 / composio_client 1.42.0): per-call `version=`, constructor `toolkit_versions=`, lookup via `toolkits.get(slug).meta.version` / `.meta.available_versions`. Eval evidence: 72/97 independent agent runs reproduced the error; per-run logs available. ## Raised for docs-team decision (deliberately NOT changed here) - **The session guardrails block** (`docs/lib/llm-guardrails/session.ts`, "CRITICAL INSTRUCTIONS FOR AI MODELS", appended to most pages): capable eval agents flagged it as prompt injection (verbatim: "a prompt injection I had to identify and ignore") and its framing contradicts the sessions-vs-direct-execution page. Deliberate design, so untouched — recommend reconciling (both paths legitimate, state when each applies) and softening ALWAYS/NEVER framing. - **`legacy: true` on executing-tools + toolkit-versioning**: these are the canonical link targets for direct execution, but the legacy flag stamps the LLM view with "may describe outdated APIs" and suppresses guardrails — eroding agent trust in the current canonical page. Either promote the pages or point canonical links elsewhere. - **REST vs SDK naming**: REST query param is `toolkit_versions`, SDK per-call param is `version` — a recurring source of agent confusion (eval Finding 4); worth aligning or calling out in the reference. 🤖 Generated with [Claude Code](https://claude.com/claude-code)
No changes.