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(...)
warmhub_shape_list	client.shape.list(...)
warmhub_subscription_list	client.subscription.list(...)
warmhub_commit_submit	client.commit.apply(...) — note the verb differs
warmhub_capabilities	client.diagnostics.capabilities() — returns the backend API version, minimum supported SDK, and feature flags (not the tool catalog)
warmhub_repo_describe	client.repo.describe() — returns repo metadata, shapes, stats, subscriptions, license, and a page of HEAD records; 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; the last three rows are the exceptions — the SDK verb differs (commit.apply), returns different data (diagnostics.capabilities), or omits the MCP-only write contract and generated examples (repo.describe).

Auth awareness in tool descriptions

All read-only tools include an auth awareness note in their runtime description, instructing agents to suggest authentication when expected data is missing. This note is appended automatically and does not appear in the static descriptions below.

Meta Tools

Orientation and capability discovery. The meta category covers five 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_use	No-op tool used to signal intent or context to the MCP host. Takes no arguments; returns an advisory noop note. Useful for structured agent workflows that declare what they are about to do before acting.
warmhub_channel	No-op tool used to establish or label a logical channel within a session. Takes no arguments; returns an advisory noop note.
warmhub_doctor	Diagnostic tool. Takes no arguments. Returns { ok: true, capabilities, hint }, where capabilities is a diagnostics payload containing apiVersion, minSupportedSdk, and features.

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, description, readOnly, openWorld, destructive, annotationJustification) advertised on the current endpoint.
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 take orgName as an argument and need no repository.

Tool	Description
warmhub_org_list	List organizations (archived hidden by default). (global only)
warmhub_org_get	Get an organization by name. (global only)
warmhub_org_set_display_name	Set the human-readable display name for an organization. The display name must be non-empty. (global only)
warmhub_org_set_description	Set or clear an organization description. (global only)
warmhub_org_archive	Archive an organization. (global only)
warmhub_org_unarchive	Unarchive an organization. (global only)

warmhub_org_list

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

warmhub_org_get

Param	Type	Required	Description
orgName	string	yes	Organization name

warmhub_org_set_description

Param	Type	Required	Description
orgName	string	yes	Organization name
description	string	no	New org description. Trimmed; empty strings clear the value; max 2000 characters.

warmhub_org_set_display_name

Param	Type	Required	Description
orgName	string	yes	Organization name
displayName	string	yes	New human-readable display name. Must be non-empty and non-whitespace; max 100 characters.

warmhub_org_archive

Param	Type	Required	Description
orgName	string	yes	Organization name

Archived organizations block new repo creation and member additions.

warmhub_org_unarchive

Param	Type	Required	Description
orgName	string	yes	Organization name

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_set_description	Set or clear a repository description.
warmhub_repo_set_display_name	Set the human-readable display name for a repository. Requires repo:write.
warmhub_repo_archive	Archive a repository.
warmhub_repo_unarchive	Unarchive a repository.

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_set_description

Param	Type	Required	Description
orgName	string	yes	Organization name
repoName	string	yes	Repository name
description	string	no	New repo description. Trimmed; empty strings clear the value; max 2000 characters.

warmhub_repo_set_display_name

Param	Type	Required	Description
orgName	string	yes	Organization name
repoName	string	yes	Repository name
displayName	string	yes	New human-readable display name. Must be non-empty and non-whitespace; max 100 characters.

Returns the updated repo object.

warmhub_repo_archive

Param	Type	Required	Description
orgName	string	yes	Organization name
repoName	string	yes	Repository name

Archived repositories reject new commits.

warmhub_repo_unarchive

Param	Type	Required	Description
orgName	string	yes	Organization name
repoName	string	yes	Repository name

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 (add/revise/retract variants, named collection rules, about semantics)
• 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	Wref of the license declaration thing.
spdxExpression	string | null	The full SPDX expression as stored.
appliesTo	string | null	Wref of the subject the license applies to.
attributionText	string | null	Optional attribution text.
declaredBy	string | null	Wref of the declaring entity.
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. The block exposes four state buckets — ready, building, failed, and other — each containing 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.

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 and a structured refs field. Read-only.
warmhub_repo_content_set	Set Content/Readme or Content/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, shape: "Content", name: "...", data: { content: "" }, active: true }).

