@withpica/mcp-server
Version:
MCP Server for withPICA — enables AI assistants to interact with your withPICA music catalog
2,313 lines • 80.9 kB
JavaScript
// Copyright (c) 2025-2026 Withpica Ltd. All rights reserved.
/**
* Metadata registry for every registered MCP tool.
*
* No count here on purpose: the header read "all 280 MCP tools" while the
* registry advertised 329 (A5, 2026-08-24). The live figure is
* `ToolRegistry.listTools().length`, pinned to `MCP_TOOL_COUNT` in
* `lib/constants/mcp-surface.ts` by
* `src/__tests__/tools/tool-count-parity.test.ts`.
*
* Categories: catalog, enrichment, business, discovery, media, comms, settings
* Risk: safe (read-only), mutating (creates/modifies), destructive (deletes/merges)
* retry_safe: true for safe tools, false for destructive, varies for mutating
*/
export const TOOL_METADATA = {
// ── Works ──────────────────────────────────────────────────────────────────
pica_works_query: {
category: "catalog",
risk: "safe",
retry_safe: true,
display_name: "find works",
},
pica_works_inspect: {
category: "catalog",
risk: "safe",
retry_safe: true,
display_name: "inspect a work",
},
pica_works_create: {
category: "catalog",
risk: "mutating",
retry_safe: false,
display_name: "create a new work",
},
pica_register_set: {
category: "catalog",
risk: "mutating",
retry_safe: false,
display_name: "register a captured set",
},
pica_works_update: {
category: "catalog",
risk: "mutating",
retry_safe: false,
display_name: "update a work",
},
pica_works_delete: {
category: "catalog",
risk: "destructive",
retry_safe: false,
display_name: "delete a work",
},
pica_works_verify: {
category: "catalog",
risk: "mutating",
retry_safe: true,
display_name: "what can be confirmed on a work (writes nothing)",
},
// ADR-264 WS2 — verify-before-assert: MLC lookup / user confirmation for
// registration gaps. Upserts are idempotent.
pica_works_verify_registrations: {
category: "catalog",
risk: "mutating",
retry_safe: true,
display_name: "verify work registration status",
},
// Human-creation provenance attestation — append-only stamp on
// work_licensing.provenance_attestation jsonb.
pica_works_attest: {
category: "catalog",
risk: "mutating",
retry_safe: true,
display_name: "stamp a human-creation provenance attestation",
},
pica_works_bulk_delete: {
category: "catalog",
risk: "destructive",
retry_safe: false,
display_name: "bulk delete works",
},
pica_works_bulk_move_to_performances: {
category: "catalog",
risk: "destructive",
retry_safe: false,
display_name: "bulk reclassify works as performances",
},
pica_works_bulk_update: {
category: "catalog",
risk: "mutating",
retry_safe: false,
display_name: "bulk update works",
},
pica_works_bulk_link_artist: {
category: "catalog",
risk: "mutating",
retry_safe: false,
display_name: "bulk link works to artist",
},
pica_recordings_bulk_reassign_artist: {
category: "catalog",
risk: "mutating",
retry_safe: false,
display_name: "bulk reassign recording artist",
},
pica_works_bulk_add_collaborator: {
category: "catalog",
risk: "mutating",
retry_safe: false,
display_name: "bulk add collaborator to works",
},
pica_work_writers_add: {
category: "catalog",
risk: "mutating",
retry_safe: false,
display_name: "add writers to a work by name",
},
pica_works_bulk_copy_credits: {
category: "catalog",
risk: "mutating",
retry_safe: false,
display_name: "bulk copy credits across works",
},
// ── People ─────────────────────────────────────────────────────────────────
pica_people_query: {
category: "catalog",
risk: "safe",
retry_safe: true,
display_name: "find people",
},
pica_approval_status: {
category: "settings",
risk: "safe",
retry_safe: true,
display_name: "check approval status",
},
pica_people_inspect: {
category: "catalog",
risk: "safe",
retry_safe: true,
display_name: "inspect a person",
},
pica_people_create: {
category: "catalog",
risk: "mutating",
retry_safe: false,
display_name: "create a new person",
},
pica_people_update: {
category: "catalog",
risk: "mutating",
retry_safe: false,
display_name: "update a person",
},
pica_people_delete: {
category: "catalog",
risk: "destructive",
retry_safe: false,
display_name: "delete a person",
},
pica_people_bulk_delete: {
category: "catalog",
risk: "destructive",
retry_safe: false,
display_name: "bulk delete people",
},
// ops 482424b7 — the opposite of a merge: two people sharing one identity.
pica_people_split_identity: {
category: "catalog",
risk: "destructive",
retry_safe: false,
display_name: "give a person their own identity",
},
pica_people_bulk_update_roles: {
category: "catalog",
risk: "mutating",
retry_safe: false,
display_name: "bulk update people roles",
},
pica_artist_projects: {
category: "catalog",
risk: "mutating",
retry_safe: false,
display_name: "manage artist projects",
},
pica_people_triangulate: {
category: "enrichment",
risk: "safe",
retry_safe: true,
display_name: "triangulate an artist",
},
pica_people_bulk_add_tags: {
category: "catalog",
risk: "mutating",
retry_safe: false,
display_name: "bulk add tags to people",
},
// ── Groups (member relationships on people, ADR-223) ─────────────────────
pica_group_add_member: {
category: "catalog",
risk: "mutating",
retry_safe: false,
display_name: "add a member to a group",
},
pica_group_remove_member: {
category: "catalog",
risk: "mutating",
retry_safe: true,
display_name: "remove a member from a group",
},
pica_group_list_members: {
category: "catalog",
risk: "safe",
retry_safe: true,
display_name: "list group members",
},
pica_person_list_groups: {
category: "catalog",
risk: "safe",
retry_safe: true,
display_name: "list groups a person belongs to",
},
// ── Recordings ─────────────────────────────────────────────────────────────
pica_recordings_query: {
category: "catalog",
risk: "safe",
retry_safe: true,
display_name: "find recordings",
},
pica_recordings_inspect: {
category: "catalog",
risk: "safe",
retry_safe: true,
display_name: "inspect a recording",
},
pica_recordings_create: {
category: "catalog",
risk: "mutating",
retry_safe: false,
display_name: "create a new recording",
},
pica_recordings_update: {
category: "catalog",
risk: "mutating",
retry_safe: false,
display_name: "update a recording",
},
pica_recordings_delete: {
category: "catalog",
risk: "destructive",
retry_safe: false,
display_name: "delete a recording",
},
// ── Recording sample provenance (ADR-259) ──────────────────────────────────
pica_recording_samples_list: {
category: "catalog",
risk: "safe",
retry_safe: true,
display_name: "list recording samples",
},
pica_recording_samples_add: {
category: "catalog",
risk: "mutating",
retry_safe: true,
display_name: "add recording sample",
},
pica_recording_samples_set_status: {
category: "catalog",
risk: "mutating",
retry_safe: true,
display_name: "set recording sample status",
},
pica_recording_samples_remove: {
category: "catalog",
// 2026-08-24 — aligned DOWN from "destructive" to match the tool's
// declared tier ("write", the ADR-230 source of truth; ADR-259 design:
// "low-stakes, re-addable → no two-step confirm token"). The destructive
// tag here was the drifted half of a tier/risk mismatch.
risk: "mutating",
retry_safe: false,
display_name: "remove recording sample",
},
// ── Credits ────────────────────────────────────────────────────────────────
// pica_credits_balance / pica_credits_history / pica_credits_purchase
// removed 2026-04-22 — see docs/MCP_REFINEMENT_LOG.md entry B-001.
// pica_credits_list / pica_credits_update are work_credits, not billing.
pica_credits_list: {
category: "catalog",
risk: "safe",
retry_safe: true,
display_name: "list credits on a work",
},
pica_credits_update: {
category: "catalog",
risk: "mutating",
retry_safe: false,
display_name: "update credits on a work",
},
// ADR-213 Primitive B — first-party recording-side production credits.
// Distinct from pica_credits_update (work_credits / songwriter side).
pica_recording_credits_update: {
category: "catalog",
risk: "mutating",
retry_safe: false,
display_name: "add a recording-side credit",
},
// REMOVED in mcp-server 2.99.0 (founder, 2026-09-29): the eleven
// deprecated aliases this history describes (ten, plus
// pica_royalties_summary added 2026-09-25) are gone from TOOL_METADATA and
// TOOL_ALIASES. Their 60-day prod traffic was 4 calls in total. The
// history below is kept as the record of how the deadline moved.
//
// ⚠️ removal_target DEFERRED 2.96.0 → 2.97.0 on 2026-08-26 (this file's ten
// "deprecated: true" entries — all originally slated for 2.96.0). The MPP
// pay rail (WS-B) needed a minor bump for the new pica_billing_pay tool,
// the next minor after 2.95.4 is unavoidably 2.96.0, and
// checkDeprecationExpiry (scripts/lint-mcp-tools.ts) hard-fails any
// version >= removal_target while the tool still exists. Removing all ten
// aliases was out of scope for a release-prep change; deferring the
// deadline is the lint's own sanctioned second option ("or consciously
// extend removal_target"). This is a conscious decision, not a lapsed one
// — do not defer it again without a reason recorded here.
//
// Tier 1 (MCP tool-surface consolidation): pica_recording_credits_update
// is now a superset (batch dispatch on credits[]); the
// pica_recording_credits_bulk_update alias of it was removed in 2.99.0.
//
// ⚠️ Deferred 2026-09-04: 2.97.0 became the ops-root-causes release
// (aliases, envelopes, offsets — PR fix/ops-root-causes-2026-09-03).
// Alias removal needs its own PR with an agent_events usage check per
// alias (SELECT tool_name, count(*) FROM agent_events WHERE tool_name IN
// (…) AND created_at > now() - interval '60 days'). Founder item F10
// schedules it before 2.98.0; deferred again 2026-09-29 to 2.99.0 (founder:
// 2.98.0 shipped the ADR-321 Phase 2 release without removals).
// ADR-232 atomic credit primitives — composable single-row writes.
pica_credit_add: {
category: "catalog",
risk: "mutating",
retry_safe: false,
display_name: "add a single credit (work or recording)",
},
pica_credit_remove: {
category: "catalog",
risk: "mutating",
retry_safe: false,
display_name: "remove a single credit by credit_id",
},
// 2026-09-11 — the verb between add and remove. Idempotent: re-sending the
// same patch writes the same values.
pica_credit_update: {
category: "catalog",
risk: "mutating",
retry_safe: true,
display_name: "edit a single credit in place by credit_id",
},
// Lightweight credit-confirmation send — fires the notification rails for
// pending credits without generating a formal split-sheet document.
pica_credits_send_for_attestation: {
category: "catalog",
risk: "mutating",
retry_safe: true,
display_name: "send pending credits for attestation",
},
// ADR-232 § Decision 2 — share trace explainability aggregator.
pica_share_trace: {
category: "catalog",
risk: "safe",
retry_safe: true,
display_name: "explain why a viewer can see this entity",
},
// ADR-232 § Decision 3 — count discrepancy explainer.
pica_count_explain: {
category: "catalog",
risk: "safe",
retry_safe: true,
display_name: "explain a dashboard or briefing count",
},
// ADR-232 § Decision 4 — operational audio pipeline status read.
pica_audio_pipeline_status: {
category: "catalog",
risk: "safe",
retry_safe: true,
display_name: "audio analysis pipeline status",
},
// ── Agreements ─────────────────────────────────────────────────────────────
pica_agreements_query: {
category: "business",
risk: "safe",
retry_safe: true,
display_name: "find agreements",
},
pica_agreements_inspect: {
category: "business",
risk: "safe",
retry_safe: true,
display_name: "inspect an agreement",
},
pica_agreements_create: {
category: "business",
risk: "mutating",
retry_safe: false,
display_name: "create a new agreement",
},
// ADR-289 follow-up — the entry point of the e-signature flow
pica_agreements_create_from_template: {
category: "business",
risk: "mutating",
retry_safe: false,
display_name: "create an agreement from a template",
},
pica_agreements_update: {
category: "business",
risk: "mutating",
retry_safe: false,
display_name: "update an agreement",
},
pica_agreements_delete: {
category: "business",
risk: "destructive",
retry_safe: false,
display_name: "delete an agreement",
},
pica_agreements_link_work: {
category: "business",
risk: "mutating",
retry_safe: false,
display_name: "link a work to an agreement",
},
pica_agreements_send_for_signature: {
category: "business",
risk: "mutating",
retry_safe: false,
display_name: "send agreement for signature",
},
pica_agreement_source_splits: {
category: "business",
risk: "mutating",
retry_safe: false,
display_name: "reconcile and source agreement splits",
},
// ── Agreement Types (unified) ──────────────────────────────────────────────
pica_agreement_types_query: {
category: "business",
risk: "safe",
retry_safe: true,
display_name: "find agreement types",
},
pica_agreement_types_inspect: {
category: "business",
risk: "safe",
retry_safe: true,
display_name: "inspect an agreement type",
},
pica_agreement_types_create: {
category: "business",
risk: "mutating",
retry_safe: false,
display_name: "create an agreement type",
},
pica_agreement_types_update: {
category: "business",
risk: "mutating",
retry_safe: false,
display_name: "update an agreement type",
},
pica_agreement_types_delete: {
category: "business",
risk: "destructive",
retry_safe: false,
display_name: "delete an agreement type",
},
pica_agreement_templates_render: {
category: "business",
risk: "safe",
retry_safe: true,
display_name: "render an agreement template",
},
pica_agreement_templates_duplicate: {
category: "business",
risk: "mutating",
retry_safe: false,
display_name: "duplicate an agreement template",
},
pica_agreement_templates_set_default: {
category: "business",
risk: "mutating",
retry_safe: false,
display_name: "set default agreement template",
},
// ── Split Sheets & Recording Splits ────────────────────────────────────────
pica_split_sheet_list: {
category: "business",
risk: "safe",
retry_safe: true,
display_name: "list split sheets",
},
pica_split_sheet_get: {
category: "business",
risk: "safe",
retry_safe: true,
display_name: "get a split sheet",
},
pica_split_sheet_generate: {
category: "business",
risk: "mutating",
retry_safe: true,
display_name: "generate a split sheet",
},
pica_split_sheet_send: {
category: "comms",
risk: "mutating",
retry_safe: false,
display_name: "send a split sheet for signing",
},
pica_recording_splits_list: {
category: "business",
risk: "safe",
retry_safe: true,
display_name: "list recording splits",
},
pica_recording_splits_create: {
category: "business",
risk: "mutating",
retry_safe: false,
display_name: "create recording splits",
},
pica_recording_splits_verify: {
category: "business",
risk: "safe",
retry_safe: true,
display_name: "verify recording splits total 100%",
},
pica_recording_splits_update: {
category: "business",
risk: "mutating",
retry_safe: true,
display_name: "edit a recording split",
},
pica_recording_splits_end: {
category: "business",
risk: "mutating",
retry_safe: false,
display_name: "end a recording split",
},
// ── Royalties & Statements ─────────────────────────────────────────────────
pica_royalties_list: {
category: "business",
risk: "safe",
retry_safe: true,
display_name: "list royalty entries",
},
pica_royalties_get: {
category: "business",
risk: "safe",
retry_safe: true,
display_name: "get a royalty entry",
},
// pica_royalties_summary was retired 2026-09-25 in favour of
// pica_royalties_blockers (ADR-321 Phase 0) and removed in 2.99.0.
// ADR-321 Phase 0 — what's holding up a song's (or the catalogue's) money.
pica_royalties_blockers: {
category: "business",
risk: "safe",
retry_safe: true,
display_name: "what's holding up money on a song or the catalogue",
},
// ADR-321 Phase 2 — programmable rights: agents propose, humans confirm.
pica_rights_propose: {
category: "business",
risk: "destructive",
retry_safe: false,
display_name: "propose a rights rule and ask the parties to confirm",
},
pica_rights_status: {
category: "business",
risk: "safe",
retry_safe: true,
display_name: "check a rights rule's confirmations",
},
pica_rights_inspect: {
category: "business",
risk: "safe",
retry_safe: true,
display_name: "see a song's rights rules and what would be held",
},
// ADR-321 Phase 3 — distribution, computed and not paid.
pica_rights_statements: {
category: "business",
risk: "safe",
retry_safe: true,
display_name: "see what income would pay each party, and check society statements against the split",
},
pica_rights_record_income: {
category: "business",
risk: "mutating",
retry_safe: false,
display_name: "record direct income so pica can show what it would pay",
},
// ADR-286 Task 8b (UNVERIFIED -- authored in worktree; verify in main checkout)
pica_royalties_unmatched: {
category: "business",
risk: "safe",
retry_safe: true,
display_name: "list unmatched royalty payment lines with candidates",
},
pica_royalties_attribute: {
category: "business",
risk: "mutating",
retry_safe: false,
display_name: "attribute a royalty payment line to a work or recording",
},
// Tier 2 consolidation: pica_statements_list/_get were superseded by the
// query/inspect pair below (ADR-149); _get was removed in 2.93.0 and _list
// in 2.99.0. pica_royalties_* above is deliberately NOT part of this
// fold (pica_royalties_get is an earnings-summary aggregate, not
// get-by-id).
pica_statements_query: {
category: "business",
risk: "safe",
retry_safe: true,
display_name: "find royalty statements",
},
pica_statements_inspect: {
category: "business",
risk: "safe",
retry_safe: true,
display_name: "inspect a royalty statement",
},
pica_statements_pending: {
category: "business",
risk: "safe",
retry_safe: true,
display_name: "pending statements",
},
pica_statement_ingest_document: {
category: "business",
risk: "mutating",
retry_safe: false,
display_name: "ingest statement document",
},
// ── Disputes ───────────────────────────────────────────────────────────────
pica_disputes_list: {
category: "business",
risk: "safe",
retry_safe: true,
display_name: "list disputes",
},
// ── Consent readiness (ADR-300) ────────────────────────────────────────────
pica_consent_readiness: {
category: "catalog",
risk: "safe",
retry_safe: true,
display_name: "consent readiness",
},
// ── Custody (ADR-158 Plan C) ───────────────────────────────────────────────
pica_custody_list: {
category: "catalog",
risk: "safe",
retry_safe: true,
display_name: "list custody claims",
},
pica_custody_history: {
category: "catalog",
risk: "safe",
retry_safe: true,
display_name: "custody history",
},
pica_custody_claim: {
category: "catalog",
risk: "mutating",
retry_safe: false,
display_name: "claim custody",
},
pica_custody_respond: {
category: "catalog",
risk: "mutating",
retry_safe: false,
display_name: "respond to a custody claim",
},
pica_custody_resolve_pending: {
category: "catalog",
risk: "safe",
retry_safe: true,
display_name: "resolve pending custody",
},
pica_custody_reconcile: {
category: "catalog",
risk: "mutating",
retry_safe: false,
display_name: "reconcile custody",
},
// ADR-262 — master-side recording custody (the control chain).
pica_recording_custody_assign: {
category: "catalog",
risk: "mutating",
retry_safe: false,
display_name: "assign recording custody",
},
pica_recording_provenance: {
category: "catalog",
risk: "safe",
retry_safe: true,
display_name: "recording provenance trail",
},
// ── Enrichment ─────────────────────────────────────────────────────────────
pica_enrichment_candidates: {
category: "enrichment",
risk: "safe",
retry_safe: true,
display_name: "list enrichment candidates",
},
// ADR-163 Tier B review queue + ADR-178 agent-proposed enrichment
pica_enrichment_proposals_list: {
category: "enrichment",
risk: "safe",
retry_safe: true,
display_name: "list pending enrichment proposals",
},
pica_enrichment_proposal_apply: {
category: "enrichment",
risk: "mutating",
retry_safe: false,
display_name: "apply an enrichment proposal",
},
pica_enrichment_proposal_reject: {
category: "enrichment",
risk: "mutating",
retry_safe: true,
display_name: "reject an enrichment proposal",
},
// ADR-264 C3: bulk review queue
pica_enrichment_proposals_bulk_reject: {
category: "enrichment",
risk: "mutating",
retry_safe: true,
display_name: "bulk-reject enrichment proposals by ids or filter",
},
pica_enrichment_proposals_bulk_apply: {
category: "enrichment",
risk: "mutating",
retry_safe: true,
display_name: "bulk-apply enrichment proposals by ids",
},
pica_enrichment_propose: {
category: "enrichment",
risk: "mutating",
retry_safe: false,
display_name: "propose an enrichment from research",
},
// ADR-289 Wave C2 — undo a wrong MusicBrainz match
pica_enrichment_clear: {
category: "enrichment",
risk: "destructive",
retry_safe: false,
display_name: "clear MusicBrainz enrichment from a work",
},
// ADR-179: outcome-shaped resolvers that replace the per-source enrich_* tools
pica_resolve_work: {
category: "enrichment",
risk: "mutating",
retry_safe: true,
display_name: "resolve a work against external sources",
},
pica_resolve_person: {
category: "enrichment",
risk: "mutating",
retry_safe: true,
display_name: "resolve a person against identity sources",
},
pica_resolve_recording: {
category: "enrichment",
risk: "mutating",
retry_safe: true,
display_name: "resolve a recording against external sources",
},
pica_resolve_release: {
category: "enrichment",
risk: "mutating",
retry_safe: true,
display_name: "resolve a release against external sources",
},
pica_enrichment_compare: {
category: "enrichment",
risk: "safe",
retry_safe: true,
display_name: "compare enrichment sources",
},
pica_registrations_compare: {
category: "enrichment",
risk: "safe",
retry_safe: true,
display_name: "compare registrations across sources",
},
// ADR-164 cascade re-run + health observability
pica_run_work_cascade: {
category: "enrichment",
risk: "mutating",
retry_safe: true,
display_name: "re-run cascade rules on a work",
},
pica_run_person_cascade: {
category: "enrichment",
risk: "mutating",
retry_safe: true,
display_name: "re-run cascade rules on a person",
},
pica_cascade_health: {
category: "enrichment",
risk: "safe",
retry_safe: true,
display_name: "check cascade health counters",
},
// ── Search & Discovery ─────────────────────────────────────────────────────
pica_search_all: {
category: "discovery",
risk: "safe",
retry_safe: true,
display_name: "search across everything",
},
pica_catalog_stats: {
category: "discovery",
risk: "safe",
retry_safe: true,
display_name: "get catalog statistics",
},
pica_graph_traverse: {
category: "discovery",
risk: "safe",
retry_safe: true,
display_name: "traverse the identity graph",
},
pica_search_for_sync: {
category: "discovery",
risk: "safe",
retry_safe: true,
display_name: "search works for sync licensing",
},
pica_submit_license_enquiry: {
category: "discovery",
risk: "mutating",
retry_safe: false,
display_name: "submit a license enquiry",
},
pica_claim_credit: {
category: "discovery",
risk: "mutating",
retry_safe: false,
display_name: "claim discovered credit",
},
pica_claim_custody: {
category: "discovery",
risk: "mutating",
retry_safe: false,
display_name: "claim discovered custody",
},
pica_claim_artist: {
category: "discovery",
risk: "mutating",
retry_safe: false,
display_name: "claim discovered artist",
},
pica_discoveries_query: {
category: "discovery",
risk: "safe",
retry_safe: true,
display_name: "find discoveries",
},
pica_discoveries_review: {
category: "discovery",
risk: "mutating",
retry_safe: false,
display_name: "review a discovery",
},
pica_dashboard_attention: {
category: "discovery",
risk: "safe",
retry_safe: true,
display_name: "get items needing attention",
},
pica_dashboard_briefing: {
category: "discovery",
risk: "safe",
retry_safe: true,
display_name: "get your daily briefing",
},
pica_catalog_health: {
category: "discovery",
risk: "safe",
retry_safe: true,
display_name: "assess catalog health",
},
// ADR-273 — catalog health runbook: plan + fix tools
pica_catalog_health_plan: {
category: "discovery",
risk: "safe",
retry_safe: true,
display_name: "preview a catalog health fix plan",
},
pica_catalog_health_fix: {
category: "catalog",
risk: "mutating",
retry_safe: false,
display_name: "apply catalog health fix actions",
},
// Registration integrity floor (spec 2026-07-09, Task 10) — the one new
// tool the floor program ships; waives (or revokes) a gap the user has
// explicitly confirmed in conversation.
pica_integrity_waive: {
category: "catalog",
risk: "mutating",
retry_safe: false,
display_name: "waive an integrity gap",
},
// ── App Tools (MCP Apps) ──────────────────────────────────────────────────
pica_upload: {
category: "media",
risk: "safe",
retry_safe: true,
display_name: "upload files",
},
pica_download: {
category: "media",
risk: "safe",
retry_safe: true,
display_name: "download a file",
},
pica_car_preview: {
category: "media",
risk: "safe",
retry_safe: true,
display_name: "preview catalog asset report",
},
// ── Audio Files ────────────────────────────────────────────────────────────
pica_audio_query: {
category: "media",
risk: "safe",
retry_safe: true,
display_name: "find audio files",
},
pica_audio_assign: {
category: "media",
risk: "mutating",
retry_safe: false,
display_name: "assign audio to a work/recording",
},
pica_audio_bulk_assign_suggested: {
category: "media",
risk: "mutating",
// Re-running attaches only what is STILL an orphan with a high-confidence
// suggestion — already-attached files drop out of the recompute, so a
// retry cannot double-apply.
retry_safe: true,
display_name: "bulk attach suggested audio",
},
pica_audio_dismiss_match: {
category: "media",
risk: "mutating",
// Repeat dismissal of the same pair is a server-side no-op success.
retry_safe: true,
display_name: "dismiss a suggested audio match",
},
pica_audio_inspect: {
category: "media",
risk: "safe",
retry_safe: true,
display_name: "inspect an audio file",
},
pica_audio_analyze: {
category: "media",
risk: "mutating",
retry_safe: true,
display_name: "analyze an audio file",
},
pica_audio_presigned_upload: {
category: "media",
risk: "mutating",
retry_safe: true,
display_name: "get presigned upload url for audio",
},
pica_audio_complete_upload: {
category: "media",
risk: "mutating",
retry_safe: false,
display_name: "complete an audio upload",
},
pica_audio_identify: {
category: "media",
risk: "mutating",
retry_safe: true,
display_name: "identify an audio file",
},
pica_audio_update: {
category: "media",
risk: "mutating",
retry_safe: true,
display_name: "update audio metadata (file_type, stem, version, title)",
},
pica_audio_bulk_update: {
category: "media",
risk: "mutating",
// Each item SETS fields to given values — re-sending the same batch
// lands the same state, so a retry cannot compound.
retry_safe: true,
display_name: "bulk update audio metadata (up to 200 files)",
},
pica_audio_delete: {
category: "media",
risk: "destructive",
retry_safe: false,
display_name: "delete an audio file",
},
// ── Multimedia ─────────────────────────────────────────────────────────────
pica_multimedia_search: {
category: "media",
risk: "safe",
retry_safe: true,
display_name: "search multimedia",
},
pica_multimedia_create: {
category: "media",
risk: "mutating",
retry_safe: false,
display_name: "create a multimedia entry",
},
pica_multimedia_import_url: {
category: "media",
risk: "mutating",
retry_safe: true,
display_name: "import multimedia from url",
},
pica_multimedia_link_youtube: {
category: "media",
risk: "mutating",
retry_safe: false,
display_name: "link a youtube video",
},
pica_multimedia_link_work: {
category: "media",
risk: "mutating",
retry_safe: false,
display_name: "link multimedia to a work",
},
// ── Documents ──────────────────────────────────────────────────────────────
// Tier 2 consolidation: pica_documents_list/_read were superseded by the
// query/inspect pair below (ADR-149) and removed in 2.99.0.
pica_documents_analyse: {
category: "media",
risk: "mutating",
retry_safe: true,
display_name: "analyse a document with ai",
},
pica_documents_query: {
category: "media",
risk: "safe",
retry_safe: true,
display_name: "find documents",
},
pica_documents_inspect: {
category: "media",
risk: "safe",
retry_safe: true,
display_name: "inspect a document",
},
pica_documents_link: {
category: "media",
risk: "mutating",
retry_safe: true,
display_name: "link a document",
},
pica_documents_delete: {
category: "media",
risk: "destructive",
retry_safe: false,
display_name: "delete a document",
},
// ── Uploads ────────────────────────────────────────────────────────────────
pica_upload_file: {
category: "media",
risk: "mutating",
retry_safe: true,
display_name: "get upload url for a file",
},
pica_upload_complete: {
category: "media",
risk: "mutating",
retry_safe: false,
display_name: "complete a file upload",
},
pica_file_deliver: {
category: "media",
risk: "mutating",
retry_safe: false,
display_name: "send a secure delivery link",
},
pica_file_revoke_delivery: {
category: "media",
risk: "mutating",
retry_safe: true,
display_name: "revoke a delivery link",
},
pica_release_notes: {
category: "discovery",
risk: "safe",
retry_safe: true,
display_name: "see what's new in pica server",
},
// ── Exports ────────────────────────────────────────────────────────────────
pica_export_catalog_csv: {
category: "catalog",
risk: "safe",
retry_safe: true,
display_name: "export works to PRO / distributor / NRO / sync",
},
pica_export_song_registration: {
category: "catalog",
risk: "mutating",
retry_safe: true,
display_name: "export for song registration",
},
pica_export_industry_ready: {
category: "catalog",
risk: "mutating",
retry_safe: true,
display_name: "export industry-ready package",
},
pica_export_catalog_asset_report: {
category: "catalog",
risk: "mutating",
retry_safe: true,
display_name: "export catalog asset report",
},
pica_export_ai_consent: {
category: "catalog",
risk: "mutating",
retry_safe: true,
display_name: "export ai consent declaration",
},
// The four diligence documents. `mutating` because each writes a
// `pica_exports` row and generates an artefact — the same classification as
// every sibling above that produces a file. `pica_export_catalog_csv` is the
// lone `safe` export because it returns inline CSV and persists nothing.
pica_export_snapshot: {
category: "catalog",
risk: "mutating",
retry_safe: true,
display_name: "export catalogue snapshot",
},
pica_export_song_dossiers: {
category: "catalog",
risk: "mutating",
retry_safe: true,
display_name: "export song dossiers",
},
pica_export_ownership_record: {
category: "catalog",
risk: "mutating",
retry_safe: true,
display_name: "export ownership record",
},
pica_export_rights_proof: {
category: "catalog",
risk: "mutating",
retry_safe: true,
display_name: "export rights proof bundle",
},
pica_export_diligence_pack: {
category: "catalog",
risk: "mutating",
retry_safe: true,
display_name: "export catalogue diligence pack",
},
// ── Calendar ───────────────────────────────────────────────────────────────
pica_calendar_events: {
category: "catalog",
risk: "safe",
retry_safe: true,
display_name: "list calendar events",
},
// ── Duplicates ─────────────────────────────────────────────────────────────
pica_find_duplicates: {
category: "catalog",
risk: "safe",
retry_safe: true,
display_name: "find potential duplicates",
},
pica_merge_duplicates: {
category: "catalog",
risk: "destructive",
retry_safe: false,
display_name: "merge duplicate records",
},
// ── Projects ───────────────────────────────────────────────────────────────
// Tier 2 consolidation: pica_projects_list/_get were superseded by the
// query/inspect pair below (ADR-149); _get was removed in 2.93.0 and _list
// in 2.99.0.
pica_projects_query: {
category: "catalog",
risk: "safe",
retry_safe: true,
display_name: "find projects",
},
pica_projects_inspect: {
category: "catalog",
risk: "safe",
retry_safe: true,
display_name: "inspect a project",
},
pica_projects_create: {
category: "catalog",
risk: "mutating",
retry_safe: false,
display_name: "create a new project",
},
pica_projects_update: {
category: "catalog",
risk: "mutating",
retry_safe: false,
display_name: "update a project",
},
pica_projects_delete: {
category: "catalog",
risk: "destructive",
retry_safe: false,
display_name: "delete a project",
},
pica_projects_attach_works: {
category: "catalog",
risk: "mutating",
retry_safe: true,
display_name: "attach works to a project",
},
pica_projects_participants: {
category: "catalog",
risk: "mutating",
retry_safe: false,
display_name: "manage project participants",
},
pica_projects_multimedia: {
category: "catalog",
risk: "mutating",
retry_safe: false,
display_name: "manage project multimedia",
},
// ── Releases ───────────────────────────────────────────────────────────────
// Tier 1 consolidation: pica_releases_list/_get were superseded by the
// query/inspect pair below (ADR-149) and removed in 2.99.0.
pica_releases_query: {
category: "catalog",
risk: "safe",
retry_safe: true,
display_name: "find releases",
},
pica_releases_inspect: {
category: "catalog",
risk: "safe",
retry_safe: true,
display_name: "inspect a release",
},
pica_releases_create: {
category: "catalog",
risk: "mutating",
retry_safe: false,
display_name: "create a new release",
},
pica_releases_update: {
category: "catalog",
risk: "mutating",
retry_safe: false,
display_name: "update a release",
},
pica_releases_delete: {
category: "catalog",
risk: "destructive",
retry_safe: false,
display_name: "delete a release",
},
pica_releases_attach_track: {
category: "catalog",
risk: "mutating",
retry_safe: true,
display_name: "attach a track to a release",
},
pica_releases_list_tracks: {
category: "catalog",
risk: "safe",
retry_safe: true,
display_name: "list tracks on a release",
},
pica_releases_detach_track: {
category: "catalog",
risk: "mutating",
retry_safe: false,
display_name: "detach a track from a release",
},
pica_releases_reorder_tracks: {
category: "catalog",
risk: "mutating",
retry_safe: false,
display_name: "reorder tracks on a release",
},
pica_releases_attach_recording_with_work: {
category: "catalog",
risk: "mutating",
retry_safe: true,
display_name: "attach a recording (with linked work) to a release",
},
// ADR-175 release workflow tools. pica_releases_bulk_attach_tracks and
// pica_releases_attach_track_by_identifier were superseded by
// pica_releases_attach_track's items[]/identifier_type+value superset
// dispatch (Tier 1 consolidation) and removed in 2.99.0.
pica_releases_move_track: {
category: "catalog",
risk: "mutating",
retry_safe: false,
display_name: "swap two track positions on a release",
},
pica_releases_create_with_tracks: {
category: "catalog",
risk: "mutating",
retry_safe: false,
display_name: "create a release with its tracks in one call",
},
pica_releases_completeness_check: {
category: "catalog",
risk: "safe",
retry_safe: true,
display_name: "release completeness diligence report",
},
// ADR-208 Phase 3 Primitive D — rich render (image + markdown summary)
pica_release_show: {
category: "catalog",
risk: "safe",
retry_safe: true,
display_name: "render a release card (cover art + markdown)",
},
// ── Sessions ───────────────────────────────────────────────────────────────
// Tier 2 consolidation: pica_sessions_list/_get were REMOVED in the
// mcp-server 2.93.0 WS5 removal sweep (0 calls/30d in prod). The
// query/inspect pair below (ADR-149) is the canonical read surface.
pica_sessions_query: {
category: "catalog",
risk: "safe",
retry_safe: true,
display_name: "find work sessions",
},
pica_sessions_inspect: {
category: "catalog",
risk: "safe",
retry_safe: true,
display_name: "inspect a work session",
},
pica_sessions_create: {
category: "catalog",
risk: "mutating",
retry_safe: false,
display_name: "create a work session",
},
pica_sessions_types: {
category: "catalog",
risk: "safe",
retry_safe: true,
display_name: "list session types",
},
// ── Notes ──────────────────────────────────────────────────────────────────
// Tier 2 consolidation: pica_notes_list/_get were superseded by the
// query/inspect pair below (ADR-149). pica_notes_get was REMOVED in the
// mcp-server 2.93.0 WS5 removal sweep (0 calls/30d in prod) and
// pica_notes_list in 2.99.0.
pica_notes_query: {
category: "catalog",
risk: "safe",
retry_safe: true,
display_name: "find notes",
},
pica_notes_inspect: {
category: "catalog",
risk: "safe",
retry_safe: true,
display_name: "inspect a note",
},
pica_notes_create: {
category: "catalog",
risk: "mutating",
retry_safe: false,
display_name: "create a note",
},
pica_notes_delete: {
category: "catalog",
risk: "destructive",
retry_safe: false,
display_name: "delete a note",
},
// ── Physical Assets ────────────────────────────────────────────────────────
pica_physical_assets_query: {
category: "catalog",
risk: "safe",
retry_safe: true,
display_name: "find physical assets",
},
pica_physical_assets_inspect: {
category: "catalog",
risk: "safe",
retry_safe: true,
display_name: "inspect a physical asset",
},
pica_physical_assets_create: {
category: "catalog",
risk: "mutating",
retry_safe: false,
display_name: "create a physical asset",
},
pica_physical_assets_update: {
category: "catalog",
risk: "mutating",
retry_safe: false,
display_name: "update a physical asset",
},
pica_physical_assets_delete: {
category: "catalog",
risk: "destructive",
retry_safe: false,
display_name: "delete a physical asset",
},
pica_physical_assets_stats: {
category: "catalog",
risk: "safe",
retry_safe: true,
display_name: "get physical assets statistics",
},
pica_physical_assets_export: {
category: "catalog",
risk: "safe",
retry_safe: true,
display_name: "export physical assets",
},
// ADR-174 Phase 2 item 5: rich provenance links between assets and works/recordings
pica_physical_assets_link_work: {
category: "catalog",
risk: "mutating",
retry_safe: false,
display_name: "link a physical asset to a work",
},
pica_physical_assets_link_recording: {
category: "catalog",
risk: "mutating",
retry_safe: false,
display_name: "link a physical asset to a recording",
},
pica_physical_assets_unlink_work: {
category: "catalog",
risk: "mutating",
retry_safe: true,
display_name: "unlink a physical asset from a work",
},
pica_physical_assets_unlink_recording: {
category: "catalog",
risk: "mutating",
retry_safe: true,
display_name: "unlink a physical asset from a recording",
},
// ── Analytics (Carbon, Provenance, Diligence) ──────────────────────────────
pica_carbon_footprint: {
category: "catalog",
risk: "safe",
retry_safe: true,
display_name: "get carbon footprint",
},
pica_carbon_live: {
category: "catalog",
risk: "safe",
retry_safe: true,
display_name: "get live carbon metrics",
},
pica_provenance_stats: {
category: "catalog",
risk: "safe",
retry_safe: true,
display_name: "get provenance statistics",
},
pica_provenance_work: {
category: "catalog",
risk: "safe",
retry_safe: true,
display_name: "get provenance for a work",
},
pica_provenance_certificate: {
category: "catalog",
risk: "mutating",
retry_safe: true,
display_name: "generate provenance certificate",
},
pica_provenance_certificate_get: {
category: "catalog",
risk: "safe",
retry_safe: true,
display_name: "get existing provenance certificate",
},
pica_catalog_diligence: {
category: "catalog",
risk: "safe",
retry_safe: true,
display_name: "run catalog due diligence",
},
// ── Import ─────────────────────────────────────────────────────────────────
pica_import_analyze: {
category: "catalog",
risk: "safe",
retry_safe: true,
display_name: "analyze an import file",
},
pica_import_validate: {
category: "catalog",
risk: "safe",
retry_safe: true,
display_name: "validate import data",
},
pica_import_execute: {
category: "catalog",
risk: "mutating",
retry_safe: false,
display_name: "execute a catalog import",
},
pica_import_fields: {
category: "catalog",
risk: "safe",
retry_safe: true,
display_name: "list available import fields",
},
pica_import_template: {
category: "catalog",
risk: "safe",
retry_safe: true,
display_name: "get import template",
},
pica_import_streaming_link: {
category: "catalog",
risk: "mutating",
retry_safe: true,
display_name: "import from streaming link",
},
pica_import_youtube_link: {
category: "catalog",
risk: "mutating",
retry_safe: false,
display_name: "import a youtube video as a recording",
},
// ── Import Documents ───────────────────────────────────────────────────────
pica_import_documents_query: {
category: "catalog",
risk: "safe",
retry_safe: true,
display_name: "find import documents",
},
pica_import_documents_inspect: {
category: "catalog",
risk: "safe",
retry_safe: true,
display_name: "inspect an import document",
},
// 2026-09-30 — an agent can see an email its person forwarded to PICA.
pica_import_emails_query: {
category: "catalog",
risk: "safe",
retry_safe: true,
display_name: "see emails forwarded to pica and what happened to them",
},
pica_ingest_statement: {
category: "catalog",
risk: "mutating",
retry_safe: false,
display_name: "ingest a royalty statement",
},
// ── Notifications ──────────────────────────────────────────────────────────
pica_notifications_list: {
category: "comms",
risk: "safe",
retry_safe: true,
display_name: "list notifications",
},
pica_notify_person: {
category: "comms",
risk: "mutating",
retry_safe: false,
display_name: "send notification to a person",
},
pica_notifications_mark_read: {
category: "comms",
risk: "mutating",
retry_safe: true,
display_name: "mark notifications as read",
},
// ADR-218 cross-transport awareness — read + acknowledge the shared
// discovery_events ledger that backs MCP / Telegram / web / email
pica_notifications_recent: {
category: "comms",
risk: "safe",
retry_safe: true,
display_name: "read recent cross-transport notifications",
},
pica_notification_acknowledge: {
category: "comms",
risk: "mutating",
retry_safe: true,
display_name: "acknowledge cross-transport notifications",
},
// ── Collaborators ──────────────────────────────────────────────────────────
pica_collaborators_invite: {
category: "comms",
risk: "mutating",
retry_safe: false,
display_name: "invite a collaborator",
},
pica_collaborators_invites_list: {
category: "comms",
risk: "safe",
retry_safe: true,
display_name: "list collaborator invites",
},
pica_collaborators_invite_resend: {
category: "comms",
risk: "mutating",
retry_safe: false,
display_name: "resend a collaborator invite",
},
// ADR-157 warm-path collaboration tools
pica_collaborators_incoming_list: {
category: "comms",
risk: "safe",
retry_safe: true,
display_name: "list invites addressed to you",
},
pica_collaborators_accept: {
category: "comms",
risk: "mutating",
retry_safe: false,
display_name: "accept a collaboration invite",
},
pica_collaborators_dispute: {
category: "comms",
risk: "mutating",
retry_safe: true,
display_name: "dispute a collaboration invite",
},
pica_collaborators_invite_bulk: {
category: "comms",
risk: "mutating",
retry_safe: false,
display_name: "send multiple collaborator invites",
},
// ADR-236 — agent-mediated work sharing
pica_collaborators_claim_by_code: {
category: "comms",
risk: "mutating",
retry_safe: false,
display_name: "preview or accept an invite by code",
},
pica_collaborators_decline_by_code: {
category: "comms",
risk: "mutating",
retry_safe: false,
display_name: "decline an invite by code",
},
pica_collaborators_invite_status: {
category: "comms",
risk: "safe",
retry_safe: true,
display_name: "look up the status of a collaboration invite",
},
pica_collaborators_invite_revoke: {
category: "comms",
risk: "destructive",
retry_safe: false,
display_name: "revoke a pending collaboration invite",
},
pica_collaborations_received: {
category: "comms",
risk: "safe",
retry_safe: true,
display_name: "list works I am credited on in other organisations",
},
// ADR-238 — agent-mediated counter-proposals
pica_collaborators_counter_propose: {
category: "comms",
risk: "mutating",
retry_safe: false,
display_name: "counter-propose new terms on a collaboration invite",
},
pica_collaborators_accept_counter: {
category: "comms",
risk: "mutating",
retry_safe: false,
display_name: "accept a counter-proposal on a collaboration invite",
},
pica_collaborators_decline_counter: {
category: "comms",
risk: "mutating",
retry_safe: false,
display_name: "decline a counter-proposal on a collaboration invite",
},
pica_collaborators_counter_back: {
category: "comms",
risk: "mutating",
retry_safe: false,
display_name: "counter back against a recipient's counter-proposal",
},
// ── User Profile (opt-in public handles + bio + avatar) ────────────────────
pica_users_find_by_handle: {
category: "discovery",
risk: "safe",
retry_safe: true,
display_name: "find a user by their public handle",
},
pica_users_get_my_profile: {
category: "settings",
risk: "safe",
retry_safe: true,
display_name: "show my profile (handle, bio, avatar)",
},
pica_users_set_handle: {
category: "settings",
risk: "mutating",
retry_safe: false,
display_name: "set my public handle",
},
pica_users_clear_handle: {
category: "settings",
risk: "mutating",
retry_safe: true,
display_name: "clear my public handle",
},
pica_users_set_bio: {
category: "settings",
risk: "mutating",
retry_safe: false,
display_name: "set my bio",
},
pica_users_set_avatar_url: {
category: "settings",
risk: "mutating",
retry_safe: false,
display_name: "set my avatar URL",
},
pica_users_import_bio_from_person: {
category: "settings",
risk: "mutating",
retry_safe: false,
display_name: "import my bio from a linked person",
},
// ── Send Hub ───────────────────────────────────────────────────────────────
pica_send_message: {
category: "comms",
risk: "mutating",
retry_safe: false,
display_name: "send a message",
},
pica_send_query: {
category: "comms",
risk: "safe",
retry_safe: true,
display_name: "find sent messages",
},
pica_send_resend: {
category: "comms",
risk: "mutating",
retry_safe: false,
display_name: "resend a message",
},
// ADR-289 Wave C2
pica_send_cancel: {
category: "comms",
risk: "mutating",
retry_safe: false,
display_name: "cancel a pending send",
},
// ── Saved Catalog Selections (ADR-319) ────────────────────────────────────
pica_selections_query: {
category: "catalog",
risk: "safe",
retry_safe: true,
display_name: "find saved selections",
},
pica_selections_inspect: {
category: "catalog",
risk: "safe",
retry_safe: true,
display_name: "inspect a saved selection",
},
pica_selections_create: {
category: "catalog",
risk: "mutating",
retry_safe: false,
display_name: "save a catalog selection",
},
pica_selections_update: {
category: "catalog",
risk: "mutating",
retry_safe: true,
display_name: "update a saved selection",
},
pica_selections_delete: {
category: "catalog",
risk: "destructive",
retry_safe: false,
display_name: "delete a saved selection",
},
// ── Share Links ────────────────────────────────────────────────────────────
// Tier 2 consolidation: pica_share_links_list was REMOVED in the mcp-server
// 2.93.0 WS5 removal sweep (0 calls/30d in prod). The query tool below
// (ADR-149) is the canonical read surface.
pica_share_links_query: {
category: "comms",
risk: "safe",
retry_safe: true,
display_name: "find share links",
},
pica_share_links_inspect: {
category: "comms",
risk: "safe",
retry_safe: true,
display_name: "inspect a share link",
},
pica_share_links_update: {
category: "comms",
risk: "mutating",
retry_safe: true,
display_name: "update a share link",
},
pica_share_links_delete: {
category: "comms",
risk: "destructive",
retry_safe: false,
display_name: "delete a share link",
},
pica_share_links_create: {
category: "comms",
risk: "mutating",
retry_safe: false,
display_name: "create a share link",
},
pica_share_send: {
category: "comms",
risk: "mutating",
retry_safe: false,
display_name: "send a withpica-branded share email",
},
// ── Access Simulator ──────────────────────────────────────────────────────
pica_access_simulate: {
category: "comms",
risk: "safe",
retry_safe: true,
display_name: "simulate access",
},
// ── Telegram ───────────────────────────────────────────────────────────────
pica_telegram_status: {
category: "comms",
risk: "safe",
retry_safe: true,
display_name: "check telegram connection status",
},
pica_telegram_connect: {
category: "comms",
risk: "mutating",
retry_safe: true,
display_name: "pair telegram with pica",
},
// ADR-289 Wave C2 — absorbs get_telegram_notification_config +
// configure_telegram_notifications from the retired bespoke assistant
pica_telegram_config: {
category: "comms",
risk: "mutating",
retry_safe: true,
display_name: "get or set telegram notification preferences",
},
pica_notify_user: {
category: "comms",
risk: "mutating",
retry_safe: false,
display_name: "send notification to user via telegram",
},
// ADR-160 scheduled telegram reminders
pica_notify_user_at: {
category: "comms",
risk: "mutating",
retry_safe: false,
display_name: "schedule a telegram reminder",
},
pica_notify_user_list_pending: {
category: "comms",
risk: "safe",
retry_safe: true,
display_name: "list pending reminders",
},
pica_notify_user_cancel: {
category: "comms",
risk: "mutating",
retry_safe: true,
display_name: "cancel a scheduled reminder",
},
// ── Publishers ─────────────────────────────────────────────────────────────
pica_publishers_query: {
category: "catalog",
risk: "safe",
retry_safe: true,
display_name: "find publishers",
},
pica_publishers_create: {
category: "catalog",
risk: "mutating",
retry_safe: false,
display_name: "create a publisher",
},
// ── Labels (ADR-174 Decision 3) ────────────────────────────────────────────
pica_labels_query: {
category: "catalog",
risk: "safe",
retry_safe: true,
display_name: "find labels",
},
pica_labels_create: {
category: "catalog",
risk: "mutating",
retry_safe: true,
display_name: "create a label or distributor",
},
// ── Party claims (ADR-268 WS1) ─────────────────────────────────────────────
pica_party_claim_invite: {
category: "catalog",
risk: "mutating",
// Duplicate-invite dedup is server-side (409 DUPLICATE_INVITE), so a
// retry can't double-send the claim email.
retry_safe: true,
display_name: "invite a party to claim its organisation",
},
pica_party_claim_status: {
category: "catalog",
risk: "safe",
retry_safe: true,
display_name: "check party claim invites",
},
// ── Profile claims (claim your profile) ────────────────────────────────────
pica_profile_claims_invite: {
category: "comms",
risk: "mutating",
// A repeat confirmed call skips anyone whose invite still works
// (ALREADY_INVITED), but two confirmed calls racing can both pass that
// check for one person, so a retry is not guaranteed single-send.
retry_safe: false,
display_name: "invite people to claim their profile",
},
pica_profile_claims_status: {
category: "comms",
risk: "safe",
retry_safe: true,
display_name: "check who has claimed their profile",
},
// ── Licensing (enquiry read/update) ────────────────────────────────────────
pica_list_license_enquiries: {
category: "comms",
risk: "safe",
retry_safe: true,
display_name: "list license enquiries",
},
pica_get_license_enquiry: {
category: "comms",
risk: "safe",
retry_safe: true,
display_name: "get a license enquiry",
},
pica_update_license_enquiry_status: {
category: "settings",
risk: "mutating",
retry_safe: false,
display_name: "update license enquiry status",
},
// ── Bookings (internal-team session/production enquiries, ADR-289 Wave C1) ─
pica_bookings_query: {
category: "comms",
risk: "safe",
retry_safe: true,
display_name: "query booking enquiries",
},
pica_bookings_update: {
category: "settings",
risk: "mutating",
retry_safe: false,
display_name: "update a booking enquiry",
},
// ── Shows (ADR-313 — live shows and tour credits) ───────────────────────────
pica_log_show: {
category: "catalog",
risk: "mutating",
retry_safe: false,
display_name: "log a live show",
},
pica_shows_query: {
category: "catalog",
risk: "safe",
retry_safe: true,
display_name: "query live shows",
},
pica_setlist_match: {
category: "catalog",
risk: "mutating",
retry_safe: true,
display_name: "confirm what was played",
},
// ── Team ───────────────────────────────────────────────────────────────────
pica_audit_list: {
category: "settings",
risk: "safe",
retry_safe: true,
display_name: "review recent AI activity",
},
// pica_team_* tools removed 2026-06-11 — /api/admin/team/* is session-only
// by design (ADR-248); bearer/MCP callers always received 401.
// ── Memory ─────────────────────────────────────────────────────────────────
pica_memory_list: {
category: "settings",
risk: "safe",
retry_safe: true,
display_name: "list saved memories",
},
pica_memory_search: {
category: "settings",
risk: "safe",
retry_safe: true,
display_name: "search memories",
},
pica_memory_save: {
category: "settings",
risk: "mutating",
retry_safe: false,
display_name: "save a memory",
},
pica_memory_delete: {
category: "settings",
risk: "destructive",
retry_safe: false,
display_name: "delete a memory",
},
// ADR-289 Wave C2
pica_memory_update: {
category: "settings",
risk: "mutating",
retry_safe: false,
display_name: "update a memory",
},
// ── Skills (ADR-140 Phase 2b) ──────────────────────────────────────────────
pica_skill_list: {
category: "discovery",
risk: "safe",
retry_safe: true,
display_name: "list available skills",
},
pica_skill_get: {
category: "discovery",
risk: "safe",
retry_safe: true,
display_name: "load a skill methodology",
},
// ── Settings ───────────────────────────────────────────────────────────────
// pica_credits_history / pica_credits_purchase removed 2026-04-22.
pica_storage_status: {
category: "settings",
risk: "safe",
retry_safe: true,
display_name: "check storage usage and connection health",
},
// ADR-217 — BYOC storage configure + disconnect.
pica_storage_configure_start: {
category: "settings",
// Mints a JWT-bound URL only — no DB writes happen at the tool layer.
// The configure page (Phase 2) does the persistence after probe success.
risk: "safe",
retry_safe: true,
display_name: "set up your own cloud storage bucket (S3, GCS, Azure, R2, Backblaze)",
},
pica_storage_disconnect: {
category: "settings",
// Future uploads route differently — destructive in the same sense as
// pica_delete_my_account. Two-step gate handled by the dispatcher.
// retry_safe:false matches the destructive-tools invariant; the
// two-step confirmation token (not blind retry) is the safety net.
risk: "destructive",
retry_safe: false,
display_name: "revert storage to PICA-managed default",
},
pica_organisation_profile: {
category: "settings",
risk: "safe",
retry_safe: true,
display_name: "view account profile",
},
pica_user_profile: {
category: "settings",
risk: "safe",
retry_safe: true,
display_name: "view your profile",
},
pica_directory_settings: {
category: "settings",
risk: "safe",
retry_safe: true,
display_name: "view directory settings",
},
// ADR-184: user-facing self-service privacy & account tools
pica_get_privacy_settings: {
category: "settings",
risk: "safe",
retry_safe: true,
display_name: "check marketing opt-in state",
},
pica_update_privacy_settings: {
category: "settings",
risk: "mutating",
retry_safe: true,
display_name: "update marketing preferences",
},
pica_submit_feedback: {
category: "comms",
risk: "mutating",
retry_safe: false,
display_name: "submit feedback to the team",
},
pica_report_issue: {
category: "comms",
risk: "mutating",
retry_safe: true,
display_name: "report a workflow issue to the PICA team",
},
pica_my_reported_issues: {
category: "comms",
risk: "safe",
retry_safe: true,
display_name: "list issues you've reported and their resolution status",
},
pica_my_recent_questions: {
// ADR-226 Phase 5 — user-scoped read of the assistant_interactions
// substrate joined with mcp_sessions. Atlas creator-entry for
// "what did I ask the AI?". Category mirrors pica_memory_* siblings.
category: "settings",
risk: "safe",
retry_safe: true,
display_name: "list your recent assistant activity with client identity",
},
pica_acknowledge_onboarding: {
category: "settings",
risk: "mutating",
retry_safe: true,
display_name: "acknowledge MCP onboarding (OAuth-arrived users only)",
},
pica_introduce_self: {
category: "settings",
risk: "mutating",
retry_safe: true,
display_name: "declare agent identity (required first call for Bearer callers)",
},
pica_outcome_log: {
category: "settings",
risk: "mutating",
retry_safe: true,
display_name: "log an agent-explicit workflow milestone",
},
pica_outcomes_recent: {
category: "settings",
risk: "safe",
retry_safe: true,
display_name: "list recent workflow outcomes for the current org",
},
pica_signup_start: {
// ADR-211 Phase 1 — agent-discoverable signup verb. Reachable in
// unauthenticated mode (lobby) on both stdio + HTTP transports.
// risk=safe because the tool itself only mints a JWT-bound URL — the
// org / trial / credentials are created by the page (Phase 2) after
// the user clicks the link and verifies email ownership.
category: "settings",
risk: "safe",
retry_safe: true,
display_name: "start a withPICA signup (sends a magic link to verify email)",
},
// ADR-210 Phase 2 — explicit billing surface
pica_subscription_status: {
category: "settings",
risk: "safe",
retry_safe: true,
display_name: "check your subscription status",
},
pica_subscription_manage: {
category: "settings",
risk: "mutating",
retry_safe: false,
display_name: "subscribe, upgrade, manage, or cancel",
},
// MPP pay rail (WS-B). risk:"safe" is the honest classification — minting a
// link mints a capability and changes nothing; the charge happens later,
// against the link, on a route of its own.
pica_billing_pay: {
category: "settings",
risk: "safe",
retry_safe: true,
display_name: "get a pay link",
},
pica_delete_my_account: {
category: "settings",
risk: "destructive",
retry_safe: false,
display_name: "delete your account",
},
pica_export_my_data: {
category: "settings",
risk: "mutating",
retry_safe: false,
display_name: "export your personal data (GDPR)",
},
// ADR-189 Phase 3 — self identity capture. Both are retry_safe
// because the writes are idempotent — re-applying the same IPI /
// ISNI leaves the row in the same final state. Rate-limited
// separately by checkActionRateLimit (20/hour per user).
pica_update_my_identity: {
category: "settings",
risk: "mutating",
retry_safe: true,
display_name: "capture your identifiers (IPI / ISNI / PRO)",
},
pica_update_organisation_profile: {
category: "settings",
risk: "mutating",
retry_safe: true,
display_name: "update your account profile",
},
// ── Agent Identity (ADR-185 Part 1) ───────────────────────────────────────
pica_create_agent_identity: {
category: "settings",
risk: "mutating",
retry_safe: false,
display_name: "create an agent identity",
},
pica_issue_agent_grant: {
category: "settings",
risk: "mutating",
retry_safe: false,
display_name: "issue an agent grant",
},
pica_list_my_agent_grants: {
category: "settings",
risk: "safe",
retry_safe: true,
display_name: "list your agent grants",
},
pica_revoke_agent_grant: {
category: "settings",
risk: "destructive",
retry_safe: false,
display_name: "revoke an agent grant",
},
pica_get_agent_activity: {
category: "settings",
risk: "safe",
retry_safe: true,
display_name: "view your agent activity",
},
// ── ADR-222 Sync Placements ───────────────────────────────────────────────
pica_sync_placements_query: {
category: "business",
risk: "safe",
retry_safe: true,
display_name: "find sync placements",
},
pica_sync_placements_inspect: {
category: "business",
risk: "safe",
retry_safe: true,
display_name: "inspect a sync placement",
},
pica_sync_placements_create: {
category: "business",
risk: "mutating",
retry_safe: false,
display_name: "create a sync placement",
},
pica_sync_placements_update: {
category: "business",
risk: "mutating",
retry_safe: false,
display_name: "update a sync placement",
},
pica_sync_placements_delete: {
category: "business",
risk: "destructive",
retry_safe: false,
display_name: "delete a sync placement",
},
pica_sync_placements_cite: {
category: "business",
risk: "mutating",
retry_safe: true,
display_name: "attach evidence to a sync placement",
},
};
/**
* Look up metadata for a tool by name.
* Returns undefined if the tool is not registered.
*/
export function getToolMetadata(name) {
return TOOL_METADATA[name];
}
// ADR-230 post-ship cleanup — the standalone `getToolTier(name)` and
// the hand-listed `DRAFT_TIER_TOOLS` set used to live here. Both have
// been removed. The declared `tier` on each tool definition (lint
// Rule 13 — required) is now the only source of truth for tier
// derivation; consumers either use `ToolRegistry.getToolTier(name)`
// or accept a `(name) => Tier | undefined` resolver as a constructor
// argument (see MyRecentQuestionsTools).
//# sourceMappingURL=metadata.js.map