MCP tool reference

Read recorded workspace events, newest first. Returns immutable event snapshots in {items, meta}; continue with offset: meta.next_offset. Filter by subject kind, event type, artifact type, role tier, or occurrence time. Pending work is available through pending_actions_list.

The artifact type catalogue: each type's fields, hierarchy, allowed parent types, tier, and allowedStates (pass one as state to artifacts_update; out-of-tier is rejected). Field authoring rules returned by this catalogue: Artifact narrative. Mission, vision, strategy, goal, persona, problem, project, and architecture descriptions support Markdown. Preserve explanatory prose and dated checkpoints here; use artifact links for relationships, spec_clauses for testable project or ticket requirements, and content only for declared structured fields. Scalar textarea strings render Markdown; use it when headings, lists, links, quotes, or fenced code improve readability, and use Markdown instead of raw HTML because raw HTML is escaped. For textarea fields with array: true, send one item per string[] element and keep Markdown inline within each item—do not include list markers. text, select, date, and number fields are plain values and should not contain Markdown. Unfiltered by default; scope it with these AND-combined filters — types (string array of type ids, e.g. ['story','ticket']), tier (one of orient/directional/structural/execution), and parent_type (a type id: keeps the types that may be created under it, i.e. those whose allowedParentTypes includes it — the "what can I put here" query). Unknown parameters and unknown filter values are rejected with validation_failed rather than silently ignored. The response carries types (the scoped, id-keyed catalogue) and meta.filters / meta.count / meta.total echoing what was applied. Also the resource hf://types (always unfiltered).

Create artifacts in ONE of two forms: pass the single-artifact fields (type and title, plus any of the optional fields below) to create one, or pass items to create up to 50 in a single call. The two forms are exclusive: sending items together with any single-artifact field returns validation_failed, and so does sending neither. Single form: use parent_id for one containment parent or parent_ids for up to 20; when both are supplied they are combined and de-duplicated. Every parent is type-validated before the atomic write, so one missing or wrong-type parent returns an error without creating the artifact or any edges. Singleton types (mission/vision/strategy/domain_model) replace their predecessor (_singleton_replaced sidecar). Agent credentials (API key / OAuth client) MUST attach a parent to a non-root type: a parentless create is REFUSED with validation_failed before anything is written, and its details carry rule_id: 'missing_parent', the expected_parent_types, ranked suggested_parents, and retry_with_parent_id pre-filled with the closest candidate — so the retry is one call. Pass allow_orphan: true to create it unparented on purpose. When an artifact does land without a parent (a web/system create, or allow_orphan), it carries _readiness_warnings whose missing_parent entry ranks the same candidates and pre-fills the top one into recommended_action.args.source_id, so attaching a parent is one links_add. Both surfaces carry a ranking block describing the candidate list's provenance, in the same vocabulary artifacts_suggest_parents uses: mode is semantic or unavailable, semantic_ranking says whether embedding ranking actually ran, returned is the candidate count, and an optional degraded (code, failure_stage, retryable, recovery) is present only when ranking could not be performed — so an empty suggested_parents means 'no candidate exists' ONLY when degraded is absent. degraded.recovery names the retry: artifacts_suggest_parents with the created artifact's id in args.orphan_ids, or artifacts_create itself for a refusal, since nothing was written. Ranking is one graph read; allow_orphan skips it, because a stated orphan needs no candidates. parent_tier_empty: true means the workspace holds no live artifact of any expected parent type at all: create that parent first instead of hunting for one. Elicitation-capable clients are additionally prompted to pick a suggested parent (or keep it root); pick one and the create links it for you. On a created result the artifact also carries a _signals sidecar: Reconcile findings (including drift findings and detected incompatibilities) on the new artifact and all parents. Returns {kind:'created'}, or {kind:'proposal',proposal_id,proposal_url} when the create requires human review — branch on kind. Put your reasoning, sources, and caveats for that reviewer in rationale, not in description: the description is saved as the artifact's text. Agent credentials (API key / OAuth client) creating a singleton type are ALWAYS routed to human review regardless of workspace policy (the predecessor replacement happens only when the proposal is applied). Applying that proposal creates the singleton in the requested state; for a committed state, the human chooses Create & ratify or Decline. Other ratification-gated agent creates land as draft. When their response includes proposal_url, give it to a human workspace editor to choose Ratify & promote or Keep as draft. Explicit draft creates do not file a promotion. Batch form (items): create up to 50 artifacts in one call (fan-out bounded to 8 in-flight globally and 3 per shared parent); each item runs through the single-create path independently, so partial failures don't sink the batch. items is exclusive with the single-create fields — send one form or the other, never both, or the call returns validation_failed. Items accept type, title, description, content, parent_id, priority, state, owner_id, allow_orphan, and rationale. Agent-created singleton items (mission/vision/strategy/domain_model) require human review before creation: their per-item result is { ok: true, kind: 'proposal', proposal_id, proposal_url }, counted in summary.proposed rather than succeeded. Returns { results, summary } with per-item ok/error so you can retry failures — UNLESS every item failed, in which case the call is a top-level error (isError) whose details.results carries the per-item errors, so a 0-succeeded batch is never reported as success. A non-root item with no parent_id from an agent credential FAILS that item with validation_failed / rule_id: 'missing_parent', carrying ranked suggested_parents and retry_with_parent_id so you can retry just that item with a parent; the rest of the batch still lands. Create-first/link-later flows must set allow_orphan: true on those items, which lets them land with a _readiness_warnings entry to resolve later with the pairs form of links_add. Candidate ranking runs on every parentless item, but an item that sets allow_orphan is not ranked at all, so a create-first batch pays nothing for candidates it would discard. For new artifacts that must reference each other's returned ids, use sequential single creates. A failed item's quality rejection carries only details.artifact_quality.{status, findings, suggestions?}; it has no error.message: each finding's rule id and reason are in findings, and suggestions holds up to three concrete fixes. Under the response cap, rows shed detail and _meta.degraded names what was dropped, but summary and each row's ok plus artifact id or error code always remain: read written items by id rather than retrying the batch. Emits notifications/progress when given a progress token.

