MCP Tools Reference

WarmHub exposes a full MCP tool catalog for organizations, repositories, shapes, things, assertions, writes, subscriptions, actions, collections, and meta (capability discovery). Repo-level tools take orgName and repoName as arguments.

SDK and MCP Method Map

If you switch between the MCP tools and the TypeScript SDK, the names line up almost one-to-one. A few common pairs:

MCP tool	SDK method
warmhub_thing_head	client.thing.head(...)
warmhub_thing_query	client.thing.query(...)
warmhub_thing_get	client.thing.get(...) for one wref, client.thing.getMany(...) for several
warmhub_shape_list	client.shape.list(...)
warmhub_subscription_list	client.subscription.list(...)
warmhub_thing_create	client.commit.apply(...) with .add(...) operations
warmhub_thing_revise	client.commit.apply(...) with .revise(...) operations
warmhub_thing_retract	client.commit.apply(...) with .retract(...) operations
warmhub_thing_restore	client.commit.apply(...) with .restore(...) operations
warmhub_thing_rename	client.commit.apply(...) with .rename(...) operations
warmhub_assertion_reaffirm	client.commit.apply(...) with .reaffirm(...) operations
warmhub_commit_validate	client.commit.validate(...)
warmhub_thing_remove	client.thing.remove(...)
warmhub_thing_redact	client.thing.redact(...)
warmhub_capabilities	client.diagnostics.capabilities() — returns the backend API version, minimum supported SDK, minimum supported clients, write contract version, feature flags, and the client flags honored for your request (not the tool catalog)
warmhub_repo_describe	client.repo.describe() — returns repo metadata, shapes, stats, license, and a page of HEAD records; subscription information is included only with effective repo:configure access. The MCP tool additionally returns the write contract and generated write examples, which the SDK method omits

Most tools follow the warmhub_<domain>_<verb> ↔ client.<domain>.<verb> pattern. warmhub_thing_get is one MCP tool over two SDK methods: the MCP tool takes a wrefs array at every cardinality, while the SDK keeps single-wref thing.get and batch thing.getMany separate. The six write tools map one-to-one to the operation builder verbs; warmhub_thing_create is .add(...). The other exceptions are warmhub_capabilities, which returns different data (diagnostics.capabilities); and warmhub_repo_describe, where the SDK method omits the MCP-only write contract and generated examples (repo.describe). warmhub_thing_remove and warmhub_thing_redact follow the standard naming pattern, but their arguments differ from the SDK. Both MCP tools take an optional expectedVersion and use the thing’s current version when it is omitted, while client.thing.remove and client.thing.redact require expectedVersion. Both MCP tools name the thing only by its durableId and reject a wref; client.thing.redact also takes a durable ID, but client.thing.remove takes a wref, which can be a local wref such as cave or a durable ID.

CLI Name Convention

warmhub_<noun>_<verb> maps to the CLI command wh <noun> <verb>. Two systematic aliases cover most of the rest:

MCP name	CLI name
<noun>_get	<noun> view — warmhub_repo_get is wh repo view
subscription_*	sub * — warmhub_subscription_list is wh sub list

Eight tools diverge from the rule and its aliases. An exception overrides both:

MCP tool	CLI command	Notes
warmhub_thing_head	wh thing list	Also described in the tool description
warmhub_component_uninstall	wh component teardown	Also described in the tool description
warmhub_commit_receipt_get	wh commit receipt	Also described in the tool description
warmhub_commit_validate	wh commit submit --dry-run	Also described in the tool description
warmhub_repo_content_get	wh repo content get
warmhub_subscription_get	wh sub view

The four marked in the Notes column also repeat the mapping in their own tool description; the rest are listed only here and in warmhub_capabilities, where a correction costs no tools/list tokens. warmhub_subscription_runs and warmhub_capabilities have no CLI command at all and are returned under noCliEquivalent.

warmhub_capabilities returns this whole mapping under naming, so an agent can read it without leaving the protocol.

The SDK is a separate mapping — mostly client.<noun>.<verb>, with the exceptions in the SDK and MCP method map above. naming covers the CLI only.

Tool Titles

Every tool carries a title alongside its name — a short display name such as Create Things or List Shapes. MCP clients show it in tool pickers and permission prompts. It is a display name only: hints, CLI mappings, and auth guidance live in the description or in warmhub_capabilities, never in the title.

Auth awareness is a runtime signal

Every tool carries a reviewed auth tier, and warmhub_capabilities reports it per tool as tier: 'anonymous' | 'builder'. That field — not readOnlyHint — is the authoritative answer to “can I call this without credentials?”: several builder-tier tools are read-only, including warmhub_commit_validate, warmhub_org_list, warmhub_org_member_list, warmhub_repo_describe, the subscription and action readers, and warmhub_commit_receipt_get, each of which reads through an authorization-gated procedure.

Tool descriptions carry no auth note. The signal is on the responses instead: every response carries structuredContent.auth.authenticated, and a miss from an anonymous caller carries auth.hint saying the resource may be private. warmhub_capabilities states the guidance once, as the Anonymous access usage pattern.

Meta Tools

Orientation and capability discovery. The meta category covers three tools:

Tool	Description
warmhub_capabilities	Static, endpoint-scoped overview of the MCP tool catalog: tools grouped by category, a workflow cookbook, wref syntax, and a pointer to the full write operation contract. Read-only; no arguments.
warmhub_repo_describe	Per-repo live view: schema, shape descriptions, field types, summary stats, wref syntax, operation contract, write examples generated from the repo’s own shapes, and the repo’s license. Documented under Repository Tools.
warmhub_doctor	Diagnostic tool. Takes no arguments. Returns { ok: true, capabilities, hint }, where capabilities is a diagnostics payload containing apiVersion, minSupportedSdk, minSupportedClients, writeContractVersion, features, and honoredClientFlags. The last of those echoes back which client flags — opt-in compatibility switches a client declares on its request — were honored for your request; it is empty when you declared none.

Call warmhub_capabilities first to orient on what tools exist; then call warmhub_repo_describe to learn the repo-specific shapes and write examples.

warmhub_capabilities

Takes no arguments. Returns a static orientation payload with the following fields:

Response Field	Type	Description
categories	object[]	One entry per tool category (org, repo, shape, thing-read, collection, commit, subscription, action, meta), each with name, description, and the tools (name, title, description, tier, readOnly, openWorld, destructive, annotationJustification) advertised on the current endpoint. tier is anonymous or builder — the authoritative answer to whether the tool is callable without credentials.
naming	object	The CLI name convention as { rule, aliases: [{ mcp, cli }], exceptions: [{ tool, cli }], noCliEquivalent: string[] }. An exceptions entry overrides the rule and any alias.
cookbook	object[]	Common workflows as { task, steps: [{ tool, note }] } — e.g. discovering shapes, searching by content, writing first data.
usagePatterns	object[]	Query-discipline guidance — recommended patterns for reading, querying, and writing efficiently.
wrefSyntax	object	Local and canonical wref forms, version modifiers, path/name constraints, and write-path preview rules.
commitContractRef	object	Pointer to warmhub_repo_describe, which returns the full write operation contract, operation variants, and live write examples scoped to a specific repo.

categories lists every registered tool — there is one endpoint and one catalog.

Call warmhub_capabilities first to orient an agent, then call warmhub_repo_describe for per-repo schema and write examples.

Organization Tools

Organization tools need no repository. Most take orgName as an argument, and warmhub_org_get also accepts an org durable ID in its place. warmhub_org_list is the exception: it operates globally and does not accept orgName.

Tool	Description
warmhub_org_list	List organizations (archived hidden by default). (global only)
warmhub_org_get	Get an organization by name or durable ID. (global only)
warmhub_org_member_list	List members of an organization. (global only)

warmhub_org_list

Param	Type	Required	Description
includeArchived	boolean	no	Include archived organizations in results

Response fields:

Response Field	Type	Description
repoCount	integer	Number of repos in the organization readable by the caller. Includes only repos the caller has effective repo:read access to.
errorCount	integer	Number of repos in the organization that have at least one active subscription whose most recent completed run failed.
lastActivityAt	integer	Unix timestamp in milliseconds of the most recent activity across the organization’s readable repos. Advances on repo creation even before the first write has been submitted to that repo. Omitted when no activity has been recorded.

warmhub_org_get

Pass exactly one of orgName or orgDurableId.

Param	Type	Required	Description
orgName	string	one of	Organization name
orgDurableId	string	one of	Organization durable ID, as returned by warmhub_org_get. It keeps identifying the organization after a rename or a reuse of its old name.

Response fields:

Response Field	Type	Description
orgDurableId	string	The organization’s durable ID. Store it instead of the name when a reference must survive renames.

warmhub_org_member_list

Param	Type	Required	Description
orgName	string	yes	Organization name
pending	boolean	no	When true, returns only pending (invited but not yet accepted) members. When omitted or false, returns all members regardless of status.

Response fields:

Returns an object, not a bare array:

Response Field	Type	Description
members	object[]	The organization’s members (only pending members when pending is true). Each entry has the member fields below.
callerRole	string	Your own role in the organization: one of owner, admin, editor, or viewer.

Each entry in members has these fields:

Member Field	Type	Description
email	string	Email address of the member.
firstName	string	First name of the member. May be absent.
lastName	string	Last name of the member. May be absent.
role	string	The member’s role in the organization: one of owner, admin, editor, or viewer.
status	string	Membership status. The currently known values are active and pending, but this is an open set — other values may appear as the platform evolves, so do not treat it as a closed enum.
invitedBy	string	Email address of the user who sent the invitation. May be absent.
createdAt	integer	Unix timestamp in milliseconds of when the membership record was created.

Repository Tools

Tool	Description
warmhub_repo_create	Create a new repository in an organization. (global only)
warmhub_repo_list	List repositories in an organization (archived hidden by default). (global only)
warmhub_repo_get	Get repository metadata by org/repo.
warmhub_repo_describe	Describe repository schema, shape descriptions, field types, per-shape queryHints, summary stats, and license for agent bootstrapping.

warmhub_repo_create

Param	Type	Required	Description
orgName	string	yes	Organization name
repoName	string	yes	Repository name (slug)
displayName	string	no	Human-readable display name for the repo. Must be non-empty and non-whitespace if provided; max 100 characters. Defaults to the repo slug when omitted.
description	string	no	Repository description. Max 2000 characters.
visibility	string	no	"public" or "private". Defaults to "private".

Returns the created repo object (same shape as warmhub_repo_get). Only available on the global MCP endpoint.

warmhub_repo_list

Param	Type	Required	Description
orgName	string	yes	Organization name
includeArchived	boolean	no	Include archived repositories in results
limit	integer	no	Max repos to return (1–200). Must be paired with cursor when paging.
cursor	string	no	Pagination cursor from a prior response. Must be paired with limit.

warmhub_repo_describe

The most important tool for agent bootstrapping. Returns:

• Repository metadata
• Shape definitions with field types and optional shape-level description
• Per-shape queryHints with queryableFields, wrefFields, and suggested MCP query patterns
• Per-field descriptions inlined into each field entry. Fields without descriptions appear as bare type strings (e.g. "string"); fields with descriptions appear as { "type": "number", "description": "Horizontal position" }. Descriptions are extracted from typed field objects.
• Summary counts (shapeCount, subscriptionCount, totalCount)
• Counts by kind and by shape
• Sample wrefs from the repo
• Wref syntax reference
• Operation contract — operationVariants (the add/revise/retract/rename/reaffirm/restore forms), commitRules (revise-data, retract-only, illegal op sequences, noop, opinion rules), and aboutSemantics — plus writeExamples generated from the repo’s own shapes
• Write examples generated from actual repo shapes
• license — the repository’s current license metadata, or null when the repo has no active, visible, valid license declaration (see the response field description below)
• Indexed field metadata when includeIndexedFields is set (see below)

Call this first when connecting to a repo.

Input parameters:

Param	Type	Required	Description
orgName	string	yes (global)	Organization name
repoName	string	yes (global)	Repository name
includeIndexedFields	boolean	no	When true, the response includes an indexedFields block with typed field index state across the repo’s shapes. Defaults to false.

Response fields (selected top-level):

Response Field	Type	Description
license	object | null	The repository’s current license metadata, or null when the repo has no active, visible, valid license declaration. Subfields are listed below.

When license is non-null, the object carries these fields:

Field	Type	Description
spdxId	string	The SPDX license identifier. Always present when license is non-null.
licenseWref	string | null	The declaration’s licenseWref value, returned as stored. Writes store wref fields by durable id, so a value written by name normally comes back as a durable id; treat it as an opaque wref string. It can point to any thing, including one in another repo; its shape is not checked.
spdxExpression	string | null	The full SPDX expression as stored.
appliesTo	string | null	Free-form string describing the kind of work covered by the license (e.g. "software", "code", "data").
attributionText	string | null	Optional attribution text.
declaredBy	string | null	Free-form string naming who made the declaration. Not resolved as a wref.
sourceUrl	string | null	Link to the license text.

The response includes an additionalInformation array pointing at the three well-known Content shape wrefs:

"additionalInformation": [
  { "name": "Readme",  "wref": "Content/Readme",  "synthesized": false },
  { "name": "Agents",  "wref": "Content/Agents",  "synthesized": false },
  { "name": "LlmsTxt", "wref": "Content/LlmsTxt", "synthesized": true  }
]

When includeIndexedFields: true is passed, the response also includes an indexedFields block with six members: four marker-state buckets plus the declaration registry and its consistency check.

The state buckets — ready, building, failed, and other — each contain an array of field entries. Every entry carries the field’s state, associated timestamps, and backfill counters. Parse all four buckets when acting on index state: a field in building is not yet queryable, and a field in failed requires attention before structured queries against it will succeed.

indexedFields.declarations is the declared-indexing registry — what has been asked for, as distinct from the markers above, which report what currently exists. It is an array of entries:

Field	Type	Description
fieldPath	string	The declared field path.
declaredByShape	string | null	The shape the declaration was made against; null when the declaration is not shape-scoped.
carrying	array	One { shapeName, state } entry per shape currently carrying an index for this path. Empty until a marker exists.
ready	boolean	Whether every carrying shape has reached ready. A declaration with ready: false is still converging.

indexedFields.consistency reconciles the two views and is always present:

Field	Type	Description
undeclaredMarkers	array	{ shapeName, fieldPath } for each index marker with no matching declaration — an index exists that nothing asked for.
uncarriedDeclarations	array of strings	Field paths declared but carried by no shape — informational; does not affect consistent.
consistent	boolean	true when undeclaredMarkers is empty. uncarriedDeclarations is populated independently and does not influence this value.

Declarations are written with wh repo index pin / wh repo index unpin; the same registry backs the Declared Fields and Index consistency sections of wh repo describe --indexed-fields.

Content Tools

Two tools cover the built-in Content shape — Readme, Agents, and the synthesized LlmsTxt — discriminated by a kind argument.

Tool	Description
warmhub_repo_content_get	Fetch repo Content markdown by kind. For readme/agents, returns a synthesized empty stub when nothing has been written — never null. kind: llms-txt always returns a synthesized response with the rendered sitemap; the structured refs field is present for authenticated callers only. Read-only.
warmhub_repo_content_set	Set Readme or Agents markdown (commits an add or revise operation). Writes to kind: llms-txt are rejected — it is synthesized and cannot be stored. Requires repo:write.

WarmHub no longer hosts README/AGENTS generation. To draft content, run the CLI command wh repo content prompt <org/repo> --kind readme to get an agent-ready prompt, let your own agent write the markdown, then persist it with warmhub_repo_content_set.

warmhub_repo_content_get

Param	Type	Required	Description
orgName	string	yes	Organization name
repoName	string	yes	Repository name
kind	string	yes	One of readme, agents, or llms-txt

For kind: readme and kind: agents, returns the stored content thing after the first write. When nothing has been written yet, the response is a synthesized empty stub ({ synthesized: true, wref: "Readme", name: "Readme", declaredShapes: ["Content@v1"], data: { content: "" }, active: true }).

For kind: llms-txt, always returns a synthesized response. data.content contains the full rendered markdown. For an authenticated caller the response also carries a refs field with partitioned outbound/inbound references, minus any cross-org refs that caller cannot read.

warmhub_repo_content_get is an anonymous-tier tool, so an unauthenticated caller gets the basic body — H1, description, license line, and shapes — with no refs field and no ref sections in the markdown. See Content Shape.

warmhub_repo_content_set

Param	Type	Required	Description
orgName	string	yes	Organization name
repoName	string	yes	Repository name
kind	string	yes	One of readme, agents, or llms-txt. llms-txt is read-only — set attempts are rejected.
content	string	yes	Markdown content to store
eventRequestId	UUID	yes	Caller-known idempotency key for this write request. Reuse only for an identical retry.

Returns the standard single-operation commit result: operationCount, one operations[] entry (name, operation, version, dataHash), plus optional committer, createdByEmail, and message metadata. Unlike the write tools, this helper does not return partial-result fields; rejected writes surface as tool errors.

Thing / Query Tools

