Fetching tools and schemas

View as markdown

Fetch specific tools, filter by permissions or search, and inspect schemas for type information. Tools are automatically formatted for your provider.

Basic usage

tools = composio.tools.get(
    user_id,
    toolkits=["GITHUB"]
)
const const tools: OpenAiToolCollectiontools = await const composio: Composio<OpenAIProvider>composio.Composio<OpenAIProvider>.tools: Tools<unknown, unknown, OpenAIProvider>
List, retrieve, and execute tools
tools.Tools<unknown, unknown, OpenAIProvider>.get<OpenAIProvider>(userId: string, filters: ToolListParams, options?: ToolOptions | undefined): Promise<OpenAiToolCollection> (+1 overload)
Get a list of tools from Composio based on filters.
This method fetches the tools from the Composio API and wraps them using the provider.
@paramuserId - The user id to get the tools for@paramfilters - The filters to apply when fetching tools@paramoptions - Optional provider options including modifiers@returnsThe wrapped tools collection@example```typescript
// Get tools from the GitHub toolkit
const tools = await composio.tools.get('default', {
  toolkits: ['github'],
  limit: 10
});

// Get tools with search
const searchTools = await composio.tools.get('default', {
  search: 'user',
  limit: 10
});

// Get a specific tool by slug
const hackerNewsUserTool = await composio.tools.get('default', 'HACKERNEWS_GET_USER');

// Get a tool with schema modifications
const tool = await composio.tools.get('default', 'GITHUB_GET_REPOS', {
  modifySchema: (toolSlug, toolkitSlug, schema) => {
    // Customize the tool schema
    return {...schema, description: 'Custom description'};
  }
});
```
get(const userId: "user-123"userId, {
  toolkits: [string]toolkits: ["GITHUB"]
});

Returns top 20 tools by default. Tools require a user_id because they're scoped to authenticated accounts. See User management and Authentication.

Tool schemas

Inspect tool parameters and types without a user_id:

tool = composio.tools.get_raw_composio_tool_by_slug("GMAIL_SEND_EMAIL")
const 
const tool: {
    slug: string;
    name: string;
    description?: string | undefined;
    inputParameters?: {
        type: "object";
        properties: Record<string, any>;
        description?: string | undefined;
        anyOf?: any[] | undefined;
        oneOf?: any[] | undefined;
        allOf?: any[] | undefined;
        not?: any;
        required?: string[] | undefined;
        title?: string | undefined;
        default?: any;
        nullable?: boolean | undefined;
        additionalProperties?: boolean | undefined;
    } | undefined;
    outputParameters?: {
        type: "object";
        properties: Record<string, any>;
        description?: string | undefined;
        anyOf?: any[] | undefined;
        oneOf?: any[] | undefined;
        allOf?: any[] | undefined;
        not?: any;
        required?: string[] | undefined;
        title?: string | undefined;
        default?: any;
        nullable?: boolean | undefined;
        additionalProperties?: boolean | undefined;
    } | undefined;
    ... 6 more ...;
    isNoAuth?: boolean | undefined;
}
tool = await const composio: Composio<OpenAIProvider>composio.Composio<OpenAIProvider>.tools: Tools<unknown, unknown, OpenAIProvider>
List, retrieve, and execute tools
tools.Tools<unknown, unknown, OpenAIProvider>.getRawComposioToolBySlug(slug: string, options?: SchemaModifierOptions): Promise<Tool>
Retrieves a specific tool by its slug from the Composio API.

This method fetches a single tool in raw format without provider-specific wrapping,
providing direct access to the tool's schema and metadata. Tool versions are controlled
at the Composio SDK initialization level through the `toolkitVersions` configuration.
@paramslug - The unique identifier of the tool (e.g., 'GITHUB_GET_REPOS')@paramoptions - Optional configuration for tool retrieval@paramoptions.modifySchema - Function to transform the tool schema@returnsThe requested tool with its complete schema and metadata@example```typescript
// Get a tool by slug
const tool = await composio.tools.getRawComposioToolBySlug('GITHUB_GET_REPOS');
console.log(tool.name, tool.description);

// Get a tool with schema transformation
const customizedTool = await composio.tools.getRawComposioToolBySlug(
  'SLACK_SEND_MESSAGE',
  {
    modifySchema: ({ toolSlug, toolkitSlug, schema }) => {
      return {
        ...schema,
        description: `Enhanced ${schema.description} with custom modifications`,
        customMetadata: {
          lastModified: new Date().toISOString(),
          toolkit: toolkitSlug
        }
      };
    }
  }
);

// Get a custom tool (will check custom tools first)
const customTool = await composio.tools.getRawComposioToolBySlug('MY_CUSTOM_TOOL');

// Access tool properties
const githubTool = await composio.tools.getRawComposioToolBySlug('GITHUB_CREATE_ISSUE');
console.log({
  slug: githubTool.slug,
  name: githubTool.name,
  toolkit: githubTool.toolkit?.name,
  version: githubTool.version,
  availableVersions: githubTool.availableVersions,
  inputParameters: githubTool.inputParameters
});
```
getRawComposioToolBySlug("GMAIL_SEND_EMAIL");

