jenkins_delete_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 disclosing behavior. It does flag irreversibility ('This cannot be undone'), which is valuable. However, it doesn't disclose whether the deletion cascades, whether authorization/permissions are needed, or what happens to downstream artifacts/logs associated with the build. For a destructive operation with zero annotations, this is a meaningful gap despite the warning.

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 efficient — a single purpose sentence, a clear irreversibility warning, and terse arg list. The warning is appropriately placed near the top. It could arguably be trimmed, but it wastes no space and is well structured.

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 destructive tool with no annotations and no output schema details covered in the description, the irreversibility warning is essential and present. However, the description could be more complete by noting which sibling tool it pairs with (e.g., jenkins_build / jenkins_get_build_info for verification) and clarifying session_name's default behavior. The output schema exists, so return-value explanation isn't required, but permission/cascade behavior would elevate completeness.

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%, meaning the description compensates by listing the three args (job_name, build_number, session_name) with terse one-line meanings. However, these mostly restate what the parameter names already convey ('Job name', 'Build number', 'Jenkins session'). The description adds little beyond the schema's field names and does not explain edge cases like whether build_number is required to exist or how session_name interacts with the default.

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 states the verb ('Delete'), the resource ('a specific build'), and the scope ('from the build history'). This clearly distinguishes it from sibling tools like jenkins_stop_build (stops but doesn't delete) and jenkins_delete_job (deletes a job, not a build), making the purpose unambiguous.

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 indicates the irreversible nature with the warning 'This cannot be undone,' which implies caution. However, it does not explicitly state when to use this tool versus jenkins_stop_build, which is a natural alternative an agent might confuse it with. The usage context is only implied through the irreversibility warning rather than explicit guidance.

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