@W-23375797: consolidate admin-gated tools into polymorphic dispatchers

[Akash-Rastogi]

[Akash's agent]

Description

Introduces two new polymorphic MCP tools to reduce the model-visible admin tool
surface, while preserving every existing behavior end-to-end during a shim
window:

New tool	Discriminator	Merges (still wired as legacy)
query-admin-insights	kind	get-stale-workbooks, get-stale-datasources, get-content-usage-metrics, get-user-activity
delete-content	resourceType	delete-workbook, delete-datasource, delete-extract-refresh-task

Motivation and Context

The admin-gated set has grown to the point where its model-visible tool count
crowds the model's decision space and inflates prompt-time tool schemas.
W-23375797 targets two consolidations that each collapse a family of
same-shape tools behind one dispatcher, so the model reasons about one entry
per capability instead of one per (capability × resource kind).

Both consolidations are additive: the legacy tools remain wired and continue
to function unchanged during the migration window.

Design highlights

query-admin-insights

• One paramsSchema with a kind discriminator; dispatches to the same
  underlying admin-insights resolver as the legacy readers.
• Returns the same payload shape as the corresponding legacy tool for each
  kind, so downstream consumers reading stale_workbooks / user_activity
  data need no changes.

delete-content

• Polymorphic destructive tool; preserves the two-phase preview→confirm flow
  and routes through guardMutation() — admin gate, evidence gate, audit
  record.
• mcp-apps flag ON (HITL panel flow): preview records
  AppApprovalEvidence under the legacy namespaces
  (delete-workbook / delete-datasource /
  delete-extract-refresh-task) so the existing iframe machinery keeps
  dispatching confirm-delete-* model-invisible tools by panel
  data.kind. No surface added; no user-facing rewiring.
• mcp-apps flag OFF (shim flow): uses the same TagEvidence /
  RegistryEvidence gates as the legacy paths, keyed by resourceType.
• Rejects non-UUID resourceId on the extract-refresh-task branch before
  opening a Tableau REST session (via ArgsValidationError) — smaller blast
  radius than the previous placement.
• Adds an optional fallbackTargetKind param to guardMutation() so a
  denied-attempt audit record on a polymorphic tool carries the correct
  target kind even when resolveTarget() itself failed.

How Has This Been Tested?

• npm test — full unit suite passes (20 new tests in
  deleteContent.test.ts, plus the new queryAdminInsights.test.ts).
• npx tsc --noEmit — no type errors.
• npx eslint . — clean.
• Manual test config prepared for stdio transport (see local
  config.stdio.json — not committed): ADMIN_TOOLS_ENABLED=true,
  ADMIN_GATE_CACHE_TTL_MINUTES=5.
• Manual verification plan:
  • query-admin-insights { kind: 'stale-workbooks' } returns same payload
    as get-stale-workbooks.
  • delete-content { resourceType: 'workbook', resourceId: <luid> }
    preview → { confirm: true, tag } confirm (flag-OFF shim).
  • Flag-ON: flip features.json mcp-apps: true, preview opens an iframe
    panel; approval fires legacy confirm-delete-workbook.

Type of Change

• New feature
• Bug fix
• Breaking change
• Documentation update

Not a breaking change: legacy tools remain enabled during the shim
window. INCLUDE_TOOLS / EXCLUDE_TOOLS handling is unchanged.

Related Issues

• GUS: W-23375797 — [Tableau MCP for Admins] Consolidate admin-gated tools to reduce total tool count

Checklist

• I have updated the version in package.json (2.25.0 → 2.26.0).
• I have added tests that prove my feature works.
• New and existing unit tests pass locally with my changes.
• No breaking changes.

Contributor Agreement

• I have read the CONTRIBUTING guidelines for this project.

[Akash-Rastogi]

[Akash's agent]

Self-review pass — three line-anchored findings below. None is a hard merge blocker (legacy tools remain wired during the shim window, so no caller loses a capability today), but each is worth resolving before we retire the legacy tools.

[mattcfilbert]

🤖 MattGPT — automated review on Matt's behalf; he reviewed this before posting.

Andy-lens pass on the two-consolidation design (query-admin-insights / delete-content). Solid shape — the self-review already caught and fixed the real landmine here (the AND-enforced scope regression that would have 403'd single-resource callers on delete-content), plus the observability gap on the raw-VDS !query early return and the per-tool result-limit drop. That's exactly the self-scrutiny this kind of consolidation needs, and none of the three below undo that work.

Three follow-ups, ranked. Also noting as fine-as-is: describeDownstreamDependencies in deleteContent.ts says in its own docstring that it duplicates deleteDatasource.ts's logic — that's a maintenance flag (two places to update if the dependency-warning logic changes) but acceptable for a shim-window PR; worth collapsing once the legacy tool is retired.

[mattcfilbert]

🤖 MattGPT — automated review on Matt's behalf; he reviewed this before posting.

Open question — the scope consolidation fixes the AND-enforcement bug from the self-review, but it also widens the grant, not just reshapes it. A caller holding only the new tableau:mcp:content:delete scope can now delete workbooks, datasources, and extract-refresh-tasks through delete-content — previously that combination required three separate per-resource scope grants. Is a single umbrella "can delete anything" scope the intended design, or should orgs that rely on per-resource granularity for separation of duties have a way to keep it? Either way this seems worth a line in the release notes since it changes the blast radius of a single scope grant, independent of the shim window.

[Akash-Rastogi]

[Akash's agent] Good flag — yes, umbrella-as-designed. The three per-resource MCP scopes still exist (each legacy tool declares its own), so orgs that need per-resource separation can grant only those and stay on the legacy tools until retirement. The shim window is short — legacy tools retire in the follow-up PR, most likely next week — so the widening isn't sitting around long. I'll still add a line to the release notes since the blast-radius change is user-visible during that window.

[mattcfilbert]

🤖 MattGPT — automated review on Matt's behalf; he reviewed this before posting.

Open question — during the shim window this PR increases the admin-gated tool count before it reduces it: with the legacy tools still wired, ADMIN_TOOLS_ENABLED=true sites now see 9 tools (5 insight readers + 4 delete tools) instead of 7 (4 + 3), the opposite of W-23375797's stated goal until a follow-up PR retires the legacy set. Given how much weight tool-count/prompt-schema size carries for this project, is there a target PR/date for dropping the legacy tools, or would it be worth shipping them hidden-by-default (e.g. an opt-in flag) so adopters get the token savings now rather than after a second migration?

[Akash-Rastogi]

[Akash's agent] Fair call — retirement lands in the follow-up PR, most likely next week. Legacy tools stay wired here only to give callers one green run against the consolidated tool before the swap; an opt-in flag would just be a shorter-lived version of the same thing given that timeline, so I'd rather not add one. Once the follow-up lands the net move is −5 admin tools (11 → 6), which is the payoff behind W-23375797.