Generate type-safe code for direct SDK execution with composio generate. This creates TypeScript or Python types from tool schemas.

View tool parameters and schemas visually in the Composio platform. Navigate to any toolkit and select a tool to see its input/output parameters.

Filtering tools

By toolkit

Get tools from specific apps. Returns top 20 tools by default.

# 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 with limit for a specific user
const const limitedTools: OpenAiToolCollectionlimitedTools = await const composio: Composio<OpenAIProvider>composio.Composio<OpenAIProvider>.tools: Tools<unknown, unknown, OpenAIProvider>
List, retrieve, and execute tools
tools.Tools<unknown, unknown, OpenAIProvider>.get<OpenAIProvider>(userId: string, filters: ToolListParams, options?: ToolOptions | undefined): Promise<OpenAiToolCollection> (+1 overload)
Get a list of tools from Composio based on filters.
This method fetches the tools from the Composio API and wraps them using the provider.
@paramuserId - The user id to get the tools for@paramfilters - The filters to apply when fetching tools@paramoptions - Optional provider options including modifiers@returnsThe wrapped tools collection@example```typescript
// Get tools from the GitHub toolkit
const tools = await composio.tools.get('default', {
  toolkits: ['github'],
  limit: 10
});

// Get tools with search
const searchTools = await composio.tools.get('default', {
  search: 'user',
  limit: 10
});

// Get a specific tool by slug
const hackerNewsUserTool = await composio.tools.get('default', 'HACKERNEWS_GET_USER');

// Get a tool with schema modifications
const tool = await composio.tools.get('default', 'GITHUB_GET_REPOS', {
  modifySchema: (toolSlug, toolkitSlug, schema) => {
    // Customize the tool schema
    return {...schema, description: 'Custom description'};
  }
});
```
get(const userId: "user-123"userId, {
  toolkits: [string]toolkits: ["GITHUB"],
  limit: numberlimit: 5  // Get top 5 tools
});

// Same filter but without userId (for schemas)
const const rawTools: ToolListrawTools = await const composio: Composio<OpenAIProvider>composio.Composio<OpenAIProvider>.tools: Tools<unknown, unknown, OpenAIProvider>
List, retrieve, and execute tools
tools.Tools<unknown, unknown, OpenAIProvider>.getRawComposioTools(query: ToolListParams, options?: SchemaModifierOptions): Promise<ToolList>
Lists all tools available in the Composio SDK including custom tools.

This method fetches tools from the Composio API in raw format and combines them with
any registered custom tools. The response can be filtered and modified as needed.
It provides access to the underlying tool data without provider-specific wrapping.
@paramquery - Query parameters to filter the tools (required)@paramoptions - Optional configuration for tool retrieval@paramoptions.modifySchema - Function to transform tool schemas@returnsList of tools matching the query criteria@example```typescript
// Get tools from specific toolkits
const githubTools = await composio.tools.getRawComposioTools({
  toolkits: ['github'],
  limit: 10
});

// Get specific tools by slug
const specificTools = await composio.tools.getRawComposioTools({
  tools: ['GITHUB_GET_REPOS', 'HACKERNEWS_GET_USER']
});

// Get tools from specific toolkits
const githubTools = await composio.tools.getRawComposioTools({
  toolkits: ['github'],
  limit: 10
});

// Get tools with schema transformation
const customizedTools = await composio.tools.getRawComposioTools({
  toolkits: ['github'],
  limit: 5
}, {
  modifySchema: ({ toolSlug, toolkitSlug, schema }) => {
    // Add custom properties to tool schema
    return {
      ...schema,
      customProperty: `Modified ${toolSlug} from ${toolkitSlug}`,
      tags: [...(schema.tags || []), 'customized']
    };
  }
});

// Search for tools
const searchResults = await composio.tools.getRawComposioTools({
  search: 'user management'
});

// Get tools by authentication config
const authSpecificTools = await composio.tools.getRawComposioTools({
  authConfigIds: ['auth_config_123']
});
```
getRawComposioTools({
  toolkits: [string]toolkits: ["GITHUB"],
  limit: numberlimit: 5
});

