jenkins_list_credentials

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

No annotations are provided, so the description carries the full burden. It's a read-only listing operation, which is inherently low-risk, but the description doesn't disclose what fields are returned, whether the output is complete or paginated, or any session/connection requirements (implied by session_name param). For a benign listing tool, this is 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 compact and front-loaded with a clear one-line purpose, followed by a terse parameter list in Args format. It uses an efficient structure with each parameter explained in one line. Minor waste: the Args block largely repeats the schema defaults that are already present in the input schema.

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, so return values are covered by structured data. The tool is a simple listing operation with 3 optional parameters. The description covers core meaning and defaults adequately, though it doesn't explain session management or credential output shape in prose. For a low-complexity list tool with an output schema, this is minimally 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 for parameter meaning. The description does add some semantics for 'domain' (with the '_' = global domain note) and 'store' (with 'system' = system store), which helps. However, 'session_name' is only described as 'Jenkins session to use' with no explanation of what a session is or how one is established. Partial compensation, but gaps remain.

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 clearly it lists all credentials stored in Jenkins, using a specific verb+resource. It distinguishes reasonably from sibling tools like jenkins_get_credential (which retrieves a single credential) and jenkins_save_credentials/create_credential (which write). However, it doesn't explicitly contrast with those siblings, so it's clear but not maximally differentiated.

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 lists parameters but provides no explicit guidance on when to use this tool versus alternatives or exclusions. The 'List all credentials' phrasing implies a listing action distinct from retrieval (get_credential) but doesn't explicitly name alternatives or when-not-to-use.

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