MCP Tools Reference

WarmHub exposes a full MCP tool catalog for organizations, repositories, shapes, things, assertions, commits, workspaces, subscriptions, and actions. 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.

Organization Tools

These tools are only available in global mode.

Tool	Description
warmhub_org_list	List organizations (archived hidden by default).
warmhub_org_get	Get an organization by name.
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 with per-repo totalItems count (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, 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

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-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)
• lastCommit — the most recent commit (author, message, operation count, timestamp), or null for empty repos
• Counts by kind and by shape
• Sample wrefs from the repo
• Wref syntax reference
• Commit contract (add/revise variants, inline collection syntax, rules, about semantics)
• Write examples generated from actual repo shapes

Call this first when connecting to a repo.

Thing / Query Tools

Tool	Description
warmhub_thing_head	Get active HEAD snapshot for broad repo orientation.
warmhub_thing_get	Get a thing by wref and optional version.
warmhub_thing_get_many	Fetch many things by wref in one call.
warmhub_thing_history	Get thing history by wref or by shape/about filters.
warmhub_thing_about	Get assertions about a thing.
warmhub_thing_query	General targeted query by shape/about/kind filters.
warmhub_thing_search	Search for things by text, vector, or hybrid search.
warmhub_thing_refs	Get backlinks (inbound) or cross-references (outbound) for a thing.
warmhub_wref_resolve	Resolve a wref to its canonical thing identity.

Workspace support

The tools marked with ws in the parameter tables below accept an optional workspaceName parameter. When set, queries and writes include the workspace overlay — the agent sees baseline + workspace edits. For warmhub_thing_head and warmhub_thing_query, this applies to normal result mode; count: true currently rejects workspaceName with VALIDATION_ERROR because workspace-scoped counts are not yet supported. See Workspaces for details.

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)
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
workspaceName	string	no	ws — Scope query to a workspace overlay

warmhub_thing_get

Param	Type	Required	Description
wref	string	yes	WarmHub reference
version	integer	no	Specific version number
workspaceName	string	no	ws — Scope query to a workspace overlay

warmhub_thing_get_many

Param	Type	Required	Description
wrefs	string[]	yes	Array of wrefs (non-empty)
version	integer	no	Pin all lookups to this version

Missing wrefs are returned in a missing array.

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
resolveCollections	boolean	no	When about is set, also include assertions about collections containing the target
includeInactive	boolean	no	Allow resolving deactivated shape or about targets (does not filter results)
limit	integer	no	Max versions to return
cursor	string	no	Pagination cursor from previous response
workspaceName	string	no	ws — Scope query to a workspace overlay

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

warmhub_thing_about

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 collections containing the target thing
includeInactive	boolean	no	Include deactivated assertions
depth	integer	no	Recursive assertion depth
limit	integer	no	Max assertions to return
cursor	string	no	Pagination cursor from previous response
workspaceName	string	no	ws — Scope query to a workspace overlay

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
includeInactive	boolean	no	Include deactivated entities
limit	integer	no	Max results
cursor	string	no	Pagination cursor from previous response
workspaceName	string	no	ws — Scope query to a workspace overlay

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)
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"
includeInactive	boolean	no	Include deactivated entities
limit	integer	no	Max results
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.
workspaceName	string	no	ws — Scope query to a workspace overlay

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
cursor	string	no	Pagination cursor from previous response
workspaceName	string	no	ws — Scope query to a workspace overlay

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

warmhub_wref_resolve

Param	Type	Required	Description
wref	string	yes	WarmHub reference to resolve

Write Tools

Tool	Description
warmhub_commit_apply	Execute a write commit with operations.
warmhub_commit_log	Get commit log for a repository.

warmhub_commit_apply

Param	Type	Required	Description
author	string	yes	Commit author tag
message	string	no	Commit message
operations	array	yes	Operations array (non-empty)
workspaceName	string	no	ws — Target workspace. When set, the commit is written to the workspace instead of baseline.

Operation variants:

