---
summary: "disabledTool() wrapper for feature-flagged tools (#96); landing page gains an `unspecified` mutability bucket so unannotated tools no longer infer as `write` (#92); skill-versioning policy in CLAUDE.md/AGENTS.md with 7 retroactive bumps (#98)."
breaking: false
---

# 0.8.11 — 2026-05-02

Three small surface changes plus a documentation policy. The framework gains a `disabledTool()` wrapper for feature-gated definitions; the HTTP landing page renders unannotated tools honestly as `unspecified` instead of inferring them into the `write` bucket; the skill-version-bump rule that the `maintenance` skill's Phase A relies on now lives in the agent-instruction files. No consumer code changes required.

## Added

- **`disabledTool(def, meta)` wrapper** — new `@cyanheads/mcp-ts-core/tools` export (also re-exported from the framework root). Marks a tool definition as present-in-manifest but skipped at MCP registration so `tools/list` clients can't invoke it while operators reading `/.well-known/mcp.json` and the HTML landing page still see the gated tool with an operator-facing `reason`, optional `hint`, and optional `since`. Public `ToolDefinition` interface and the `tool()` builder are untouched — the wrapper attaches an internal `__mcpDisabled` field that only `ToolRegistry` and `buildServerManifest()` read. ([#96](https://github.com/cyanheads/mcp-ts-core/issues/96))
- **`DisabledMetadata` type** — `{ reason: string; hint?: string; since?: string }`. Re-exported from `@cyanheads/mcp-ts-core` and `/tools`.
- **`ManifestTool.disabled`** — optional `DisabledMetadata` field threaded through `buildServerManifest()`. Surfaces in `/.well-known/mcp.json` `definitions.tools` for discovery agents that need to know a tool is gated without invoking it.
- **Landing page `disabled` bucket** — new fourth bucket rendered after `read | unspecified | write | destructive`. Cards use a muted dashed-border variant (`tool-card--disabled`), replace the invocation `<details>` with a callout containing reason + optional hint + optional `since`, and keep the schema preview so operators can still read the tool's contract. Companion "would be `<mutability>`" pill surfaces the underlying classification, suppressed when underlying is `unspecified`.
- **Landing page `unspecified` bucket** — new third bucket between `read` and `write`. Pills, chip, and card spine use muted/italic styling to read as indeterminate, distinct from the `write` bucket's deliberate-mutation signal. ([#92](https://github.com/cyanheads/mcp-ts-core/issues/92))

## Changed

- **`classifyMutability()` rewritten** to render only what the author declared: `destructiveHint === true` → `destructive`; `readOnlyHint === true` → `read`; `readOnlyHint === false` → `write` (deliberate claim); neither set → `unspecified`. Previously, annotation-less tools fell back to `write`, falsely claiming mutation that the author never declared. ([#92](https://github.com/cyanheads/mcp-ts-core/issues/92))
- **Filter chip / group order** — `read → unspecified → write → destructive → disabled`. Safety-ascending, with operator-context bucket last.
- **`ToolRegistry.registerAll()`** logs disabled tools at debug level and surfaces `(N disabled, skipped)` in the registration summary so operators see the gate without parsing per-tool log lines.
- **`add-tool` skill** (2.5 → 2.6) — new "Feature-flagged tools (`disabledTool` wrapper)" subsection with a three-tool-listings table contrasting `tools/list`, Server Card, and landing-page coverage.
- **`AGENTS.md` / `CLAUDE.md`** — new `### Skill versioning` subsection under `## API Quick References` documenting the `metadata.version` field that the downstream `maintenance` skill's Phase A reads, plus the bump policy: change a SKILL.md body, bump the version in the same edit; pure typo/whitespace edits exempt; one bump per release cycle is sufficient. ([#98](https://github.com/cyanheads/mcp-ts-core/issues/98))
- **Skill version bumps** — retroactive bumps for skills changed in 0.8.9/0.8.10 without bumps: `add-tool` (2.5), `api-config` (1.3), `api-workers` (1.2), `design-mcp-server` (2.9), `report-issue-framework` (1.5), `report-issue-local` (1.4), `security-pass` (1.3). Backstops the upcoming linter enforcement filed at [#99](https://github.com/cyanheads/mcp-ts-core/issues/99).
