fix(tools): correct download_attachment annotation; complete parameter descriptions#21
Merged
Conversation
… descriptions Improves MCP tool-description quality (the dimensions Glama grades). - download_attachment was annotated readOnlyHint:true but WRITES to disk when saveTo is set. Corrected to readOnlyHint:false (destructiveHint:false, idempotentHint:true) and clarified in the description that inline calls are read-only while saveTo is the only side effect. Matters for agent auto-approval — a tool that can write must not advertise as read-only. - Added per-parameter .describe() to the 6 tools whose params previously reached the wire with no descriptions: count_messages, folder_stats, delete_thread, flag_thread, bulk_update_flags, bulk_update_labels. Covers syntax (flag formats \Seen vs bare keywords; label paths must start with Labels/), constraints (uids XOR match; at least one of add/remove), and when-to-use guidance (single vs bulk vs thread; dryRun first). Verified via a listTools probe: all 31 registered tools now emit a description for every parameter (list_folders has 0 params). build, lint, format:check, and 366 tests pass. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…egation tools Follow-up to the prior commit, which missed several tools whose old-string edits silently failed. A listTools probe now confirms ALL 31 registered tools emit a description for every parameter (was: bulk_update_flags 0/6, bulk_update_labels 0/6, bulk_delete 3/6, top_senders 1/6, move_thread 1/4). Covers: uids XOR match constraint, flag/label syntax, dryRun-first guidance, date-range and scanLimit semantics on top_senders, and acrossFolders behavior on move_thread. Verified: probe shows full coverage; build, format:check, and 366 tests pass. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
sethbang
added a commit
that referenced
this pull request
May 30, 2026
Release the download_attachment annotation fix and complete tool-parameter descriptions (#21). Bumps every version reference for consistency, including two that had drifted: - package.json 1.0.1 -> 1.0.2 - package-lock.json (top-level + root package entry) 1.0.0 -> 1.0.2 (was never bumped for 1.0.1) - server.json top-level + npm package entry 1.0.1 -> 1.0.2 - src/index.ts McpServer({version}) 1.0.0 -> 1.0.2 (the server had been reporting 1.0.0 over MCP regardless of the published version) build, lint, format:check, and 366 tests pass. Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Lifts the MCP tool-description quality that Glama grades, and fixes one real annotation bug.
Bug:
download_attachmentannotationWas
readOnlyHint: truebut the tool writes to disk whensaveTois set (fs.writeFile). Corrected toreadOnlyHint: false(destructiveHint: false,idempotentHint: true) and clarified the description (inline = read-only;saveTois the only side effect). This matters for agent auto-approval — a tool that can write must not advertise read-only.Parameter descriptions
A
listToolsprobe showed 6 tools emitting parameters with no descriptions (the "0% schema coverage" Glama flagged). Added per-field.describe()to:count_messages,folder_stats,delete_thread,flag_thread,bulk_update_flags,bulk_update_labels.Descriptions cover syntax (flag formats
\Seenvs bare keywords; label paths must start withLabels/), constraints (uidsXORmatch; at least one of add/remove non-empty), and when-to-use guidance (single vs bulk vs thread; rundryRunfirst).The other ~25 tools already had full descriptions — left untouched.
Verification
listToolsprobe: all 31 registered tools now emit a description for every parameter (list_foldershas 0 params).npm run build,npm run lint,npm run format:check, and 366 tests all pass.Follow-up (not in this PR)
After merge, cut a release (tag
vX.Y.Z→publish.ymlships to npm with provenance) and re-trigger Glama's scan — grades reflect the scanned npm artifact, so they won't move until a new version is published.🤖 Generated with Claude Code