Tool	Description
warmhub_thing_head	List all items at HEAD with optional filters (shape, kind, glob match). Supports incremental reads via sinceRepoSeq — see the parameter reference below. Use to enumerate a repo’s current state; for fuzzy lookups use warmhub_thing_search.
warmhub_thing_get	Fetch one or more things by wref in one call — pass every wref you need together rather than calling repeatedly. Always returns a { requested, items, missing } envelope; a wref that does not exist or is not visible to you is listed in missing, not returned as an error.
warmhub_thing_graph	Get one thing and its embedded assertion/about/wref graph to a bounded depth.
warmhub_thing_history	List version history for a thing. Provide wref for one thing’s history, or shape/about to survey history across matching things. With about, resolveCollections:true includes assertions about Arc/Bond/Set/List collections containing the target identity.
warmhub_thing_about	List assertions whose about target resolves to the supplied target identity. Use resolveCollections:true to include assertions about Arc/Bond/Set/List collections containing the target; pinned @vN inputs stay version-exact and do not expand collection members. Use warmhub_thing_refs with direction:"inbound" for broader backlink discovery.
warmhub_thing_query	Query things by structured filters (shape, kind, about, glob match). Supports incremental reads via sinceRepoSeq — see the parameter reference below. Best for exact/structured lookups; for fuzzy or semantic search use warmhub_thing_search.
warmhub_thing_search	Full-text/vector/hybrid search across thing data. Best for fuzzy lookups; for exact field matches use warmhub_thing_query with a glob filter.
warmhub_thing_refs	List inbound or outbound refs for a target wref. Use direction:"inbound" to find what references X. Pair with warmhub_thing_get to resolve details.

warmhub_thing_head

Param	Type	Required	Description
shape	string	no	Filter by shape name
kind	string	no	Filter by kind. One of shape, thing, assertion, or collection.
match	string	no	Glob pattern to filter wrefs (* = one segment, ** = zero or more)
where	object[]	no	Typed field-value predicates ({ fieldPath, op, rhs }), ANDed, max 8. See Field-Value Predicates.
excludeInfraShapes	boolean	no	Hide internal infra shapes from results
count	boolean	no	Return a count of matching items instead of the full result list. The response count field is a lower-bound value — it may be capped. Read it as “at least N” rather than an exact total; check the optional hasMore field to determine whether the count was capped.
limit	integer	no	Max items (minimum 1)
cursor	string	no	Pagination cursor from previous response
sinceRepoSeq	integer	no	Return only items that changed after this repo sequence number. Pass -1 to start from the beginning. Reuse the same lower bound across all pages of a single incremental read; only persist the repoSeq returned on the exhausted final page or on a count: true result — intermediate pages do not carry repoSeq. Requires full-repository read authority. Not available when using glob filters (match).

When an incremental read is complete (final page exhausted, or count: true result), the response carries a top-level repoSeq field. Use that value as sinceRepoSeq on the next poll to receive only subsequent changes.

warmhub_thing_get

Param	Type	Required	Description
wrefs	string[]	yes	One or more WarmHub references, 1 through 500 entries per call
version	integer	no	Pin all lookups to this version
includeRetracted	boolean	no	Return things even when retracted at HEAD or at the requested version
dataMode	string	no	"auto" (default) or "full". In "auto" mode, collections larger than 100 members return a summary (member count plus a truncated preview) instead of the full body; fixed-arity Arc/Bond collections and collections with 100 or fewer members keep their full body. Use "full" to force the complete body for large collections too.

There is one call shape for every cardinality: pass a single-entry wrefs array for one thing and a longer array for many. The response is always the batch envelope { requested, items, missing } — requested is the number of wrefs the call processed, items[] carries the resolved things, and missing[] is a string[] of the wrefs that came back empty.

A wref that does not exist, is retracted (without includeRetracted: true), or is not visible to the caller is listed in missing — it is not an error, so a partially-satisfiable batch still returns the things it could read. When a top-level version is supplied and the input wref is not already pinned, missing entries are version-qualified (hub/shapes/<Name>@vN or name@vN) so the round-trip is unambiguous; per-wref pins survive intact (no double-pinning). Duplicates in wrefs are not deduped — they count toward the 500-entry cap and produce duplicate items/missing entries.

orgName/repoName may be omitted when every wref is a durable id or a canonical wh:org/repo/... reference — those route themselves to the repo that owns the target.

warmhub_thing_graph

Param	Type	Required	Description
wref	string	yes	WarmHub reference
version	integer	no	Specific version number
depth	integer	no	Embedded traversal depth, 1 through 5
limit	integer	no	Max embedded nodes, 1 through 500

Returns the root thing with readable assertion about links and readable wref-typed fields embedded as objects. Refs the caller cannot read remain string wrefs, with no internal IDs or denial reasons exposed.

orgName/repoName may be omitted when wref is a durable id.

warmhub_thing_history

Param	Type	Required	Description
wref	string	no	Thing wref
shape	string	no	Filter by shape
about	string	no	Filter by about target
includeRetracted	boolean	no	Allow resolving retracted shape or about targets (does not filter results)
resolveCollections	boolean	no	With about, include assertion history for Arc/Bond/Set/List collections containing the target identity, including when the about wref is pinned
limit	integer	no	Max versions to return
cursor	string	no	Pagination cursor from previous response

At least one of wref, shape, or about is required.

orgName/repoName may be omitted only when wref is a durable id. shape/about surveys and local wrefs always require orgName/repoName — a repo-less filter query is rejected.

warmhub_thing_about

By default, this tool returns assertions whose about target resolves to the supplied target identity. It does not expand collection member refs, so assertions about Arc, Bond, Set, or List collection things that contain the target appear only when resolveCollections:true is set. Pinned @vN inputs stay version-exact and do not expand collection members.

For broader graph discovery, use warmhub_thing_refs with direction:"inbound" to find current things that reference the target through wref fields. Use warmhub_thing_about when you specifically need assertion records and about-target filtering.

orgName/repoName may be omitted when wref is a durable id — a durable id routes itself to the repo that owns the target. When wref is a local wref (e.g. cave with no wh:org/repo/ prefix), orgName and repoName are required; a repo-less call with a local wref is rejected.

Param	Type	Required	Description
orgName	string	no	Organization name. Required when wref is a local wref (no wh:org/repo/ prefix); may be omitted when wref is a durable id.
repoName	string	no	Repository name. Required when wref is a local wref (no wh:org/repo/ prefix); may be omitted when wref is a durable id.
wref	string	yes	Target wref. Accepts a Thing wref (cave) or a Shape wref (hub/shapes/Location).
shape	string	no	Filter assertions by shape
match	string	no	Glob pattern to filter assertion wrefs
where	object[]	no	Typed field-value predicates ({ fieldPath, op, rhs }), ANDed, max 8. See Field-Value Predicates.
resolveCollections	boolean	no	When true, includes assertions about Arc/Bond/Set/List collections containing the target entity. For identity-scoped inputs (bare wrefs, @HEAD, or @ALL), collection members are expanded. Pinned @vN inputs stay version-exact and do not expand collection members — the flag is accepted but has no expansion effect on pinned targets.
role	string	no	Filter by the role the target plays within a collection. Accepted only when resolveCollections:true is set; rejected otherwise.
includeRetracted	boolean	no	Resolve a retracted target and include retracted assertions in the returned results, including within the single children layer when depth is also set.
depth	integer	no	When set, returns one level of child assertions for each top-level result. Values greater than 1 do not produce additional nesting — only one children layer is returned regardless of the value supplied. Each child entry has an empty children array.
limit	integer	no	Max assertions to return
cursor	string	no	Pagination cursor from previous response

Binomial-opinion constraint

Any returned subjective-logic opinion (b, d, u, α) is a binomial opinion — well-formed only when the underlying assertion expresses a binary proposition (true/false). See Opinions as Separate Assertions.

warmhub_thing_query

