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: Fetch and filter tools refactor (#2178)
Sushmitha Malleshf1b1eebe6ad7
diff --git a/fern/docs.yml b/fern/docs.ymlindex 153665c9e..50cfb97bc 100644--- a/fern/docs.yml+++ b/fern/docs.yml@@ -135,7 +135,7 @@ navigation:- page: Authenticating Toolspath: pages/dist/tool-calling/authenticating-tools.mdxslug: authenticating-tools- - page: Fetch and Filter Tools+ - page: Fetching tools and schemaspath: pages/dist/tool-calling/fetching-tools.mdxslug: fetching-tools- page: Executing Toolsdiff --git a/fern/pages/src/tool-calling/fetching-tools.mdx b/fern/pages/src/tool-calling/fetching-tools.mdxindex 458efac96..f57b11cc9 100644--- a/fern/pages/src/tool-calling/fetching-tools.mdx+++ b/fern/pages/src/tool-calling/fetching-tools.mdx@@ -1,210 +1,137 @@----title: Fetching and Filtering Tools-image: "https://og.composio.dev/api/og?title=Fetching%20and%20Filtering%20Tools" # image for socials-keywords: "fetch tool, filter tool"-subtitle: "Learn how to fetch and filter Composio's tools and toolsets"+title: Fetching tools and schemas+image: "https://og.composio.dev/api/og?title=Fetching%20tools%20and%20schemas" # image for socials+keywords: "fetch tool, filter tool, tool schema, tool types, inspect schema, raw tools"+subtitle: "Fetch and filter tools, and inspect schemas"hide-nav-links: false----To effectively use tools, it is recommended to fetch, inspect, and filter them based on your criteria.+Fetch specific tools, filter by permissions or search, and inspect schemas for type information. Tools are automatically formatted for your provider.-This process returns a union of all tools that match the specified criteria, ensuring you provide the most relevant tools to the agents.--When fetching tools, they are automatically formatted to match the requirements of the provider you are using. This means you do not need to manually convert or adapt the tool format.--## Filtering by toolkit-Toolkits are collections of tools from a specific app!--Fetching tools from a toolkit is a good way to get a sense of the tools available.--<Tip title="Tools are ordered by importance" icon="info">-When you fetch tools from a toolkit, the most important tools are returned first.--Composio determines the importance of a tool based on the usage and relevance of the tool.-</Tip>+## Basic usage<CodeGroup>-```python Python maxLines=60 wordWrap-tools = composio.tools.get(- user_id,- toolkits=["GITHUB", "HACKERNEWS"],-)-```--```typescript TypeScript maxLines=60 wordWrap-const tools = await composio.tools.get(- userId,- {- toolkits: ["GITHUB", "LINEAR"],- }-);-```+<SnippetCode+ src="fern/snippets/tool-calling/python/fetching-tools.py"+ title="Python"+ startLine={6}+ endLine={9}+/>+<SnippetCode+ src="fern/snippets/tool-calling/typescript/fetching-tools.ts"+ title="TypeScript"+ startLine={6}+ endLine={8}+/></CodeGroup>-**Limiting the results**+Returns top 20 tools by default. Tools require a `user_id` because they're scoped to authenticated accounts. See [User management](./user-management) and [Authentication](./authenticating-tools).-Multiple toolkits have 100s of tools. These can easily overwhelm the LLM. Hence, the SDK allows you to limit the number of tools returned.+## Tool schemas-The default `limit` is 20 -- meaning you get the top 20 important tools from the toolkit.+Inspect tool parameters and types without a user_id:<CodeGroup>-```python Python maxLines=60 wordWrap-tools = composio.tools.get(- user_id,- toolkits=["GITHUB"],- limit=5, # Returns the top 5 important tools from the toolkit-)-```-```typescript TypeScript maxLines=60 wordWrap-const tools = await composio.tools.get(userId, {- toolkits: ["GITHUB"],- limit: 5, // Returns the top 5 important tools from the toolkit-});-```+<SnippetCode+ src="fern/snippets/tool-calling/python/fetching-tools.py"+ title="Python"+ startLine={66}+ endLine={66}+/>+<SnippetCode+ src="fern/snippets/tool-calling/typescript/fetching-tools.ts"+ title="TypeScript"+ startLine={60}+ endLine={60}+/></CodeGroup>-**Filtering by scopes**+Generate type-safe code for direct SDK execution with [`composio generate`](/docs/cli#generate-type-definitions). This creates TypeScript or Python types from tool schemas.-When working with OAuth-based toolkits, you can filter tools based on their required scopes. This is useful when you want to:-- Get tools that match specific permission levels-- Ensure tools align with available user permissions-- Filter tools based on their required OAuth scopes--<Tip title="Single Toolkit Requirement" icon="warning">-Scope filtering can only be used with a single toolkit at a time.+<Tip>+View tool parameters and schemas visually in the [Composio platform](https://platform.composio.dev). Navigate to any toolkit and select a tool to see its input/output parameters.</Tip>-<CodeGroup>-```python Python maxLines=60 wordWrap-# Get GitHub tools that require specific scopes-tools = composio.tools.get(- user_id,- toolkits=["GITHUB"],- scopes=["repo"], # Only get tools requiring these scopes- limit=10-)-```-```typescript TypeScript maxLines=60 wordWrap-// Get GitHub tools that require specific scopes-const tools = await composio.tools.get(userId, {- toolkits: ["GITHUB"],- scopes: ["repo"], // Only get tools requiring these scopes- limit: 10-});-```-</CodeGroup>--## Tool versions+## Filtering tools-You can configure toolkit versions at SDK initialization to ensure consistent tool behavior across environments. When fetching tools, you can also [inspect which version each tool is using](/docs/toolkit-versioning#inspect-current-versions).+### By toolkit-## Filtering by tool-You may specify the list of tools to fetch by directly providing the tool names. Browse the list of tools [here](/tools) to view and inspect the tools for each toolkit.+Get tools from specific apps. Returns top 20 tools by default.<CodeGroup>--```python Python maxLines=60 wordWrap-tools = composio.tools.get(- user_id,- tools=[- "GITHUB_CREATE_AN_ISSUE",- "GITHUB_CREATE_AN_ISSUE_COMMENT",- "GITHUB_CREATE_A_COMMIT",- ],-)-```--```typescript TypeScript maxLines=60 wordWrap-const tools = await composio.tools.get(userId, {- tools: [- "GITHUB_CREATE_AN_ISSUE",- "GITHUB_CREATE_AN_ISSUE_COMMENT",- "GITHUB_CREATE_A_COMMIT",- ],-});-```+<SnippetCode+ src="fern/snippets/tool-calling/python/fetching-tools.py"+ title="Python"+ startLine={12}+ endLine={23}+/>+<SnippetCode+ src="fern/snippets/tool-calling/typescript/fetching-tools.ts"+ title="TypeScript"+ startLine={11}+ endLine={21}+/></CodeGroup>-## Fetching raw tools-To examine the raw schema definition of a tool to understand the input/output parameters or to build custom logic around tool definitions, you can use the following methods. This can be useful for:-- Understanding exact input parameters and output structures.-- Building custom logic around tool definitions.-- Debugging tool interactions.-- Research and experimentation.++### By name++Fetch specific tools when you know their names.<CodeGroup><SnippetCode- src="fern/snippets/tool-calling/python/raw_tools.py"- startLine={5}- endLine={7}+ src="fern/snippets/tool-calling/python/fetching-tools.py"title="Python"+ startLine={25}+ endLine={34}/><SnippetCode- src="fern/snippets/tool-calling/typescript/raw_tools.ts"- startLine={5}- endLine={7}+ src="fern/snippets/tool-calling/typescript/fetching-tools.ts"title="TypeScript"+ startLine={23}+ endLine={31}/></CodeGroup>-## Filtering by search (Experimental)-You may also filter tools by searching for them. This is a good way to find tools that are relevant to a given use case.+### By scopes-This step runs a semantic search on the tool names and descriptions and returns the most relevant tools.+Filter OAuth tools by permission level. Only works with a single toolkit.<CodeGroup>-```python Python maxLines=60 wordWrap-tools = composio.tools.get(- user_id,- search="hubspot organize contacts",-)--# Search within a specific toolkit-tools = composio.tools.get(- user_id,- search="repository issues",- toolkits=["GITHUB"], # Optional: limit search to specific toolkit- limit=5 # Optional: limit number of results-)-```--```typescript TypeScript maxLines=60 wordWrap-const tools = await composio.tools.get(userId, {- search: "hubspot organize contacts",-});--// Search within a specific toolkit-const tools = await composio.tools.get(userId, {- search: "repository issues",- toolkits: ["GITHUB"], // Optional: limit search to specific toolkit- limit: 5 // Optional: limit number of results-});-```+<SnippetCode+ src="fern/snippets/tool-calling/python/fetching-tools.py"+ title="Python"+ startLine={36}+ endLine={41}+/>+<SnippetCode+ src="fern/snippets/tool-calling/typescript/fetching-tools.ts"+ title="TypeScript"+ startLine={33}+ endLine={37}+/></CodeGroup>-## Filter Combinations--When fetching tools, you must use one of these filter combinations:--1. **Tools Only**: Fetch specific tools by their slugs- ```typescript- { tools: ["TOOL_1", "TOOL_2"] }- ```+### By search (experimental)-2. **Toolkits Only**: Fetch tools from specific toolkits- ```typescript- { toolkits: ["TOOLKIT_1", "TOOLKIT_2"], limit?: number }- ```+Find tools semantically.-3. **Single Toolkit with Scopes**: Fetch tools requiring specific OAuth scopes- ```typescript- { toolkits: ["GITHUB"], scopes: ["read:repo"], limit?: number }- ```--4. **Search**: Search across all tools or within specific toolkits- ```typescript- { search: "query", toolkits?: string[], limit?: number }- ```+<CodeGroup>+<SnippetCode+ src="fern/snippets/tool-calling/python/fetching-tools.py"+ title="Python"+ startLine={43}+ endLine={65}+/>+<SnippetCode+ src="fern/snippets/tool-calling/typescript/fetching-tools.ts"+ title="TypeScript"+ startLine={39}+ endLine={59}+/>+</CodeGroup>-These combinations are mutually exclusive - you can't mix `tools` with `search` or use `scopes` with multiple toolkits.\ No newline at end of file+<Tip>+Use specific toolkit versions in production to prevent breaking changes. See [toolkit versioning](./toolkit-versioning).+</Tip>\ No newline at end of filediff --git a/fern/snippets/tool-calling/python/fetching-tools.py b/fern/snippets/tool-calling/python/fetching-tools.pynew file mode 100644index 000000000..e7565a3a6--- /dev/null+++ b/fern/snippets/tool-calling/python/fetching-tools.py@@ -0,0 +1,66 @@+from composio import Composio++composio = Composio()+user_id = "uuid-1234-5678-9012"++tools = composio.tools.get(+ user_id,+ toolkits=["GITHUB"]+)++# Fetch with limit for a specific user+tools = composio.tools.get(+ user_id,+ toolkits=["GITHUB"],+ limit=5 # Get top 5 tools+)++# Same filter but without user_id (for schemas)+raw_tools = composio.tools.get_raw_composio_tools(+ toolkits=["GITHUB"],+ limit=5+)++# Fetch specific tools by name+tools = composio.tools.get(+ user_id,+ tools=["GITHUB_CREATE_ISSUE", "GITHUB_CREATE_PULL_REQUEST"]+)++# Get schemas without user_id+raw_tools = composio.tools.get_raw_composio_tools(+ tools=["GITHUB_CREATE_ISSUE", "GITHUB_CREATE_PULL_REQUEST"]+)++# Filter by OAuth scopes (single toolkit only)+tools = composio.tools.get(+ user_id,+ toolkits=["GITHUB"],+ scopes=["write:org"]+)++# Search tools semantically+tools = composio.tools.get(+ user_id,+ search="create calendar event"+)++# Search schemas without user_id+raw_tools = composio.tools.get_raw_composio_tools(+ search="create calendar event"+)++# Search within a specific toolkit+tools = composio.tools.get(+ user_id,+ search="issues",+ toolkits=["GITHUB"],+)++# Search toolkit schemas without user_id+raw_tools = composio.tools.get_raw_composio_tools(+ search="issues",+ toolkits=["GITHUB"]+)++tool = composio.tools.get_raw_composio_tool_by_slug("GMAIL_SEND_EMAIL")\ No newline at end of filediff --git a/fern/snippets/tool-calling/typescript/fetching-tools.ts b/fern/snippets/tool-calling/typescript/fetching-tools.tsnew file mode 100644index 000000000..cbc6259d4--- /dev/null+++ b/fern/snippets/tool-calling/typescript/fetching-tools.ts@@ -0,0 +1,60 @@+import { Composio } from '@composio/core';++const composio = new Composio();+const userId = "uuid-1234-5678-9012";++const tools = await composio.tools.get(userId, {+ toolkits: ["GITHUB"]+});++// Fetch with limit for a specific user+const limitedTools = await composio.tools.get(userId, {+ toolkits: ["GITHUB"],+ limit: 5 // Get top 5 tools+});++// Same filter but without userId (for schemas)+const rawTools = await composio.tools.getRawComposioTools({+ toolkits: ["GITHUB"],+ limit: 5+});++// Fetch specific tools by name+const specificTools = await composio.tools.get(userId, {+ tools: ["GITHUB_LIST_STARGAZERS", "GITHUB_STAR_A_REPOSITORY_FOR_THE_AUTHENTICATED_USER"]+});++// Get schemas without userId+const specificRawTools = await composio.tools.getRawComposioTools({+ tools: ["GITHUB_LIST_STARGAZERS", "GITHUB_STAR_A_REPOSITORY_FOR_THE_AUTHENTICATED_USER"]+});++// Filter by OAuth scopes (single toolkit only)+const scopedTools = await composio.tools.get(userId, {+ toolkits: ["GITHUB"],+ scopes: ["write:org"]+});++// Search tools semantically+const searchResults = await composio.tools.get(userId, {+ search: "create google calendar event"+});++// Search schemas without userId+const searchRawTools = await composio.tools.getRawComposioTools({+ search: "create google calendar event"+});++// Search within a specific toolkit+const toolkitSearch = await composio.tools.get(userId, {+ search: "star a repository",+ toolkits: ["GITHUB"]+});++// Search toolkit schemas without userId+const toolkitSearchRaw = await composio.tools.getRawComposioTools({+ search: "star a repository",+ toolkits: ["GITHUB"]+});++const tool = await composio.tools.getRawComposioToolBySlug("GMAIL_SEND_EMAIL");\ No newline at end of file