jenkins_get_queue_item

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

No annotations are provided, so the description carries the burden. It doesn't mention error behavior for invalid queue IDs (e.g., what happens when the item no longer exists or was consumed), rate limits, or whether the item persists after building. For a read-only lookup tool, this is a moderate gap but not severe for a simple fetch operation.

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 - two short sentences plus an args list. It's front-loaded with the purpose statement. The args section is slightly redundant given the schema also lists these params, but it adds the provenance note about queue_id which is useful. No wasted words.

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?

Given the tool has an output schema and only 2 simple parameters (one required), the description is mostly adequate. The main gap is no guidance on behavior when the queue item is no longer present (already built, cancelled, expired). For a lookup tool with an output schema, this is near-sufficient but not fully complete.

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. It explains queue_id ('Queue item ID (from jenkins_get_queue)') adding provenance context beyond the schema type, and session_name ('Jenkins session to use') gives purpose. While an output schema exists, the param explanations add value by linking queue_id to its source tool.

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 'Get details of a specific item in the build queue' with a clear verb and resource. It distinguishes from its sibling 'jenkins_get_queue' (which lists the queue) versus getting a specific item. The sibling 'jenkins_cancel_queue_item' is clearly different. Clear enough purpose.

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?

It provides an Args section explaining where queue_id comes from ('from jenkins_get_queue'), which gives some usage context. However, there's no explicit statement of when to use this vs alternatives, and no mention of the relationship to cancel_queue_item or when getting individual item details is needed.

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