Param	Type	Required	Description
shape	string	no	Filter by shape
about	string	no	Filter by about target
affirmedAbout	string	no	Pinned target wref (name@vN) that returns only active assertions whose current version was recorded as affirming that exact pinned version of their about target. Use this filter when you need assertions that were explicitly evaluated against a specific version of a target — for example, to find all assertions that affirmed sensor-42@v7. At least one affirmedTargets entry on the assertion must match the supplied pinned wref exactly. See warmhub_thing_create for how affirmedTargets are set and updated. May be combined with match, count, and scoped tokens, but not with sinceRepoSeq. warmhub_thing_search accepts the same filter.
kind	string	no	Filter by kind. One of shape, thing, assertion, or collection.
match	string	no	Glob pattern to filter wrefs
where	object[]	no	Typed field-value predicates ({ fieldPath, op, rhs }), ANDed, max 8. See Field-Value Predicates.
count	boolean	no	Return a count of matching items instead of the full result list. The response count field is a lower-bound value — it may be capped. Read it as “at least N” rather than an exact total; check the optional hasMore field to determine whether the count was capped.
resolveCollections	boolean	no	When about is set, also include assertions about collections containing the target
includeRetracted	boolean	no	Include retracted entities
componentRef	string	no	Filter results to items owned by the given component (its Org/Name ref)
excludeComponents	boolean	no	Exclude component-owned items from results. Accepted alongside componentRef, but the two are mutually exclusive filters, so passing both returns no items.
excludeInfraShapes	boolean	no	Hide internal infra shapes from results
limit	integer	no	Max results. Must be between 1 and 500.
cursor	string	no	Pagination cursor from previous response
sinceRepoSeq	integer	no	Return only items that changed after this repo sequence number. Pass -1 to start from the beginning. Reuse the same lower bound across all pages of a single incremental read; only persist the repoSeq returned on the exhausted final page or on a count: true result — intermediate pages do not carry repoSeq. Requires full-repository read authority. Not available when using glob filters (match), collection expansion (resolveCollections), affirmedAbout, or queries against foreign sources — those query shapes cannot guarantee incremental results.

When an incremental read is complete (final page exhausted, or count: true result), the response carries a top-level repoSeq field. Use that value as sinceRepoSeq on the next poll to receive only subsequent changes.

warmhub_thing_search

Param	Type	Required	Description
query	string	yes	Search query text
shape	string	no	Filter by shape name
kind	string	no	Filter by kind. One of shape, thing, assertion, or collection.
about	string	no	Filter by about target (not supported with vector mode)
affirmedAbout	string	no	Pinned target wref (name@vN) that returns only active assertions whose current version was recorded as affirming that exact pinned version of their about target. Same semantics as the warmhub_thing_query filter.
match	string	no	Glob pattern to filter wrefs
resolveCollections	boolean	no	When about is set, also include assertions about collections containing the target (text mode only)
mode	string	no	"text" (default), "vector", or "hybrid"
includeRetracted	boolean	no	Include retracted entities
componentRef	string	no	Filter results to items owned by the given component (its Org/Name ref)
excludeComponents	boolean	no	Exclude component-owned items from results. Accepted alongside componentRef, but the two are mutually exclusive filters, so passing both returns no items.
excludeInfraShapes	boolean	no	Hide internal infra shapes from results
limit	integer	no	Max results. Must be between 1 and 500.
cursor	string	no	Pagination cursor from previous response (text mode only — vector and hybrid reject cursor). When about or resolveCollections is set, pages may be sparse — paginate until nextCursor is absent.

warmhub_thing_refs

Param	Type	Required	Description
wref	string	yes	WarmHub reference
direction	string	no	"inbound" (default) or "outbound"
fieldPath	string	no	Filter by field path (inbound only)
limit	integer	no	Max results. Must be between 1 and 500.
cursor	string	no	Pagination cursor from previous response

Direction "inbound" returns things that reference the target wref. Direction "outbound" returns things the target wref references.

Use inbound refs as a broad discovery tool when you are unsure whether data points directly at a thing or at a collection containing it. Inbound refs are not a substitute for warmhub_thing_about when you need assertion-only results or assertion filters.

Cross-repo visibility

Cross-repo wref lookups (canonical forms wh:org/repo/hub/shapes/<Name> and wh:org/repo/<name>) require effective repo:read permission on the target repo. Public repos are readable by anyone. For private repos, callers without that access see an error — except warmhub_thing_search with a cross-repo about (returns { items: [] }) and warmhub_thing_get (puts unreadable wrefs into missing[]) — both to keep batch and search streaming-friendly.

See Getting Access for the precise rules.

Write Tools

Tool	Description
warmhub_thing_create	Add Things, Shapes, assertions, or collections in one ordered commit. Returns a structured write result containing a receipt object and a per-item results array.
warmhub_thing_revise	Replace the current body of existing Things or assertions in one ordered commit. Same result shape as warmhub_thing_create.
warmhub_thing_retract	Withdraw Things or assertions from HEAD while keeping their history. Same result shape as warmhub_thing_create.
warmhub_thing_restore	Make retracted Things or Shapes active again, named by durable ID. Same result shape as warmhub_thing_create.
warmhub_thing_rename	Rename Things or Shapes in one ordered commit. Same result shape as warmhub_thing_create.
warmhub_assertion_reaffirm	Change which pinned target versions assertions are affirmed for, without changing claim data. Same result shape as warmhub_thing_create.
warmhub_commit_validate	Evaluate one bounded operation batch with the real commit evaluator without persisting repository state or consuming a receipt.
warmhub_commit_receipt_get	Look up one immutable operation-event receipt by the eventRequestId a write returned or, for a commit write, by the submissionId you sent. Most often used to resolve an ambiguous or lost write, but not limited to that.
warmhub_thing_remove	Permanently remove a thing from the repo by durable ID. Destructive and irreversible. Requires an unrestricted things:delete grant (repo:admin).
warmhub_thing_redact	Irreversibly erase one thing’s canonical content and former name by durable ID, while preserving its durable identity, version history topology, and existing inbound references. Requires an unrestricted things:redact grant (repo:admin). Does not erase backups, completed exports, logs, or copies already delivered downstream.

Use warmhub_thing_history for per-thing version trails.

warmhub_thing_create

warmhub_thing_create and its five siblings, warmhub_thing_revise, warmhub_thing_retract, warmhub_thing_restore, warmhub_thing_rename, and warmhub_assertion_reaffirm, share the input and response contract documented in this section. Each tool carries one operation kind: it takes an items array of that kind’s operation without its operation field, submits the items as one ordered commit, and returns one receipt. A workflow that spans kinds is separate calls with separate receipts; mixed-operation single-commit batches are available through the CLI and SDK.

Each tool’s input schema describes the structural contract for its items. Supply a caller-known submissionId; the call returns a structured success payload with a top-level receipt object and a results array containing one outcome entry per submitted item. Opinion-bearing assertions must be binary propositions.

Shapeless Thing data and arrays of arrays

A shapeless Thing (shapes: []) accepts any JSON value as data. The MCP input schema covers an object, a scalar, null, or a top-level array whose items are scalars, null, or objects, but it cannot express a top-level array of arrays such as [[1, 2], [3, 4]]. To write that shape, use the CLI or SDK, which apply the full write contract. See Data Requirements for the complete contract.

Ambiguous append failures are separate from per-operation failures and return a tool-result error. An ambiguous append failure may have landed server-side. The error message tells you to call warmhub_commit_receipt_get with the submissionId, and its data carries both submissionId and eventRequestId; call that tool before retrying, rather than submitting another write or inferring the outcome from repository state. See MCP Error Handling for the full failure taxonomy.

Param	Type	Required	Description
committer	string	no	Optional untyped wref identifying the actor on whose behalf the writes are made. It must identify an existing thing. Omit it to use the authenticated caller’s normal attribution.
componentRef	string	no	Attribute writes to an installed component, identified by its Org/Name ref. See component identity rules below.
message	string	no	Optional message recorded with each thing-version produced by this call
submissionId	UUID	yes	Caller-known logical submission identity. UUID casing is ignored; the normalized lowercase value is echoed back in the response. Reuse only for an identical retry.
items	array	yes	Non-empty ordered batch of the tool’s operation kind, each item without an operation field. At most 10,000 items per call (100 for warmhub_assertion_reaffirm); use CLI or SDK streaming for larger bulk writes. After an ambiguous append failure, use the named receipt lookup before retrying.
streamId	string	no	Caller-managed stream identity for observability and diagnostic correlation; it does not provide recovery or idempotency.

Response shape:

A submission returns a structured success payload. The receipt fields are spread onto the response root and nested under a receipt key, so callers can read either form. The top-level fields you can rely on are:

