Stop a run

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

Beyond the annotations, the description discloses two traits an agent cannot infer: the confirmation/authorization rule based on token ownership, and the side effect that profiles opened by a stopped run are closed. That side effect is materially important given destructiveHint=false, so the added context is genuinely valuable, though the phrase 'Profiles a run opened are closed by the run' is awkwardly worded and could be misread.

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?

Purpose is correctly front-loaded in the first sentence, but the remaining two sentences are syntactically garbled ('Runs this token started stop without asking', 'Profiles a run opened are closed by the run'), which costs clarity even though no sentence is superfluous.

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 one-parameter mutation with annotations present and no output schema, the description covers purpose, confirmation behavior, and the profile-closing side effect. The main remaining gap is runId provenance, which matters for actually invoking the tool correctly.

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?

The schema has zero description coverage on the single runId parameter, so the description carries the burden. It confirms the tool is keyed by runId but never states where a runId comes from (e.g., returned by run_macro or observed via get_run_status) or its expected format, leaving an agent to guess at provenance.

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?

States a specific verb (stops) and the exact resource classes it acts on (macro run, warm-up, background job) plus the identifier used (runId), which distinguishes it from the sibling stop_profile and stop_all_profiles tools. It stops short of an explicit 'not for stopping profiles' exclusion, so the differentiation is implied rather than stated.

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 sentence 'Runs this token started stop without asking; others ask the user first' gives concrete, actionable guidance about when the call will require user confirmation versus proceeding silently. It does not name a sibling alternative or say when not to stop a run, so it is clear context without full routing guidance.

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