Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
Mirrored from https://github.com/Camo67/composio.git
Synced Nov 21, 12:15 UTC
docs(core): fix tools getInput, proxyExecute, and execute examples
Correct the getInput JSDoc to pass the required text field, rewrite the proxyExecute example with the real flat parameter shape and explain that relative endpoints are appended to a base URL that may include a path, and show where to find the version to pin for tools.execute.
jkomyno committed
Sep 14, 2026 at 13:56 UTC
9a69683efb4dc845e9432a4d63fc7aebfa76bd6c
5 files changed
+132
-51
.changeset/tools-jsdoc-examples.md
new
+5
@@ -0,0 +1,5 @@
1
+---
2
+'@composio/core': patch
3
+---
4
+
5
+Correct the JSDoc for `tools.getInput` and `tools.proxyExecute`. The `getInput` example now passes the required `text` field and reads the generated `arguments`. The `proxyExecute` example now uses the flat `endpoint` / `method` / `connectedAccountId` shape and explains that a relative endpoint is appended to the toolkit's base URL, which can already include a path. The `tools.execute` example shows where to find the version to pin.
docs/content/docs/extending-sessions/proxy-execute.mdx
+4
@@ -65,6 +65,10 @@ console.log(data);
65
66
The `endpoint` is a path relative to the toolkit's base URL (`/repos/...` resolves against `api.github.com`). Pass an absolute URL only when you need a host that isn't the toolkit's standard API, such as a regional Salesforce or Zendesk domain.
67
68
+<Callout type="warn" title="Don't repeat the base URL's path">
69
+The `endpoint` is appended to the base URL, and many base URLs already include a path. Google Calendar's base URL is `https://www.googleapis.com/calendar/v3`, so pass `/users/me/calendarList`. Passing `/calendar/v3/users/me/calendarList` requests `/calendar/v3/calendar/v3/users/me/calendarList` and returns a `404`.
70
+</Callout>
71
+
72
<Callout type="warn">
73
Proxy execute rejects cross-domain requests. The `endpoint` must resolve to the same domain as the toolkit's connected account (a GitHub connection can only call `api.github.com` paths). This is an intentional security boundary, not a quota, so you can't work around it by reshaping the request.
74
</Callout>
docs/content/docs/tools-direct/executing-tools.mdx
+48
-5
@@ -212,7 +212,7 @@ If you just want to call a tool without using any framework or LLM provider, you
212
**A toolkit version is required for direct execution** — calling `tools.execute()` without one raises `ToolVersionRequiredError`, and `"latest"` alone is not accepted here. Two ways to satisfy it:
213
214
- **An LLM or agent consumes the outputs:** keep `"latest"` and pass `dangerously_skip_version_check=True` (TypeScript: `dangerouslySkipVersionCheck: true`) on the execute call — you always run the newest tools, and the flag's name is the reminder that output schemas can change between releases.
215
-- **Your code parses the outputs:** pin a dated version — look it up with `composio.toolkits.get(slug="...").meta.version` or in the [Toolkits catalog](/toolkits), and pass it at SDK initialization or per call via `version="..."`.
215
+- **Your code parses the outputs:** pin a dated version: look it up in the [Toolkits catalog](/toolkits) or from the SDK (see [Pin a version](#pin-a-version)), and pass it at SDK initialization or per call via `version`.
216
217
See [toolkit versioning](/docs/tools-direct/toolkit-versioning) for the full tradeoffs.
218
</Callout>
@@ -234,7 +234,7 @@ from composio import Composio
234
235
user_id = "user-k7334"
236
# Configure toolkit versions at SDK level for every toolkit you execute.
237
-# Use "latest", or pin a version — find them with composio.toolkits.get(slug="github").meta.available_versions
237
+# Use "latest", or pin a version (see "Pin a version" below)
238
composio = Composio(
239
api_key="your_composio_key",
240
toolkit_versions={"github": "latest"}
@@ -245,7 +245,7 @@ result = composio.tools.execute(
245
"GITHUB_LIST_STARGAZERS",
246
user_id=user_id,
247
arguments={"owner": "ComposioHQ", "repo": "composio", "page": 1, "per_page": 5},
248
- # "latest" requires this opt-in; to pin instead, pass version=composio.toolkits.get(slug="github").meta.version
248
+ # "latest" requires this opt-in; to pin instead, pass version (see "Pin a version" below)
249
dangerously_skip_version_check=True,
250
)
251
print(result)
@@ -257,7 +257,7 @@ import { Composio } from "@composio/core";
257
258
const userId = "user-k7334";
259
// Configure toolkit versions at SDK level for every toolkit you execute.
260
-// Use "latest", or pin a version — find them with (await composio.toolkits.get("github")).meta.availableVersions
260
+// Use "latest", or pin a version (see "Pin a version" below)
261
const composio = new Composio({
262
apiKey: "your_composio_key",
263
toolkitVersions: { github: "latest" }
@@ -272,7 +272,7 @@ const result = await composio.tools.execute("GITHUB_LIST_STARGAZERS", {
272
"page": 1,
273
"per_page": 5
274
},
275
- // "latest" requires this opt-in; to pin instead, pass version from (await composio.toolkits.get("github")).meta.version
275
+ // "latest" requires this opt-in; to pin instead, pass `version` (see "Pin a version" below)
276
dangerouslySkipVersionCheck: true,
277
});
278
console.log('GitHub stargazers:', JSON.stringify(result, null, 2));
@@ -280,6 +280,47 @@ console.log('GitHub stargazers:', JSON.stringify(result, null, 2));
280
</Tab>
281
</Tabs>
282
283
+### Pin a version
284
+
285
+When your code parses tool outputs, look up the current version once, then pass that dated string as `version` on every call. Hard-code the string (or keep it in config) rather than looking it up at runtime, so a new release can't change the output shape under you.
286
+
287
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
288
+ <Tab value="Python">
289
+```python
290
+from composio import Composio
291
+
292
+composio = Composio(api_key="your_composio_key")
293
+
294
+# One-off lookup: prints something like "20250909_00"
295
+print(composio.toolkits.get(slug="github").meta.version)
296
+
297
+result = composio.tools.execute(
298
+ "GITHUB_LIST_STARGAZERS",
299
+ user_id="user-k7334",
300
+ version="20250909_00",
301
+ arguments={"owner": "ComposioHQ", "repo": "composio", "page": 1, "per_page": 5},
302
+)
303
+```
304
+ </Tab>
305
+ <Tab value="TypeScript">
306
+```typescript
307
+import { Composio } from "@composio/core";
308
+
309
+const composio = new Composio({ apiKey: "your_composio_key" });
310
+
311
+// One-off lookup: prints something like "20250909_00"
312
+const tool = await composio.tools.getRawComposioToolBySlug("GITHUB_LIST_STARGAZERS");
313
+console.log(tool.version);
314
+
315
+const result = await composio.tools.execute("GITHUB_LIST_STARGAZERS", {
316
+ userId: "user-k7334",
317
+ version: "20250909_00",
318
+ arguments: { owner: "ComposioHQ", repo: "composio", page: 1, per_page: 5 },
319
+});
320
+```
321
+ </Tab>
322
+</Tabs>
323
+
324
<Callout>
325
The examples above configure toolkit versions at SDK initialization. You can also pass versions per-execution or use environment variables. See [toolkit versioning](/docs/tools-direct/toolkit-versioning) for all configuration options.
326
</Callout>
@@ -298,6 +339,8 @@ The `endpoint` can be a relative path or absolute URL. Relative paths are resolv
339
340
<Callout type="warn">
341
Prefer relative endpoints when possible. They resolve against the connected account's base URL and avoid same-domain validation issues.
342
+
343
+A relative endpoint is appended to the base URL, and many base URLs already include a path. Google Calendar's base URL is `https://www.googleapis.com/calendar/v3`, so pass `/users/me/calendarList`. Passing `/calendar/v3/users/me/calendarList` requests `/calendar/v3/calendar/v3/users/me/calendarList` and returns a `404`.
344
</Callout>
345
346
<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
docs/content/reference/sdk-reference/typescript/tools.mdx
+33
-23
@@ -44,6 +44,10 @@ async execute(slug: string, body: ToolExecuteParams, options?: ExecuteToolModifi
44
**Example**
45
46
```typescript
47
+// Look up the tool's current version once, then pin that string in your code or config
48
+const { version } = await composio.tools.getRawComposioToolBySlug('GITHUB_GET_REPOS');
49
+console.log(version); // e.g. '20250909_00'
50
+
51
const result = await composio.tools.execute('GITHUB_GET_REPOS', {
52
userId: 'default',
53
version: '20250909_00',
@@ -180,9 +184,10 @@ const emailTools = await composio.tools.get('default', {
184
185
### getInput()
186
183
-Fetches the input parameters for a given tool.
187
+Generates arguments for a tool from a natural-language description of the task.
188
185
-This method is used to get the input parameters for a tool before executing it.
189
+Composio uses an LLM to fill the tool's input parameters from `text`. Review the
190
+generated arguments before passing them to `tools.execute()`.
191
192
```typescript
193
async getInput(slug: string, body: ToolGetInputParams, requestOptions?: ComposioRequestOptions): Promise<ToolGetInputResponse>
@@ -192,22 +197,23 @@ async getInput(slug: string, body: ToolGetInputParams, requestOptions?: Composio
197
198
| Name | Type | Description |
199
|------|------|-------------|
195
-| `slug` | `string` | The ID of the tool to find input for |
196
-| `body` | `ToolGetInputParams` | The parameters to be passed to the tool |
200
+| `slug` | `string` | The slug of the tool to generate arguments for |
201
+| `body` | `ToolGetInputParams` | The generation request |
202
| `requestOptions?` | `ComposioRequestOptions` | |
203
204
**Returns**
205
201
-`Promise<ToolGetInputResponse>` — The input parameters schema for the specified tool
206
+`Promise<ToolGetInputResponse>` — The generated `arguments`, or an `error` when generation fails
207
208
**Example**
209
210
```typescript
206
-// Get input parameters for a specific tool
207
-const inputParams = await composio.tools.getInput('GITHUB_CREATE_ISSUE', {
208
- userId: 'default'
211
+const { arguments: args, error } = await composio.tools.getInput('GITHUB_CREATE_ISSUE', {
212
+ text: 'Open an issue in composiohq/composio titled "Docs typo" describing the broken link',
213
+ version: '20250909_00',
214
});
210
-console.log(inputParams.schema);
215
+if (error) throw new Error(error);
216
+console.log(args); // { owner: 'composiohq', repo: 'composio', title: 'Docs typo', ... }
217
```
218
219
---
@@ -415,10 +421,16 @@ console.log(toolsEnum.items);
421
422
### proxyExecute()
423
418
-Proxies a custom request to a toolkit/integration.
424
+Sends an HTTP request to a toolkit's API, authenticated as a connected account.
425
+
426
+Use it to call an endpoint that no predefined tool covers. Composio injects the
427
+connected account's credentials on the server side.
428
420
-This method allows sending custom requests to a specific toolkit or integration
421
-when you need more flexibility than the standard tool execution methods provide.
429
+A relative `endpoint` is appended to the toolkit's base URL, and that base URL can
430
+already include a path. Google Calendar's base URL is
431
+`https://www.googleapis.com/calendar/v3`, so pass `/users/me/calendarList`, not
432
+`/calendar/v3/users/me/calendarList` (which resolves to `/calendar/v3/calendar/v3/...`
433
+and returns a 404 from Google). An absolute URL on the same domain is sent as-is.
434
435
```typescript
436
async proxyExecute(body: ToolProxyParams, requestOptions?: ComposioRequestOptions): Promise<ToolProxyResponse>
@@ -428,26 +440,24 @@ async proxyExecute(body: ToolProxyParams, requestOptions?: ComposioRequestOption
440
441
| Name | Type | Description |
442
|------|------|-------------|
431
-| `body` | `ToolProxyParams` | The parameters for the proxy request including toolkit slug and custom data |
443
+| `body` | `ToolProxyParams` | The proxy request |
444
| `requestOptions?` | `ComposioRequestOptions` | |
445
446
**Returns**
447
436
-`Promise<ToolProxyResponse>` — The response from the proxied request
448
+`Promise<ToolProxyResponse>` — The upstream status, headers, and parsed body
449
450
**Example**
451
452
```typescript
441
-// Send a custom request to a toolkit
442
-const response = await composio.tools.proxyExecute({
443
- toolkitSlug: 'github',
444
- userId: 'default',
445
- data: {
446
- endpoint: '/repos/owner/repo/issues',
447
- method: 'GET'
448
- }
453
+// Google Calendar's base URL is https://www.googleapis.com/calendar/v3
454
+const { status, data } = await composio.tools.proxyExecute({
455
+ endpoint: '/users/me/calendarList',
456
+ method: 'GET',
457
+ connectedAccountId: 'ca_...',
458
+ parameters: [{ in: 'query', name: 'maxResults', value: 10 }],
459
});
450
-console.log(response.data);
460
+console.log(status, data);
461
```
462
463
---
ts/packages/core/src/models/Tools.ts
+42
-23
@@ -1108,6 +1108,10 @@ export class Tools<
1108
*
1109
* @example Execute with a specific version (recommended for production)
1110
* ```typescript
1111
+ * // Look up the tool's current version once, then pin that string in your code or config
1112
+ * const { version } = await composio.tools.getRawComposioToolBySlug('GITHUB_GET_REPOS');
1113
+ * console.log(version); // e.g. '20250909_00'
1114
+ *
1115
* const result = await composio.tools.execute('GITHUB_GET_REPOS', {
1116
* userId: 'default',
1117
* version: '20250909_00',
@@ -1294,21 +1298,27 @@ export class Tools<
1298
}
1299
1300
/**
1297
- * Fetches the input parameters for a given tool.
1301
+ * Generates arguments for a tool from a natural-language description of the task.
1302
*
1299
- * This method is used to get the input parameters for a tool before executing it.
1303
+ * Composio uses an LLM to fill the tool's input parameters from `text`. Review the
1304
+ * generated arguments before passing them to `tools.execute()`.
1305
*
1301
- * @param {string} slug - The ID of the tool to find input for
1302
- * @param {ToolGetInputParams} body - The parameters to be passed to the tool
1303
- * @returns {Promise<ToolGetInputResponse>} The input parameters schema for the specified tool
1306
+ * @param {string} slug - The slug of the tool to generate arguments for
1307
+ * @param {ToolGetInputParams} body - The generation request
1308
+ * @param {string} body.text - What you want the tool to do, in natural language
1309
+ * @param {string} [body.custom_description] - Extra context about the tool for the LLM
1310
+ * @param {string} [body.system_prompt] - System prompt that steers the LLM
1311
+ * @param {string} [body.version] - Tool version to generate arguments for
1312
+ * @returns {Promise<ToolGetInputResponse>} The generated `arguments`, or an `error` when generation fails
1313
*
1314
* @example
1315
* ```typescript
1307
- * // Get input parameters for a specific tool
1308
- * const inputParams = await composio.tools.getInput('GITHUB_CREATE_ISSUE', {
1309
- * userId: 'default'
1316
+ * const { arguments: args, error } = await composio.tools.getInput('GITHUB_CREATE_ISSUE', {
1317
+ * text: 'Open an issue in composiohq/composio titled "Docs typo" describing the broken link',
1318
+ * version: '20250909_00',
1319
* });
1311
- * console.log(inputParams.schema);
1320
+ * if (error) throw new Error(error);
1321
+ * console.log(args); // { owner: 'composiohq', repo: 'composio', title: 'Docs typo', ... }
1322
* ```
1323
*/
1324
async getInput(
@@ -1323,26 +1333,35 @@ export class Tools<
1333
}
1334
1335
/**
1326
- * Proxies a custom request to a toolkit/integration.
1336
+ * Sends an HTTP request to a toolkit's API, authenticated as a connected account.
1337
+ *
1338
+ * Use it to call an endpoint that no predefined tool covers. Composio injects the
1339
+ * connected account's credentials on the server side.
1340
*
1328
- * This method allows sending custom requests to a specific toolkit or integration
1329
- * when you need more flexibility than the standard tool execution methods provide.
1341
+ * A relative `endpoint` is appended to the toolkit's base URL, and that base URL can
1342
+ * already include a path. Google Calendar's base URL is
1343
+ * `https://www.googleapis.com/calendar/v3`, so pass `/users/me/calendarList`, not
1344
+ * `/calendar/v3/users/me/calendarList` (which resolves to `/calendar/v3/calendar/v3/...`
1345
+ * and returns a 404 from Google). An absolute URL on the same domain is sent as-is.
1346
*
1331
- * @param {ToolProxyParams} body - The parameters for the proxy request including toolkit slug and custom data
1332
- * @returns {Promise<ToolProxyResponse>} The response from the proxied request
1347
+ * @param {ToolProxyParams} body - The proxy request
1348
+ * @param {string} body.endpoint - Path relative to the toolkit's base URL, or an absolute URL
1349
+ * @param {'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH'} body.method - HTTP method
1350
+ * @param {string} [body.connectedAccountId] - The connected account to authenticate as
1351
+ * @param {unknown} [body.body] - JSON request body
1352
+ * @param {Array<{ in: 'query' | 'header'; name: string; value: string | number }>} [body.parameters] - Extra query parameters or headers
1353
+ * @returns {Promise<ToolProxyResponse>} The upstream status, headers, and parsed body
1354
*
1355
* @example
1356
* ```typescript
1336
- * // Send a custom request to a toolkit
1337
- * const response = await composio.tools.proxyExecute({
1338
- * toolkitSlug: 'github',
1339
- * userId: 'default',
1340
- * data: {
1341
- * endpoint: '/repos/owner/repo/issues',
1342
- * method: 'GET'
1343
- * }
1357
+ * // Google Calendar's base URL is https://www.googleapis.com/calendar/v3
1358
+ * const { status, data } = await composio.tools.proxyExecute({
1359
+ * endpoint: '/users/me/calendarList',
1360
+ * method: 'GET',
1361
+ * connectedAccountId: 'ca_...',
1362
+ * parameters: [{ in: 'query', name: 'maxResults', value: 10 }],
1363
* });
1345
- * console.log(response.data);
1364
+ * console.log(status, data);
1365
* ```
1366
*/
1367
async proxyExecute(