Repository Manager

Explain

rm_build_explain

Inspect a content-addressed build key to see cached artifacts, checksums, and why a build deduplicated or rebuilt instead of serving stale output.

Instructions

Explain (rm_build). Content-addressed build broker for ANY repository (CONCEPT:RM-TASK-LEDGER).

Keyed by (repo, tree-sha, feature-set, toolchain-fingerprint, target-triple). The DEDUP is the value: N lanes asking for the same build today each pay for a full cargo/pnpm build into their own target-isolated/node_modules — measured at 21.7 GB across 4 duplicate directories after pruning. This tool publishes named artifacts to a shared, checksummed cache instead.

Honest degradation: a dirty tree or an unfingerprintable toolchain BUILDS — it never serves a possibly-stale artifact and never silently skips the cache as though it were consulted.

Co-location: this tool always passes colocated=True to the underlying reservation, because being inside this pinned MCP server process IS the proof of same-node execution that a bare CLI invocation cannot provide — fcntl leases do not arbitrate across nodes, and the lease files live under an NFS-exported path. Route build requests through this tool rather than a bare local invocation when you are not certain you are on the pinned node.

Arbitration is advisory (D-CP-8): an agent running cargo build directly bypasses this broker entirely.

Input Schema

Name	Required	Description
`key`	No	A cache key, for status/artifacts/explain.
`host`	No	For 'request': dispatch to this REGISTERED, authorized remote host (its rm_remote_workers 'register_worker' host_id) instead of building locally. Requires a clean local tree (its HEAD sha + origin are what gets staged and built remotely) and does not yet retrieve artifacts back — see the returned result's 'note'. Omit to build locally (the default, always colocated=True).
`spec`	No	Which declared build spec to use (.buildcache.yaml). Defaults to the repo's first.
`repo_path`	No	Any working tree of the target repository. Defaults to the server's cwd.
`keep_recent`	No	For gc: always keep this many most-recent cache entries.
`max_age_days`	No	For gc: reclaim cache entries older than this (subject to keep_recent).
`wait_timeout`	No	Seconds 'request' waits on an in-flight build of the same key before building anyway.

Output Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

First observedv3.5.1Oct 19, 2026

TDQS

C2.6/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations set readOnlyHint=false and idempotentHint=false, and the description adds genuinely useful context beyond them: the honest-degradation rule (dirty tree builds rather than serving stale artifacts), the mandatory colocated=True reservation, the fcntl-lease/NFS cross-node limitation, and the advisory-only arbitration. That is real behavioral disclosure, though it is framed for the broker generally and never states whether the explain call itself writes or reserves.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness2/5

Is the description appropriately sized, front-loaded, and free of redundancy?

It is an essay with bold pseudo-headings, ALL-CAPS emphasis and ledger references, most of which serve the broker concept rather than this tool. The one sentence that matters (what explain returns) is absent while multiple paragraphs explain siblings' behavior, so it is both over-long and mis-front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return-shape detail is unnecessary, but for a 7-parameter tool in a dense family the description still fails to say what explain does with a key, how it resolves repo_path/spec, or how to read the result. The context it supplies is about the family, leaving the specific operation under-defined.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and the per-parameter descriptions (host, spec, repo_path, keep_recent, max_age_days, wait_timeout) are detailed, so the schema carries the semantics. The description adds nothing parameter-specific beyond the general colocated=True claim, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose2/5

Does the description clearly state what the tool does and how it differs from similar tools?

The opening line is only 'Explain (rm_build)' and the body describes the build broker family as a whole (dedup value, cache keying, co-location leases) rather than what the explain operation actually returns or computes. An agent cannot tell from this text what an 'explain' of a cache key produces, nor how it differs from rm_build_status or rm_build_artifacts, which the schema's own 'key' description bundles together ('for status/artifacts/explain').

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is advice about routing build requests through the pinned node and the note that arbitration is purely advisory, but that guidance targets the request/build path, not when to call explain versus its siblings. No statement of when explain is the right tool, what input it needs, or when to prefer status/artifacts instead.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server