Stop Hermes run

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

Annotations exist but are minimal: readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false. These already signal a non-read, non-idempotent mutation with external side effects. The description adds the behavior of 'writing redacted receipts' and the gate/permission requirements, which is useful context beyond the annotations. However, it doesn't disclose what happens to the run's state, whether the stop is reversible, or failure/consistency behavior. With annotations carrying a portion of the burden, a 3 is fair.

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?

One tight sentence that front-loads the mechanism (typed POST wrapper), the action (requests stop), the side effect (redacted receipts), and the gates. Slightly verbose with the gate enumeration, but each clause earns its place. No filler or redundant restatement of the title.

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?

Output schema exists (though not shown), annotations are present, schema covers 100% of params, and the descriptions is compact but competent. The tool is a straightforward wrapper for a known endpoint. It covers permissions/gates and side effects. Minor gap: doesn't describe what the response/return looks like or what happens on failure, but with an output schema present this isn't the description's job. Complete enough for a well-typed wrapper tool.

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% — all three parameters (run_id, reason, wait_seconds) have descriptions in the schema. The description itself adds the 'redacted receipts' write behavior and gate requirements but does not add parameter-level detail beyond the schema. Per the baseline rule (coverage >80%), a 3 is appropriate since the schema does the heavy lifting.

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 clearly identifies it as a typed POST wrapper for /v1/runs/{run_id}/stop that requests a Hermes run stop, writing redacted receipts. It distinguishes itself from siblings like hermes_api_runs_start (start flow) and hermes_api_runs_get/events (read flows). However, it doesn't explicitly contrast against job_stop-like siblings since none exist; hermes_api_jobs_pause/cancel are nearby but different resources. Clear verb+resource+scope.

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 states the tier requirement (api_call) and gate requirements (live, agent-tool, external-side-effect), giving conditional context for when the tool is permissible. It also implies use for stopping runs, but does not explicitly say when NOT to use it or name alternatives (e.g., when to prefer graceful stop vs hard cancel, or relation to hermes_job_cancel). Adequate but no explicit exclusions or alternatives.

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