Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

next
mdx 186 lines 6.6 KB
Raw
1 ---
2 title: "Tools"
3 description: "Tools class definition This class is used to manage tools in the Composio SDK. It provides methods to list, get, and execute tools. Generic Param..."
4 ---
5
6 ## Methods
7
8 ### get_raw_composio_tool_by_slug()
9
10 Returns schema for the given tool slug.
11
12 ```python
13 def get_raw_composio_tool_by_slug(slug: str) -> Tool
14 ```
15
16 **Parameters**
17
18 | Name | Type |
19 |------|------|
20 | `slug` | `str` |
21
22 **Returns**
23
24 `Tool`
25
26 **Raises**
27
28 - `ToolNotFoundError` — when the backend reports the slug as unknown (404, or 400 for a malformed slug). Any other client error, such as an invalid API key, is re-raised unchanged.
29
30 ---
31
32 ### get_raw_composio_tools()
33
34 Get a list of tool schemas based on the provided filters.
35
36 ```python
37 def get_raw_composio_tools(tools: list[str] | None = ..., search: str | None = ..., toolkits: list[str] | None = ..., scopes: List[str] | None = ..., limit: int | None = ...) -> list[Tool]
38 ```
39
40 **Parameters**
41
42 | Name | Type |
43 |------|------|
44 | `tools?` | `list[str] \| None` |
45 | `search?` | `str \| None` |
46 | `toolkits?` | `list[str] \| None` |
47 | `scopes?` | `List[str] \| None` |
48 | `limit?` | `int \| None` |
49
50 **Returns**
51
52 `list[Tool]`
53
54 ---
55
56 ### get_raw_tool_router_meta_tools()
57
58 Fetches the tools exposed by a tool router session. This method fetches helper/meta tools and any preloaded app tools from the Composio API and transforms them to the expected format. It provides access to the underlying tool data without provider-specific wrapping.
59
60 ```python
61 def get_raw_tool_router_meta_tools(session_id: str, modifiers: 'Modifiers' | None = ...) -> list[Tool]
62 ```
63
64 **Parameters**
65
66 | Name | Type | Description |
67 |------|------|-------------|
68 | `session_id` | `str` | The session ID to get the meta tools for |
69 | `modifiers?` | `'Modifiers' \| None` | Optional modifiers to apply to the tool schemas |
70
71 **Returns**
72
73 `list[Tool]` — The list of meta tools
74
75 **Example**
76
77 ```python
78 from composio import Composio
79
80 composio = Composio()
81 tools_model = composio.tools
82
83 # Get meta tools for a session
84 meta_tools = tools_model.get_raw_tool_router_meta_tools("session_123")
85 print(meta_tools)
86
87 # Get meta tools with schema modifiers
88 from composio.core.models import schema_modifier
89
90 @schema_modifier
91 def modify_schema(tool: str, toolkit: str, schema):
92 # Customize the schema
93 schema.description = f"Modified: {schema.description}"
94 return schema
95
96 meta_tools = tools_model.get_raw_tool_router_meta_tools(
97 "session_123",
98 modifiers=[modify_schema]
99 )
100 ```
101
102 ---
103
104 ### get()
105
106 Get a tool or list of tools based on the provided arguments. The return type is automatically inferred based on the provider's generic parameters. For example: - OpenAIProvider -> list[ChatCompletionToolParam] - AnthropicProvider -> list[ToolParam] - CustomProvider[MyTool, list[MyTool]] -> list[MyTool]
107
108 ```python
109 def get(user_id: str, *, slug: str | None = ..., tools: list[str] | None = ..., search: str | None = ..., toolkits: list[str] | None = ..., scopes: List[str] | None = ..., modifiers: Modifiers | None = ..., limit: int | None = ...) -> TToolCollection
110 ```
111
112 **Parameters**
113
114 | Name | Type | Description |
115 |------|------|-------------|
116 | `user_id` | `str` | The user ID to get tools for. |
117 | `slug?` | `str \| None` | Get a single tool by slug. |
118 | `tools?` | `list[str] \| None` | Get tools by a list of tool slugs. |
119 | `search?` | `str \| None` | Search tools by search term. |
120 | `toolkits?` | `list[str] \| None` | Get tools from specific toolkits. |
121 | `scopes?` | `List[str] \| None` | Filter by scopes. |
122 | `modifiers?` | `Modifiers \| None` | Optional modifiers to apply. |
123 | `limit?` | `int \| None` | Limit the number of tools returned. |
124
125 **Returns**
126
127 `TToolCollection` — Provider-specific tool collection (TToolCollection).
128
129 ---
130
131 ### execute()
132
133 Execute a tool with the provided parameters. This method calls the Composio API to execute the tool and returns the response.
134
135 ```python
136 def execute(slug: str, arguments: Dict, *, connected_account_id: str | None = ..., custom_auth_params: tool_execute_params.CustomAuthParams | None = ..., custom_connection_data: tool_execute_params.CustomConnectionData | None = ..., user_id: str | None = ..., text: str | None = ..., version: str | None = ..., dangerously_skip_version_check: bool | None = ..., modifiers: Modifiers | None = ...) -> ToolExecutionResponse
137 ```
138
139 **Parameters**
140
141 | Name | Type | Description |
142 |------|------|-------------|
143 | `slug` | `str` | The slug of the tool to execute. |
144 | `arguments` | `Dict` | The arguments to pass to the tool. |
145 | `connected_account_id?` | `str \| None` | The connected account ID, or `instant_account` to explicitly use the Composio Instant account. |
146 | `custom_auth_params?` | `tool_execute_params.CustomAuthParams \| None` | The custom auth params to use for the tool. |
147 | `custom_connection_data?` | `tool_execute_params.CustomConnectionData \| None` | The custom connection data to use for the tool, takes priority over custom_auth_params. |
148 | `user_id?` | `str \| None` | The ID of the user to execute the tool for. |
149 | `text?` | `str \| None` | The text to pass to the tool. |
150 | `version?` | `str \| None` | The version of the tool to execute (overrides the SDK-level toolkit versions for this execution). |
151 | `dangerously_skip_version_check?` | `bool \| None` | Skip the version check for 'latest' version. This might cause unexpected behavior when new versions are released. |
152 | `modifiers?` | `Modifiers \| None` | The modifiers to apply to the tool (include `@before_file_upload` for file path hooks). |
153
154 **Returns**
155
156 `ToolExecutionResponse` — The response from the tool.
157
158 ---
159
160 ### proxy()
161
162 Proxy a tool call to the Composio API. `user_id` is the user the connected account belongs to. Projects with 2FA enabled check it against the connected account and may require it.
163
164 ```python
165 def proxy(endpoint: str, method: Literal['GET', 'POST', 'PUT', 'DELETE', 'PATCH', 'HEAD'], body: object | None = ..., connected_account_id: str | None = ..., parameters: List[tool_proxy_params.Parameter] | None = ..., custom_connection_data: tool_proxy_params.CustomConnectionData | None = ..., user_id: str | None = ...) -> tool_proxy_response.ToolProxyResponse
166 ```
167
168 **Parameters**
169
170 | Name | Type |
171 |------|------|
172 | `endpoint` | `str` |
173 | `method` | `Literal['GET', 'POST', 'PUT', 'DELETE', 'PATCH', 'HEAD']` |
174 | `body?` | `object \| None` |
175 | `connected_account_id?` | `str \| None` |
176 | `parameters?` | `List[tool_proxy_params.Parameter] \| None` |
177 | `custom_connection_data?` | `tool_proxy_params.CustomConnectionData \| None` |
178 | `user_id?` | `str \| None` |
179
180 **Returns**
181
182 `tool_proxy_response.ToolProxyResponse`
183
184 ---
185
186 [View source](https://github.com/composiohq/composio/blob/next/python/composio/core/models/tools.py#L338)