Soft-delete an artifact (history/links/findings preserved, no public restore surface) — prefer artifacts_update({state:'closed'}) or {archived:true} unless it's genuine garbage. Two-phase: the first call returns {kind:'requires_confirmation', confirmation_token, preview}; call again with the token to execute. Branch on kind.

Get one artifact by ID with saved quality level (low, moderate, or high; null when unassessed), full content, state, closure_reason, archived_at. Explicit ID retrieval includes archived artifacts for recovery and audit; default grounding reads exclude them. By default attaches three sidecars: up to 3 recent _external_references, a _signals sidecar of the reconcile signals on this artifact (findings on it + conflicts naming it) so you see them before acting, and _owner. Pass include: ['specifications'] (opt-in, never attached by default) to add _specifications: the effective specification view for this artifact, its own and inherited specification clauses, bounded, with meta reporting omitted clauses and state: 'unavailable' (with retryable) when the contract cannot be read; any other failure fails the call. Read it before implementing a ticket or project. These sidecars are large — bound the payload with include (attach only the named sidecars) or exclude (drop the named ones from the default set); pass include: [] for the core row alone, which also skips the graph reads entirely. Project the core row with fields (id/type/title always returned) — e.g. fields: ['state','closure_reason','archived_at'] for a lifecycle-only read or fields: ['owner_id'] for ownership, dropping the heavy content blob. The applied projection is echoed back in _projection. ArtifactReadNotFound carries details.recently_updated — the workspace's most-recently-updated artifacts as orientation, NOT a ranked match for the id you asked for (a UUID gives nothing to rank against).

List artifacts in the workspace, newest first; filters compose. Returns {items, meta} and pages with offset: meta.next_offset. Rows are slim by default (no content/drift, descriptions previewed at 280 chars, to stay under the response cap) — opt in via include (content, drift, description); meta.truncated_fields flags omitted fields. For content search use artifacts_search.

Search workspace artifacts by exact title and semantic similarity. Exact-title matches rank first; meta reports ranking, degradation, and pagination, and meta.title_excluded lists exact-title matches left out (archived or a retired type) with the reason. Rows are slim by default ({id, type, state, title, description preview, similarity, matched}); pass include: ['content'] only when the structured artifact body is required. Continue from meta.next_offset. Archived artifacts are excluded, like every default grounding read; retrieve one by id with artifacts_get.

