mcp-server-tools

When to Use

• Adding, removing or renaming an inbound MCP tool, or changing its description, arguments, annotations or scopes.
• Changing a token scope, its label or blurb, the expiry presets or the token prefix.

For a tool RedAmon's OWN agent calls (outbound, mcp/servers/), use agentic-tool-integration. For making a recon setting writable over MCP, use project-settings-cascade. The tools that exist are listed by the server itself and by the generated reference page, never by this skill.

Critical Rules

• ALWAYS run npm run docs:mcp in webapp/ after any change this skill's trigger names, and commit MCP-API-Reference.md inside the redamon.wiki repo. A main-repo commit moves only the submodule pointer. The page is rendered by apiReference.ts; a hand edit is overwritten by the next run.
• NEVER set destructiveHint: false on a tool that overwrites or aborts existing state. In the MCP spec false means only additive updates, and clients use it to decide when to ask the user first. No test checks this.
• ALWAYS add an EXAMPLE_EXTRA_ARGS entry in apiReference.ts when a tool's body requires an argument its JSON Schema marks optional. The generated example sends only schema-required arguments, and the test calls every example.
• ALWAYS give a new tool an ONBOARDING_PLAYBOOK entry and a capability area in playbook.ts. The Agent Onboarding pack is generated from the live tools/list, and a coverage test in onboarding.test.ts fails the moment a tool ships without whenToUse + gotchas, or sits in zero or two capability areas. Also decide whether any profile in profiles.ts should leansOn it; that half is editorial and is not enforced.
• A tool that reads NO backend must be added to BACKEND_FREE_TOOLS in apiReference.test.ts. That file proves a tool's declared scopes are enough by calling it and expecting the generic database failure, because every Prisma model is mocked away. A tool derived purely from constants (describe_recon_settings, list_recon_presets) SUCCEEDS instead, and would otherwise read as a failure. Do not relax the assertion; name the tool.
• When a capability flips from "cannot" to "can", sweep the old claims. Add the old claim's phrasing to STALE_CLAIMS in toolNameDrift.test.ts, and make sure every file carrying agent-facing strings is in its AGENT_FACING list: the "nothing here can mute" lines outlived the feature in server.ts and profiles.ts, which were outside it.
• Keep agent op names out of agent-facing files. TOOL_SHAPED only knows the verbs it lists, so a new tool's verb goes there; an op literal such as list_muted or mute_many in an agent-facing file then reads as an unknown tool. Wrap ops in triageGraph.ts helpers instead.
• Watch the write bucket headroom. apiReference.test.ts calls every tool with ONE token inside one test, against the write limit (10/min by default). A new write tool that overflows it must raise that test's limit, not drop a call.
• A required ARRAY argument needs an EXAMPLE_EXTRA_ARGS entry. placeholderFor has no array branch, so the generated example would name no item (mute_findings' findingIds).
• A new scope gates writes; reads go under an existing read scope. Every ScopeAccess in scopeCopy.ts is read or write except kali:exec, the one read-write scope. A tool that only reads what a write needs (get_finding_evidence for submit_finding_review) belongs under the read scope, so a read-only token can see what an agent would act on.
• Order the body's checks: requireScope first, then no McpToolError before the first backend read. The apiReference test proves declared scopes by calling each example and expecting the mocked database failure; a refusal on the example's placeholder arguments ahead of that read looks like a scope gap. A tool that STARTS something checks access (and its own caps) before it spends a rate token, so a refused start costs the caller nothing.
• Free text a caller writes goes in UNAUDITED_ARGS in server.ts. auditDetail copies every other string argument into the audit row, which also prints as a console line; a quote is target text, and a reason is recorded, better, by the tool that owns it.