ZeroWidth Compass

Search ZeroWidth product documentation. Returns matching pages with title, slug, public URL, and a query-relevant snippet. Use this when the user asks about a ZeroWidth product (Compass, Workbench, Caliper, Prism, Ledger, Napkin, zv1), an API behavior, or a policy. No authentication required — the docs corpus is public.

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "minLength": 1,
      "description": "Search query — keywords or natural-language phrase."
    },
    "limit": {
      "default": 10,
      "description": "Max number of results. Defaults to 10.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 20
    }
  },
  "required": [
    "query"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Fetch the full Markdown body of a specific docs page by its slug. Use this after `search_docs` when the user needs the complete content of a page. No authentication required.

{
  "type": "object",
  "properties": {
    "slug": {
      "type": "string",
      "minLength": 1,
      "description": "Page slug. Accepts 'compass/api', '/compass/api', or 'docs/compass/api'."
    }
  },
  "required": [
    "slug"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Enumerate all available docs pages, optionally filtered by product (e.g. 'compass', 'legal', 'overview'). Use this to discover what slugs exist before calling `get_doc`. No authentication required.

{
  "type": "object",
  "properties": {
    "product": {
      "description": "Optional product slug filter (e.g. 'compass', 'legal', 'overview').",
      "type": "string"
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Lists pages in the active workspace's Compass compendium. Optional `type` filter narrows to one node type (WORKFLOW, PERSON, SYSTEM, PAIN_POINT, DOCUMENT, VALUE, PRIORITY, AUDIENCE, OFFERING). Returns summaries, 50 at a time (`limit` / `offset`, `total` and `nextOffset` in the result) — fetch one with `compass_pages_get` for the full body. When you know what you're looking for, `compass_pages_search` is the better first call.

{
  "type": "object",
  "properties": {
    "workspace": {
      "description": "Workspace slug. Personal tokens with no default workspace MUST pass this; tokens with a default can override per call. Ignored for workspace API keys.",
      "type": "string"
    },
    "type": {
      "description": "Narrow to a specific page type (WORKFLOW, PERSON, SYSTEM, PAIN_POINT, DOCUMENT, VALUE, PRIORITY, AUDIENCE, OFFERING).",
      "type": "string"
    },
    "limit": {
      "description": "Page size, default 50. Prefer compass_pages_search when you know what you're looking for.",
      "type": "integer",
      "minimum": 1,
      "maximum": 200
    },
    "offset": {
      "description": "Skip this many, for the next page.",
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Keyword search over page titles, bodies, and tags (case-insensitive substring match), paginated. The fast way to check whether a subject already has a page before creating or linking. Returns summaries with a 300-char body snippet — fetch full text with `compass_pages_get`.

{
  "type": "object",
  "properties": {
    "workspace": {
      "description": "Workspace slug. Personal tokens with no default workspace MUST pass this; tokens with a default can override per call. Ignored for workspace API keys.",
      "type": "string"
    },
    "q": {
      "type": "string",
      "description": "Search term. Use the most distinctive word or phrase for the subject ('Zendesk', 'invoice approval') — not full sentences."
    },
    "type": {
      "description": "Narrow to one page type.",
      "type": "string",
      "minLength": 1,
      "maxLength": 40
    },
    "limit": {
      "description": "Results per page, 1-25. Default 10.",
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991
    },
    "offset": {
      "description": "Pagination offset. Default 0.",
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991
    }
  },
  "required": [
    "q"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Fetches one Compass page by id, including its full Markdown body, header fields, and any attached Napkin sketches — view an attached sketch's actual drawing with `napkin_boards_view` (its boardId) before discussing it.

{
  "type": "object",
  "properties": {
    "workspace": {
      "description": "Workspace slug. Personal tokens with no default workspace MUST pass this; tokens with a default can override per call. Ignored for workspace API keys.",
      "type": "string"
    },
    "pageId": {
      "type": "string",
      "description": "The page id (from compass_pages_list)."
    }
  },
  "required": [
    "pageId"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Creates a typed page in the workspace's Compass compendium. Check `compass_pages_list` first — don't create a page for a subject the map already has; link to it instead. May return `needs_confirmation` — if so, tell the user what you're proposing, wait for their approval, then re-call with the approvalId. Only record what the human has actually told you.

{
  "type": "object",
  "properties": {
    "visibility": {
      "description": "Who can see it: PRIVATE (only the user), WORKSPACE (every member, the default), or SHARED (specific people, granted afterwards). Say 'make it private' → PRIVATE.",
      "type": "string",
      "enum": [
        "PRIVATE",
        "WORKSPACE",
        "SHARED"
      ]
    },
    "workspace": {
      "description": "Workspace slug. Personal tokens with no default workspace MUST pass this; tokens with a default can override per call. Ignored for workspace API keys.",
      "type": "string"
    },
    "type": {
      "description": "Page type for this subject. VALUE = something the business won't sacrifice; PRIORITY = an outcome it's pushing toward; AUDIENCE = who the work is for; OFFERING = what the business delivers.",
      "type": "string",
      "minLength": 1,
      "maxLength": 40
    },
    "title": {
      "type": "string",
      "description": "≤80 chars, sentence case, no filler verbs."
    },
    "body": {
      "description": "Markdown body shaped to the type (steps for WORKFLOW, role/contact sections for PERSON, etc.).",
      "type": "string"
    },
    "tags": {
      "description": "Optional tags.",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "approvalId": {
      "description": "Approval id from a prior needs_confirmation response, after the user has approved. Omit on the first call.",
      "type": "string"
    }
  },
  "required": [
    "type",
    "title"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Edits an existing page's title, description, body, tags, header fields, or visibility — use this to FIX what you (or an extraction) got wrong instead of creating a duplicate. Fetch the current page with `compass_pages_get` first and preserve what the human wrote; title / body / tags replace the field wholesale, while `headerFields` MERGES over the current ones (send only the keys you're changing — 'set the owner' leaves status alone). Page ids come from compass_pages_list. May return `needs_confirmation` — tell the user what you're changing, wait for approval, then re-call with the approvalId.

{
  "type": "object",
  "properties": {
    "visibility": {
      "description": "Who can see it: PRIVATE (only the user), WORKSPACE (every member, the default), or SHARED (specific people, granted afterwards). Say 'make it private' → PRIVATE.",
      "type": "string",
      "enum": [
        "PRIVATE",
        "WORKSPACE",
        "SHARED"
      ]
    },
    "workspace": {
      "description": "Workspace slug. Personal tokens with no default workspace MUST pass this; tokens with a default can override per call. Ignored for workspace API keys.",
      "type": "string"
    },
    "pageId": {
      "type": "string",
      "description": "Id of the page to edit."
    },
    "title": {
      "description": "New title (≤200 chars).",
      "type": "string"
    },
    "description": {
      "description": "New one-line gallery summary (≤2,000 chars).",
      "type": "string"
    },
    "body": {
      "description": "New Markdown body — replaces the whole body.",
      "type": "string"
    },
    "tags": {
      "description": "New tag set — replaces existing tags.",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "headerFields": {
      "description": "Partial header fields for the page's type (PERSON: role, email, …; WORKFLOW: owner, status, …) — merged over the current values; the server validates the merged result against the type.",
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {}
    },
    "approvalId": {
      "description": "Approval id from a prior needs_confirmation response, after the user has approved. Omit on the first call.",
      "type": "string"
    }
  },
  "required": [
    "pageId"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Creates a typed, directed edge between two pages — the knowledge graph's connective tissue. Canonical directions: PERSON owns WORKFLOW/SYSTEM, PERSON involved_in WORKFLOW, WORKFLOW uses SYSTEM, SYSTEM uses SYSTEM, PAIN_POINT affects WORKFLOW/SYSTEM/PERSON, DOCUMENT documents anything, relates_to as fallback. Idempotent on (from, to, kind) — re-creating an existing edge returns it. May return `needs_confirmation`; tell the user what you're proposing, wait for their approval, then re-call with the approvalId.

{
  "type": "object",
  "properties": {
    "workspace": {
      "description": "Workspace slug. Personal tokens with no default workspace MUST pass this; tokens with a default can override per call. Ignored for workspace API keys.",
      "type": "string"
    },
    "fromPageId": {
      "type": "string",
      "description": "Edge source page id."
    },
    "toPageId": {
      "type": "string",
      "description": "Edge target page id."
    },
    "kind": {
      "type": "string",
      "enum": [
        "owns",
        "involved_in",
        "uses",
        "serves",
        "delivers",
        "affects",
        "documents",
        "relates_to"
      ],
      "description": "Edge type, in canonical direction."
    },
    "note": {
      "description": "≤500-char qualifier when the kind alone undersells it.",
      "type": "string"
    },
    "source": {
      "description": "Provenance label. Defaults AI_ACCEPTED (agent writing under live human direction); pass USER for human-driven scripts.",
      "type": "string",
      "enum": [
        "USER",
        "AI_ACCEPTED"
      ]
    },
    "approvalId": {
      "description": "Approval id from a prior needs_confirmation response, after the user has approved. Omit on the first call.",
      "type": "string"
    }
  },
  "required": [
    "fromPageId",
    "toPageId",
    "kind"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

All typed edges touching one page, both directions, each hydrated with the other endpoint's page summary. Use this to understand a subject's neighborhood before adding to it.

{
  "type": "object",
  "properties": {
    "workspace": {
      "description": "Workspace slug. Personal tokens with no default workspace MUST pass this; tokens with a default can override per call. Ignored for workspace API keys.",
      "type": "string"
    },
    "pageId": {
      "type": "string",
      "description": "The page id."
    }
  },
  "required": [
    "pageId"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Mints a stakeholder-interview invite: a no-account guest link where the person talks to an interviewer agent briefed by your focusPrompt, and the transcript flows back into Compass as reviewable draft pages. THE KNOWLEDGE-GAP MOVE: when caliper_flow_performance shows failures clustered on missing company facts (the judge says the flow invented a policy, missed a rule, didn't know who owns something), the fix is usually not a prompt edit — it's asking the human who actually knows. Write a focusPrompt that names the SPECIFIC gaps (cite the eval run id), pick the owner of the relevant workflow as interviewee when the map knows one, and hand the user the invite link to forward. May return `needs_confirmation` — tell the user who you want to interview and why, then wait.

{
  "type": "object",
  "properties": {
    "workspace": {
      "description": "Workspace slug. Personal tokens with no default workspace MUST pass this; tokens with a default can override per call. Ignored for workspace API keys.",
      "type": "string"
    },
    "focusPrompt": {
      "type": "string",
      "description": "What the interviewer should dig into — specific, grounded in the gap you found (≤2000 chars). Never shown verbatim to the guest."
    },
    "intervieweeName": {
      "description": "Who this invite is for, when known.",
      "type": "string"
    },
    "intervieweeEmail": {
      "description": "Their email, when known — enables compass_interview_invite to send the link directly (with approval).",
      "type": "string"
    },
    "contextPageIds": {
      "description": "Compass page ids the interviewer gets as briefing context (e.g. the workflow page whose flow underperformed).",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "approvalId": {
      "description": "Approval id from a prior needs_confirmation response, after the user has approved. Omit on the first call.",
      "type": "string"
    }
  },
  "required": [
    "focusPrompt"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Ranks the PEOPLE the map says know about a page (workflow, system, pain point): `owns` links first, then `involved_in`, then weaker edges. Each target carries contact email + role from their PERSON page and their latest interview (skip someone who just gave one — interview fatigue is real). Empty result = the map doesn't know an owner: ASK THE USER who runs this, create the PERSON page + owns link from the answer, and the map gets smarter. Use before compass_interviews_create to pick the interviewee.

{
  "type": "object",
  "properties": {
    "pageId": {
      "type": "string",
      "description": "The page the knowledge gap is about."
    },
    "workspace": {
      "description": "Workspace slug. Personal tokens with no default workspace MUST pass this; tokens with a default can override per call. Ignored for workspace API keys.",
      "type": "string"
    }
  },
  "required": [
    "pageId"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Emails the guest link for an existing interview, framed as coming from the REQUESTING USER (their name signs it; replies go to them). Author `message` in their voice — short, human, says why THEIR knowledge matters and that it takes ~15 minutes, no account needed. The approval card shows the exact subject + message before anything sends. Limit: the invite plus ONE reminder; a third ask is the user's conversation to have. Completion arrives as a notification with draft-page counts — don't poll.

{
  "type": "object",
  "properties": {
    "interviewId": {
      "type": "string",
      "description": "Interview id from compass_interviews_create."
    },
    "email": {
      "type": "string",
      "description": "The interviewee's email address."
    },
    "subject": {
      "type": "string",
      "description": "Email subject, e.g. '15 minutes on how refunds actually work?'"
    },
    "message": {
      "type": "string",
      "description": "The body, written in the requesting user's voice. Greeting + link + signature are added automatically — write only the middle."
    },
    "workspace": {
      "description": "Workspace slug. Personal tokens with no default workspace MUST pass this; tokens with a default can override per call. Ignored for workspace API keys.",
      "type": "string"
    },
    "approvalId": {
      "description": "Approval id from a prior needs_confirmation response, after the user has approved. Omit on the first call.",
      "type": "string"
    }
  },
  "required": [
    "interviewId",
    "email",
    "subject",
    "message"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Lists the workspace's open questions — the gap registry: what the map doesn't know yet. Defaults to OPEN gaps. This is where you keep your head — check it before asking the user something you may already have flagged, and compose interview briefs from a subject's open questions.

{
  "type": "object",
  "properties": {
    "workspace": {
      "description": "Workspace slug. Personal tokens with no default workspace MUST pass this; tokens with a default can override per call. Ignored for workspace API keys.",
      "type": "string"
    },
    "status": {
      "description": "Filter by lifecycle stage. Default OPEN.",
      "type": "string",
      "enum": [
        "OPEN",
        "INTERVIEW_SENT",
        "ANSWERED",
        "DISMISSED"
      ]
    },
    "subjectType": {
      "description": "Only gaps ABOUT this subject type (e.g. compass_page).",
      "type": "string"
    },
    "subjectId": {
      "description": "Only gaps ABOUT this subject id.",
      "type": "string"
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Records something you don't yet know — the gap registry is your working memory, so use it liberally while mapping or interviewing. Give one clear question, WHY it matters (what answering it unblocks), and how you'd resolve it (ask the user / interview a specific person / connect a source). No approval needed — noting your own uncertainty isn't acting on the user's behalf. Attach it to a subject (subjectType/subjectId) when it's ABOUT a specific page or person.

{
  "type": "object",
  "properties": {
    "workspace": {
      "description": "Workspace slug. Personal tokens with no default workspace MUST pass this; tokens with a default can override per call. Ignored for workspace API keys.",
      "type": "string"
    },
    "question": {
      "type": "string",
      "description": "The open question, plainly ('Who approves refunds over $500?')."
    },
    "rationale": {
      "description": "Why it matters / what answering it unblocks.",
      "type": "string"
    },
    "suggestedResolution": {
      "description": "How to resolve it: 'ask the user', 'interview Dana', 'connect Drive'.",
      "type": "string"
    },
    "subjectType": {
      "description": "What it's about, e.g. compass_page.",
      "type": "string"
    },
    "subjectId": {
      "description": "Id of the subject.",
      "type": "string"
    }
  },
  "required": [
    "question"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Closes a gap once you've learned the answer (ANSWERED, with the resolution) or decided it doesn't matter (DISMISSED). Keep the registry honest — resolve gaps as their answers land (from an interview, a doc, or the user) so it always reflects what's still unknown. Gaps you raised close without a card; a question a person wrote needs their approval.

{
  "type": "object",
  "properties": {
    "approvalId": {
      "description": "Re-call with the approvalId from a needs_confirmation response after the user approves.",
      "type": "string"
    },
    "workspace": {
      "description": "Workspace slug. Personal tokens with no default workspace MUST pass this; tokens with a default can override per call. Ignored for workspace API keys.",
      "type": "string"
    },
    "gapId": {
      "type": "string",
      "description": "Id of the gap (from compass_gaps_list)."
    },
    "status": {
      "type": "string",
      "enum": [
        "ANSWERED",
        "DISMISSED"
      ],
      "description": "ANSWERED (you learned it) or DISMISSED (irrelevant)."
    },
    "resolution": {
      "description": "The answer / note, when marking ANSWERED.",
      "type": "string"
    }
  },
  "required": [
    "gapId",
    "status"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

The workspace's changes — fixes, chores, new steps, experiments. Each carries `statusName` (the workspace's own word for where it is) and `statusCategory` (TRIAGE undecided, BACKLOG not started, ACTIVE in progress, DONE, CANCELED dropped), plus the older lane key in `status`. `experiment: true` marks a change measured against the Ledger: `ledgerEntryId` null means no expectation registered; `ledger.verdict` carries confirmed/missed after settlement. Scores (value/feasibility/risk) and a workflow anchor are optional. Filter by lane key in `status` or by workflowPageId; compass_statuses_list has the status names.

{
  "type": "object",
  "properties": {
    "workspace": {
      "description": "Workspace slug. Personal tokens with no default workspace MUST pass this; tokens with a default can override per call. Ignored for workspace API keys.",
      "type": "string"
    },
    "status": {
      "description": "Filter to one lane.",
      "type": "string",
      "enum": [
        "NEW",
        "QUALIFYING",
        "BACKLOG",
        "EXPERIMENTING",
        "SETTLED",
        "REJECTED"
      ]
    },
    "workflowPageId": {
      "description": "Only opportunities anchored to this workflow page.",
      "type": "string"
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

File an AI-PROPOSED opportunity into the workspace's review queue — the scouting verb (the opportunity-scout routine's main move). Unlike compass_opportunities_create this needs NO approval: the proposal itself is the human gate — it lands in the Compass Inbox and the cockpit's Needs-you for accept/dismiss. Check compass_opportunities_list first so you never duplicate an idea. Anchor to a workflow page when one fits; score value/feasibility/risk 1–5.

{
  "type": "object",
  "properties": {
    "workspace": {
      "description": "Workspace slug. Personal tokens with no default workspace MUST pass this; tokens with a default can override per call. Ignored for workspace API keys.",
      "type": "string"
    },
    "label": {
      "type": "string",
      "description": "≤200 chars, the opportunity in one line."
    },
    "description": {
      "type": "string",
      "description": "What it is and why it's worth trying, grounded in the map."
    },
    "workflowPageId": {
      "description": "Workflow page to anchor to, when one fits.",
      "type": "string"
    },
    "valueScore": {
      "type": "integer",
      "minimum": 1,
      "maximum": 5
    },
    "feasibilityScore": {
      "type": "integer",
      "minimum": 1,
      "maximum": 5
    },
    "riskScore": {
      "type": "integer",
      "minimum": 1,
      "maximum": 5
    },
    "reasoning": {
      "description": "One or two sentences on why you're proposing this.",
      "type": "string"
    }
  },
  "required": [
    "label",
    "description"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Record a change — a fix, a chore, a new step, or an experiment worth trying. Anchor it to a workflow page when one fits (compass_pages_list); leave unanchored otherwise. It lands in the board's first status unless you name another (compass_statuses_list). Set `experiment` only when the user wants it measured against the Ledger. May return `needs_confirmation` — summarize and wait for approval.

{
  "type": "object",
  "properties": {
    "workspace": {
      "description": "Workspace slug. Personal tokens with no default workspace MUST pass this; tokens with a default can override per call. Ignored for workspace API keys.",
      "type": "string"
    },
    "label": {
      "type": "string",
      "description": "≤200 chars, the change in one line."
    },
    "description": {
      "description": "What the change is, and why it's worth doing.",
      "type": "string"
    },
    "workflowPageId": {
      "description": "Workflow page to anchor to, when one fits.",
      "type": "string"
    },
    "statusName": {
      "description": "Start in this status (a name from compass_statuses_list).",
      "type": "string"
    },
    "experiment": {
      "description": "Measure it against the Ledger. Default false.",
      "type": "boolean"
    },
    "tags": {
      "description": "Tags to file it under.",
      "maxItems": 20,
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "links": {
      "description": "Where the work also lives — issue, ticket, PR or doc URLs.",
      "maxItems": 10,
      "type": "array",
      "items": {
        "type": "string",
        "format": "uri"
      }
    },
    "approvalId": {
      "description": "Approval id from a prior needs_confirmation response, after the user has approved. Omit on the first call.",
      "type": "string"
    }
  },
  "required": [
    "label"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

The honesty mechanism: write what the experiment is expected to change BEFORE evidence exists. Creates a Ledger decision entry and links it to the opportunity — never backfill an expectation to match an outcome. Bind a metric (ledger_metrics_list) + comparator + target when the expectation is measurable; readings then land on the entry as evidence automatically. One expectation per opportunity — revise by superseding in Ledger. May return `needs_confirmation`.

{
  "type": "object",
  "properties": {
    "workspace": {
      "description": "Workspace slug. Personal tokens with no default workspace MUST pass this; tokens with a default can override per call. Ignored for workspace API keys.",
      "type": "string"
    },
    "opportunityId": {
      "type": "string",
      "description": "The change's key (e.g. ACME-12) or id, from compass_opportunities_list."
    },
    "expectation": {
      "type": "string",
      "description": "One sentence — what we expect this to change."
    },
    "deadline": {
      "description": "ISO date the expectation is due by.",
      "type": "string"
    },
    "metricId": {
      "description": "Ledger metric to bind (requires target). From ledger_metrics_list.",
      "type": "string"
    },
    "comparator": {
      "type": "string",
      "enum": [
        ">=",
        "<=",
        ">",
        "<",
        "="
      ]
    },
    "target": {
      "description": "Target value, in the metric's unit.",
      "type": "number"
    },
    "approvalId": {
      "description": "Approval id from a prior needs_confirmation response, after the user has approved. Omit on the first call.",
      "type": "string"
    }
  },
  "required": [
    "opportunityId",
    "expectation"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

The measurement window's boundary: when the user says the experiment's change actually shipped / went live / rolled out, record the landing date. Readings before it are baseline; after it, evidence of effect. Recorded once — it cannot move afterward, so confirm the date. Attaches to the linked Ledger entry as evidence. May return `needs_confirmation`.

{
  "type": "object",
  "properties": {
    "workspace": {
      "description": "Workspace slug. Personal tokens with no default workspace MUST pass this; tokens with a default can override per call. Ignored for workspace API keys.",
      "type": "string"
    },
    "opportunityId": {
      "type": "string",
      "description": "The change's key (e.g. ACME-12) or id, from compass_opportunities_list."
    },
    "at": {
      "description": "ISO date the change landed — omit for today.",
      "type": "string"
    },
    "note": {
      "description": "What shipped, if worth recording.",
      "type": "string",
      "maxLength": 1000
    },
    "approvalId": {
      "description": "Approval id from a prior needs_confirmation response, after the user has approved. Omit on the first call.",
      "type": "string"
    }
  },
  "required": [
    "opportunityId"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Renders the workspace's visual map to an image and returns it so you can SEE it the way the user does: an isometric drawing where every page is a structure whose shape is its type — people are figures, audiences are crowds, workflows are gears lying on the ground, systems are database drums, offerings are price tags, pain points are warning signs, documents are standing sheets of paper, values are shields, priorities are flags — sized by how many other pages connect to them, placed near what they link to, with pages connected to nothing parked to one side, and routes drawn between linked pages. A coloured ring on the ground around a page shows the changes touching it by stage (blue undecided, amber not started, green in progress, violet done; thicker = more), with a key in the top-left corner. Use this when the user asks about the shape of their map, where the problems are, what connects to what, or anything spatial. The text part counts the pages of each type, the links, and how many pages are unconnected, plus `mapUrl`. The image is for you to look at; do NOT put it in your reply as a markdown image (the chat can't show it). When the user should see the map, link `mapUrl` — e.g. `[Open your map](mapUrl)` — and describe what you saw.

{
  "type": "object",
  "properties": {
    "workspace": {
      "description": "Workspace slug. Personal tokens with no default workspace MUST pass this; tokens with a default can override per call. Ignored for workspace API keys.",
      "type": "string"
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Moves a page to the trash (soft delete — its connections and anchored opportunities go with it, and compass_pages_restore brings the whole set back). Use this to REMOVE a page you or an extraction created wrongly, or one the user says no longer belongs on the map; to fix a wrong title or body, use compass_pages_update instead. Page ids come from compass_pages_list / compass_pages_search. May return `needs_confirmation` — name the page and wait for approval.

{
  "type": "object",
  "properties": {
    "workspace": {
      "description": "Workspace slug. Personal tokens with no default workspace MUST pass this; tokens with a default can override per call. Ignored for workspace API keys.",
      "type": "string"
    },
    "pageId": {
      "type": "string",
      "description": "Id of the page to delete."
    },
    "approvalId": {
      "description": "Approval id from a prior needs_confirmation response, after the user has approved. Omit on the first call.",
      "type": "string"
    }
  },
  "required": [
    "pageId"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Puts a trashed page back on the map, together with exactly the connections and opportunities its delete took. Use when the user wants a deleted page back (the pageId from the earlier compass_pages_delete, or from the Compass trash). Fails with not_found when the page is already live or never existed. May return `needs_confirmation`.

{
  "type": "object",
  "properties": {
    "workspace": {
      "description": "Workspace slug. Personal tokens with no default workspace MUST pass this; tokens with a default can override per call. Ignored for workspace API keys.",
      "type": "string"
    },
    "pageId": {
      "type": "string",
      "description": "Id of the deleted page."
    },
    "approvalId": {
      "description": "Approval id from a prior needs_confirmation response, after the user has approved. Omit on the first call.",
      "type": "string"
    }
  },
  "required": [
    "pageId"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Edits an existing edge between two pages: its `kind` (how the two relate) and/or its `note`. Use to CORRECT a connection typed wrongly — 'Dana doesn't own billing, she's involved in it'. Link ids come from compass_page_links_list. Fails with conflict when the new reading already exists between the same two pages (delete this one instead). May return `needs_confirmation`.

{
  "type": "object",
  "properties": {
    "workspace": {
      "description": "Workspace slug. Personal tokens with no default workspace MUST pass this; tokens with a default can override per call. Ignored for workspace API keys.",
      "type": "string"
    },
    "linkId": {
      "type": "string",
      "description": "Id of the link (from compass_page_links_list)."
    },
    "kind": {
      "description": "New edge type, in canonical direction.",
      "type": "string",
      "enum": [
        "owns",
        "involved_in",
        "uses",
        "serves",
        "delivers",
        "affects",
        "documents",
        "relates_to"
      ]
    },
    "note": {
      "description": "New qualifier note (≤500 chars); empty string clears it.",
      "type": "string",
      "maxLength": 500
    },
    "approvalId": {
      "description": "Approval id from a prior needs_confirmation response, after the user has approved. Omit on the first call.",
      "type": "string"
    }
  },
  "required": [
    "linkId"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Deletes one edge from the graph (the pages stay). Use when a connection is simply wrong — the system isn't used by that workflow, the person left the team. Link ids come from compass_page_links_list. Re-creating the same edge later revives it. May return `needs_confirmation`.

{
  "type": "object",
  "properties": {
    "workspace": {
      "description": "Workspace slug. Personal tokens with no default workspace MUST pass this; tokens with a default can override per call. Ignored for workspace API keys.",
      "type": "string"
    },
    "linkId": {
      "type": "string",
      "description": "Id of the link (from compass_page_links_list)."
    },
    "approvalId": {
      "description": "Approval id from a prior needs_confirmation response, after the user has approved. Omit on the first call.",
      "type": "string"
    }
  },
  "required": [
    "linkId"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Corrects an opportunity's content: label, description, priority, what done means, the 1–5 value / feasibility / risk scores, the owner (a PERSON page), notes, tags, workflow anchor, external link, visibility. Fields you omit are untouched; the lane is NOT here — move it with compass_opportunities_set_status. Opportunity ids come from compass_opportunities_list. May return `needs_confirmation` — say what you're changing and wait.

{
  "type": "object",
  "properties": {
    "workspace": {
      "description": "Workspace slug. Personal tokens with no default workspace MUST pass this; tokens with a default can override per call. Ignored for workspace API keys.",
      "type": "string"
    },
    "opportunityId": {
      "type": "string",
      "description": "The change's key (e.g. ACME-12) or id, from compass_opportunities_list."
    },
    "label": {
      "description": "New one-line label (2–200 chars).",
      "type": "string"
    },
    "description": {
      "description": "New description (≤5,000 chars).",
      "type": "string"
    },
    "valueScore": {
      "type": "integer",
      "minimum": 1,
      "maximum": 5
    },
    "feasibilityScore": {
      "type": "integer",
      "minimum": 1,
      "maximum": 5
    },
    "riskScore": {
      "type": "integer",
      "minimum": 1,
      "maximum": 5
    },
    "ownerPageId": {
      "description": "PERSON page id who owns the work; null clears.",
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "workflowPageId": {
      "description": "Workflow page to anchor to; null un-anchors.",
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "externalUrl": {
      "description": "Where the doing happens off-platform (URL); null clears.",
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "qualitativeNotes": {
      "description": "Free-form notes (≤20,000 chars) — replaces the current notes.",
      "type": "string"
    },
    "tags": {
      "description": "New tag set — replaces existing tags.",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "assignee": {
      "description": "The workspace member doing the work, by email or user id; null unassigns. They're notified.",
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "experiment": {
      "description": "Measure it against the Ledger (expectation when it starts, verdict when it's done).",
      "type": "boolean"
    },
    "priority": {
      "description": "How soon it matters; null clears it, and the map's suggestion shows again.",
      "anyOf": [
        {
          "type": "string",
          "enum": [
            "URGENT",
            "HIGH",
            "MEDIUM",
            "LOW"
          ]
        },
        {
          "type": "null"
        }
      ]
    },
    "doneWhen": {
      "description": "What's true when it's done, that someone else could check (≤1,000 chars).",
      "type": "string"
    },
    "visibility": {
      "description": "Who can see it: PRIVATE (only the user), WORKSPACE (every member, the default), or SHARED (specific people, granted afterwards). Say 'make it private' → PRIVATE.",
      "type": "string",
      "enum": [
        "PRIVATE",
        "WORKSPACE",
        "SHARED"
      ]
    },
    "approvalId": {
      "description": "Approval id from a prior needs_confirmation response, after the user has approved. Omit on the first call.",
      "type": "string"
    }
  },
  "required": [
    "opportunityId"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Removes an opportunity from the pipeline (soft delete). For an AI proposal the user doesn't want, this is the dismiss verb; for a captured experiment that was a duplicate or a mistake, the remove verb. To conclude a real experiment without evidence, prefer compass_opportunities_set_status REJECTED — that keeps the record. Ids come from compass_opportunities_list. May return `needs_confirmation`.

{
  "type": "object",
  "properties": {
    "workspace": {
      "description": "Workspace slug. Personal tokens with no default workspace MUST pass this; tokens with a default can override per call. Ignored for workspace API keys.",
      "type": "string"
    },
    "opportunityId": {
      "type": "string",
      "description": "The change's key (e.g. ACME-12) or id, from compass_opportunities_list."
    },
    "approvalId": {
      "description": "Approval id from a prior needs_confirmation response, after the user has approved. Omit on the first call.",
      "type": "string"
    }
  },
  "required": [
    "opportunityId"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

The review verb for the Inbox: promotes an AI-PROPOSED opportunity (from compass_opportunities_propose or the opportunity scout) into the workspace's own pipeline. compass_opportunities_set_status does NOT do this — a proposal stays in the Inbox until accepted. Optional `status` decides its lane in the same step (BACKLOG to park it, EXPERIMENTING to start it); omitted, it lands in NEW. Fails with not_proposed when the row isn't an AI proposal. Ids come from compass_inbox_list / compass_opportunities_list. May return `needs_confirmation` — name the proposal and wait.

{
  "type": "object",
  "properties": {
    "workspace": {
      "description": "Workspace slug. Personal tokens with no default workspace MUST pass this; tokens with a default can override per call. Ignored for workspace API keys.",
      "type": "string"
    },
    "opportunityId": {
      "type": "string",
      "description": "The AI-proposed opportunity's id."
    },
    "status": {
      "description": "Lane to place it in on accept (default NEW).",
      "type": "string",
      "enum": [
        "NEW",
        "QUALIFYING",
        "BACKLOG",
        "EXPERIMENTING",
        "SETTLED",
        "REJECTED"
      ]
    },
    "approvalId": {
      "description": "Approval id from a prior needs_confirmation response, after the user has approved. Omit on the first call.",
      "type": "string"
    }
  },
  "required": [
    "opportunityId"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Every stakeholder interview in the workspace, newest first: who was invited, status (INVITED / IN_PROGRESS / COMPLETED), focus, message count, whether the transcript was already reviewed (documentPageId set), and the invite URL while the link is still live. Check this before inviting someone again — interview fatigue is real — and to answer 'who have we already asked?'. Read one in full with compass_interviews_get.

{
  "type": "object",
  "properties": {
    "workspace": {
      "description": "Workspace slug. Personal tokens with no default workspace MUST pass this; tokens with a default can override per call. Ignored for workspace API keys.",
      "type": "string"
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

One interview in full — metadata plus the transcript of what the guest actually said. Read this before summarizing an interview or drafting pages from it: the transcript is the source you work from, and your compass skill has the rules for typing and splitting what's in it. Ids come from compass_interviews_list or compass_inbox_list.

{
  "type": "object",
  "properties": {
    "workspace": {
      "description": "Workspace slug. Personal tokens with no default workspace MUST pass this; tokens with a default can override per call. Ignored for workspace API keys.",
      "type": "string"
    },
    "interviewId": {
      "type": "string",
      "description": "Interview id (from compass_interviews_list)."
    }
  },
  "required": [
    "interviewId"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Kills an interview's invite link — the guest's next visit sees that the link is no longer active. Use when an invite went to the wrong person, the user changed their mind, or the link leaked. Idempotent. Ids come from compass_interviews_list. May return `needs_confirmation`.

{
  "type": "object",
  "properties": {
    "workspace": {
      "description": "Workspace slug. Personal tokens with no default workspace MUST pass this; tokens with a default can override per call. Ignored for workspace API keys.",
      "type": "string"
    },
    "interviewId": {
      "type": "string",
      "description": "Interview id (from compass_interviews_list)."
    },
    "approvalId": {
      "description": "Approval id from a prior needs_confirmation response, after the user has approved. Omit on the first call.",
      "type": "string"
    }
  },
  "required": [
    "interviewId"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

The Compass Inbox in one read: finished interviews awaiting review (transcript in, not yet turned into pages), AI-proposed opportunities awaiting accept / dismiss, and the caller's pending approval cards for Compass writes. THE place to answer 'what needs me?' for the map. Next moves: compass_interviews_get to read a transcript, then propose pages from it with compass_pages_create; compass_opportunities_accept or compass_opportunities_delete for a proposal.

{
  "type": "object",
  "properties": {
    "workspace": {
      "description": "Workspace slug. Personal tokens with no default workspace MUST pass this; tokens with a default can override per call. Ignored for workspace API keys.",
      "type": "string"
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Edits an open question's wording, rationale, or suggested resolution — for sharpening a vague question or fixing one you phrased badly. Closing a gap is compass_gaps_resolve, not this. Gap ids come from compass_gaps_list. May return `needs_confirmation`.

{
  "type": "object",
  "properties": {
    "workspace": {
      "description": "Workspace slug. Personal tokens with no default workspace MUST pass this; tokens with a default can override per call. Ignored for workspace API keys.",
      "type": "string"
    },
    "gapId": {
      "type": "string",
      "description": "Id of the gap (from compass_gaps_list)."
    },
    "question": {
      "description": "New wording of the question.",
      "type": "string"
    },
    "rationale": {
      "description": "Why it matters / what answering it unblocks.",
      "type": "string"
    },
    "suggestedResolution": {
      "description": "How to resolve it: 'ask the user', 'interview Dana', 'connect Drive'.",
      "type": "string"
    },
    "approvalId": {
      "description": "Approval id from a prior needs_confirmation response, after the user has approved. Omit on the first call.",
      "type": "string"
    }
  },
  "required": [
    "gapId"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

The statuses this workspace's changes move through, in board order — the names people use. Each sits in a group: Undecided (TRIAGE), Not started (BACKLOG), In progress (ACTIVE), Done (DONE), Dropped (CANCELED). Groups are stable across workspaces; names aren't, so use the names when talking to people and the groups when reasoning about progress. Move a change with compass_opportunities_set_status.

{
  "type": "object",
  "properties": {
    "workspace": {
      "description": "Workspace slug. Personal tokens with no default workspace MUST pass this; tokens with a default can override per call. Ignored for workspace API keys.",
      "type": "string"
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Move a change to one of the workspace's statuses, by name (compass_statuses_list has them — e.g. "In review"). The old lane keys (NEW / QUALIFYING / BACKLOG / EXPERIMENTING / SETTLED / REJECTED) still work and land on that lane's default status. Only changes marked as experiments follow the Ledger: when an experiment enters an In progress status with no registered expectation, offer compass_opportunities_register_expectation; when it enters Done with its Ledger entry still open, offer ledger_entries_settle. Other changes just move. May return `needs_confirmation`.

{
  "type": "object",
  "properties": {
    "workspace": {
      "description": "Workspace slug. Personal tokens with no default workspace MUST pass this; tokens with a default can override per call. Ignored for workspace API keys.",
      "type": "string"
    },
    "opportunityId": {
      "type": "string",
      "description": "The change's key (e.g. ACME-12) or id, from compass_opportunities_list."
    },
    "statusName": {
      "description": "A status name from compass_statuses_list. Use this or `status`.",
      "type": "string"
    },
    "status": {
      "description": "A lane key. Use this or `statusName`.",
      "type": "string",
      "enum": [
        "NEW",
        "QUALIFYING",
        "BACKLOG",
        "EXPERIMENTING",
        "SETTLED",
        "REJECTED"
      ]
    },
    "approvalId": {
      "description": "Approval id from a prior needs_confirmation response, after the user has approved. Omit on the first call.",
      "type": "string"
    }
  },
  "required": [
    "opportunityId"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Create or update up to 100 changes in one call, each matched by `url` — the GitHub issue, Linear or Jira ticket, PR or doc it mirrors. A url already linked to a change updates that change (label, description, status, tags, experiment, workflow — omitted fields are left alone); any other url creates a change with that link. Run it again with the same urls to keep Compass in step; nothing duplicates. Statuses are by name (compass_statuses_list). Returns one result per item — created / updated with the change's key, or failed with why; a failed item doesn't stop the rest. Summarize what you're about to bring in before calling. May return `needs_confirmation` — one approval covers the whole batch.

{
  "type": "object",
  "properties": {
    "workspace": {
      "description": "Workspace slug. Personal tokens with no default workspace MUST pass this; tokens with a default can override per call. Ignored for workspace API keys.",
      "type": "string"
    },
    "items": {
      "minItems": 1,
      "maxItems": 100,
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "url": {
            "type": "string",
            "maxLength": 2000,
            "format": "uri"
          },
          "linkTitle": {
            "type": "string",
            "maxLength": 300
          },
          "label": {
            "type": "string",
            "minLength": 2,
            "maxLength": 200
          },
          "description": {
            "type": "string",
            "maxLength": 5000
          },
          "statusName": {
            "type": "string",
            "minLength": 1,
            "maxLength": 40
          },
          "tags": {
            "maxItems": 50,
            "type": "array",
            "items": {
              "type": "string",
              "minLength": 1,
              "maxLength": 40,
              "pattern": "^[a-zA-Z0-9](?:[a-zA-Z0-9 -]*[a-zA-Z0-9])?$"
            }
          },
          "experiment": {
            "type": "boolean"
          },
          "workflowPageId": {
            "anyOf": [
              {
                "type": "string",
                "minLength": 1
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "required": [
          "url",
          "label"
        ]
      }
    },
    "approvalId": {
      "description": "Approval id from a prior needs_confirmation response, after the user has approved.",
      "type": "string"
    }
  },
  "required": [
    "items"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Lists the comment threads on one workspace entity (open first, then resolved) with authors and timestamps. Read this before weighing in on contested work — the threads are where disagreement lives before it becomes a decision.

{
  "type": "object",
  "properties": {
    "entityKind": {
      "type": "string",
      "enum": [
        "workbench_flow",
        "compass_page",
        "compass_opportunity",
        "caliper_review",
        "caliper_dataset",
        "caliper_rubric",
        "caliper_eval",
        "caliper_spec",
        "napkin_board",
        "napkin_diagram",
        "napkin_doc",
        "napkin_sheet",
        "napkin_interface",
        "ledger_entry",
        "prism_field",
        "workspace_file"
      ],
      "description": "What the thread hangs on."
    },
    "entityId": {
      "type": "string",
      "minLength": 1,
      "maxLength": 60
    },
    "workspace": {
      "description": "Workspace slug. Personal tokens with no default workspace MUST pass this; tokens with a default can override per call. Ignored for workspace API keys.",
      "type": "string"
    }
  },
  "required": [
    "entityKind",
    "entityId"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Posts a comment on a workspace entity — a new thread, or a reply when rootId is given. Use it to leave findings where the discussion already lives (an eval result on the flow being debated, a summary on a long thread). Mention people via mentionedUserIds (from workspace member ids) to ring their notification bell; never mention someone who didn't ask to be pulled in.

{
  "type": "object",
  "properties": {
    "entityKind": {
      "type": "string",
      "enum": [
        "workbench_flow",
        "compass_page",
        "compass_opportunity",
        "caliper_review",
        "caliper_dataset",
        "caliper_rubric",
        "caliper_eval",
        "caliper_spec",
        "napkin_board",
        "napkin_diagram",
        "napkin_doc",
        "napkin_sheet",
        "napkin_interface",
        "ledger_entry",
        "prism_field",
        "workspace_file"
      ],
      "description": "What the thread hangs on."
    },
    "entityId": {
      "type": "string",
      "minLength": 1,
      "maxLength": 60
    },
    "body": {
      "type": "string",
      "minLength": 1,
      "maxLength": 10000
    },
    "rootId": {
      "description": "Reply into this thread; omit to start a new one.",
      "type": "string"
    },
    "mentionedUserIds": {
      "maxItems": 20,
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "workspace": {
      "description": "Workspace slug. Personal tokens with no default workspace MUST pass this; tokens with a default can override per call. Ignored for workspace API keys.",
      "type": "string"
    },
    "approvalId": {
      "type": "string"
    }
  },
  "required": [
    "entityKind",
    "entityId",
    "body"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Sets a comment thread's resolved state (rootId = the thread's root comment id). Resolve ONLY when the human asked or the thread's question is demonstrably settled — and say what settled it in a reply first. Reopening is for new evidence.

{
  "type": "object",
  "properties": {
    "rootId": {
      "type": "string",
      "minLength": 1,
      "maxLength": 60
    },
    "resolved": {
      "type": "boolean"
    },
    "workspace": {
      "description": "Workspace slug. Personal tokens with no default workspace MUST pass this; tokens with a default can override per call. Ignored for workspace API keys.",
      "type": "string"
    },
    "approvalId": {
      "type": "string"
    }
  },
  "required": [
    "rootId",
    "resolved"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Finds entities across every tool by name in one call — Workbench flows, Compass pages, Caliper datasets, evals, rubrics, reviews, specs and sources (apps sending agent traces), Ledger entries, Napkin sketches and decks. Use it FIRST when the user names something without saying where it lives ('the onboarding flow', 'that invoice page'); reach for a tool's own list only when you already know the tool. Each hit carries its id, kind, and workspace-relative path, so the id feeds the matching *_get tool and the path makes a link. Results only include what the user can see, and only kinds this token may read.

{
  "type": "object",
  "properties": {
    "q": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200,
      "description": "Case-insensitive substring matched against names/titles."
    },
    "kinds": {
      "description": "Restrict to these kinds (flow, page, dataset, eval, entry, board). Omit to search everything.",
      "minItems": 1,
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "flow",
          "page",
          "dataset",
          "eval",
          "entry",
          "board",
          "file",
          "shim",
          "knowledge_base",
          "task",
          "rubric",
          "review",
          "spec",
          "source"
        ]
      }
    },
    "limit": {
      "default": 20,
      "type": "integer",
      "minimum": 1,
      "maximum": 50
    },
    "workspace": {
      "description": "Workspace slug. Personal tokens with no default workspace MUST pass this; tokens with a default can override per call. Ignored for workspace API keys.",
      "type": "string"
    }
  },
  "required": [
    "q"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Returns the tags on a batch of entities of one kind — the labels galleries organize by. Ids come from the kind's list/get tool or from search_workspace. Use it before entity_tags_set so you replace the full set knowingly, and to answer 'what is this filed under'. Entities the user can't see are omitted.

{
  "type": "object",
  "properties": {
    "entityKind": {
      "type": "string",
      "enum": [
        "workbench_flow",
        "workbench_task",
        "workbench_kb",
        "compass_page",
        "compass_opportunity",
        "caliper_dataset",
        "caliper_rubric",
        "caliper_eval",
        "caliper_review",
        "caliper_spec",
        "caliper_source",
        "ledger_entry",
        "ledger_metric",
        "napkin_board",
        "napkin_deck",
        "napkin_doc",
        "napkin_sheet",
        "napkin_diagram",
        "prism_field",
        "prism_study"
      ],
      "description": "Which kind the ids belong to."
    },
    "ids": {
      "minItems": 1,
      "maxItems": 100,
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1,
        "maxLength": 100
      }
    },
    "workspace": {
      "description": "Workspace slug. Personal tokens with no default workspace MUST pass this; tokens with a default can override per call. Ignored for workspace API keys.",
      "type": "string"
    }
  },
  "required": [
    "entityKind",
    "ids"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Without a tag: every tag in use across the workspace with how many entities carry it, most-used first — the vocabulary the team already organizes by. With a tag: everything filed under it across every tool, each with its kind, id, title, and path. Use it to reuse existing labels instead of inventing near-duplicates, and to answer 'show me everything about X' when X is a label.

{
  "type": "object",
  "properties": {
    "tag": {
      "description": "A tag to expand into its items. Omit to list tags.",
      "type": "string",
      "minLength": 1,
      "maxLength": 40
    },
    "workspace": {
      "description": "Workspace slug. Personal tokens with no default workspace MUST pass this; tokens with a default can override per call. Ignored for workspace API keys.",
      "type": "string"
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Replaces the FULL tag set on one entity (an empty list clears it). Read the current tags with entity_tags_get first and pass the merged list — this is not additive. Tags are lowercase letters, numbers, spaces, and hyphens; prefer labels already in use (entity_tags_browse) so the workspace's vocabulary stays small. The id comes from the kind's list/get tool or search_workspace.

{
  "type": "object",
  "properties": {
    "entityKind": {
      "type": "string",
      "enum": [
        "workbench_flow",
        "workbench_task",
        "workbench_kb",
        "compass_page",
        "compass_opportunity",
        "caliper_dataset",
        "caliper_rubric",
        "caliper_eval",
        "caliper_review",
        "caliper_spec",
        "caliper_source",
        "ledger_entry",
        "ledger_metric",
        "napkin_board",
        "napkin_deck",
        "napkin_doc",
        "napkin_sheet",
        "napkin_diagram",
        "prism_field",
        "prism_study"
      ]
    },
    "entityId": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100
    },
    "tags": {
      "maxItems": 50,
      "type": "array",
      "items": {
        "type": "string",
        "maxLength": 40,
        "pattern": "^[a-z0-9](?:[a-z0-9 -]*[a-z0-9])?$"
      }
    },
    "workspace": {
      "description": "Workspace slug. Personal tokens with no default workspace MUST pass this; tokens with a default can override per call. Ignored for workspace API keys.",
      "type": "string"
    },
    "approvalId": {
      "description": "Approval id from a prior needs_confirmation response. Omit on the first call.",
      "type": "string"
    }
  },
  "required": [
    "entityKind",
    "entityId",
    "tags"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}