Set (or clear) an artifact's parent — the single-purpose re-parent intent with replace semantics: it atomically closes the child's existing active parent edge and opens the new one, enforcing a single parent. Pass parent_id: null to clear the parent (make the artifact a root). A wrong parent type returns the self-correcting invalid_parent_type envelope (as links_add / artifacts_create). Prefer this over links_add for re-parenting — links_add appends a parent edge (a child can accrue two), whereas this replaces. Returns { previousParentId, nextParentId } plus a _signals sidecar with Reconcile findings on the affected artifacts.

For each artifact in orphan_ids (up to 50), rank the live, type-valid parent candidates by exact cosine similarity to its stored embedding. Get orphan ids from workspace_audit (category orphans, each finding's artifact_id); the ids are not re-checked for orphan status, so any current artifact can be ranked. The whole batch is one graph read. Each row carries suggestions: [{ id, title, type, similarity }] (highest first) filtered to the type's valid parent tiers — link one with links_add or artifacts_set_parent. parent_tier_empty: true means the workspace holds no live artifact of any expected parent type: create that parent first. Every row also carries ranking, using the same vocabulary artifacts_search returns in meta: mode is semantic or unavailable, and ranking.degraded (code, failure_stage, retryable, recovery) is present only when the row could not be ranked because the artifact has no usable stored embedding yet (embedding stage). An empty suggestions list means the row needs manual placement ONLY when ranking.degraded is absent; otherwise retry later with the ids in recovery.args. An id that is not a current artifact in the workspace has no row. A graph failure fails the whole call with a retryable error. The candidate set, scoring, and ranking marker are shared with the create-time missing_parent nudge, so both surfaces stay consistent.

The single tool for editing artifacts (only provided fields written): content, shelving (archived), lifecycle state, validation renewal (renew_validation), and a human-review audit event (flag_review). Call it in ONE of two forms: pass id plus the fields to change for one artifact, or pass items to update up to 50 in a single call. The two forms are exclusive: sending items together with any single-artifact field returns validation_failed, and so does sending neither. Single form: the response adds a _signals sidecar with the current findings naming this artifact, in the shape signals_list returns. Detection runs after the write commits, so findings this edit introduces appear on a later read. Scoped to this artifact only — _signals: [] is not a workspace all-clear; use Reconcile through signals_list for workspace findings. An agent-requested promotion of a strict-authority artifact whose premise has no human ratification is not applied directly: the call returns {kind:'proposal', proposal_id, proposal_url} (no fields written; a riding renew_validation/flag_review is skipped and listed in ignored_fields; repeat attempts return the same proposal) — hand the proposal_url to a human, who can Ratify & promote or Keep as draft. An agent edit to the title, description, or content of a ratified mission, vision, strategy, or domain model is also not applied directly: it returns the same {kind:'proposal'} shape, the live premise stays unchanged, and applying the proposal ratifies the new premise. Put your reasoning for the reviewer in rationale. The workspace singleton_write_policy set to yolo turns this review off. Version check: to avoid replacing an edit someone saved after your read, send expected_version_seq with the version_seq from artifacts_get or artifacts_list. If the artifact has a newer version, the call writes nothing and fails with ArtifactUpdateStaleBase; details.current_version_seq and details.current_updated_at name the newer version. Read the artifact again, merge your change into it, and retry with the new version_seq. The check covers changes that write a new version (title, description, content, priority, archived, state). owner_id, spec_clauses, renew_validation, and flag_review write no version, so a call that sends expected_version_seq with only those returns validation_failed. Without expected_version_seq, the last write wins. Batch form (items): update up to 50 artifacts in one call (fan-out bounded to 8 in-flight globally and 3 per shared non-null owner); each item is updated independently, so partial failures don't sink the batch. items is exclusive with the single-update fields — send one form or the other, never both, or the call returns validation_failed. Items may patch title, description, content, priority, owner_id, archived, and lifecycle state. Omitted priority is unchanged and null clears it. Each item may set its own expected_version_seq together with a change to title, description, content, priority, archived, or state (an item that changes only owner_id or spec_clauses fails with validation_failed, because those changes write no version): an item whose artifact has a newer version fails alone with ArtifactUpdateStaleBase and details.current_version_seq, and the other items still apply; read that artifact again and retry only that item. An agent-requested promotion of a strict-authority artifact whose premise has no human ratification, or an agent edit to the title, description, or content of a ratified mission, vision, strategy, or domain model, is not applied directly: that item returns {ok:true, proposal:{kind:'proposal', proposal_id, proposal_url}}, counted in summary.proposed rather than succeeded, and writes nothing; hand the proposal to a human reviewer, and put your reasoning in the item's rationale. Returns { results, summary } — UNLESS every item failed, in which case the call is a top-level error (isError) whose details.results carries the per-item errors, so a 0-succeeded batch is never reported as success. _signals are NOT computed per item — call signals_list after. A failed item's quality rejection carries only details.artifact_quality.{status, findings, suggestions?}; it has no error.message: each finding's rule id and reason are in findings, and suggestions holds up to three concrete fixes. Under the response cap, rows shed detail and _meta.degraded names what was dropped, but summary and each row's ok plus artifact id or error code always remain: read written items by id rather than retrying the batch. Emits notifications/progress when given a progress token.

The full context chain for an artifact (ancestors ← current → descendants); each node carries state/closure_reason. Current chains exclude archived artifacts. Pass as_of only when you need the auditable historical chain. On launch-scale graphs, don't pull the whole tree: pass shape:'slim' (drops titles/state/drift/edges), and scope with direction (ancestors for grounding, descendants for subtree work), max_depth (1 = parents + direct children), and types. Every response carries meta with pre-filter totals (total_nodes/ancestors/descendants), matched, truncated, and next_offset — page with offset until next_offset is null. Safe pattern for big projects: {shape:'slim', direction:'descendants', max_depth:1} first, then drill into one child. Default page size 200, max 500. Pass as_of (ISO-8601) to reconstruct the chain as it stood at that instant from artifact version history; historical chains return undecorated nodes (no drift/edge sidecars).

Resolve effective serves and addresses context for one artifact. For a project, requirement, or story, outgoing contains the active personas/problems it reaches directly or through containment ancestors. For a persona/problem, incoming contains the execution artifacts covered by each direct semantic relationship, including inherited descendants. Every item reports direct, declaredAt, and inheritedDepth so provenance is explicit. This does not alter chain_get: demand relationships remain non-containment.

Fetch the canonical Helen’s Foundry documentation, in either of two forms. Pass exactly one of check (a reconcile check kind), metric (an Insights metric id), error (an MCP error code), or topic (an inline guide or reference) to get back { title, url, body } for that concept, with the full doc text inline in body (no fetch of url required). Call it with NO arguments to get the index instead: every documentable check, metric, error code, and topic, each with its title and canonical URL, so you can discover what to ask for. Passing more than one concept is rejected with validation_failed.

See which external entities (PRs, GitHub/Linear issues) are attached to an artifact — "where else does this live?" before closing a ticket or triaging drift. Distinct from the context chain (chain_get); this returns artifact↔external edges, newest-first.

Create directed edges between artifacts; kind selects the edge type. Call it in ONE of two forms: pass source_id + target_id for a single edge, or pass pairs for up to 50 edges in one call. Sending both forms, or neither, returns validation_failed. parent (default): containment parent to child, traversed by chain_get. Adding a parent link validates the child's allowedParentTypes; a wrong type returns the self-correcting invalid_parent_type envelope (as artifacts_create). references: non-containment typed reference, any artifact to any, ignored by chain_get. supersedes: non-containment, source replaces target, ignored by chain_get. Creating a supersedes edge also closes its target (closure_reason='obsolete', reported as _superseded_target_closed), idempotently and self-healingly: a retry completes a close a prior call left undone, and an already-closed target is never re-closed. depends_on: non-containment, source depends on target, ignored by chain_get. serves: non-containment project/requirement/story to persona relationship. addresses: non-containment project/requirement/story to problem relationship. Full rules for each kind: docs_get({ topic: 'edge-kinds' }). Idempotent for every kind: re-adding returns the existing edge with _already_existed: true and no new history. The single form returns the edge plus a _signals sidecar with Reconcile findings on both endpoints, in the signals_list shape; _signals: [] means none on these two artifacts, not a workspace all-clear. The pairs form bounds fan-out to 8 writes in flight globally and 1 per shared source or target, runs each pair through the same path independently (partial failures don't sink the batch), and applies kind (or per-pair kind) to each pair. It returns { results, summary } with per-item ok/error, where summary is { total, succeeded, failed, partial, unknown }: partial counts a persisted primary edge with a side-effect outstanding, and unknown counts a bounded readback that could not prove whether the edge landed, so neither is mislabeled as a hard failure. If every pair is a definite hard failure the call is a top-level error whose details retain all per-item results. Per-item _signals are NOT attached in the pairs form (it would be one signals_list query per item) — run signals_list after the batch to see the findings introduced. The pairs form emits notifications/progress when given a progress token. To re-parent an artifact (replace its current parent), use artifacts_set_parent — this tool with kind='parent' appends a parent edge, so a child can accrue more than one.