By name

Fetch specific tools when you know their names.

# 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"]
)
// Fetch specific tools by name
const const specificTools: OpenAiToolCollectionspecificTools = await const composio: Composio<OpenAIProvider>composio.Composio<OpenAIProvider>.tools: Tools<unknown, unknown, OpenAIProvider>
List, retrieve, and execute tools
tools.Tools<unknown, unknown, OpenAIProvider>.get<OpenAIProvider>(userId: string, filters: ToolListParams, options?: ToolOptions | undefined): Promise<OpenAiToolCollection> (+1 overload)
Get a list of tools from Composio based on filters.
This method fetches the tools from the Composio API and wraps them using the provider.
@paramuserId - The user id to get the tools for@paramfilters - The filters to apply when fetching tools@paramoptions - Optional provider options including modifiers@returnsThe wrapped tools collection@example```typescript
// Get tools from the GitHub toolkit
const tools = await composio.tools.get('default', {
  toolkits: ['github'],
  limit: 10
});

// Get tools with search
const searchTools = await composio.tools.get('default', {
  search: 'user',
  limit: 10
});

// Get a specific tool by slug
const hackerNewsUserTool = await composio.tools.get('default', 'HACKERNEWS_GET_USER');

// Get a tool with schema modifications
const tool = await composio.tools.get('default', 'GITHUB_GET_REPOS', {
  modifySchema: (toolSlug, toolkitSlug, schema) => {
    // Customize the tool schema
    return {...schema, description: 'Custom description'};
  }
});
```
get(const userId: "user-123"userId, {
  tools: string[]tools: ["GITHUB_LIST_STARGAZERS", "GITHUB_STAR_A_REPOSITORY_FOR_THE_AUTHENTICATED_USER"]
});

// Get schemas without userId
const const specificRawTools: ToolListspecificRawTools = await const composio: Composio<OpenAIProvider>composio.Composio<OpenAIProvider>.tools: Tools<unknown, unknown, OpenAIProvider>
List, retrieve, and execute tools
tools.Tools<unknown, unknown, OpenAIProvider>.getRawComposioTools(query: ToolListParams, options?: SchemaModifierOptions): Promise<ToolList>
Lists all tools available in the Composio SDK including custom tools.

This method fetches tools from the Composio API in raw format and combines them with
any registered custom tools. The response can be filtered and modified as needed.
It provides access to the underlying tool data without provider-specific wrapping.
@paramquery - Query parameters to filter the tools (required)@paramoptions - Optional configuration for tool retrieval@paramoptions.modifySchema - Function to transform tool schemas@returnsList of tools matching the query criteria@example```typescript
// Get tools from specific toolkits
const githubTools = await composio.tools.getRawComposioTools({
  toolkits: ['github'],
  limit: 10
});

// Get specific tools by slug
const specificTools = await composio.tools.getRawComposioTools({
  tools: ['GITHUB_GET_REPOS', 'HACKERNEWS_GET_USER']
});

// Get tools from specific toolkits
const githubTools = await composio.tools.getRawComposioTools({
  toolkits: ['github'],
  limit: 10
});

// Get tools with schema transformation
const customizedTools = await composio.tools.getRawComposioTools({
  toolkits: ['github'],
  limit: 5
}, {
  modifySchema: ({ toolSlug, toolkitSlug, schema }) => {
    // Add custom properties to tool schema
    return {
      ...schema,
      customProperty: `Modified ${toolSlug} from ${toolkitSlug}`,
      tags: [...(schema.tags || []), 'customized']
    };
  }
});

// Search for tools
const searchResults = await composio.tools.getRawComposioTools({
  search: 'user management'
});

// Get tools by authentication config
const authSpecificTools = await composio.tools.getRawComposioTools({
  authConfigIds: ['auth_config_123']
});
```
getRawComposioTools({
  tools: string[]tools: ["GITHUB_LIST_STARGAZERS", "GITHUB_STAR_A_REPOSITORY_FOR_THE_AUTHENTICATED_USER"]
});

By scopes

Filter OAuth tools by permission level. Only works with a single toolkit.

