Fetching and Filtering Tools

To effectively use tools, it is recommended to fetch, inspect, and filter them based on your criteria.

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.

1
tools = composio.tools.get(
2
    user_id,
3
    toolkits=["GITHUB", "HACKERNEWS"],
4
)

Limiting the results

Multiple toolkits have 100s of tools. These can easily overwhelm the LLM. Hence, the SDK allows you to limit the number of tools returned.

The default limit is 20 — meaning you get the top 20 important tools from the toolkit.

1
tools = composio.tools.get(
2
    user_id,
3
    toolkits=["GITHUB"],
4
    limit=5,  # Returns the top 5 important tools from the toolkit
5
)

Filtering by scopes

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

1
# Get GitHub tools that require specific scopes
2
tools = composio.tools.get(
3
    user_id,
4
    toolkits=["GITHUB"],
5
    scopes=["repo"],  # Only get tools requiring these scopes
6
    limit=10
7
)

Filtering by tool

You may specify the list of tools to fetch by directly providing the tool names. Browse the list of tools here to view and inspect the tools for each toolkit.

1
tools = composio.tools.get(
2
    user_id,
3
    tools=[
4
        "GITHUB_CREATE_AN_ISSUE",
5
        "GITHUB_CREATE_AN_ISSUE_COMMENT",
6
        "GITHUB_CREATE_A_COMMIT",
7
    ],
8
)

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.

1
tool = composio.tools.get_raw_composio_tool_by_slug("HACKERNEWS_GET_LATEST_POSTS")
2
3
print(tool.model_dump_json())

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.

This step runs a semantic search on the tool names and descriptions and returns the most relevant tools.

1
tools = composio.tools.get(
2
    user_id,
3
    search="hubspot organize contacts",
4
)
5
6
# Search within a specific toolkit
7
tools = composio.tools.get(
8
    user_id,
9
    search="repository issues",
10
    toolkits=["GITHUB"],  # Optional: limit search to specific toolkit
11
    limit=5  # Optional: limit number of results
12
)

Filter Combinations

When fetching tools, you must use one of these filter combinations:

1. Tools Only: Fetch specific tools by their slugs

   1
   { tools: ["TOOL_1", "TOOL_2"] }

2. Toolkits Only: Fetch tools from specific toolkits

   1
   { toolkits: ["TOOLKIT_1", "TOOLKIT_2"], limit?: number }

3. Single Toolkit with Scopes: Fetch tools requiring specific OAuth scopes

   1
   { toolkits: ["GITHUB"], scopes: ["read:repo"], limit?: number }

4. Search: Search across all tools or within specific toolkits

   1
   { search: "query", toolkits?: string[], limit?: number }

These combinations are mutually exclusive - you can’t mix tools with search or use scopes with multiple toolkits.