MCP Tools Reference

WarmHub exposes a full MCP tool catalog for organizations, repositories, shapes, things, assertions, commits, subscriptions, actions, and meta (capability discovery). In repo-scoped mode, orgName/repoName are omitted from all tool schemas. In global mode, they’re required on repo-level tools.

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 two 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, and write examples generated from the repo’s own shapes. Documented under Repository Tools.

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, commit, subscription, action, meta), each with name, description, and the tools (name, description, readOnly) advertised on the current endpoint.
cookbook	object[]	Common workflows as { task, steps: [{ tool, note }] } — e.g. discovering shapes, searching by content, writing first data.
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.

The payload reflects the endpoint scope. On the repo-scoped endpoint (/mcp/:org/:repo), categories omits global-only tools: warmhub_org_list, warmhub_org_get, warmhub_repo_list, and warmhub_repo_create.

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

Organization Tools

warmhub_org_list and warmhub_org_get are global-only. The per-org administration tools (warmhub_org_set_description, warmhub_org_archive, warmhub_org_unarchive) are available in both global and repo-scoped mode; repo-scoped callers operate on the org baked into the URL.

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_description	Set or clear an organization description.
warmhub_org_archive	Archive an organization.
warmhub_org_unarchive	Unarchive an organization.

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_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, and summary stats for agent bootstrapping.
warmhub_repo_set_description	Set or clear a repository description.
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
description	string	no	Repository description
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_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, inline collection syntax, rules, about semantics)
• Write examples generated from actual repo shapes

Call this first when connecting to a repo.

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  }
]

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 things: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

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). Use to enumerate a repo’s current state; for fuzzy lookups use warmhub_thing_search.
warmhub_thing_get	Fetch one thing/assertion/collection 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 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 Pair/Triple/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). 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 (wh:org/repo/Shape/name); 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
match	string	no	Glob pattern to filter wrefs (* = one segment, ** = zero or more)
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

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

In global mode, 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.

In global mode, 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)

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/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 Pair/Triple/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.

In global mode, 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 Pair, Triple, 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
resolveCollections	boolean	no	Include assertions about Pair/Triple/Set/List collections containing the target thing for identity-scoped inputs; ignored for pinned @vN inputs
includeRetracted	boolean	no	Resolve a retracted target and include retracted assertions
depth	integer	no	Recursive assertion depth
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
match	string	no	Glob pattern to filter wrefs
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
componentId	string	no	Filter results to items owned by the given component
excludeComponents	boolean	no	Exclude component-owned items from results. Cannot be combined with componentId.
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

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
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
componentId	string	no	Filter results to items owned by the given component
excludeComponents	boolean	no	Exclude component-owned items from results. Cannot be combined with componentId.
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 form 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 per-operation results; see the heading section below for the failure taxonomy and write examples.

Use warmhub_thing_history for per-thing version trails.

warmhub_commit_submit

The tool returns per-operation results. Per-op failures show up as operations[] entries with status: "error" and partial: true. For the full operation contract and shape-specific write examples, call warmhub_repo_describe and inspect the commitContract field. Opinion-bearing assertions must be binary propositions.

See MCP Error Handling for the full failure taxonomy. Ambiguous append failures (a separate class from per-op failures) return a tool-result error with continuation recovery state; the failed append may have landed server-side, so inspect repository state before deciding whether to resume.

Param	Type	Required	Description
committer	string	no	Optional wref identifying the actor on whose behalf the writes are made (e.g. Agent/bot-1). Omit to attribute to the authenticated user via createdByEmail.
componentId	string	no	Attribute writes to an installed component. See component identity rules below.
message	string	no	Optional message recorded with each thing-version produced by this call
operations	array	yes	Operations array (non-empty). When resuming after an ambiguous append failure, pass only the operations that haven’t been acknowledged (the prior attempt’s slice from operationOffset onward).
streamId	string	no	When resuming after an ambiguous append failure, copy the streamId from the prior error’s continuation payload.
allocatedTokens	array	no	When resuming, copy allocatedTokens from the prior error’s continuation payload. Must accompany the matching streamId.
operationOffset	integer	no	When resuming, copy operationOffset from the prior error’s continuation payload.

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, members, name?, skipExisting? }
• REVISE shape/thing/assertion: { operation: "revise", kind, name, data, expectedVersion? }
• RETRACT: { operation: "retract", name, reason? } — withdraws the entity from default reads; kind is an optional hint

Token rules: $N allocates in the last segment of add-operation names. #N references prior allocations in the same stream. Write path rejects @ALL.

Per-operation result warnings:

Successful and noop result entries can include:

{
  "warnings": {
    "undeclaredFields": ["status", "filePath"],
    "undeclaredFieldsTruncated": true,
    "totalUndeclared": 600
  }
}

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. This warning is informational; it does not turn the operation into a failure. For add operations, skipExisting: true returns noop when the target already exists instead of failing. For revise operations, expectedVersion applies the change 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_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.

Subscription Tools

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

Tool	Description
warmhub_subscription_list	List subscriptions in a repository.
warmhub_subscription_get	Get subscription metadata by name.
warmhub_subscription_create	Create a webhook or cron subscription.
warmhub_subscription_update	Update an existing subscription’s trigger or webhook config.
warmhub_subscription_pause	Pause an active subscription.
warmhub_subscription_resume	Resume a paused subscription.
warmhub_subscription_delete	Delete a subscription.

warmhub_subscription_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"
shapeName	string	no	Shape to subscribe to. For webhook subscriptions, provide either shapeName or filterJson.shape — except for shape lifecycle subscriptions, which omit both and rely on a {"kind":"shape", ...} filter.
filterJson	object	no	Filter object for matching write operations (required for webhook, not needed for cron)
webhookUrl	string	no	Webhook endpoint URL (required for both kinds)
fallbackWebhookUrl	string	no	Optional fallback endpoint called after a terminal delivery failure
cronConfig	object	no	Cron configuration with cronspec and optional timezone (required when kind is "cron")

warmhub_subscription_update

Param	Type	Required	Description
name	string	yes	Existing subscription name
shapeName	string	no	Replacement shape for webhook subscriptions
filterJson	object	no	Replacement filter object
webhookUrl	string	no	Replacement webhook URL
fallbackWebhookUrl	string or null	no	Replacement fallback webhook URL. Use null to clear it
cronConfig	object	no	Cron config patch; provided keys merge into the existing config
allowTraceReentry	boolean	no	Replacement reentry policy for write-triggered subscriptions

warmhub_subscription_pause / warmhub_subscription_resume / warmhub_subscription_delete

Param	Type	Required	Description
name	string	yes	Subscription name

Action Tools

Tool	Description
warmhub_action_livefeed	Get delivery feed for a subscription. Includes run status, attempt count, and error details.
warmhub_action_runs	List action runs in a repository.
warmhub_action_attempts	Get attempt history for a specific action run.
warmhub_action_notifications	List repo-scoped action notification records, including terminal failures and optional success notifications.

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

Param	Type	Required	Description
status	string	no	Filter by status: pending, running, processing, retry_wait, succeeded, failed_terminal, dead_letter
since	string	no	ISO datetime or unix timestamp
limit	integer	no	Max results. Must be between 1 and 200.

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

Returns repo-scoped action notification records for action deliveries, including terminal failures and optional success notifications. This is distinct from the web app’s cross-repo user notification feed.