Description
The server exposes roughly 180 tools. Several clusters overlap enough that choosing correctly requires loading multiple schemas and comparing them, and choosing wrong fails in ways that are not always obvious.
Examples of clusters that read as near-duplicates from the tool list alone:
readFile, readDriveFile, downloadFile, getFileInfomodifyMessage, modifyThread, batchModifyTextlistMessages, listThreads, batchGetMessages, batchGetThreadsreplaceDocumentWithMarkdown, replaceRangeWithMarkdown, appendMarkdown
This is not a request to delete functionality. Two lighter changes would help most of the cost:
-
Make the one-line descriptions disambiguating rather than merely accurate. For any tool with a near-twin, the description should lead with what distinguishes it and name the sibling to use instead, e.g. "Read a Drive file's content. For metadata only, use getFileInfo. For binary/local save, use downloadFile." Several descriptions currently describe the tool in isolation, which is exactly when the wrong one gets picked.
-
Consider merging pure variants behind a parameter where the underlying call is the same, in the way manageFilter and manageLabel already fold create/delete/get/list into one tool with an action. That pattern works well and is applied inconsistently across the rest of the surface.
Context for why this is worth weighing: in deferred-tool setups the model sees only tool names until a schema is fetched, so name-level ambiguity directly causes either a wrong call or an extra round-trip to disambiguate. The manage* naming convention makes the grouped tools easy to find. The ungrouped clusters are where the cost lands.
Environment: server 3.4.6, node v22.22.3, win32 10.0.26200, stdio transport.
Diagnostic Info
- Server version: 3.4.6
- Node version: v22.22.3
- OS: win32 10.0.26200 (x64)
- Auth status: valid
- Scopes: documents, drive, spreadsheets, script.external_request, gmail.modify, gmail.compose, gmail.send, gmail.settings.basic, gmail.settings.sharing, calendar, forms.body, forms.body.readonly, forms.responses.readonly, presentations, tasks, service.management
Description
The server exposes roughly 180 tools. Several clusters overlap enough that choosing correctly requires loading multiple schemas and comparing them, and choosing wrong fails in ways that are not always obvious.
Examples of clusters that read as near-duplicates from the tool list alone:
readFile,readDriveFile,downloadFile,getFileInfomodifyMessage,modifyThread,batchModifyTextlistMessages,listThreads,batchGetMessages,batchGetThreadsreplaceDocumentWithMarkdown,replaceRangeWithMarkdown,appendMarkdownThis is not a request to delete functionality. Two lighter changes would help most of the cost:
Make the one-line descriptions disambiguating rather than merely accurate. For any tool with a near-twin, the description should lead with what distinguishes it and name the sibling to use instead, e.g. "Read a Drive file's content. For metadata only, use
getFileInfo. For binary/local save, usedownloadFile." Several descriptions currently describe the tool in isolation, which is exactly when the wrong one gets picked.Consider merging pure variants behind a parameter where the underlying call is the same, in the way
manageFilterandmanageLabelalready fold create/delete/get/list into one tool with anaction. That pattern works well and is applied inconsistently across the rest of the surface.Context for why this is worth weighing: in deferred-tool setups the model sees only tool names until a schema is fetched, so name-level ambiguity directly causes either a wrong call or an extra round-trip to disambiguate. The
manage*naming convention makes the grouped tools easy to find. The ungrouped clusters are where the cost lands.Environment: server 3.4.6, node v22.22.3, win32 10.0.26200, stdio transport.
Diagnostic Info