# Filter by OAuth scopes (single toolkit only)
tools = composio.tools.get(
    user_id,
    toolkits=["GITHUB"],
    scopes=["write:org"]
)
// Filter by OAuth scopes (single toolkit only)
const const scopedTools: OpenAiToolCollectionscopedTools = await const composio: Composio<OpenAIProvider>composio.Composio<OpenAIProvider>.tools: Tools<unknown, unknown, OpenAIProvider>
List, retrieve, and execute tools
tools.Tools<unknown, unknown, OpenAIProvider>.get<OpenAIProvider>(userId: string, filters: ToolListParams, options?: ToolOptions | undefined): Promise<OpenAiToolCollection> (+1 overload)
Get a list of tools from Composio based on filters.
This method fetches the tools from the Composio API and wraps them using the provider.
@paramuserId - The user id to get the tools for@paramfilters - The filters to apply when fetching tools@paramoptions - Optional provider options including modifiers@returnsThe wrapped tools collection@example```typescript
// Get tools from the GitHub toolkit
const tools = await composio.tools.get('default', {
  toolkits: ['github'],
  limit: 10
});

// Get tools with search
const searchTools = await composio.tools.get('default', {
  search: 'user',
  limit: 10
});

// Get a specific tool by slug
const hackerNewsUserTool = await composio.tools.get('default', 'HACKERNEWS_GET_USER');

// Get a tool with schema modifications
const tool = await composio.tools.get('default', 'GITHUB_GET_REPOS', {
  modifySchema: (toolSlug, toolkitSlug, schema) => {
    // Customize the tool schema
    return {...schema, description: 'Custom description'};
  }
});
```
get(const userId: "user-123"userId, {
  toolkits: [string]toolkits: ["GITHUB"],
  scopes: string[]scopes: ["write:org"]
});

By search (experimental)

Find tools semantically.

# 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"]
)
// Search tools semantically
const const searchResults: OpenAiToolCollectionsearchResults = await const composio: Composio<OpenAIProvider>composio.Composio<OpenAIProvider>.tools: Tools<unknown, unknown, OpenAIProvider>
List, retrieve, and execute tools
tools.Tools<unknown, unknown, OpenAIProvider>.get<OpenAIProvider>(userId: string, filters: ToolListParams, options?: ToolOptions | undefined): Promise<OpenAiToolCollection> (+1 overload)
Get a list of tools from Composio based on filters.
This method fetches the tools from the Composio API and wraps them using the provider.
@paramuserId - The user id to get the tools for@paramfilters - The filters to apply when fetching tools@paramoptions - Optional provider options including modifiers@returnsThe wrapped tools collection@example```typescript
// Get tools from the GitHub toolkit
const tools = await composio.tools.get('default', {
  toolkits: ['github'],
  limit: 10
});

// Get tools with search
const searchTools = await composio.tools.get('default', {
  search: 'user',
  limit: 10
});

// Get a specific tool by slug
const hackerNewsUserTool = await composio.tools.get('default', 'HACKERNEWS_GET_USER');

// Get a tool with schema modifications
const tool = await composio.tools.get('default', 'GITHUB_GET_REPOS', {
  modifySchema: (toolSlug, toolkitSlug, schema) => {
    // Customize the tool schema
    return {...schema, description: 'Custom description'};
  }
});
```
get(const userId: "user-123"userId, {
  search: stringsearch: "create google calendar event"
});

// Search schemas without userId
const const searchRawTools: ToolListsearchRawTools = await const composio: Composio<OpenAIProvider>composio.Composio<OpenAIProvider>.tools: Tools<unknown, unknown, OpenAIProvider>
List, retrieve, and execute tools
tools.Tools<unknown, unknown, OpenAIProvider>.getRawComposioTools(query: ToolListParams, options?: SchemaModifierOptions): Promise<ToolList>
Lists all tools available in the Composio SDK including custom tools.

This method fetches tools from the Composio API in raw format and combines them with
any registered custom tools. The response can be filtered and modified as needed.
It provides access to the underlying tool data without provider-specific wrapping.
@paramquery - Query parameters to filter the tools (required)@paramoptions - Optional configuration for tool retrieval@paramoptions.modifySchema - Function to transform tool schemas@returnsList of tools matching the query criteria@example```typescript
// Get tools from specific toolkits
const githubTools = await composio.tools.getRawComposioTools({
  toolkits: ['github'],
  limit: 10
});

// Get specific tools by slug
const specificTools = await composio.tools.getRawComposioTools({
  tools: ['GITHUB_GET_REPOS', 'HACKERNEWS_GET_USER']
});

// Get tools from specific toolkits
const githubTools = await composio.tools.getRawComposioTools({
  toolkits: ['github'],
  limit: 10
});

// Get tools with schema transformation
const customizedTools = await composio.tools.getRawComposioTools({
  toolkits: ['github'],
  limit: 5
}, {
  modifySchema: ({ toolSlug, toolkitSlug, schema }) => {
    // Add custom properties to tool schema
    return {
      ...schema,
      customProperty: `Modified ${toolSlug} from ${toolkitSlug}`,
      tags: [...(schema.tags || []), 'customized']
    };
  }
});

// Search for tools
const searchResults = await composio.tools.getRawComposioTools({
  search: 'user management'
});

// Get tools by authentication config
const authSpecificTools = await composio.tools.getRawComposioTools({
  authConfigIds: ['auth_config_123']
});
```
getRawComposioTools({
  search: stringsearch: "create google calendar event"
});

