jenkins_get_build_info

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

No annotations exist, so the description carries the full transparency burden. 'Get detailed information' implies a read-only operation, and the tool name itself (get_build_info) makes the non-destructive nature reasonably clear. However, it doesn't disclose any error behaviors (e.g., what happens if the build doesn't exist), auth requirements, or whether session_name matters. Adequate but not rich.

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 short and well-organized with a clear summary line, a fields line, and an Args block. No filler or repetition. The Args section earns its place since schema coverage is 0%, though the definitions are thin. Reasonably front-loaded with the core purpose stated first.

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?

An output schema exists (per context signals), so the return value explanation is not required. The tool has 3 params and a clear read operation. For a simple informational tool, the description is mostly adequate, but the thin parameter documentation (0% schema coverage) and lack of usage guidance leave modest gaps. Not egregious, but could mention what distinguishes this from build_log or last_build tools.

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 Args section repeats parameter names with terse definitions: 'Full job name', 'Build number to inspect', 'Jenkins session to use'. These add minimal value beyond the schema — job_name being 'full' is mildly useful but build_number and session_name definitions are largely tautological. No format, constraints, or examples are given. The description does not fully compensate for the 0% schema coverage.

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 states a specific verb+resource ('Get detailed information about a specific build') and lists what the info includes (result, duration, timestamp, changes, artifacts). It distinguishes from siblings like jenkins_get_build_log (which shows logs) and jenkins_get_last_build (last build only). However, it doesn't explicitly differentiate itself from get_last_successful/failed_build variants in the wording.

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?

No when-to-use guidance, no exclusions, no alternative tools named. The presence of sibling build-related tools (get_last_build, get_build_log, stop_build, delete_build) suggests context where choosing between them matters, but the description provides no guidance on which to pick. The fields listed (result, duration, artifacts) hint that it's the comprehensive inspect tool, but this isn't stated explicitly.

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