Response Field	Type	Description
event	object | null	Header for the persisted event: committedAt, eventDigest, operationCount, repo.orgName / repo.repoName, and repoSeq (a decimal string). null when outcome is "no_event". Also present at receipt.event.
eventRequestId	UUID	Receipt identity for this submission. Pass it to warmhub_commit_receipt_get to resolve an ambiguous write. Also present at receipt.eventRequestId.
operations	array	One outcome entry per submitted operation — same entries as the top-level results array. Also present at receipt.operations.
outcome	string	"event" when the submission persisted an operation event, "no_event" when it persisted nothing. This is the submission-level result, not a per-operation status. Also present at receipt.outcome.
requestDigest	string	sha256:-prefixed digest of the submitted request. Also present at receipt.requestDigest.
schemaVersion	string	"operation-event-receipt/v2" for new writes; a replayed older receipt can be "operation-event-receipt/v1" (see the note below). Also present at receipt.schemaVersion.
submissionId	UUID	The submissionId you supplied, normalized to lowercase. Also present at receipt.submissionId.
results	array	One outcome entry per submitted operation — see the per-operation entry description below.
allocatedTokenRanges	array	Always [].
createdByEmail	string	Email of the authenticated writer, when available.
receipt	object	Nested copy of the receipt. Contains the same event, eventRequestId, operations, outcome, requestDigest, schemaVersion, and submissionId fields described above.

The receipt fields (event, eventRequestId, operations, outcome, requestDigest, schemaVersion, submissionId) are present both at the response root and under receipt. Read them from whichever location suits your client; both are authoritative. The root may also carry write-path timing fields; treat any key not listed above as diagnostic and do not branch on it.

Every entry in results[] (and in receipt.operations[]) carries opIndex, name, operation, and status; warnings and resolvedName may appear on any entry. The rest of the entry depends on status:

• "applied" or "noop" — may also carry version and dataHash.
• "error" — carries a non-empty errors[] array describing the per-operation failure, and no version or dataHash.

A "noop" entry is a successful outcome: the operation was valid and changed nothing.

older receipt shape

A retry that replays a pre-v2 receipt returns schemaVersion: "operation-event-receipt/v1", whose operations[] entries carry an optional status of "success" | "noop" | "failed" and a singular error instead of errors[]. Branch on schemaVersion before reading per-operation results.

committer identity restriction

warmhub/users Identity wrefs (e.g. wh:warmhub/users/<id>) are only valid as the committer when the token belongs to the user that Identity represents. You cannot set committer to another user’s Identity even if that Identity is visible in the public graph. Any other existing thing is a valid committer target without this restriction, named by its bare wref (for example alice-bot) or its canonical form (wh:<org>/<repo>/<name>).

Binomial-opinion constraint

When writing an assertion that carries a subjective-logic opinion (b, d, u, α), the assertion must express a binary proposition (true/false). The opinion tuple is a binomial opinion and is meaningless on open-ended claims. See Opinions as Separate Assertions.

Component identity rules:

• User tokens may claim components installed by that user.
• Callers with org:configure for the org may claim any installed component in the org.
• Action tokens derive the component from the running subscription and reject mismatched explicit values.

Item forms per tool:

The entries below show the primary fields for each operation kind; they are not an exhaustive schema. Optional fields such as expectedVersion and leaseId are documented in Write Operations, and warmhub_repo_describe returns write examples for the repo’s own Shapes under commitContract.writeExamples.

• warmhub_thing_create, Shape: { name: "hub/shapes/<Name>", shapes: [], data: { fields }, skipExisting? }
• warmhub_thing_create, Thing: { name, shapes, data, skipExisting? } — shapes: [] for a shapeless Thing
• warmhub_thing_create, assertion: { name, shapes, data: { about, ... }, affirmedTargets?, skipExisting? } — one of shapes composes Assertion
• warmhub_thing_create, collection: { name, shapes: ["Set"], data: { members }, skipExisting? } — Arc takes data: { from, to }, Bond takes data: { ends }
• warmhub_thing_revise: { name, shapes, data, expectedVersion?, leaseId? } — for assertions, also accepts affirmedTargets?
• warmhub_thing_retract: { name, reason?, expectedVersion?, leaseId? } — withdraws the entity from default reads
• warmhub_thing_restore: { name, newName?, expectedVersion?, leaseId? } — name is the retracted Thing’s durable ID (name-form wrefs and wref prefixes are not accepted); newName restores it under another name; leaseId pins the restore to a held lease
• warmhub_thing_rename: { name, newName } — changes identity metadata without creating a new body version
• warmhub_assertion_reaffirm: { name, add?, remove?, leaseId?, expectedVersion? } — mints a new assertion version that keeps the existing assertion content unchanged while updating which pinned target versions it affirms, via the add? and remove? delta fields. At least one of add or remove must be present; a reaffirm with neither is rejected.

Items carry no operation, kind, or shape field: the tool names the operation, and the v2 write contract refuses kind and shape.

Write path rejects @ALL. Create things with explicit names; dependent assertions and collections should reference those names directly.

affirmedTargets on assertion add and revise is an array of pinned target wrefs (name@vN) that records which specific versions of the about-target the assertion was evaluated against. The reaffirm operation updates the affirmed targets via add? and remove? delta fields while keeping the assertion content the same.

On revise, affirmedTargets is the complete new set, not a delta — and omitting it clears the assertion’s affirmations rather than carrying them forward. This is deliberate: a revise changes the claim, and affirmations recorded against the old claim do not transfer to the new one. If a revise should keep its existing affirmations, restate them in affirmedTargets on that same operation. Use reaffirm when the affirmation set should change but the claim should not.

Per-operation result warnings:

Successful and noop result entries can include:

{
  "warnings": {
    "undeclaredFields": ["status", "filePath"],
    "undeclaredFieldsTruncated": true,
    "totalUndeclared": 600,
    "coalescedWrefs": [
      { "fieldPath": "owner", "wref": "nobody", "reason": "thing_absent" }
    ],
    "ignoredVersionPins": [
      { "fieldPath": "target", "wref": "sensor-42@v3", "binding": "identity" }
    ],
    "deprecations": [
      { "shape": "Pair", "message": "Pair is deprecated; use an ordinary Arc Thing with data {from, to}. Existing Pairs remain readable forever. Removal is tracked by warmhub/warmhub-app#10668.", "removalMilestone": "1.0" }
    ]
  }
}

warnings.undeclaredFields lists top-level keys present in the submitted data but not declared in the target shape. When the list is capped, undeclaredFieldsTruncated: true is set and totalUndeclared reports the full count. warnings.coalescedWrefs lists optional wref fields whose resolver outcome was thing_absent and was coalesced to null — each entry carries fieldPath, wref, and reason; missing shapes and every other failure remain hard errors. When capped, coalescedWrefsTruncated: true is set with totalCoalescedWrefs. warnings.ignoredVersionPins lists wref fields whose version pin was stripped during write processing — each entry carries fieldPath, wref, and binding. warnings.deprecations lists deprecation notices for deprecated Shapes or legacy write forms — each entry carries shape, message, and removalMilestone. Notices are deduplicated across the commit: only the first successful operation that uses a given deprecated Shape carries its notice. message is human-readable migration guidance and can change, so branch on shape and removalMilestone, not on the message text. warnings.shapeless: true is set on an add or revise of a shapeless Thing (shapes: []), including an add that skipExisting turns into noop; retract, restore, and rename results do not carry it. The struct is additive — an operation can carry any combination of warning kinds. All warnings are informational; they do not turn the operation into a failure. See Optional Wref Fields. For add operations, skipExisting: true returns noop when the target already exists instead of failing. For revise and retract operations, expectedVersion applies the write only if the target is still at that version, otherwise it rejects with CONFLICT. A revise whose data matches the current version returns noop instead of creating a new version. See Conditional Operations for the full model.

Unauthorized component claims reject with FORBIDDEN.

warmhub_commit_validate

Evaluates the complete ordered operation batch with the same server evaluator as the write tools, but creates no repository state or receipt and dispatches no asynchronous action. The tool requires write authority even though its MCP contract is read-only and non-destructive.

Param	Type	Required	Description
orgName	string	yes (global)	Organization name
repoName	string	yes (global)	Repository name
operations	array	yes	One complete ordered batch, at most 10,000 operations.
message	string	no	Message projected with the preview; not persisted.
committer	string	no	Optional untyped committer wref, evaluated under the same rules as the write tools.
componentRef	string	no	Optional installed component attribution.
skipExisting	boolean	no	Apply skipExisting to add operations only.
includeWouldBeBody	boolean	no	Include projected resulting bodies when disclosure rules permit.

The response contains one ordered top-level result per input, optional nested effects, aggregate counts, canCommit, persistence caveats, and an authorization-safe baseline. Statuses are would_apply, noop, or error; failed one-to-many lowering marks valid sibling effects discarded.

MCP’s shared route limit is 1 MiB, smaller than the 4 MiB SDK/CLI validation limit. The tool has no submissionId, streamId, chunking, or receipt arguments. Use the CLI or an SDK for larger previews. A preview is a snapshot, so concurrent repository changes or real-write admission can still make a later write fail.

warmhub_commit_receipt_get