// Search within a specific toolkit
const const toolkitSearch: OpenAiToolCollectiontoolkitSearch = await const composio: Composio<OpenAIProvider>composio.Composio<OpenAIProvider>.tools: Tools<unknown, unknown, OpenAIProvider>
List, retrieve, and execute tools
tools.Tools<unknown, unknown, OpenAIProvider>.get<OpenAIProvider>(userId: string, filters: ToolListParams, options?: ToolOptions | undefined): Promise<OpenAiToolCollection> (+1 overload)
Get a list of tools from Composio based on filters.
This method fetches the tools from the Composio API and wraps them using the provider.
@paramuserId - The user id to get the tools for@paramfilters - The filters to apply when fetching tools@paramoptions - Optional provider options including modifiers@returnsThe wrapped tools collection@example```typescript
// Get tools from the GitHub toolkit
const tools = await composio.tools.get('default', {
  toolkits: ['github'],
  limit: 10
});

// Get tools with search
const searchTools = await composio.tools.get('default', {
  search: 'user',
  limit: 10
});

// Get a specific tool by slug
const hackerNewsUserTool = await composio.tools.get('default', 'HACKERNEWS_GET_USER');

// Get a tool with schema modifications
const tool = await composio.tools.get('default', 'GITHUB_GET_REPOS', {
  modifySchema: (toolSlug, toolkitSlug, schema) => {
    // Customize the tool schema
    return {...schema, description: 'Custom description'};
  }
});
```
get(const userId: "user-123"userId, {
  search?: string | undefinedsearch: "star a repository",
  toolkits: [string]toolkits: ["GITHUB"]
});

// Search toolkit schemas without userId
const const toolkitSearchRaw: ToolListtoolkitSearchRaw = await const composio: Composio<OpenAIProvider>composio.Composio<OpenAIProvider>.tools: Tools<unknown, unknown, OpenAIProvider>
List, retrieve, and execute tools
tools.Tools<unknown, unknown, OpenAIProvider>.getRawComposioTools(query: ToolListParams, options?: SchemaModifierOptions): Promise<ToolList>
Lists all tools available in the Composio SDK including custom tools.

This method fetches tools from the Composio API in raw format and combines them with
any registered custom tools. The response can be filtered and modified as needed.
It provides access to the underlying tool data without provider-specific wrapping.
@paramquery - Query parameters to filter the tools (required)@paramoptions - Optional configuration for tool retrieval@paramoptions.modifySchema - Function to transform tool schemas@returnsList of tools matching the query criteria@example```typescript
// Get tools from specific toolkits
const githubTools = await composio.tools.getRawComposioTools({
  toolkits: ['github'],
  limit: 10
});

// Get specific tools by slug
const specificTools = await composio.tools.getRawComposioTools({
  tools: ['GITHUB_GET_REPOS', 'HACKERNEWS_GET_USER']
});

// Get tools from specific toolkits
const githubTools = await composio.tools.getRawComposioTools({
  toolkits: ['github'],
  limit: 10
});

// Get tools with schema transformation
const customizedTools = await composio.tools.getRawComposioTools({
  toolkits: ['github'],
  limit: 5
}, {
  modifySchema: ({ toolSlug, toolkitSlug, schema }) => {
    // Add custom properties to tool schema
    return {
      ...schema,
      customProperty: `Modified ${toolSlug} from ${toolkitSlug}`,
      tags: [...(schema.tags || []), 'customized']
    };
  }
});

// Search for tools
const searchResults = await composio.tools.getRawComposioTools({
  search: 'user management'
});

// Get tools by authentication config
const authSpecificTools = await composio.tools.getRawComposioTools({
  authConfigIds: ['auth_config_123']
});
```
getRawComposioTools({
  search?: string | undefinedsearch: "star a repository",
  toolkits: [string]toolkits: ["GITHUB"]
});

Use specific toolkit versions in production to prevent breaking changes. See toolkit versioning.

On this page

Basic usageTool schemasFiltering toolsBy toolkitBy nameBy scopesBy search (experimental)