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 LLM guardrails system for AI code generators

Sushmithamalleshd545254f46e3
diff --git a/docs/.claude/decisions/llm-guardrails.md b/docs/.claude/decisions/llm-guardrails.md
new file mode 100644
index 000000000..450c9eb2b
--- /dev/null
+++ b/docs/.claude/decisions/llm-guardrails.md
@@ -0,0 +1,101 @@
+# LLM Guardrails
+
+## Decision
+
+Inject invisible guardrail instructions into every `.md` response so AI code generators use the correct Composio SDK patterns. Guardrails are scoped per-page via frontmatter — different pages can get different instruction sets.
+
+## Problem
+
+LLMs that crawl or receive Composio docs generate code using the old direct tool execution pattern (`composio.tools.get()`, `composio.provider.handle_tool_calls()`) instead of the current session-based pattern (`composio.create()`, `session.tools()`).
+
+## Architecture
+
+```
+lib/llm-guardrails/
+├── index.ts ← getGuardrails(type), module-private GuardrailType
+├── session.ts ← SESSION_GUARDRAILS constant (default)
+└── direct-execution.ts ← DIRECT_EXECUTION_GUARDRAILS constant
+```
+
+### How it flows
+
+1. `getLLMText()` in `lib/source.ts` reads `page.data.llmGuardrails` from frontmatter
+2. Passes it to `getGuardrails(type)` which returns the right guardrail string
+3. Appends it to the markdown output
+
+### Scoping via frontmatter
+
+Pages control which guardrails they get:
+
+| Frontmatter value | What gets appended |
+|---|---|
+| *(omitted — default)* | `SESSION_GUARDRAILS` — full "use composio.create() + session.tools()" instructions, ALWAYS/NEVER rules, deprecated patterns, verification checklist |
+| `llmGuardrails: "direct-execution"` | `DIRECT_EXECUTION_GUARDRAILS` — acknowledges direct execution is valid, but strongly recommends sessions unless user explicitly asks for it |
+| `llmGuardrails: "none"` | Nothing |
+
+The Zod schema in `source.config.ts` validates the field at build time — typos cause build failures.
+
+### Tagged pages (12 total)
+
+`tools-direct/` (8):
+- executing-tools, fetching-tools, authenticating-tools, custom-tools
+- toolkit-versioning
+- modify-tool-behavior/schema-modifiers, before-execution-modifiers, after-execution-modifiers
+
+`auth-configuration/` (4):
+- connected-accounts, custom-auth-configs, custom-auth-params, programmatic-auth-configs
+
+### Endpoint behavior
+
+| Endpoint | Guardrails behavior |
+|---|---|
+| `/:path*.md` (per-page) | Appended per page based on frontmatter |
+| `llms.txt` (index) | One-liner note at top pointing to session pattern |
+| `llms-full.txt` (all pages) | `SESSION_GUARDRAILS` once at the top, per-page guardrails disabled (`includeGuardrails: false`) to avoid 1148x repetition |
+| Copy Page button | Fetches `.md` endpoint, so guardrails are included automatically |
+
+### getLLMText options
+
+```typescript
+getLLMText(page, {
+ includeFooter?: boolean; // default true — nav links at bottom
+ includeGuardrails?: boolean; // default true — guardrail block
+})
+```
+
+`llms-full.txt` passes both as `false` and handles them at the route level instead.
+
+## Why this approach
+
+| Alternative | Why not |
+|---|---|
+| Per-page component/accordion | Requires adding to every page, new pages miss it |
+| URL-path matching in code | Implicit — moving a file breaks it silently |
+| Separate "Copy Prompt" button (Clerk-style) | Clashes with existing "Copy Page" button |
+| Guardrails in frontmatter content | Visible to humans on the site |
+
+Frontmatter tag + pipeline injection = zero visual impact, zero per-page maintenance, explicit opt-in for different behavior, build-time validation.
+
+## Adding a new guardrail set
+
+1. Create `lib/llm-guardrails/your-set.ts` exporting a string constant
+2. Add the enum value to `llmGuardrails` in `source.config.ts`
+3. Add a case to `getGuardrails()` in `lib/llm-guardrails/index.ts`
+4. Tag pages with `llmGuardrails: "your-set"` in frontmatter
+
+## Session guardrails content
+
+The default guardrails include:
+- Correct pattern code (Python + TypeScript)
+- Provider packages table (9 providers)
+- ALWAYS rules (4)
+- NEVER rules (4)
+- Deprecated patterns with markers
+- Verification checklist (5 items)
+
+## Direct execution guardrails content
+
+The softer guardrails include:
+- Note that this page documents the low-level API
+- Recommended session pattern code (Python + TypeScript)
+- "When to use direct execution" — only when user explicitly asks for it
diff --git a/docs/CLAUDE.md b/docs/CLAUDE.md
index 7a3fa05e3..f79c09473 100644
--- a/docs/CLAUDE.md
+++ b/docs/CLAUDE.md
@@ -18,7 +18,7 @@ docs/
├── app/ # Next.js app router
├── content/ # MDX content
│ ├── docs/ # Main documentation
-│ ├── examples/ # Example guides
+│ ├── cookbooks/ # Cookbooks & guides
│ ├── changelog/ # Release notes
│ └── reference/ # SDK & API reference
├── components/ # React components
@@ -42,8 +42,9 @@ Detailed documentation for Claude is organized in `.claude/`:
### Decisions (ADRs)
- [toolkits.md](.claude/decisions/toolkits.md) - Toolkits page implementation
-- [examples.md](.claude/decisions/examples.md) - Examples page plan
+- [examples.md](.claude/decisions/examples.md) - Examples/cookbooks page plan
- [feedback.md](.claude/decisions/feedback.md) - Feedback system
+- [llm-guardrails.md](.claude/decisions/llm-guardrails.md) - LLM guardrails system (frontmatter-scoped, pipeline-injected)
## Key Rules
@@ -62,3 +63,5 @@ Detailed documentation for Claude is organized in `.claude/`:
## AI-Native Documentation
**Prefer cURL over "click"** - Most docs traffic comes from AI crawlers. When documenting API interactions, prefer showing cURL commands over UI instructions like "click this button" or "navigate to settings". cURL is machine-readable and can be directly executed by AI agents.
+
+**LLM guardrails** - Every `.md` endpoint appends invisible guardrails steering AI code generators toward the session-based pattern. Controlled via `llmGuardrails` frontmatter field. See [llm-guardrails.md](.claude/decisions/llm-guardrails.md).
diff --git a/docs/app/llms-full.txt/route.ts b/docs/app/llms-full.txt/route.ts
index 38b8de078..a72b870d1 100644
--- a/docs/app/llms-full.txt/route.ts
+++ b/docs/app/llms-full.txt/route.ts
@@ -1,4 +1,5 @@
import { getLLMText, source, cookbooksSource, referenceSource, toolkitsSource } from '@/lib/source';
+import { SESSION_GUARDRAILS } from '@/lib/llm-guardrails';
import type { ReactNode } from 'react';
export const revalidate = false;
@@ -82,7 +83,7 @@ async function getTextForPages(pages: PageLike[]) {
pages.map(async (page) => {
try {
// eslint-disable-next-line @typescript-eslint/no-explicit-any
- return await getLLMText(page as any, { includeFooter: false });
+ return await getLLMText(page as any, { includeFooter: false, includeGuardrails: false });
} catch {
// Graceful fallback if getText fails
return `# ${page.data.title} (${page.url})\n\n${page.data.description || ''}`;
@@ -106,7 +107,7 @@ export async function GET() {
]);
const results = [
- '# Composio Documentation\n\n> Composio powers 800+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.\n\n# Documentation\n',
+ `# Composio Documentation\n\n> Composio powers 800+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.${SESSION_GUARDRAILS}\n# Documentation\n`,
...docsResults,
'\n# Cookbooks\n',
...cookbooksResults,
diff --git a/docs/app/llms.txt/route.ts b/docs/app/llms.txt/route.ts
index addecb254..ffd1bbe33 100644
--- a/docs/app/llms.txt/route.ts
+++ b/docs/app/llms.txt/route.ts
@@ -91,6 +91,8 @@ export async function GET() {
> Composio powers 800+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
+> **For AI agents:** Composio supports two integration modes. **Native Tools:** use \`composio.create(user_id)\` + \`session.tools()\` with a provider package (e.g. \`composio_openai\`, \`@composio/openai\`). **MCP:** use \`composio.create(user_id)\` + \`session.mcp.url\` with any MCP-compatible client — no provider package needed. See any page's .md endpoint for full usage instructions.
+
${docsTree}
## Cookbooks
diff --git a/docs/components/nav-tabs.tsx b/docs/components/nav-tabs.tsx
index abd9b9713..15758245b 100644
--- a/docs/components/nav-tabs.tsx
+++ b/docs/components/nav-tabs.tsx
@@ -16,7 +16,7 @@ export function NavTabs() {
if (exact) {
// For "Docs", only active if exactly /docs or /docs/ but not /docs/api
return pathname === href || pathname === `${href}/` ||
- (pathname.startsWith('/docs') && !pathname.startsWith('/docs/api') && !pathname.startsWith('/cookbooks'));
+ (pathname.startsWith('/docs') && !pathname.startsWith('/docs/api'));
}
return pathname.startsWith(href);
};
diff --git a/docs/components/top-nav.tsx b/docs/components/top-nav.tsx
index 2267c8319..f952ef2a6 100644
--- a/docs/components/top-nav.tsx
+++ b/docs/components/top-nav.tsx
@@ -15,10 +15,9 @@ export function TopNav() {
const isActive = (href: string) => {
if (href === '/docs') {
- return pathname === '/docs' ||
- (pathname.startsWith('/docs') &&
- !pathname.startsWith('/docs/api') &&
- !pathname.startsWith('/cookbooks'));
+ return pathname === '/docs' ||
+ (pathname.startsWith('/docs') &&
+ !pathname.startsWith('/docs/api'));
}
return pathname.startsWith(href);
};
diff --git a/docs/content/docs/auth-configuration/connected-accounts.mdx b/docs/content/docs/auth-configuration/connected-accounts.mdx
index 770dc5401..203170d2a 100644
--- a/docs/content/docs/auth-configuration/connected-accounts.mdx
+++ b/docs/content/docs/auth-configuration/connected-accounts.mdx
@@ -2,6 +2,7 @@
title: Connected Accounts
description: Manage and monitor user connections to toolkits
keywords: [list accounts, refresh token, disable, delete account]
+llmGuardrails: "direct-execution"
---
Connected accounts are authenticated connections between your users and toolkits. After users authenticate (see [Authenticating tools](/docs/tools-direct/authenticating-tools)), you can manage these accounts throughout their lifecycle.
diff --git a/docs/content/docs/auth-configuration/custom-auth-configs.mdx b/docs/content/docs/auth-configuration/custom-auth-configs.mdx
index 8cc7d80e9..2306f3617 100644
--- a/docs/content/docs/auth-configuration/custom-auth-configs.mdx
+++ b/docs/content/docs/auth-configuration/custom-auth-configs.mdx
@@ -2,6 +2,7 @@
title: Custom Auth Configs
description: Customize auth configs for any toolkit
keywords: [white label, custom oauth, own developer app]
+llmGuardrails: "direct-execution"
---
Many toolkits support a level of customization for the auth config, specifically OAuth applications.
diff --git a/docs/content/docs/auth-configuration/custom-auth-params.mdx b/docs/content/docs/auth-configuration/custom-auth-params.mdx
index 0bef39230..03800e330 100644
--- a/docs/content/docs/auth-configuration/custom-auth-params.mdx
+++ b/docs/content/docs/auth-configuration/custom-auth-params.mdx
@@ -2,6 +2,7 @@
title: Custom Auth Parameters
description: Inject custom credentials in headers or parameters
keywords: [inject headers, custom credentials]
+llmGuardrails: "direct-execution"
---
In cases where Composio is not being used for managing the auth but only for the tools, it is possible to use the `beforeExecute` hook to inject custom auth headers or parameters for a toolkit.
diff --git a/docs/content/docs/auth-configuration/programmatic-auth-configs.mdx b/docs/content/docs/auth-configuration/programmatic-auth-configs.mdx
index e265dc50f..ce4382147 100644
--- a/docs/content/docs/auth-configuration/programmatic-auth-configs.mdx
+++ b/docs/content/docs/auth-configuration/programmatic-auth-configs.mdx
@@ -2,6 +2,7 @@
title: Programmatic Auth Configs
description: Create auth configs programmatically
keywords: [create auth config, sdk]
+llmGuardrails: "direct-execution"
---
Auth configs are created once and reused many times. However, when managing multiple toolkits, you may want to create auth configs programmatically.
diff --git a/docs/content/docs/tools-direct/authenticating-tools.mdx b/docs/content/docs/tools-direct/authenticating-tools.mdx
index 4099bc828..18e8a7d81 100644
--- a/docs/content/docs/tools-direct/authenticating-tools.mdx
+++ b/docs/content/docs/tools-direct/authenticating-tools.mdx
@@ -2,6 +2,7 @@
title: Authenticating Tools
description: Create auth configs and connect user accounts
keywords: [oauth, api key, auth config, connect account, credentials]
+llmGuardrails: "direct-execution"
---
The first step in authenticating your users is to create an **Auth Config**. Every toolkit has its own authentication method such as `OAuth`, `API key`, `Basic Auth`, or custom schemes.
diff --git a/docs/content/docs/tools-direct/custom-tools.mdx b/docs/content/docs/tools-direct/custom-tools.mdx
index 79ab68a28..9a0199f82 100644
--- a/docs/content/docs/tools-direct/custom-tools.mdx
+++ b/docs/content/docs/tools-direct/custom-tools.mdx
@@ -2,6 +2,7 @@
title: Creating Custom Tools
description: Learn how to extend Composio's toolkits with your own tools
keywords: [create tool, custom action, extend, standalone tool]
+llmGuardrails: "direct-execution"
---
Custom tools allow you to create your own tools that can be used with Composio.
diff --git a/docs/content/docs/tools-direct/executing-tools.mdx b/docs/content/docs/tools-direct/executing-tools.mdx
index 41f82450f..34ac27bc7 100644
--- a/docs/content/docs/tools-direct/executing-tools.mdx
+++ b/docs/content/docs/tools-direct/executing-tools.mdx
@@ -2,6 +2,7 @@
title: Executing Tools
description: Learn how to execute Composio tools with different providers and frameworks
keywords: [execute, run, tool calling, function calling, direct execution]
+llmGuardrails: "direct-execution"
---
LLMs on their own can only do generation. Tool calling changes that by letting them interact with external services. Instead of just drafting an email, the model can call `GMAIL_SEND_EMAIL` to actually send it. The tool's results feed back to the LLM, closing the loop so it can decide, act, observe, and adapt.
diff --git a/docs/content/docs/tools-direct/fetching-tools.mdx b/docs/content/docs/tools-direct/fetching-tools.mdx
index fcf24dd26..b4919f286 100644
--- a/docs/content/docs/tools-direct/fetching-tools.mdx
+++ b/docs/content/docs/tools-direct/fetching-tools.mdx
@@ -2,6 +2,7 @@
title: Fetching tools and schemas
description: Fetch and filter tools, and inspect schemas
keywords: [get tools, list tools, filter, schema]
+llmGuardrails: "direct-execution"
---
Fetch specific tools, filter by permissions or search, and inspect schemas for type information. Tools are automatically formatted for your provider.
diff --git a/docs/content/docs/tools-direct/modify-tool-behavior/after-execution-modifiers.mdx b/docs/content/docs/tools-direct/modify-tool-behavior/after-execution-modifiers.mdx
index 4d8112440..af1968e23 100644
--- a/docs/content/docs/tools-direct/modify-tool-behavior/after-execution-modifiers.mdx
+++ b/docs/content/docs/tools-direct/modify-tool-behavior/after-execution-modifiers.mdx
@@ -1,6 +1,7 @@
---
title: After Execution Modifiers
description: Transform tool results after execution
+llmGuardrails: "direct-execution"
---
After execution modifiers are part of Composio SDK's powerful middleware capabilities that allow you to customize and extend the behavior of tools.
diff --git a/docs/content/docs/tools-direct/modify-tool-behavior/before-execution-modifiers.mdx b/docs/content/docs/tools-direct/modify-tool-behavior/before-execution-modifiers.mdx
index d0170fed9..a5177510f 100644
--- a/docs/content/docs/tools-direct/modify-tool-behavior/before-execution-modifiers.mdx
+++ b/docs/content/docs/tools-direct/modify-tool-behavior/before-execution-modifiers.mdx
@@ -1,6 +1,7 @@
---
title: Before Execution Modifiers
description: Modify tool arguments before execution
+llmGuardrails: "direct-execution"
---
Before execution modifiers are part of Composio SDK's powerful middleware capabilities that allow you to customize and extend the behavior of tools.
diff --git a/docs/content/docs/tools-direct/modify-tool-behavior/schema-modifiers.mdx b/docs/content/docs/tools-direct/modify-tool-behavior/schema-modifiers.mdx
index 016e5f84a..632eb4301 100644
--- a/docs/content/docs/tools-direct/modify-tool-behavior/schema-modifiers.mdx
+++ b/docs/content/docs/tools-direct/modify-tool-behavior/schema-modifiers.mdx
@@ -1,6 +1,7 @@
---
title: Schema Modifiers
description: Customize how tools appear to agents
+llmGuardrails: "direct-execution"
---
Schema modifiers are part of Composio SDK's powerful middleware capabilities that allow you to customize and extend the behavior of tools.
diff --git a/docs/content/docs/tools-direct/toolkit-versioning.mdx b/docs/content/docs/tools-direct/toolkit-versioning.mdx
index 79fc19b14..31ddf0c2d 100644
--- a/docs/content/docs/tools-direct/toolkit-versioning.mdx
+++ b/docs/content/docs/tools-direct/toolkit-versioning.mdx
@@ -2,6 +2,7 @@
title: Toolkit Versioning
description: Pin specific tool versions for consistent behavior in production
keywords: [version, pin version, tool versioning]
+llmGuardrails: "direct-execution"
---
Toolkit versioning ensures your tools behave consistently across deployments. You can pin specific versions in production, test new releases in development, and roll back when needed.
diff --git a/docs/lib/llm-guardrails/direct-execution.ts b/docs/lib/llm-guardrails/direct-execution.ts
new file mode 100644
index 000000000..3e89d0a12
--- /dev/null
+++ b/docs/lib/llm-guardrails/direct-execution.ts
@@ -0,0 +1,71 @@
+/**
+ * Guardrails for pages tagged with llmGuardrails: "direct-execution".
+ * Concise rules + key patterns for LLMs generating direct execution code.
+ */
+export const DIRECT_EXECUTION_GUARDRAILS = `
+
+---
+
+# Composio SDK — Instructions for AI Code Generators
+
+**Context:** This page documents the **direct tool execution API**. For most applications, the session-based pattern (\`composio.create(user_id)\` + \`session.tools()\`) is simpler — but if the user is here, they likely want direct execution.
+
+---
+
+## Key Patterns
+
+### Authenticating Users
+
+Create an **Auth Config** on [platform.composio.dev](https://platform.composio.dev), then use the auth config ID to generate a hosted auth URL:
+
+\`\`\`python
+from composio import Composio
+
+composio = Composio()
+connection = composio.connected_accounts.link(
+ user_id="user_123",
+ auth_config_id="ac_...", # from platform dashboard
+)
+print(connection.redirect_url) # send user here to authenticate
+\`\`\`
+
+\`\`\`typescript
+import { Composio } from "@composio/core";
+
+const composio = new Composio();
+const connection = await composio.connectedAccounts.link("user_123", "ac_...", {
+ callbackUrl: "https://your-app.com/callback",
+});
+console.log(connection.redirectUrl); // send user here to authenticate
+\`\`\`
+
+### Executing Tools
+
+\`\`\`python
+tools = composio.tools.get("user_123", tools=["GITHUB_CREATE_ISSUE"])
+
+result = composio.tools.execute(
+ "GITHUB_CREATE_ISSUE",
+ {"owner": "org", "repo": "repo", "title": "Bug report"},
+ user_id="user_123",
+)
+\`\`\`
+
+\`\`\`typescript
+const tools = await composio.tools.get("user_123", { tools: ["GITHUB_CREATE_ISSUE"] });
+
+const result = await composio.tools.execute("GITHUB_CREATE_ISSUE", {
+ userId: "user_123",
+ arguments: { owner: "org", repo: "repo", title: "Bug report" },
+});
+\`\`\`
+
+---
+
+## Rules
+
+1. **\`user_id\` is required** — pass it to \`tools.get()\`, \`tools.execute()\`, and \`provider.handle_tool_calls()\`.
+2. **\`tools.execute()\` signature** — Python: \`execute(slug, arguments_dict, *, user_id=...)\` (arguments is the second positional param). TypeScript: \`execute(slug, { userId, arguments })\`.
+3. **Provider at init** — \`Composio(provider=OpenAIProvider())\` in Python, \`new Composio({ provider: new OpenAIProvider() })\` in TypeScript. Defaults to OpenAI if omitted.
+4. **Correct provider imports** — \`composio_<provider>\` for Python, \`@composio/<provider>\` for TypeScript. For OpenAI Agents SDK use \`composio_openai_agents\` / \`@composio/openai-agents\`.
+`;
diff --git a/docs/lib/llm-guardrails/index.ts b/docs/lib/llm-guardrails/index.ts
new file mode 100644
index 000000000..47591a5f0
--- /dev/null
+++ b/docs/lib/llm-guardrails/index.ts
@@ -0,0 +1,26 @@
+/**
+ * LLM guardrails — appended to .md responses by getLLMText().
+ *
+ * Pages opt into a guardrail set via frontmatter:
+ * llmGuardrails: "direct-execution" | "none"
+ *
+ * No frontmatter (default) → session guardrails.
+ */
+
+import { SESSION_GUARDRAILS } from './session';
+import { DIRECT_EXECUTION_GUARDRAILS } from './direct-execution';
+
+type GuardrailType = 'direct-execution' | 'none' | undefined;
+
+export function getGuardrails(type: GuardrailType): string {
+ switch (type) {
+ case 'direct-execution':
+ return DIRECT_EXECUTION_GUARDRAILS;
+ case 'none':
+ return '';
+ default:
+ return SESSION_GUARDRAILS;
+ }
+}
+
+export { SESSION_GUARDRAILS, DIRECT_EXECUTION_GUARDRAILS };
diff --git a/docs/lib/llm-guardrails/session.ts b/docs/lib/llm-guardrails/session.ts
new file mode 100644
index 000000000..c75f31450
--- /dev/null
+++ b/docs/lib/llm-guardrails/session.ts
@@ -0,0 +1,68 @@
+/**
+ * Default guardrails appended to most pages.
+ * Steers LLMs toward the session-based pattern (composio.create + session.tools).
+ */
+export const SESSION_GUARDRAILS = `
+
+---
+
+# Composio SDK — Instructions for AI Code Generators
+
+**Purpose:** Enforce only the **current** and **correct** patterns for integrating [Composio](https://composio.dev/) tools into AI agents.
+**Scope:** All AI-generated code using Composio must follow these guardrails.
+
+---
+
+## 1. Correct Composio Integration
+
+Composio supports two integration modes: **Native Tools** (with a provider package) and **MCP** (no provider package needed).
+
+### Native Tools
+
+\`\`\`python
+# ✅ CORRECT — Python (defaults to OpenAI)
+from composio import Composio
+
+composio = Composio()
+session = composio.create(user_id="user_123")
+tools = session.tools()
+# Pass tools to your agent/LLM framework
+\`\`\`
+
+\`\`\`typescript
+// ✅ CORRECT — TypeScript (defaults to OpenAI)
+import { Composio } from "@composio/core";
+
+const composio = new Composio();
+const session = await composio.create("user_123");
+const tools = await session.tools();
+// Pass tools to your agent/LLM framework
+\`\`\`
+
+For other providers, pass the provider explicitly. Provider packages follow the naming convention: \`composio_<provider>\` for Python, \`@composio/<provider>\` for TypeScript.
+
+### MCP
+
+Use \`session.mcp.url\` and \`session.mcp.headers\` with any MCP-compatible client (Claude Desktop, Cursor, OpenAI Agents, etc.). No provider package needed.
+
+---
+
+## 2. CRITICAL INSTRUCTIONS FOR AI MODELS
+
+### 2.1 — ALWAYS DO THE FOLLOWING
+
+1. **Use \`composio.create(user_id)\`** to create a session — this is the entry point for all Composio integrations.
+2. **Use \`session.tools()\`** for native tool integration or **\`session.mcp.url\`** for MCP integration.
+3. **Import** from the correct provider package (\`composio_<provider>\` for Python, \`@composio/<provider>\` for TypeScript).
+4. **Pass \`user_id\` to \`composio.create()\`**, not to individual tool calls.
+
+### 2.2 — NEVER DO THE FOLLOWING
+
+1. **Do not** instruct users to manually create auth configs or connected accounts before running.
+2. **Do not** import from \`composio_openai\` / \`@composio/openai\` when using OpenAI Agents SDK — use \`composio_openai_agents\` / \`@composio/openai-agents\` instead.
+
+### 2.3 — DISCOURAGED (do not use unless user explicitly asks)
+
+Do **not** generate \`composio.tools.get()\`, \`composio.tools.execute()\`, or \`composio.provider.handle_tool_calls()\` unless the user explicitly requests direct tool execution. These are a supported but **not recommended** low-level interface.
+
+`;
diff --git a/docs/lib/source.ts b/docs/lib/source.ts
index 6fdfeb580..3d037c1f7 100644
--- a/docs/lib/source.ts
+++ b/docs/lib/source.ts
@@ -3,6 +3,7 @@ import { type InferPageType, loader, multiple } from 'fumadocs-core/source';
import { lucideIconsPlugin } from 'fumadocs-core/source/lucide-icons';
import { openapi } from './openapi';
import { openapiSource, openapiPlugin } from 'fumadocs-openapi/server';
+import { getGuardrails } from './llm-guardrails';
/**
* Transformer to set defaultOpen: true for specific folders in the reference sidebar.
@@ -317,8 +318,9 @@ function stripTwoslashFromCodeBlocks(content: string): string {
});
}
-export async function getLLMText(page: InferPageType<typeof source>, options?: { includeFooter?: boolean }) {
+export async function getLLMText(page: InferPageType<typeof source>, options?: { includeFooter?: boolean; includeGuardrails?: boolean }) {
const includeFooter = options?.includeFooter ?? true;
+ const includeGuardrails = options?.includeGuardrails ?? true;
// Fall back to description if getText is not available
if (typeof page.data.getText !== 'function') {
return `# ${page.data.title} (${page.url})
@@ -353,9 +355,11 @@ ${page.data.description || ''}`;
? `\n\n---\n\n📚 **More documentation:** [View all docs](https://docs.composio.dev/llms.txt) | [Cookbooks](https://docs.composio.dev/llms.mdx/cookbooks) | [API Reference](https://docs.composio.dev/llms.mdx/reference)`
: '';
+ const guardrails = includeGuardrails ? getGuardrails(page.data.llmGuardrails) : '';
+
return `# ${page.data.title} (${page.url})
-${cleanContent}${footer}`;
+${cleanContent}${footer}${guardrails}`;
}
export function formatDate(dateStr: string): string {
diff --git a/docs/source.config.ts b/docs/source.config.ts
index 46e5d106f..03ed4901f 100644
--- a/docs/source.config.ts
+++ b/docs/source.config.ts
@@ -17,6 +17,11 @@ import { z } from 'zod';
// Extended schema with keywords for search
const docsSchema = frontmatterSchema.extend({
keywords: z.array(z.string()).optional(),
+ /** Controls which LLM guardrail set is appended to the .md output.
+ * - undefined / omitted → default session-based guardrails
+ * - "direct-execution" → softer guardrails acknowledging this is the low-level API
+ * - "none" → no guardrails appended */
+ llmGuardrails: z.enum(['direct-execution', 'none']).optional(),
});
export const docs = defineDocs({