For kind: llms-txt, always returns a synthesized response. data.content contains the full rendered markdown, and the response includes a refs field with partitioned outbound/inbound references; cross-org refs the caller cannot read are omitted. (MCP requests are always authenticated; for the anonymous reduced-body variant of llms.txt, 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 warmhub_commit_submit, 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 thing by wref. For many wrefs in one call use warmhub_thing_get_many; to resolve a wref’s canonical identity first use warmhub_wref_resolve.
warmhub_thing_graph	Get one thing and its embedded assertion/about/wref graph to a bounded depth.
warmhub_thing_get_many	Batch-fetch things by wref in one call — prefer over looping warmhub_thing_get. Missing wrefs are returned in a missing array.
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. For identity-scoped inputs, use resolveCollections:true to include assertions about Arc/Bond/Set/List collections containing the target; pinned @vN inputs stay version-exact. 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_wref_resolve	Resolve a wref (local or canonical) to its canonical thing identity. Accepts cross-repo canonical wrefs; pair with warmhub_thing_get to fetch the resolved data.

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 count of matching items instead of the full result list
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 an exact count 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
wref	string	yes	WarmHub reference
version	integer	no	Specific version number
includeRetracted	boolean	no	Return the thing even if it is retracted
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.

orgName/repoName may be omitted when wref is a durable id — a durable id routes itself 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_get_many

Param	Type	Required	Description
wrefs	string[]	yes	Array of wrefs, 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 (mirrors warmhub_thing_get)
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. Pass dataMode:"full" to force large collection bodies.

Missing wrefs are returned in a missing array. When a top-level version is supplied and the input wref is not already pinned, missing entries are version-qualified (Shape@vN or Shape/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.

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 on identity-scoped inputs: bare wrefs, @HEAD, or @ALL. 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.

Param	Type	Required	Description
wref	string	yes	Target thing wref
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	Include assertions about Arc/Bond/Set/List collections containing the target entity for identity-scoped inputs; ignored for pinned @vN inputs
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
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 count of matching items instead of the full result list
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 an exact count result — intermediate pages do not carry repoSeq. Requires full-repository read authority. Not available when using glob filters (match), collection expansion (resolveCollections), 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)
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.

warmhub_wref_resolve

Param	Type	Required	Description
wref	string	yes	WarmHub reference to resolve

Cross-repo visibility

Cross-repo wref lookups (canonical forms wh:org/repo/Shape and wh:org/repo/Shape/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_many (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_commit_submit	Submit a list of operations against a repo. Returns one exact immutable operation-event receipt.
warmhub_commit_receipt_get	Recover one immutable operation-event receipt by caller-known request UUID.

Use warmhub_thing_history for per-thing version trails.

warmhub_commit_submit

The tool’s input schema contains the full structural contract for all operation variants. Supply a caller-known submissionId; this single MCP chunk uses ordinal zero and returns one exact OperationEventReceiptV1. Opinion-bearing assertions must be binary propositions.

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 names eventRequestId and warmhub_commit_receipt_get; 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. Reuse only for an identical retry.
operations	array	yes	Non-empty atomic operation batch. 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.

committer identity restriction

warmhub/users Identity wrefs (e.g. wh:warmhub/users/Identity/<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. Other existing things, such as Agent or Agent/..., are valid committer targets without this restriction.

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.

Operation variants:

• ADD shape: { operation: "add", kind: "shape", name, data, skipExisting? }
• ADD thing: { operation: "add", kind: "thing", name, data, skipExisting? }
• ADD assertion: { operation: "add", kind: "assertion", name, about, data, skipExisting? }
• ADD collection: { operation: "add", kind: "collection", type, name, members, skipExisting? }
• REVISE shape/thing/assertion: { operation: "revise", kind, name, data, expectedVersion?, leaseId? }
• REVISE collection: { operation: "revise", kind: "collection", type, name, members, expectedVersion?, leaseId? }
• RETRACT: { operation: "retract", name, reason?, kind?, expectedVersion?, leaseId? } — withdraws the entity from default reads
• RENAME: { operation: "rename", name, newName, kind? } — changes identity metadata without creating a new body version

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

Per-operation result warnings:

Successful and noop result entries can include:

{
  "warnings": {
    "undeclaredFields": ["status", "filePath"],
    "undeclaredFieldsTruncated": true,
    "totalUndeclared": 600,
    "coalescedWrefs": [
      { "fieldPath": "owner", "wref": "User/nobody", "reason": "thing_absent" }
    ]
  }
}

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. The struct is additive — an operation can carry either warning kind or both. Both 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.

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).

warmhub_collection_create

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
from	string	no	Source wref to copy members from
add	string[]	no	Wrefs to add to the initial member set
remove	string[]	no	Wrefs to remove from the initial member set
replaceMembers	string[]	no	Replace the full member list with these wrefs
shape	string	no	Selector: filter by shape
about	string	no	Selector: filter by about target
match	string	no	Selector: glob pattern to filter wrefs
componentRef	string	no	Selector: filter to items owned by the given component
where	object[]	no	Selector: typed field-value predicates
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

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
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
about	string	no	Selector: filter by about target
match	string	no	Selector: glob pattern to filter wrefs
componentRef	string	no	Selector: filter to items owned by the given component
where	object[]	no	Selector: typed field-value predicates
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. Set/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. Those guides cover repo-scoped subscriptions; for org-scoped subscriptions, see the Org-Scoped Subscription Tools section below.

Tool	Description
warmhub_subscription_list	List subscriptions in a repository.
warmhub_subscription_get	Get subscription metadata by name.
warmhub_subscription_create	Create a webhook subscription in a repository.
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_org_subscription_create	Create an org-scoped metadata webhook subscription.
warmhub_org_subscription_list / get / update / pause / resume / delete	Manage org-scoped subscriptions.

warmhub_subscription_get

Param	Type	Required	Description
name	string	yes	Subscription name

warmhub_subscription_create

Param	Type	Required	Description
name	string	yes	Subscription name
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. One of commit, repo.renamed, thing.renamed, or shape.renamed. Defaults to commit when omitted.
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
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": "signals",
  "name": "new-signals",
  "kind": "webhook",
  "shapeName": "Signal",
  "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.

warmhub_org_subscription_create

This tool creates organization-owned automation. The caller must be an organization owner or admin. It accepts no repoName, shape, filter, or source repository.

Param	Type	Required	Description
orgName	string	yes	Organization name
name	string	yes	Subscription name
eventType	string	no	org.renamed, org.member_added, org.repo_created, or org.repo_published; defaults to org.renamed
kind	string	yes	"webhook"
webhookUrl	string	yes	Webhook endpoint URL
fallbackWebhookUrl	string	no	Optional fallback endpoint
allowTraceReentry	boolean	no	Allow another delivery in the same action trace
notifyOnSuccess	boolean	no	Deprecated compatibility field; accepted but ignored. Action notifications are terminal-failure-only

warmhub_subscription_update

Param	Type	Required	Description
name	string	yes	Existing subscription name
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
name	string	yes	Subscription name

Org-Scoped Subscription Tools

Org-scoped subscription tools manage subscriptions at the organization level. The current org-scoped subscription type is fixed to the org.renamed event — these subscriptions fire when the organization is renamed. There is no event selector or filter to configure; the event type is hardcoded. These tools follow the same pause/resume/delete lifecycle as repo-scoped subscription tools.

Tool	Description
warmhub_org_subscription_create	Create a webhook subscription at the organization level. Fires on org.renamed events.
warmhub_org_subscription_list	List org-scoped subscriptions.
warmhub_org_subscription_get	Get org-scoped subscription metadata by name.
warmhub_org_subscription_pause	Pause an active org-scoped subscription.
warmhub_org_subscription_resume	Resume a paused org-scoped subscription.
warmhub_org_subscription_delete	Delete an org-scoped subscription.
warmhub_org_subscription_update	Update an existing org-scoped subscription’s webhook delivery config.

warmhub_org_subscription_create

Creates a webhook subscription that fires when the organization is renamed (org.renamed). The event type is fixed and cannot be changed. Only the delivery configuration fields listed below are accepted; sending any other key returns an Invalid arguments error.

Param	Type	Required	Description
orgName	string	yes	Organization name
name	string	yes	Subscription name
kind	string	yes	"webhook"
webhookUrl	string	yes	Webhook endpoint URL
fallbackWebhookUrl	string	no	Optional fallback endpoint called after a terminal delivery failure
allowTraceReentry	boolean	no	Reentry policy. Defaults to false
notifyOnSuccess	boolean	no	Deprecated compatibility field; accepted but ignored. Action notifications are terminal-failure-only
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.

warmhub_org_subscription_list

Param	Type	Required	Description
orgName	string	yes	Organization name

warmhub_org_subscription_get

Param	Type	Required	Description
orgName	string	yes	Organization name
name	string	yes	Subscription name

warmhub_org_subscription_update

Patches the webhook delivery configuration of an existing org-scoped subscription. Only delivery fields can be updated — org-scoped subscriptions have a fixed org.renamed event type with no shape or filter to edit. Sending filterJson or any other unsupported key returns an Invalid arguments error.

Param	Type	Required	Description
orgName	string	yes	Organization name
name	string	yes	Existing subscription name
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
notifyOnSuccess	boolean	no	Deprecated compatibility field; accepted but ignored. Action notifications are terminal-failure-only

warmhub_org_subscription_pause / warmhub_org_subscription_resume / warmhub_org_subscription_delete

Param	Type	Required	Description
orgName	string	yes	Organization name
name	string	yes	Subscription name

Action Tools

Tool	Description
warmhub_action_livefeed	Get delivery feed for a subscription. Narrowed readers receive operational metadata and visible matched operations; full-repository readers also receive free-form diagnostics.
warmhub_action_runs	List action runs in a repository.
warmhub_action_attempts	Get attempt history for a specific action run. Free-form diagnostics require full-repository read.
warmhub_action_notifications	List terminal action-failure notifications for a repo. Only runs that have reached a non-recoverable failure state appear in this feed.
warmhub_notifications	Alias for warmhub_action_notifications. Lists terminal action-failure notifications for a repo.

warmhub_action_livefeed

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_action_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_action_attempts

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

warmhub_action_notifications

Param	Type	Required	Description
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 — succeeded and suppressed runs do not appear. See Actions for the full HTTP contract, including the GET /api/repos/:orgName/:repoName/actions/notifications endpoint.

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)

Aliases warmhub_action_notifications over the same backend. 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. Returns the install state plus any setup-deferred resources. 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-known idempotency key for this install or uninstall request. Reuse only for an identical retry.

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.