Complete an issued harness

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

With no annotations supplied, the description carries the full burden. It does disclose a genuine behavioral prerequisite — the caller must produce a valid HMAC signature over a payload with offset = -1 and event_type = 'complete' — which an agent cannot infer from the schema. However, it says nothing about irreversibility, whether completion is final, what happens if the signature is invalid, or what a successful call returns, and "same scheme as spoc.harness.report" defers the actual algorithm to another tool's definition.

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?

Three tight sentences with the action front-loaded and no filler; every sentence carries operational content. The one inefficiency is the indirection "same HMAC scheme as spoc.harness.report," which forces a second lookup rather than being self-contained, and the payload clause duplicates the schema enum.

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?

For a three-parameter terminal mutation with no annotations and no output schema, this is close to right-sized: it states the action, the authentication requirement, and the exact signed payload. An agent that also reads spoc.harness.report can construct a correct call. Missing side-effect and return-value detail is defensible given the tool's narrow scope and the referenced sibling.

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 0%, so the description must compensate. It does add real meaning for hmac_signature by specifying the signed payload content and the offset/event_type values used in the digest, which the regex-only schema does not convey. But the final_status payload note merely restates the enum already in the schema, and harness_id — the primary identifier, up to 120 chars — receives no explanation of format, provenance, or where to obtain it.

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?

Opens with a specific verb+resource: "Mark a harness as completed." That is enough to separate it from siblings like issue/report/verify/get at a glance. It stops short of 5 only because the domain term "harness" and the significance of the terminal state are never grounded, though the title supplies partial context.

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 no statement of when to call this versus spoc.harness.report, verify, or get — the only sibling mentioned is cited as a signing-scheme reference, not as an alternative with a selection condition. It also omits preconditions (e.g. whether the harness must be in a particular state or previously tested) and any note that this is the terminal step in the issue→test→report→complete sequence.

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