jenkins_stop_build

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It fails to state whether the abort is immediate or graceful, whether the build enters an 'aborted' state vs 'failed', whether it requires specific permissions, or what happens if the build is already completed. The behavior of stopping versus aborting is ambiguous.

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 and reasonably structured with a clear Args list. No wasted sentences. However, given the behavioral ambiguity noted in transparency, the brevity comes at the cost of completeness.

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 mutation tool with no annotations and no behavioral detail. It has an output schema, which slightly reduces the need for return-value documentation, and the build_number=0 special value is helpful. However, for a destructive-ish action on a running build, the absence of behavioral context (what state results, what happens to output, error conditions for non-running builds) makes it incomplete.

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%, and the description only lists parameter names without adding meaning. It notes that build_number uses 0 = last build (a useful special value the schema doesn't convey), which is the only added semantics. session_name is unexplained, and job_name format nuance ('Full job name') is mentioned but adds minimal value over the schema's 'Job Name' title.

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 'Abort/stop a running build' uses a specific verb+resource pair. It clearly distinguishes this from sibling tools like jenkins_delete_build (delete) and jenkins_cancel_queue_item (cancel queued item). However, it doesn't explicitly differentiate itself from these related build-management siblings, so it doesn't earn 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 provides no guidance on when to use this tool versus alternatives. It doesn't clarify the difference between aborting a running build versus jenkins_delete_build (which deletes a build record) or whether it applies only to running/in-progress builds. No exclusions or alternative-tool references are provided.

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