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_commit_validate	client.commit.validate(...)
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, 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 four 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

Every tool carries a reviewed auth tier. Anonymous-tier tools serve public data without credentials and include an auth awareness note in their runtime description, instructing agents to suggest authentication when expected data is missing. Builder-tier tools require an authenticated user and do not receive that note — including read-only ones such as 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.

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, 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, 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_member_list	List members of an organization. (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_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

Param	Type	Required	Description
orgName	string	yes	Organization name

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.

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.

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_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_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 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	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. 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_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. 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. Shape/name 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 shaped-thing wref (Shape/name) or a bare shape wref (Shape).
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 (Shape/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 Device/sensor-42@v7. At least one affirmedTargets entry on the assertion must match the supplied pinned wref exactly. See warmhub_commit_submit for how affirmedTargets are set and updated. May be combined with match, count, scoped tokens, and search.
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)
affirmedAbout	string	no	Pinned target wref (Shape/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.

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 a write receipt: whether the write landed, plus one outcome entry per submitted operation.
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 any caller-known eventRequestId in the repo. Most often used to resolve an ambiguous write, but not limited to that.

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; the call returns a write receipt, and the receipt’s own fields are the top level of the response — there is no wrapper object to unpack. The response root also carries a few compatibility fields, including a nested copy of the same receipt; read the receipt fields directly. 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.

Response shape:

A submission returns an operation-event-receipt/v2 receipt. These are its fields, at the top level of the response:

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".
eventRequestId	UUID	Receipt identity for this submission. Pass it to warmhub_commit_receipt_get to resolve an ambiguous write.
operations	array	One outcome entry per submitted operation — see below.
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.
requestDigest	string	sha256:-prefixed digest of the submitted request.
schemaVersion	string	"operation-event-receipt/v2".
submissionId	UUID	The submissionId you supplied, echoed back.

Every entry in 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.

The response root also carries these fields. Prefer the receipt fields above:

Compatibility Field	Type	Description
results	array	The same per-operation entries as operations[].
receipt	object	A nested copy of the receipt above.
allocatedTokenRanges	array	Always [].
createdByEmail	string	Email of the authenticated writer, when available.

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/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, affirmedTargets?, skipExisting? }
• ADD collection: { operation: "add", kind: "collection", type, name, members, skipExisting? }
• REVISE shape/thing/assertion: { operation: "revise", kind, name, data, expectedVersion?, leaseId? } — for assertions, also accepts affirmedTargets?
• 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
• REAFFIRM assertion: { operation: "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. kind is optional.

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 (Shape/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": "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.

warmhub_commit_validate

Evaluates the complete ordered operation batch with the same server evaluator as warmhub_commit_submit, 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 submit.
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 submit fail.

warmhub_commit_receipt_get

Looks up one immutable write receipt by a caller-known eventRequestId. 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 warmhub_commit_submit — 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.

When warmhub_commit_submit returns an ambiguous append failure, the error includes an eventRequestId. Pass that error-provided value here. Do not pass your original submissionId — the two values differ.

Param	Type	Required	Description
orgName	string	yes (global)	Organization name
repoName	string	yes (global)	Repository name
eventRequestId	UUID	yes	The id of the write whose receipt you want. After an ambiguous warmhub_commit_submit this is the eventRequestId the error carries — not the submissionId you supplied, which is a different value. For the other write tools it is the eventRequestId you passed in.

The tool rejects any argument outside this set, so do not pass submissionId alongside them.

Returns the same immutable write receipt documented under warmhub_commit_submit 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.

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. 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 non-retired subscriptions in a repository. 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 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.