• ADD shape: { operation: "add", kind: "shape", name, data }
• ADD thing: { operation: "add", kind: "thing", name, data }
• ADD assertion: { operation: "add", kind: "assertion", name, about, data }
• ADD collection: { operation: "add", kind: "collection", type, members, name? }
• REVISE shape/thing/assertion: { operation: "revise", kind, name, data, active? }
• REVISE collection: { operation: "revise", kind: "collection", name, active? }

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

warmhub_commit_log

Param	Type	Required	Description
limit	integer	no	Max commits to return
cursor	string	no	Pagination cursor from previous response
author	string	no	Filter by author
since	string/number	no	ISO datetime or unix timestamp
until	string/number	no	ISO datetime or unix timestamp

Shape Tools

Tool	Description
warmhub_shape_list	List shapes in a repository.
warmhub_shape_get	Get a shape by name.

warmhub_shape_get

Param	Type	Required	Description
shapeName	string	yes	Shape name

Workspace Tools

These tools manage the workspace lifecycle — create isolated workspaces, make changes, then publish as changesets for review and acceptance.

Tool	Description
warmhub_workspace_create	Create a new workspace in a repository.
warmhub_workspace_list	List workspaces in a repository.
warmhub_workspace_get	Get workspace details by name.
warmhub_workspace_delete	Delete (abandon) a workspace.
warmhub_workspace_status	Get workspace status including diff summary and conflict detection.
warmhub_workspace_validate	Validate a workspace — check for conflicts with the baseline.
warmhub_workspace_rebase	Rebase a workspace onto the latest baseline.
warmhub_workspace_revert	Revert workspace changes to a baseline thing.
warmhub_workspace_discard	Discard a workspace-added thing.
warmhub_workspace_publish	Publish a workspace as a changeset for review.
warmhub_workspace_accept	Accept a workspace changeset, merging into baseline.
warmhub_workspace_reject	Reject a workspace changeset.
warmhub_workspace_withdraw	Withdraw a workspace changeset, reopening the workspace.
warmhub_workspace_review	Get operation-by-operation review of a workspace changeset.

warmhub_workspace_create

Param	Type	Required	Description
name	string	yes	Workspace name (lowercase alphanumeric with hyphens, max 64 chars)
description	string	no	Workspace description

warmhub_workspace_list

Param	Type	Required	Description
status	string	no	Filter: "open", "published", "abandoned", or "permanent"
includeDefault	boolean	no	Include the default workspace in results

warmhub_workspace_get

Param	Type	Required	Description
workspaceName	string	yes	Workspace name

warmhub_workspace_delete

Param	Type	Required	Description
workspaceName	string	yes	Workspace name

warmhub_workspace_status

Param	Type	Required	Description
workspaceName	string	yes	Workspace name

Returns workspace metadata, change summary (added/revised/deactivated things), conflict status, and changeset number if published.

warmhub_workspace_validate

Param	Type	Required	Description
workspaceName	string	yes	Workspace name

For open workspaces, validates against the baseline. For published workspaces, validates the changeset against current HEAD.

warmhub_workspace_rebase

Param	Type	Required	Description
workspaceName	string	yes	Workspace name

Advances the workspace’s baseline to current repo HEAD and re-runs conflict detection.

warmhub_workspace_revert

Param	Type	Required	Description
workspaceName	string	yes	Workspace name
wref	string	yes	The wref to revert (restores baseline state)

warmhub_workspace_discard

Param	Type	Required	Description
workspaceName	string	yes	Workspace name
wref	string	yes	The wref to discard (removes workspace-added thing)

warmhub_workspace_publish

Param	Type	Required	Description
workspaceName	string	yes	Workspace name
message	string	yes	Changeset message describing the proposed changes
rationale	string	no	Rationale for the changeset

Publishing validates the workspace, computes the diff, creates a numbered changeset, and locks the workspace.

warmhub_workspace_accept

Param	Type	Required	Description
workspaceName	string	yes	Workspace name

Resolves the workspace to its open changeset, re-validates, then replays operations into baseline.

warmhub_workspace_reject

Param	Type	Required	Description
workspaceName	string	yes	Workspace name
reason	string	no	Reason for rejecting

Rejects the changeset and reopens the workspace for further iteration.

