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

Annotations declare readOnlyHint=false and destructiveHint=false, so the description carries the burden of explaining the mutation behavior. The description adds valuable context beyond the annotations: it warns that content for a rig-step harness is the FULL config object (replacement semantics, not a partial patch) and instructs the agent to keep `skill` intact. This is genuinely useful behavioral disclosure about how the update merges or replaces data.

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 description is compact — roughly two sentences — and front-loads the core purpose ('Update an existing harness's content or metadata') before diving into the rig-step specifics. The conditional 'For a rig-step harness' scoping prevents the guidance from being overstated. It is efficient with no filler, though the reference to 'see create_harness' adds a cross-tool dependency that requires the agent to fetch another tool's definition.

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 3-parameter update tool with no output schema, the description covers the core semantics well: it explains full-replacement behavior for rig-step harnesses and which fields to preserve or set. However, it leaves gaps — it doesn't state what happens to fields omitted from the content object (are they reset/cleared?), doesn't explain the `metadata` parameter's merge behavior, and defers the model-pin semantics to create_harness rather than summarizing them. These are minor but real gaps for a tool whose behavior around partial updates is ambiguous.

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 all three parameters (content, metadata, harness_id) are documented in the schema. The description adds meaning beyond the schema for the `content` parameter by explaining that it is a full config object for rig-step harnesses with specific fields to preserve (skill) and set (instruction/endpoint/tool/params/model/model_policy), plus a pointer to create_harness for model-pin semantics. This is useful, but the metadata parameter gets no added explanation, and the high schema coverage means the description only modestly supplements it, so a baseline 3 is appropriate.

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 states a clear verb ('Update') and resource ('an existing harness') and specifies what is updatable ('content or metadata'). It implicitly distinguishes from siblings like create_harness, delete_harness, get_harness, and list_harnesses by the 'existing harness' phrasing, and it explicitly references create_harness for model-pin semantics, which aids differentiation. However, it doesn't name any sibling tool explicitly as an alternative, so it stops short of a 5.

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 description clearly states what the tool does ('Update an existing harness's content or metadata') and the rig-step replacement semantics, which implies when it should be used. It also points to create_harness for the model-pin semantics, hinting at the create-vs-update boundary. However, there are no explicit exclusions, when-not-to-use conditions, or named alternative tools for partial edits versus full replacements, leaving the agent to infer the exact decision boundary.

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