List directed edges between artifacts, each row enriched with the type + title of both endpoints (no follow-up artifacts_get needed). kind selects which edge set; non-containment kinds are absent from chain_get by construction. Every edge points source to target; a parent edge points from the parent to the child, and there is no separate child kind. parent (default): containment parent to child, traversed by chain_get. references: non-containment typed reference, any artifact to any, ignored by chain_get. supersedes: non-containment, source replaces target, ignored by chain_get. depends_on: non-containment, source depends on target, ignored by chain_get. serves: non-containment project/requirement/story to persona relationship. addresses: non-containment project/requirement/story to problem relationship. Full rules for each kind: docs_get({ topic: 'edge-kinds' }). Pass artifact_id to scope to edges touching that artifact; omit it for the workspace-wide edge set. A scoped row adds direction (outgoing when the artifact is the source, incoming when it is the target) and other_id/other_type/other_title for the endpoint that is not the artifact; read those instead of target_*, which names the artifact itself on an incoming edge. direction:'outgoing' keeps only edges from the artifact (for parent: its children), direction:'incoming' only edges to it (for parent: its parent). Returns { links, kind, meta }. Paging: repeat the call with offset: meta.next_offset until it is null; that reads every edge exactly once. A page can end early, with meta.truncated: true, because of limit or because the response reached its byte cap (meta.truncated_reason), and can hold fewer rows than limit while edges remain: meta.skipped counts edges dropped in the window because an endpoint is no longer a current artifact. Only next_offset tells you whether more edges exist. shape:'slim' drops the endpoint titles (keeps ids + types) so pages hold more rows; re-fetch a title with artifacts_get when you need it.