warmhub_workspace_withdraw

Param	Type	Required	Description
workspaceName	string	yes	Workspace name

Author-only. Withdraws the changeset and reopens the workspace.

warmhub_workspace_review

Param	Type	Required	Description
workspaceName	string	yes	Workspace name

Returns the changeset details with operation-by-operation breakdown: verb (ADD/REVISE/DELETE), name, shape, kind, data, and deactivation status.

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. Includes actionContainer, actionContainerConfig, and tokenScopes for subscriptions executed by sprite when present.
warmhub_subscription_create	Create a subscription that triggers actions on matching commits.
warmhub_subscription_update	Update an existing subscription’s trigger or executor 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

For subscriptions executed by sprite, the response includes:

Response Field	Type	Description
actionContainer	string?	Derived action container name
actionContainerConfig	object?	Action container configuration (command, githubRepo, ref, inputMode)
tokenScopes	object[]?	Configured token scopes for sprite-minted WarmHub tokens, when present

warmhub_subscription_create

Param	Type	Required	Description
name	string	yes	Subscription name
kind	string	yes	"webhook", "sprite", or "cron"
shapeName	string	no	Shape to subscribe to (required for webhook/sprite, not needed for cron)
filterJson	object	no	Filter object for matching commit operations (required for webhook/sprite, not needed for cron)
webhookUrl	string	no	Webhook endpoint URL (required when kind is "webhook")
spriteConfig	object	no	Sprite executor configuration (required when kind is "sprite"). Supports tokenTtlMinutes (number, 5-60) to configure WarmHub token TTL; defaults to 10 minutes.
cronConfig	object	no	Cron configuration with cronspec and optional timezone (required when kind is "cron")
executorKind	string	no	Executor type for cron subscriptions: "webhook" or "sprite"
tokenScopes	object[]	no	Optional token scopes for WarmHub tokens minted by sprite executors. Must be a non-empty array when provided. Each entry includes permissions: string[] and optional allowedMatches: string[], and a permission may appear in only one entry across the full array. Ignored for webhook subscriptions; honored for cron subscriptions when executorKind is "sprite".

warmhub_subscription_update

Param	Type	Required	Description
name	string	yes	Existing subscription name
shapeName	string	no	Replacement shape for webhook/sprite subscriptions
filterJson	object	no	Replacement filter object
webhookUrl	string	no	Replacement webhook URL
spriteConfig	object	no	Sprite config patch; provided keys merge into the existing config
cronConfig	object	no	Cron config patch; provided keys merge into the existing config
executorKind	string	no	Replacement cron executor kind ("webhook" or "sprite")
allowTraceReentry	boolean	no	Replacement reentry policy for commit-triggered subscriptions
workspacePolicy	string	no	Replacement workspace commit policy ("ignore" or "include")

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, error details, and action container name.
warmhub_action_runs	List action runs in a repository.
warmhub_action_attempts	Get attempt history for a specific action run.
warmhub_action_notifications	List action failure notifications (terminal delivery-failure records).

warmhub_action_livefeed

Param	Type	Required	Description
subscriptionName	string	yes	Subscription name
cursor	string	no	Pagination cursor from previous response
limit	integer	no	Max items

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 (5)
lastErrorCode	string?	Error classification code (e.g. SPRITE_EXIT_NONZERO)
lastErrorMessage	string?	Human-readable error description
actionContainer	string?	Derived action container name (for sprite subscriptions)

warmhub_action_runs

Param	Type	Required	Description
status	string	no	Filter by status: pending, running, retry_wait, succeeded, failed_terminal, dead_letter
since	string	no	ISO datetime or unix timestamp
limit	integer	no	Max results

warmhub_action_attempts

Param	Type	Required	Description
subscriptionName	string	yes	Subscription name
commitId	string	yes	Commit identifier (16-char hex string)

warmhub_action_notifications

Param	Type	Required	Description
since	string	no	ISO datetime or unix timestamp
limit	integer	no	Max results

Returns repo-scoped terminal failure notification records for action deliveries. This is distinct from the web app’s cross-repo user notification feed.