Status

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

Annotations declare readOnlyHint=true and idempotentHint=true, but the description attributes mutating behavior directly to this tool: "This tool publishes named artifacts to a shared, checksummed cache instead," "a dirty tree or an unfingerprintable toolchain BUILDS," and "this tool always passes colocated=True to the underlying reservation" (a lease acquisition). A status/query endpoint described as building, publishing, and taking leases is inconsistent with its read-only annotation.

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?

Four dense bolded sections covering dedup economics, degradation policy, co-location rationale, and advisory arbitration consume far more space than a single status tool warrants, and most of that content is not about this tool's operation. The actionable sentence (the key tuple) is not front-loaded; the reader must wade through broker philosophy to find anything usable.

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 described, but for a broker this complex the description still leaves the essential question unanswered: what does a status call report, and how does the agent act on it? With 7 parameters and no mode selector documented, the agent cannot tell which parameters are live for this endpoint versus request/gc.

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%, with per-parameter text already covering key, host, spec, repo_path, keep_recent, max_age_days, and wait_timeout, so the baseline is 3. The description adds only the composite key tuple (repo, tree-sha, feature-set, toolchain-fingerprint, target-triple), which is contextual framing rather than new per-parameter meaning.

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 opens with "Status (rm_build)" and then explains the build broker's value proposition (dedup, caching, co-location) rather than what this specific tool does or returns. It never states the actionable outcome of a status call, and it does not distinguish itself from the sibling endpoints rm_build_request, rm_build_artifacts, rm_build_explain, or rm_build_gc, which the parameter text itself implies exist. The name/verb is clear but the purpose is buried under concept documentation.

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?

The only routing advice given ("Route build requests through this tool rather than a bare local invocation...") concerns the broker as a whole, not when to call status versus artifacts/explain/gc. There is no guidance on prerequisites (e.g., what a valid cache key is, whether a key is required for a meaningful status result) or on when this tool should be skipped.

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