Add a single tool to one of this repo's existing MCP servers (google-docs, google-sheets, google-calendar, google-gmail, google-drive, clickup, slack, etc.). Wires the addTool block into src/<provider>/server.ts using the canonical pattern (Zod params, UserError handling, log.info breadcrumb, getXClient helper), classifies the tool as read or write in e2e/tools.ts, bumps the CLAUDE.md tool count, and optionally chains to /add-e2e-test to scaffold the smoke test. This skill is the single source of truth for the tool shape used across the codebase — use it whenever the user wants to add, create, or wire up a new MCP tool, action, endpoint, or operation, even when phrased indirectly ("expose X to Claude", "I want a tool that does Y"). Also use when invoked as `/add-mcp-tool <toolName> [provider]`.
95%
Does it follow best practices?
Run evals on this skill
Adds up to 20 points to the overall score
Passed
No findings from the security scan
Add one tool to an existing MCP server. The skill exists because tool addition is the most common ongoing change in this repo (43+ tools across the providers) and the work touches several files that need to stay in sync.
For the tool's actual shape, the canonical pattern lives in references/tool-pattern.md. That document explains why each part is there; this SKILL.md is the procedure for inserting it.
<toolName> (required): camelCase, verb-first, e.g. archiveEvent, listFiles. Should not collide with an existing tool in the target server.[provider] (optional): which MCP server to add to. One of google-docs, google-sheets, google-calendar, google-gmail, google-drive, clickup, slack, etc. If omitted, ask. If the user is currently editing one of the server files, default to that provider.If <toolName> is missing, ask.
If the provider wasn't given:
src/<provider>/server.ts, use that.Confirm the file exists at src/<provider>/server.ts. If not, abort and suggest the user run /add-mcp-server first to scaffold the server.
Grep src/<provider>/server.ts for name: '<toolName>'. If present, abort — silently shadowing an existing tool is the worst-case outcome; both addTool blocks register and the second wins, but the first stays in source as dead code that future readers will edit by accident.
Use one AskUserQuestion call to collect:
Description: one-line, action-first. The LLM uses it to pick the tool, so be concrete.
Read or write — mark every tool; never leave it unannotated. Three cases:
annotations: { readOnlyHint: true }, goes in READ_TOOLS.annotations: { readOnlyHint: false }, goes in WRITE_TOOLS.annotations: { readOnlyHint: false, destructiveHint: true }, goes in WRITE_TOOLS.Do this automatically from the tool's verb/effect — infer the class from the name and the API call and apply the matching annotation without prompting; only ask the user when it's genuinely ambiguous (rule of thumb from references/tool-pattern.md: anything that changes state in the user's account is write; anything that removes/overwrites data is destructive). Getting it wrong has runbook consequences (the e2e readonly connector unchecks WRITE_TOOLS), and omitting the annotation entirely — the old advice — leaves the tool un-flagged to the MCP client and inconsistent with the other 40+ tools, so it's never correct.
Parameters: name + type + required/optional + one-line description for each. Reuse shared Zod fragments from src/types.ts where they exist (DocumentIdParameter, RangeParameters, TextStyleParameters, etc.).
For Google providers also confirm which session.google<X> client this tool needs (usually obvious from the SDK call). For third-party providers, the client is whatever get<X>Client returns in that server file.
Read references/tool-pattern.md before generating. The non-obvious conventions live there — log.info breadcrumb shape, the UserError mapping for 403, response formatting style. Don't skip this step even if the tool feels simple — the value of the skill is consistency with the existing 40+ tools.
Use one of:
assets/templates/google-tool.ts.tmpl for Google-API tools.assets/templates/third-party-tool.ts.tmpl for clickup / slack / future third-party servers.Substitute the placeholders ({{toolName}}, {{description}}, {{zodFields}}, {{executeBody}}, {{readOnlyAnnotationLine}}, etc.). For {{executeBody}}, write the actual API call; pattern-match against an existing tool in the same server file to get the SDK call right.
Fill {{readOnlyAnnotationLine}} from the step-3 classification — always emit a line, never leave it empty:
annotations: { readOnlyHint: true },annotations: { readOnlyHint: false },annotations: { readOnlyHint: false, destructiveHint: true },Tools tend to be grouped by category in each server file (read tools together, write tools together; sometimes tiered as in clickup's Tier 1: Core Navigation block). Drop the new tool at the end of the matching group, not at the bottom of the file — keeping related tools adjacent makes future readers' job easier.
If the file has no obvious grouping, append at the end of the existing addTool calls, right before the module exports.
e2e/tools.tsPush the tool name into either READ_TOOLS or WRITE_TOOLS depending on the classification from step 3. The arrays are as const tuples — order doesn't change behavior but match the alphabetical-ish grouping that's already there.
If the new tool isn't fully implemented (e.g. you scaffolded params + executes a placeholder), also add it to the NOT_IMPLEMENTED set so the e2e harness skips it.
src/<provider>/CLAUDE.md (only if there is something to say)Do not bump any tool count — docs/MCP_TOOLS.md is generated and authoritative. If the tool has a limitation, an upstream quirk, or a guard someone could undo by accident, add one terse bullet to the provider's nested src/<provider>/CLAUDE.md (create it if absent, and add it to the index in the root CLAUDE.md): the rule plus a one-clause reason. Keep investigation history out of it — that belongs in the commit message. Only a rule that applies across services goes in the root CLAUDE.md.
End the procedure with:
The tool is wired in. Want me to follow up with:
- Smoke test —
/add-e2e-test <toolName>- OpenAPI spec —
/update-openapi <provider>- Both
- Neither (do later)
If the user picks the smoke test, follow ../add-e2e-test/SKILL.md with <toolName> as the input. If they pick the OpenAPI update, follow ../update-openapi/SKILL.md with <provider> as the input. Both → do the smoke test first (more interactive, asks more questions), then OpenAPI (more mechanical, mostly auto-scaffolds).
Skip the OpenAPI option entirely when the provider has no OpenAPI file (currently Slack). In that case revert to the single offer:
The tool is wired in. Want me to scaffold the smoke test now? I'll invoke
/add-e2e-test <toolName>.
Both are soft chains rather than auto-execution because each surfaces its own questions — the e2e test scaffold asks about fixtures and special cases, the OpenAPI update asks the user to confirm HTTP method and path for non-obvious cases. Better to handle them deliberately than rush at the tail of adding a tool.
Run npm run typecheck. Surface any errors. Common failure modes:
UserError or a type from googleapis).args.getXClient doesn't exist on the server file yet — the user is adding the first tool that needs a new helper, which means they should add the helper too (see references/tool-pattern.md for the shape).Added <toolName> to src/<provider>/server.ts
Read/write: <read | write>
Parameters: <count>
Updated:
e2e/tools.ts (added to <READ_TOOLS | WRITE_TOOLS>)
src/<provider>/CLAUDE.md (<added note | no change>)
Typecheck: <pass | N errors>
Next:
/add-e2e-test <toolName> ← scaffolds the smoke test
/update-openapi <provider> ← syncs the REST surface (omit if no OpenAPI file)
npm run typecheck ← if not run automatically/add-mcp-server <slug> first..describe() — fail loudly; the LLM uses descriptions to fill arguments and a missing description silently degrades quality.delete* registered as read-only) — flag with one question before continuing. Better to interrupt than misclassify.add-mcp-tool/
├── SKILL.md
├── references/
│ └── tool-pattern.md ← canonical FastMCP tool shape; shared with add-mcp-server
└── assets/
└── templates/
├── google-tool.ts.tmpl
└── third-party-tool.ts.tmpladd-mcp-server scaffolds the server file with one example tool. It references references/tool-pattern.md from this skill as the canonical shape for that example, so both skills produce identical tool shapes.add-e2e-test scaffolds the smoke test. Step 9 above offers to chain into it.update-openapi syncs the REST/OpenAPI surface. Step 9 above offers to chain into it for providers that have an OpenAPI file. Skip the offer for providers that don't (Slack today; new third-party MCPs until someone deliberately creates the spec).boarlabsxyz/awesome-mcp
85cee7a
If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.