Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
docs: shorten how tools are tagged and expand the tag table
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Mukund committed
Oct 15, 2026 at 17:41 UTC
9f54451ef60916202da831a5a0f1f2eecc63dcbc
1 file changed
+6
-15
docs/content/docs/tool-tags.mdx
+6
-15
@@ -10,27 +10,18 @@ Every tool has a **tag** that describes the action it takes: reading, creating,
10
11
| Tag | The tool | For example |
12
| --- | --- | --- |
13
-| `readOnlyHint` | Reads data and changes nothing | Fetch emails, list pull requests, export a report |
14
-| `createHint` | Adds something new | Send an email, create an issue |
15
-| `updateHint` | Changes something that already exists | Edit an issue, rename a file |
16
-| `destructiveHint` | Deletes something | Delete a file, delete a repository |
13
+| `readOnlyHint` | Reads data without changing anything. This includes tools that search, list, compute or export data. | Fetch emails, list pull requests, export a report |
14
+| `createHint` | Adds something new, such as a message, record or file. It doesn't change anything that already exists. | Send an email, create an issue |
15
+| `updateHint` | Changes something that already exists, such as its content or settings. It doesn't delete anything. | Edit an issue, rename a file |
16
+| `destructiveHint` | Deletes something, such as a file, record or repository. A tool that can delete something has this tag, even if it also creates or updates. | Delete a file, delete a repository |
17
18
## How tools are tagged
19
20
-Composio tags each tool with the most severe action it can take. A tool that can delete something is tagged `destructiveHint`, even if it also updates. A tool that changes something that already exists is tagged `updateHint`. A tool that only adds something new is tagged `createHint`. Every other tool is tagged `readOnlyHint`.
21
-
22
-A tool's tag reflects what changes for the user, not the HTTP method of the API behind it:
23
-
24
-- A tool that sends a search query with `POST` and returns results is `readOnlyHint`.
25
-- A tool that cancels or resets something with `GET` is `updateHint` or `destructiveHint`.
26
-- A tool that computes, converts, summarizes or exports data without changing anything is `readOnlyHint`.
27
-- A tool that adds an item to a list or folder is `createHint`.
28
-
29
-In MCP toolkits, such as `granola_mcp` and [custom MCP toolkits](/docs/extending-sessions/custom-mcp), `readOnlyHint` comes from the MCP server's tool annotations, and Composio tags the server's other tools when the toolkit syncs.
20
+Composio tags tools on a best-effort basis, based on each tool's description and behavior. For MCP tools, Composio infers the tag from the tool's description and the hints the MCP server provides.
21
22
## Viewing a tool's tags
23
33
-[Get a tool](/reference/api-reference/tools/getToolsByToolSlug) returns its tags in the `tags` field. Pass `version=latest` to see the tags a session uses.
24
+[Get a tool](/reference/api-reference/tools/getToolsByToolSlug) returns a tool's tags in the `tags` field.
25
26
## Using tags in a session
27