Looks up one immutable write receipt by either the eventRequestId a write response returned or, for a commit write (warmhub_thing_create or a sibling write tool), the submissionId you sent; pass exactly one. Any exact write that carries an eventRequestId produces a receipt this tool can read — warmhub_repo_content_set, warmhub_collection_create, and warmhub_collection_revise as well as the six write tools — so it is not limited to one tool or one failure mode.

The common use is resolving an ambiguous write: call it after an ambiguous append failure, before retrying, to determine whether the submission landed server-side.

After an ambiguous append failure, pass the eventRequestId the error carries. If a commit write’s response was lost and you hold only your submissionId, pass that instead. warmhub_repo_content_set, warmhub_collection_create, and warmhub_collection_revise take an eventRequestId you supply, so pass that id for their receipts.

Param	Type	Required	Description
orgName	string	yes (global)	Organization name
repoName	string	yes (global)	Repository name
eventRequestId	UUID	one of the two	The id of the write whose receipt you want. After an ambiguous commit write this is the eventRequestId the error carries. For warmhub_repo_content_set, warmhub_collection_create, and warmhub_collection_revise it is the eventRequestId you passed in.
submissionId	UUID	one of the two	The caller-known UUID sent with a commit write (warmhub_thing_create or a sibling write tool). Use when the response was lost.

Passing both ids, or neither, is rejected.

Returns the same immutable write receipt documented under warmhub_thing_create when a matching write exists — the receipt on its own, without the compatibility keys that tool adds alongside it. Missing receipts and receipts the caller is not authorized to read are intentionally indistinguishable — both return a not-found result rather than a distinct authorization error, so that the existence of a write cannot be inferred from the error shape.

warmhub_thing_remove

Permanently removes a thing from the repo by durable ID. This operation is destructive and irreversible. Requires an unrestricted things:delete grant. Because it removes by durable ID, a token limited to particular refs is rejected with FORBIDDEN.

Param	Type	Required	Description
orgName	string	yes	Organization name
repoName	string	yes	Repository name (slug)
durableId	string	yes	Durable ID of the thing to remove.
expectedVersion	integer	no	The version you read. If the thing has changed since, the call fails with CONFLICT. When omitted, the current version is used.
eventRequestId	UUID	yes	Caller-known idempotency key for this write request. Reuse only for an identical retry.

warmhub_thing_redact

Redaction irreversibly erases one thing’s canonical content and former name while preserving its durable identity, version history topology, and existing inbound references. Every version’s body becomes {}, every current and historical name becomes hub/redacted/<durableId> (the former name no longer resolves), and no new version is created. Redaction does not delete the thing; to delete it, use warmhub_thing_remove. See Redaction for the full behavior.

Requires an unrestricted things:redact grant, which maps from repo:admin. A token narrowed to particular refs is rejected with FORBIDDEN. Shapes and removed things cannot be redacted. Redacting an already-redacted thing is a no-op.

Redaction does not erase backups, completed exports, logs, or copies already delivered downstream. See Redaction for other copies it leaves in place.

Param	Type	Required	Description
orgName	string	yes	Organization name
repoName	string	yes	Repository name (slug)
durableId	string	yes	Durable ID of the thing to redact (metadata.durableId from a read). Name-form wrefs, the wh: prefix, and version selectors are not accepted.
expectedVersion	integer	no	The version you read. If the thing has changed since, the call fails with CONFLICT. When omitted, the current version is used.
eventRequestId	UUID	yes	Supply a new UUID per redaction, and reuse it to retry an ambiguous outcome.

Shape Tools

Tool	Description
warmhub_shape_list	List shapes in a repository. Each item includes per-shape queryHints.
warmhub_shape_get	Get a shape by name. Response includes queryHints.
warmhub_shape_template	Generate write-operation templates for one or more shapes. Read-only; commit category. See Generating Templates.

warmhub_shape_list

Lists shapes in the repo. orgName and repoName are required.

Param	Type	Required	Description
orgName	string	yes	Organization name.
repoName	string	yes	Repository name.
match	string	no	Glob pattern to filter shape names by bare name (e.g. Sensor*), not by full wref.
componentRef	string	no	Return only shapes owned by this component, identified by its Org/Name ref (e.g. warmhub/veritas). Mutually exclusive with excludeComponents.
excludeComponents	boolean	no	Exclude all component-owned shapes from results. Mutually exclusive with componentRef — passing both returns no shapes.

Each item in the response includes a queryHints block (queryableFields, wrefFields, suggestedPatterns) to help you choose the right warmhub_thing_query, warmhub_thing_search, or warmhub_thing_refs pattern for that shape.

warmhub_shape_get

Param	Type	Required	Description
shapeName	string	yes	Shape name

Both warmhub_shape_get and warmhub_shape_list include a queryHints block (queryableFields, wrefFields, suggestedPatterns) to help agents choose warmhub_thing_query, warmhub_thing_search, and warmhub_thing_refs patterns for each shape.

warmhub_shape_template

Generates write-operation templates for one or more shapes in the repo. Read-only tool in the commit category. For conceptual background see Generating Templates.

Param	Type	Required	Description
shapeNames	string	yes	Comma-separated shape names to generate templates for
kind	string	no	Filter templates to a specific kind. One of thing or assertion.
operation	string	no	Filter to a specific operation type. One of add, revise, or retract.
about	string	no	Populate the about field in generated assertion templates with this wref
count	integer	no	Number of example templates to generate per shape

Collection Tools

First-class tools for working with named collections in a repo.

Shape support at a glance:

Shape family	Writable (create, revise)	Readable (members, contains, diff, stats)
Arc	✓	✓
Bond	✓	✓
Set	✓	✓
List	✓	✓
Pair	✓ (deprecated — accepted with a deprecation warning)	✓
Triple	—	✓ (legacy, read-only)

Use create to make a collection and revise to change its membership; members, stats, and contains to read one; and diff to compare two collections or two versions of the same collection.

Tool	Description
warmhub_collection_create	Create a new named collection in the repo. Requires repo:write.
warmhub_collection_members	List the current members of a named collection.
warmhub_collection_contains	Check whether a named collection contains one or more given wrefs.
warmhub_collection_diff	Compute the diff between two versions of a named collection.
warmhub_collection_revise	Revise the membership of an existing named collection. Requires repo:write.
warmhub_collection_stats	Return summary statistics for a named collection (type, wref, version, memberCount, and uniqueMemberCount).

Selector-backed collection rules

warmhub_collection_create and warmhub_collection_revise both accept selector fields — shape, about, match, kind, excludeComponents, componentRef, where, sourceOrgName, sourceRepoName — which populate membership from a live query instead of an explicit member list. These rules apply to both:

• Set-only. Any selector field requires the collection to be a set; every other type is rejected, including the deprecated pair, whether the selector reads this repo or a foreign one.
• Needs an anchor. At least one of shape, about, match, componentRef, or where is required when any selector field is used. kind and excludeComponents only narrow an already-anchored selector.
• Foreign source repos. sourceOrgName and sourceRepoName must be paired with each other and require an anchor selector. They cannot be combined with any explicit member argument — use canonical wh:org/repo/... member wrefs instead, or omit the source repo.
• Otherwise selectors and members compose on create: the result set is seeded from members first, then selector query matches are added. A foreign source repo is the exception, per the rule above — and on revise, add/remove are a further exception, below.

Each tool then adds one rule of its own, below.

warmhub_collection_create

Selector fields follow the shared rules above, where create’s explicit member arguments are members, add, remove, and replaceMembers. Create has one rule of its own:

• add, remove, and replaceMembers require from. They adjust a collection copied by from, so without it the call is rejected. from is in turn exclusive with members, with selector fields, and with sourceOrgName/sourceRepoName — so a create either copies an existing collection and adjusts it, or builds a fresh set from members and/or a selector, never both.
• add/remove only work on a set. Delta updates are rejected for arc, bond, list, and the deprecated pair — copying one of those and changing its membership means passing the full list via replaceMembers, which is the non-set escape hatch and is not a delta.