Remove directed edges (one direction each); kind must match the edges you created. Call it in ONE of two forms: pass source_id + target_id for a single edge, or pass pairs for up to 50 edges in one call. Sending both forms, or neither, returns validation_failed. Removing a supersedes edge does not re-open the superseded target — un-superseding a target's lifecycle is a separate, explicit state change (artifacts_update). parent (default): containment parent to child, traversed by chain_get. references: non-containment typed reference, any artifact to any, ignored by chain_get. supersedes: non-containment, source replaces target, ignored by chain_get. depends_on: non-containment, source depends on target, ignored by chain_get. serves: non-containment project/requirement/story to persona relationship. addresses: non-containment project/requirement/story to problem relationship. Full rules for each kind: docs_get({ topic: 'edge-kinds' }). Idempotent: removing a missing edge returns { deleted: 0, _already_absent: true }. The single form returns { deleted, _already_absent? } plus a _signals sidecar with Reconcile findings on both endpoints. The pairs form bounds fan-out to 8 writes in flight globally and 1 per shared source or target, runs each pair through the same path independently and idempotently, and applies kind to every pair. It returns { results, summary } with per-item ok/error, where summary is { total, succeeded, failed, unknown }: an _already_absent no-op counts as succeeded, and unknown means bounded exact readback could not prove the removal, so it is not mislabeled as a definite failure. Per-item _signals are NOT attached in the pairs form (run signals_list after), and that form emits notifications/progress when given a progress token. To clear an artifact's parent entirely (rather than a specific known edge), prefer artifacts_set_parent({ parent_id: null }).

