feat(tags): add delete_tag_definition + document track/tag probe findings

[arapov]

Summary

Acts on the post-v1.6.6 connector-gap audit — but only after a wire-trace probe (scripts/wire-trace-v167.ts) graded each proposed tool buildable-or-not against the live API, instead of trusting the audit's confident-but-unchecked claims.

Probe	Result	Outcome
GET /tracks	405 Method not allowed	No tenant-wide track-instance list → list_tracks NOT buildable (the audit's "highest-leverage addition" has no endpoint). Documented in NOTES §33.
DELETE /<entity>/tags/{id}	204, gone tenant-wide on re-read	Tag definitions ARE deletable → ships delete_tag_definition

The audit had also flagged "no people-at-org lookup" and "no party-type filter" as gaps — both already exist (list_employees, filter_parties type), and team-membership / custom-field-read-depth are hard Capsule API limits. So this one tool is the entire actionable surface from the audit.

delete_tag_definition

• Write, destructive, confirm-gated. Schema {entity, tagId, confirm: true} — entity selects the tag namespace (parties/opportunities/kases), same selector as add_tag / list_tags.
• Handler: DELETE /<entity>/tags/{tagId}, idempotent on 404 (alreadyDeleted: true), invalidates the list_tags cache, explicit confirm guard for direct callers (mirrors defineDelete).
• Annotation: delete_ prefix auto-applies destructiveHint via inferAnnotations — no register-tool.ts change.
• Distinct from remove_tag_by_id: that DETACHES a tag from one record (definition survives); this removes the definition from the namespace and from every record that shared it. The description spells out that blast radius; the confirm gate guards it.

Test plan

• 529 → 536 tests (+7 in tags.test.ts): per-entity DELETE path, idempotent 404, confirm-false/missing schema rejection, unknown-entity rejection, direct-call confirm guard
• mcp-integration.test.ts: catalog 87 → 88, present in writes / absent in read-only (delete_ prefix → hidden in read-only mode)
• tool-annotations.test.ts: destructive 7 → 8, total 88, aggregate buckets re-balanced (49 read / 8 destructive / 31 routine)
• Typecheck / lint / format:check / build clean
• Tool-count + bundle figures synced across README / DEPLOY / DESIGN / HOWTO / bundle-shape canary (some were stale from earlier un-synced merges)
• Privacy sweep clean — probe-run record ids exist only at runtime, never committed

Notes

• scripts/wire-trace-v167.ts ships for re-runnability (same ZZZ-* throwaway + cleanup pattern as v164–v166). Its probe-2 run was fully clean — the throwaway tag was created, deleted via the endpoint under test, and confirmed gone; nothing stranded.

🤖 Generated with Claude Code