Param	Type	Required	Description
orgName	string	yes (global)	Organization name
repoName	string	yes (global)	Repository name
eventRequestId	UUID	yes	Caller-known idempotency key for this write request. Reuse only for an identical retry.
type	string	yes	Collection type: "arc", "bond", "set", "list", or "pair" (deprecated — accepted with a deprecation warning; use "arc", "bond", "set", or "list" for new collections)
name	string	yes	Collection name (local wref segment)
members	string[]	no	Initial member wrefs. May be combined with selector fields — the result set is seeded from these wrefs before selector query matches are added.
from	string	no	Source wref to copy members from. Exclusive with members, selector fields, and sourceOrgName/sourceRepoName.
add	string[]	no	Wrefs to add to the copied member set. Requires from.
remove	string[]	no	Wrefs to remove from the copied member set. Requires from.
replaceMembers	string[]	no	Replace the copied member list with these wrefs. Requires from.
shape	string	no	Selector: filter by shape. Acts as an anchor selector.
about	string	no	Selector: filter by about target. Acts as an anchor selector.
match	string	no	Selector: glob pattern to filter wrefs. Acts as an anchor selector.
kind	string	no	Selector: filter by kind. One of shape, thing, assertion, or collection. Requires at least one anchor selector to be present.
excludeComponents	boolean	no	Selector: exclude component-owned items from the selector result. Requires at least one anchor selector to be present.
componentRef	string	no	Selector: filter to items owned by the given component. Acts as an anchor selector.
sourceOrgName	string	no	Selector: org name of a foreign repo to read selector results from. Must be paired with sourceRepoName. Only valid for selector-backed set collections. Cannot be combined with any explicit member argument — members, add, remove, or replaceMembers.
sourceRepoName	string	no	Selector: repo name of a foreign repo to read selector results from. Must be paired with sourceOrgName. Only valid for selector-backed set collections. Cannot be combined with any explicit member argument — members, add, remove, or replaceMembers.
where	object[]	no	Selector: typed field-value predicates. Acts as an anchor selector.
message	string	no	Message recorded with the write
committer	string	no	Wref identifying the actor on whose behalf the write is made
skipExisting	boolean	no	Return noop instead of failing when the collection already exists

warmhub_collection_members

orgName and repoName may be omitted when wref is a self-routing durable ID — the durable ID routes itself to the repo that owns the collection. cursor must be paired with limit.

Param	Type	Required	Description
orgName	string	no	Organization name. Required unless wref is a durable ID.
repoName	string	no	Repository name. Required unless wref is a durable ID.
wref	string	yes	Collection wref
version	integer	no	Pin the lookup to a specific collection version
limit	integer	no	Max members to return. Required when cursor is provided.
cursor	string	no	Pagination cursor from previous response. Must be paired with an explicit limit.

warmhub_collection_contains

Param	Type	Required	Description
orgName	string	yes (global)	Organization name
repoName	string	yes (global)	Repository name
wref	string	yes	Collection wref
members	string[]	yes	Wrefs to check for membership
position	integer	no	Check membership at a specific position. Valid for ordered collection types (Arc, Pair, List, and legacy Triple); rejected for unordered Set and Bond collections.
version	integer	no	Check membership at a specific collection version

warmhub_collection_diff

Param	Type	Required	Description
orgName	string	yes (global)	Organization name
repoName	string	yes (global)	Repository name
leftWref	string	yes	Left-hand collection wref
rightWref	string	yes	Right-hand collection wref
leftVersion	integer	no	Version to use for the left-hand collection. Defaults to HEAD.
rightVersion	integer	no	Version to use for the right-hand collection. Defaults to HEAD.
mode	string	no	Comparison mode: "auto" (default), "membership", or "ordered"

warmhub_collection_revise

Selector fields follow the shared rules above, where revise’s explicit member arguments are members, add, and remove. Revise takes no from, and has one rule of its own:

• add/remove are exclusive with replacement membership. Passing either alongside members or any selector field is rejected. So a revise is either a delta — add and/or remove against current membership — or a replacement built from members and/or a selector, never both.
• Deltas only work on a set. add/remove are rejected for arc, bond, list, and the deprecated pair; revise those by passing the full members list.

Param	Type	Required	Description
orgName	string	yes (global)	Organization name
repoName	string	yes (global)	Repository name
eventRequestId	UUID	yes	Caller-known idempotency key for this write request. Reuse only for an identical retry.
wref	string	yes	Collection wref
members	string[]	no	Replace the full member list with these wrefs. May be combined with selector fields — the result set is seeded from these wrefs before selector query matches are added.
add	string[]	no	Wrefs to add to the collection
remove	string[]	no	Wrefs to remove from the collection
shape	string	no	Selector: filter by shape. Acts as an anchor selector.
about	string	no	Selector: filter by about target. Acts as an anchor selector.
match	string	no	Selector: glob pattern to filter wrefs. Acts as an anchor selector.
kind	string	no	Selector: filter by kind. One of shape, thing, assertion, or collection. Requires at least one anchor selector to be present.
excludeComponents	boolean	no	Selector: exclude component-owned items from the selector result. Requires at least one anchor selector to be present.
componentRef	string	no	Selector: filter to items owned by the given component. Acts as an anchor selector.
sourceOrgName	string	no	Selector: org name of a foreign repo to read selector results from. Must be paired with sourceRepoName. Only valid for selector-backed set collections. Cannot be combined with any explicit member argument — members, add, or remove.
sourceRepoName	string	no	Selector: repo name of a foreign repo to read selector results from. Must be paired with sourceOrgName. Only valid for selector-backed set collections. Cannot be combined with any explicit member argument — members, add, or remove.
where	object[]	no	Selector: typed field-value predicates. Acts as an anchor selector.
message	string	no	Message recorded with the write
committer	string	no	Wref identifying the actor on whose behalf the write is made

warmhub_collection_stats

orgName and repoName may be omitted when wref is a self-routing durable ID.

Param	Type	Required	Description
orgName	string	no	Organization name. Required unless wref is a durable ID.
repoName	string	no	Repository name. Required unless wref is a durable ID.
wref	string	yes	Collection wref
version	integer	no	Pin the lookup to a specific collection version

Returns the following fields:

Response Field	Type	Description
type	string	Collection shape family. One of "set", "list", "arc", "bond", "pair" (deprecated — writable but accepted with a deprecation warning), or "triple" (legacy, read-only).
wref	string	The returned collection wref, always in local form (e.g. my-set) — it names the collection within the repo you queried and is never expanded to the cross-repo wh:org/repo/... form, even when you addressed the collection by a canonical wref.
version	integer	Version number of the returned collection snapshot. When no version parameter is supplied this is the HEAD version; when a version parameter is supplied this reflects that pinned version.
memberCount	integer	Total number of member entries, including duplicates for ordered collection types.
uniqueMemberCount	integer	Number of distinct member wrefs in the collection.

Subscription Tools

See Subscriptions for concepts and Creating Subscriptions for setup guides with filter and credential examples.

Every subscription tool addresses either scope. Omitting scope (or passing scope: "repo") addresses a repository subscription and requires repoName. Passing scope: "org" addresses an organization subscription: supply orgName only, and omit repoName, shapeName, filterJson, and sourceRepoRef. A missing repoName is an error rather than a silent switch to org scope, so a lifecycle call can never retarget the org subscription that happens to share a name.

Tool	Description
warmhub_subscription_list	List non-retired subscriptions. Retired subscriptions remain readable by name via warmhub_subscription_get but do not appear in list results — see Managing Subscriptions for what retirement means and when it happens.
warmhub_subscription_get	Get subscription metadata by name.
warmhub_subscription_create	Create a webhook subscription.
warmhub_subscription_update	Update an existing subscription’s trigger or webhook config.
warmhub_subscription_pause	Pause an active subscription.
warmhub_subscription_resume	Resume a paused subscription.
warmhub_subscription_delete	Delete a subscription.

warmhub_subscription_list

Param	Type	Required	Description
orgName	string	yes	Organization name
repoName	string	no	Repository name. Required when scope is "repo" (the default); omit when scope is "org".
scope	string	no	"repo" (default) or "org"

warmhub_subscription_get

Param	Type	Required	Description
orgName	string	yes	Organization name
repoName	string	no	Repository name. Required when scope is "repo" (the default); omit when scope is "org".
name	string	yes	Subscription name
scope	string	no	"repo" (default) or "org"

warmhub_subscription_create