List the members of the caller's workspace as {id, display_name, role, is_current}[]. id is the member's user id — pass it as owner_id to artifacts_create / artifacts_update, or as the owner_id filter on artifacts_list. display_name is null when a member has no profile row yet (new auth user, race with profile insert). is_current marks the row that is the CALLING principal — the canonical id to self-assign ownership with. The envelope also carries current_user_id (the caller's canonical id) and, when two or more members share a display_name, duplicate_display_names: [{display_name, ids}] so a duplicate identity (a second :User created via Clerk email-linking / JIT) is explained rather than read as two distinct people — write to the is_current id. Stable ordering: named members alphabetical first, then unnamed.

File a proposed change WITHOUT applying it. Only a person can apply or decline it, in the app; no agent credential can decide it. When a person applies it, the change replays under this principal's identity. The payload is validated now, not just at decide time. Returns the queued proposal for review in the activity feed; give its link to a person.

List proposed-change queue rows (newest first). Returns {items, meta}; page with offset: meta.next_offset until it is null. Defaults to status='pending'; pass status for another bucket. Each row carries the proposer's credential kind/id so reviewers can see who proposed it, and a preview of the predicted side effects when one was captured.

The exact evaluation Helen’s Foundry produced the last time it dispatched for a pull request, as typed JSON — the same versioned report model that renders the sticky GitHub comment and the hf.dev check report page. Reach for it when an agent needs that evaluation (Agent Helen code review, governance authority, reviewer health, drift) and would otherwise scrape the comment. The read is scoped to the caller's own workspace, which comes from the credential, not from an argument: a pull request evaluated only in some other workspace reads as absent, and no other tenant's report is reachable. Every outcome is a named status rather than an error. ready returns the full report in snapshot. legacy_version identifies a version-1 report that lacks a safe v2 decision migration. unsupported_version identifies a newer report and returns schema_version. malformed failed the stored-report contract. inaccessible means the store did not answer or the report object is gone. Only inaccessible can improve without a new dispatch. When the report names an unsatisfied link, link_guidance states the pull-request marker syntax that clears it, with an example. It is null in every other state. Staleness is explicit. snapshot_head_sha is the evaluated head. observed_head_sha is the newest dispatched head. stale: true means the commit or PR details changed after the report. Re-read after the next dispatch. Limits: this report is dispatch-time and read-only. It does not recompute current artifact state, gate work, or publish. Non-ready states carry a null snapshot and null heads. A report too large to return inline comes back as response_too_large with the check report URL.

Act on detector findings from signals_list. Call it in ONE of two forms. Single form: pass id plus at least one of disposition and rating. disposition:'dismiss' is terminal — the "not actionable" verdict, recording the optional reason and writing the dismissal suppression so the finding stops re-firing; disposition:'acknowledge' records that the finding was seen and leaves it open until the detector no longer finds the condition. Disposition is idempotent: re-disposing an already-terminal row returns it unchanged. rating is structured quality feedback (useful = surfaced a real problem; not_useful = technically correct but not actionable; wrong_evidence = the evidence misrepresents the situation, a detector bug) that feeds the per-kind precision report and the weighted evaluation corpus. Rating is append-only, so re-rating the same finding inserts a new history row rather than replacing one, and it does NOT by itself change the finding's lifecycle — the detector stays the source of truth. Sending both rates first and then disposes, and returns the disposition payload with the rating row on a _rating sidecar. Instead of an explicit disposition, a negative rating can carry dispose: true to dismiss through the same suppression path; that flag applies only when no disposition is given, and is ignored for useful. Batch form: pass items to dispose (and optionally rate) up to 50 findings in one call. Each item is { id, disposition, rating?, reason?, note?, idempotency_key? } and is handled independently, so partial failures don't sink the batch; every item reuses the single-finding paths, preserving idempotency and rating history. It returns { results, summary }: per-item { ok, id, ... } plus { total, succeeded, failed }, and emits notifications/progress when given a progress token. The two forms are exclusive: sending items alongside any single-finding field returns validation_failed, and so does sending neither. Set submission_mode:'replay' in either form when reproducing prior judgments rather than making new ones.

Send product feedback capturing friction, bugs, or feature ideas relating to this MCP server and the underlying product. For dispatcher feedback, include relevant artifact, request, signal, check, or tool identifiers and compact structured fields.

Page the current canonical members of a query-backed finding. ABOUT subjects in signals_list are bounded display witnesses, not this membership.

Reconcile is the workbench for current detector findings, newest-first. The returned source:'conflict' is a legacy wire value and does not mean every finding is a genuine incompatibility. Returns {items, meta}; limit is 1–50 (default 50) so a bare call stays under the response cap — page older findings with offset, and meta.matched can exceed meta.returned. Default shape:'slim' is the cap-safe routing shape: it drops evidence entirely and caps subjects at 5 per row, adding subjects_returned, subjects_omitted_at_least, subjects_truncated, and subjects_refetch (meta.subjects is bounded). The slim cap composes with kind-specific canonical bounds while preserving their total omitted count and refetch path; shape:'full' preserves the canonical bound. Explanation fields are kind-specific in both shapes: summary is currently always null; rationale and confidence are non-null only for LLM-adjudicated semantic and property kinds (for example orphaned_metric) and are null for deterministic kinds. presentation is also kind-specific: it is non-null only for portfolio_distribution_anomaly rows with recognized evidence and is null otherwise. Slim is insufficient for evidence-based review of deterministic findings; refetch with shape:'full' to inspect evidence. Full adds evidence but does not otherwise populate null explanation fields. meta.subjects reports whether every subject is present or a canonical bound remains. A non-null presentation provides group_key, group_label, and facet_label so clients can show related rows in one chassis without merging their ids or actions. Each row carries recommended_action: {tool, args, fill?, description} — the MCP verb that addresses that finding, with the subject artifact id pre-filled in args for direct verbs; a pending_actions_create action instead names the id in its description for the payload you fill; null for kinds without a safe deterministic verb (use reconcile to acknowledge, dismiss, or rate it). When fill is present the agent must ADD that key to args with a value of its choosing — the key is deliberately omitted so a verbatim call fails the tool's validation loudly instead of silently no-opping. Read-only — act on a row with reconcile (id plus a disposition and/or rating) or the recommended_action tool.

Use for "what's wrong with this workspace?" or after a bulk import. Returns severity-grouped findings for orphans, duplicates, lifecycle inconsistencies, unowned in-flight execution work, and stale strict-authority drafts, each with an optional recommended_action: {tool, args}. Every advertised category runs a real detector; findings are capped and severity-ordered. On large workspaces use grouped mode (group: true) — lifecycle findings batch by closed parent, orphans by expected parent type, and unowned or stale-draft findings into one group, with full counts + ≤3 representatives — and page with offset: meta.next_offset until it is null (summary.total can exceed meta.returned). After a response_too_large, retry with group: true, a narrower categories, a lower findings_limit, or include_sidecars: false (drops the _schema_drift / _detector_precision blobs). Schema drift is opt-in: pass categories: ['schema_drift'] to get the _schema_drift sidecar (compact rows grouped by artifact type + unknown key, with count, top 3 examples, and status: 'legacy_alias' | 'unknown'). Category-scoped audits that omit schema_drift never attach the sidecar, so legacy drift rows cannot dominate a targeted call. Partial results are explicit: summary.by_category is null for any category that did not run (not requested, or its detector failed) and a number only when the detector ran, so a 0 is a real all-clear; summary.category_status and meta.failed_categories name the categories that failed, and one failing detector never discards the categories that succeeded. In grouped mode the rows live in groups and findings carries only ungroupable rows — read meta.returned_collection with meta.returned_groups / meta.returned_findings to see what meta.returned counted.

Read one authorized workspace external reference by ID, whichever source it came from: the source policy is resolved from the stored reference, not from a parameter. The active workspace comes only from the authenticated request context; callers cannot select another workspace, and a reference in another workspace reads as not found. A feedback-source reference returns its source-policy presentation with bounded body content and attachment IDs, never raw persistence fields. An imported GitHub issue returns the issue projection plus its stored body and a body_state that separates a body that loaded from one that was never stored and one that could not be read. This is the only read that resolves a body, which is why workspace_external_references_list omits it.

List the authorized workspace-wide external-reference inbox for one source, newest first. This is distinct from external_references_list, which starts from one artifact. Returns safe presentation rows as {items, meta: {next_continuation}}; raw persistence fields are omitted. Repeat the same source and attachment with continuation: meta.next_continuation until it is null; a continuation is only valid against the source and attachment that produced it. source: 'github_issue' lists this workspace's imported GitHub issues, newest capture first, including issues with no artifact relationship, which every artifact-scoped read misses: a repository import records an issue whether or not its body carried an artifact URL, so use attachment: 'unattached' to triage what arrived unlinked. Bodies are omitted from every source here; read one with workspace_external_reference_get. Each source keeps its own row projection, so branch on source when reading items, and its own default page size (50 for feedback, 25 for GitHub issues).

One-call session bootstrap: workspace meta, current unarchived artifact counts by type and state, and the 5 most recently updated current artifacts. Pair with signals_list and activity_feed_list.