Request

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

With annotations declaring readOnlyHint=false, idempotentHint=false and destructiveHint=false, the description adds substantial non-duplicative context: honest degradation (a dirty tree or unfingerprintable toolchain always BUILDS, never serves a possibly-stale artifact, never silently skips the cache), the always-colocated=True invariant and why (fcntl leases don't arbitrate across nodes), and that arbitration is advisory (D-CP-8). It does not say what a gc-mode call destroys, which is the one behavioral gap given the max_age_days/keep_recent parameters in the schema.

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

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

The purpose line is front-loaded and the bold headers give it shape, but the body is heavy with material that does not help an agent act: a measured '21.7 GB across 4 duplicate directories' anecdote, the CONCEPT:RM-TASK-LEDGER tag, and the spec-style 'D-CP-8' citation. Em-dash-laden prose inflates the size well past the information it carries, so few sentences earn their place.

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

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

An output schema exists, so return values need not be explained, and the primary 'request' path plus its degradation and co-location invariants are covered. What is missing is the tool's own mode surface: the schema exposes gc/status/artifacts/explain parameters that the description never acknowledges, leaving the agent unable to tell whether to call this tool or rm_build_gc/rm_build_status/rm_build_artifacts/rm_build_explain.

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

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

Schema description coverage is 100%, so the schema already documents all seven parameters, making 3 the baseline. The description adds a conceptual gloss on the cache key — the (repo, tree-sha, feature-set, toolchain-fingerprint, target-triple) tuple — which is genuinely beyond the schema's terse 'A cache key, for status/artifacts/explain', but it does not attach that explanation to the `key` parameter explicitly and says nothing about wait_timeout, keep_recent or max_age_days.

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

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

The description characterizes the tool as a 'content-addressed build broker' and explains the dedup payoff (publishing named artifacts to a shared checksummed cache instead of N lanes each paying for a full cargo/pnpm build), so the general intent is graspable. However, it never states the primary action as a verb, and the schema's own parameters ('for gc', 'for status/artifacts/explain') reveal this tool also serves GC and status/explain modes that the description never mentions or reconciles with the sibling tools rm_build_gc, rm_build_status, rm_build_artifacts and rm_build_explain. Purpose is therefore clear-ish but muddled about what the tool actually does and where it stops.

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

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

There is real guidance for one alternative: 'Route build requests through this tool rather than a bare local invocation when you are not certain you are on the pinned node,' plus the note that a direct `cargo build` bypasses the broker. But the far more decision-relevant routing — this tool vs the four rm_build_* siblings that appear to cover the gc/status/artifacts/explain parameters exposed here — is entirely absent, and no conditions are given for choosing the `host` remote-dispatch path beyond what the schema already says.

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