query_items

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

With no annotations provided, the description carries full burden for behavioral disclosure. It does not explicitly state that this tool is read-only, nor does it mention permissions, side effects, or performance implications. The description implies a safe query operation but lacks explicit transparency.

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 concise and well-structured with a clear header and bullet-point explanations for arguments and return type. It avoids unnecessary verbiage, though a brief usage note would improve it.

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?

The description explains the return type and parameter roles, and an output schema exists to cover return structure. However, it omits details like pagination, result limits, or how patterns are matched. For a query tool with four parameters, this is adequate but not fully comprehensive.

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 description provides brief explanations for each of the four parameters, which adds some meaning beyond the bare schema (which has no descriptions). However, it does not specify the pattern syntax (regex, glob, etc.), leaving ambiguity. Given 0% schema coverage, the description partially compensates but could be more precise.

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 tool queries items from Jenkins, which is the intended purpose. However, it does not differentiate from the sibling tool 'get_all_items' which also retrieves items, potentially causing confusion about when to use a filtered query vs. an unfiltered one.

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?

There is no explicit guidance on when to use this tool versus alternatives. The description lists parameters but does not explain the appropriate context for using query_items instead of get_all_items or get_item. No when-not-to-use information is provided.

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