Param	Type	Required	Description
orgName	string	yes	Organization name
repoName	string	no	Repository name. Required when scope is "repo" (the default); omit when scope is "org".
name	string	yes	Subscription name
scope	string	no	"repo" (default) or "org". Under "org" the event catalog is the org one below and repoName, shapeName, filterJson, and sourceRepoRef are rejected
kind	string	yes	"webhook" or "cron". "webhook" is the supported value for new subscriptions; "cron" is accepted by the schema only so older callers receive a deterministic rejection.
eventType	string	no	Event type to subscribe to. Under repo scope, one of commit, repo.renamed, thing.renamed, or shape.renamed, defaulting to commit. Under scope: "org", one of org.renamed, org.member_added, org.repo_created, org.repo_published, org.service_account_created, org.service_account_role_changed, org.service_account_disabled, org.service_account_enabled, or org.service_account_deleted, defaulting to org.renamed.
shapeName	string	no	Shape to subscribe to. For commit subscriptions, provide either shapeName or filterJson.shape — except for shape lifecycle subscriptions, which omit both and rely on a {"kind":"shape", ...} filter. Not applicable for repo.renamed, thing.renamed, or shape.renamed subscriptions.
filterJson	object	no	Recursive subfilter/v1 commit-operation filter with operation, kind, shape, name, match, all, any, and not. Required for commit; rejected for metadata rename events.
webhookUrl	string	yes	Webhook endpoint URL
fallbackWebhookUrl	string	no	Optional fallback endpoint called after a terminal delivery failure
allowTraceReentry	boolean	no	Reentry policy for write-triggered subscriptions. Defaults to false
sourceRepoRef	string	no	Source repo (org/repo) for a cross-repo subscription. Must be in the same org as the home repo
componentRef	string	no	Attribute this subscription to an installed component, identified by its Org/Name ref (e.g. warmhub/veritas). See Component Tools for the component ref format.
notifyOnSuccess	boolean	no	Deprecated compatibility field; accepted but ignored. Action notifications are terminal-failure-only

For a commit subscription, omitted eventType defaults to commit, so this is a complete filter example:

{
  "orgName": "acme",
  "repoName": "sensors",
  "name": "new-sensors",
  "kind": "webhook",
  "shapeName": "Sensor",
  "filterJson": {
    "all": [
      { "operation": "add" },
      { "kind": "thing" }
    ]
  },
  "webhookUrl": "https://hooks.example.com/warmhub"
}

When both shapeName and filterJson.shape are present, they must identify the same shape. A structurally shape-only filter such as {"kind":"shape"} is the only commit form that needs neither binding. Metadata rename events reject shapeName, filterJson, and sourceRepoRef.

Creating an org-scoped subscription

scope: "org" creates organization-owned automation. The caller must be an organization owner or admin. repoName, shapeName, filterJson, and sourceRepoRef are rejected, and an omitted eventType means org.renamed.

{
  "orgName": "acme",
  "scope": "org",
  "name": "org-rename-hook",
  "kind": "webhook",
  "eventType": "org.member_added",
  "webhookUrl": "https://hooks.example.com/warmhub"
}

warmhub_subscription_update

Param	Type	Required	Description
orgName	string	yes	Organization name
repoName	string	no	Repository name. Required when scope is "repo" (the default); omit when scope is "org".
name	string	yes	Existing subscription name
scope	string	no	"repo" (default) or "org". shapeName and filterJson are rejected under "org"
shapeName	string	no	Replacement commit-subscription shape. Rejected for metadata-event and cross-repo subscriptions.
filterJson	object	no	Replacement recursive subfilter/v1 filter. Rejected for metadata-event and cross-repo subscriptions.
webhookUrl	string	no	Replacement webhook URL
fallbackWebhookUrl	string or null	no	Replacement fallback webhook URL. Use null to clear it
allowTraceReentry	boolean	no	Replacement reentry policy for write-triggered subscriptions
notifyOnSuccess	boolean	no	Deprecated compatibility field; accepted but ignored. Action notifications are terminal-failure-only

Updates patch only the fields supplied; omitted fields retain their current values. name, kind, and eventType cannot be changed. For commit subscriptions, the merged shapeName and filterJson.shape constraints must still agree and retain a valid shape binding (or a structurally shape-only filter).

warmhub_subscription_pause / warmhub_subscription_resume / warmhub_subscription_delete

Param	Type	Required	Description
orgName	string	yes	Organization name
repoName	string	no	Repository name. Required when scope is "repo" (the default); omit when scope is "org".
name	string	yes	Subscription name
scope	string	no	"repo" (default) or "org"

Action Tools

Tool	Description
warmhub_subscription_log	Get delivery feed for a subscription. Narrowed readers receive operational metadata and visible matched operations; full-repository readers also receive free-form diagnostics.
warmhub_subscription_runs	List a repository’s subscription delivery runs. For application-level round or session containers, use warmhub_thing_query with a shape filter.
warmhub_subscription_attempts	Get attempt history for one delivery run of a subscription. Free-form diagnostics require full-repository read.
warmhub_notifications	List terminal action-failure notifications for a repo. Only runs that have reached a non-recoverable failure state appear in this feed.

warmhub_subscription_log

Param	Type	Required	Description
subscriptionName	string	yes	Subscription name
limit	integer	no	Max items, 1–500. Required when cursor is provided
cursor	string	no	Pagination cursor from previous response. Must be paired with an explicit limit — supplying cursor alone is rejected with "cursor" requires "limit"

Each item in the response includes delivery fields plus optional run diagnostics:

Response Field	Type	Description
deliveryId	string	Required identifier for this delivery. Use this value when waiting on lease-based deliveries.
runId	string?	Identifier for the action run associated with this delivery. May be absent when the delivery has not yet been associated with a run.
runStatus	string?	Run outcome: succeeded, failed_terminal, dead_letter, etc.
attemptCount	number?	Current attempt number
maxAttempts	number?	Maximum attempts allowed
lastErrorCode	string?	Error classification code (for example HTTP_502 or WEBHOOK_TARGET_REJECTED)
lastErrorMessage	string?	Human-readable error description

warmhub_subscription_runs

Lists action runs in a repository. Accepts optional filters to narrow results by status, outcome, time range, or exact run or subscription identity.

Param	Type	Required	Description
runId	string	no	Return the single run with this identifier. Can be combined with subscriptionName, status, outcome, since, and cursor.
subscriptionName	string	no	Filter runs to those triggered by this subscription.
status	string	no	Filter by status: pending, running, processing, retry_wait, suppressed, succeeded, failed_terminal, dead_letter
outcome	string	no	Filter by terminal outcome. Accepted values: succeeded or failed. failed matches runs in a terminal failure state (failed_terminal or dead_letter); it does not match every non-success state. Cannot be combined with status.
since	string	no	ISO datetime or unix timestamp. Cannot be combined with cursor.
limit	integer	no	Max results. Must be between 1 and 200.
cursor	string	no	Pagination cursor from previous response. Cannot be combined with since. When present, the response includes nextCursor when more results are available.

The combinations status+outcome and since+cursor are not accepted and will be rejected.

warmhub_subscription_attempts

Param	Type	Required	Description
runId	string	yes	Action run identifier (UUIDv7) for the target run.

warmhub_notifications

Param	Type	Required	Description
orgName	string	yes (global)	Organization name
repoName	string	yes (global)	Repository name
since	string	no	ISO datetime or unix timestamp
limit	integer	no	Max results (1–200)

Returns terminal action-failure notifications for the repo — only runs that have reached a non-recoverable failure state produce records in this feed. See Actions for the full HTTP contract, including the GET /api/repos/:orgName/:repoName/actions/notifications endpoint.

Component Tools

Tool	Description
warmhub_component_install	Install a registered component (<org>/<name>) into the repo: applies its manifest (shapes, credential sets, subscriptions, seeds) and runs the optional setup handshake. A fresh resource-phase failure rolls back and throws CONFLICT. A replay of a historical install may return state: degraded with errors[]; callers must check returned results. Requires repo:write. Components whose manifests declare credentials or subscriptions require additional permissions — see the note below.
warmhub_component_uninstall	Uninstall a registered component (the wh component teardown operation): pauses its subscriptions, revokes its tokens, dispatches the optional uninstall callback, and marks the install record uninstalled. Frees the shape names the component claimed so a reinstall can reclaim them, while leaving the existing shapes and any seeded data in place. Non-destructive — reinstall revives the install. Requires repo:write.

warmhub_component_install / warmhub_component_uninstall

Param	Type	Required	Description
orgName	string	yes (global)	Organization name
repoName	string	yes (global)	Repository name
componentRef	string	yes	The registered component to install or uninstall, as <org>/<name> (e.g. warmhub/veritas).
submissionId	UUID	yes	Caller-owned root idempotency key for this install or uninstall request; every install phase derives its own event-request id from it. UUID casing is ignored and the normalized lowercase value is echoed back in the response. Reuse it only for an identical retry — and note that reuse is not a blanket replay: when a setup dispatch from the first attempt may already have reached the component’s receiver, the retry is refused rather than dispatched a second time.

Additional permissions for manifest-driven installs

repo:write is always required for warmhub_component_install. Components whose manifests declare credential sets or subscriptions require the token to also carry the corresponding repo-level permissions for those resources. If the caller is missing any manifest-required permissions, the install is rejected with Cannot install: caller is missing repo permissions required by the manifest: .... Check the component’s published manifest to determine which permissions apply before attempting an install.