Fetching tools and schemas
Legacy API: prefer sessions
This guide covers legacy direct-execution methods, which remain supported for existing integrations. For new integrations, use sessions to discover and fetch tools at runtime. If you need a fixed tool set, consider the direct tools preset. See Sessions vs direct execution and the migration guide.
Fetch specific tools, filter by permissions or search, and inspect schemas for type information. Tools are automatically formatted for your provider.
Not sure which toolkit covers your use case? Browse the Toolkits catalog — each toolkit page lists its tool slugs — or search by task below.
Basic usage
tools = composio.tools.get(
user_id,
toolkits=["GITHUB"]
)Returns up to 20 tools by default. Tools require a user_id because they're scoped to authenticated accounts. See User scoping 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")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 up to 20 tools by default.
limit caps the number of returned tools. It does not select the tools needed for a task or guarantee relevance order. A small limit can exclude the tool you need. For a fixed workflow, fetch explicit tool names.
TypeScript: limit and important tools
When you filter only by toolkit, the TypeScript SDK automatically requests tools marked important unless you set important: false. Supplying limit, search, or tags disables that automatic filter. To keep the important subset with a limit, pass important: true explicitly. The Python SDK does not expose this option.
# Fetch with limit for a specific user
tools = composio.tools.get(
user_id,
toolkits=["GITHUB"],
limit=5 # Return at most 5 tools
)
# Same filter but without user_id (for schemas)
raw_tools = composio.tools.get_raw_composio_tools(
toolkits=["GITHUB"],
limit=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"]
)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"]
)By search (experimental)
Search for tools with the search option. Start with short action keywords such as create event, free busy, or send email, and narrow the query with toolkits when you know the app.
Inspect the returned descriptions and input schemas before selecting a tool. Do not assume the first result is the best match or that a natural-language goal returns every relevant tool. If you get no results, shorten the query or fetch a known tool by name.
# Search tools by action keywords
tools = composio.tools.get(
user_id,
search="create event",
toolkits=["googlecalendar"]
)
# Search schemas without user_id
raw_tools = composio.tools.get_raw_composio_tools(
search="create event",
toolkits=["googlecalendar"]
)
# 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"]
)These SDK examples use latest by default. REST v3 tool endpoints default to 00000000_00; REST v3.1 tool endpoints default to latest. Pin a dated version when application code parses tool output. See toolkit versioning.
Next
Executing tools
Run tools with providers, agentic frameworks, or direct execution