Apply gated Hermes deploy repair command

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

Annotations declare readOnlyHint=false, destructiveHint=true, idempotentHint=false, openWorldHint=true — so the safety profile (destructive mutation, side effects) is already communicated. The description reinforces this by saying 'only at owner policy tier' and listing gates, which signals this is a high-risk, heavily-guarded operation. It adds the notion of prerequisite verification (verified artifact, hashes) beyond annotations. However, it doesn't disclose what exactly gets destroyed/modified, whether the command executes arbitrary shell, or what happens on gate failure. With annotations already marking destructive=true, the description adds moderate but not rich context.

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 a single dense sentence that packs too much jargon into one clause. It front-loads the core action ('Run a preconfigured deploy repair command against a verified repair-plan artifact') which is good, but then appends a long gate list that reads as run-on. Splitting into a clear purpose sentence plus a short 'requires X, Y, Z gates' sentence would improve readability. Each gate name is earned but the presentation is cramped.

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?

This is a destructive, complex tool (destructiveHint=true, 9 params, multiple hash/nonce gates) but has an output schema which removes the need to describe return values. The description covers the gating mechanism and owner-tier requirement. However, with 0% schema description coverage and high complexity, it falls short: it doesn't explain the significance of home/profile/toolkit_root, what constitutes a valid 'verified repair-plan artifact', or the workflow prerequisite (e.g., must run hermes_deploy_repair_plan first to obtain the hashes). For a dangerous tool that requires a verification workflow, this is a meaningful completeness gap.

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. The description references the key safety parameters: 'command-hash, plan-hash, and confirmation nonce gates' which map to expected_deploy_repair_command_sha256, expected_repair_plan_sha256, and confirmation_nonce. This tells the agent these params serve as integrity-verification gates. The phrase 'proposal_artifact_dir' is partially explained by 'repair-plan artifact'. However, with 9 parameters and 0% schema coverage, the description names only the hash/nonce params and leaves home, profile, toolkit_root, timeout_seconds unexplained — a gap for a multi-parameter tool.

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 starts with 'Run a preconfigured deploy repair command against a verified repair-plan artifact' — a specific verb ('Run'), resource (deploy repair), and clear target (verified repair-plan artifact). It distinguishes from sibling hermes_deploy_repair_plan (planning vs applying) and clarifies this is the apply side. However, the cascade of gate terminology ('at owner policy tier with git/config/gateway/external gates, command-hash, plan-hash, and confirmation nonce gates') is dense jargon that obscures the core action for an agent.

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 implies usage by mentioning 'verified repair-plan artifact' and 'only at owner policy tier', suggesting it should only be invoked after a verified repair plan exists and at high privilege. It names gates (git/config/gateway/external) that serve as preconditions. However, there's no explicit 'when to use vs alternatives' — no mention of not using it when no verified plan exists, nor clear contrast with hermes_deploy_repair_plan. The gating hints are implicit rather than explicit.

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