jenkins_get_credential

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

With no annotations provided, the description carries the full burden. It discloses that 'secrets are masked' which is a useful behavioral trait for a credential-returning tool, hinting this is a safe read operation. However, it doesn't mention permissions/authentication requirements, whether the operation fails for non-existent credentials, or the response structure beyond masking. The masking disclosure is the key value-add here.

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 the essential purpose in the first line. The Args block is redundant with the schema and arguably shouldn't be repeated. It doesn't contain egregious waste but the Args listing adds no value beyond what the input schema provides, so it's not fully economical.

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 tool has an output schema, so return values need not be explained. However, with 0% schema description coverage, no annotations, and 4 parameters, the description should more thoroughly explain the domain/store/session concepts that are Jenkins-specific and would be unclear to an agent. The '(secrets are masked)' note is helpful, but overall the description is thin for a tool that interacts with Jenkins's credential subsystem.

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 the 4 undocumented parameters. As written, the Args section is a near-verbatim restatement of the schema (credential_id: Credential ID, domain, store, session_name with the same defaults). It adds virtually no meaning beyond what parameter names and defaults convey. It doesn't explain what '_' means as a domain value beyond a parenthetical that's still cryptic, nor does it explain the concept of a credential store or session.

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+resource ('Get details of a specific Jenkins credential') and distinguishes it from siblings like jenkins_list_credentials (list all) and jenkins_save_credentials (create/update). The parenthetical '(secrets are masked)' adds valuable scope clarification. However, it doesn't explicitly differentiate from jenkins_create_credential or jenkins_delete_credential, though the purpose is still distinct enough.

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 implies usage through the verb 'Get details of' and the parenthetical about masking, but it doesn't explicitly state when to use this vs alternatives like jenkins_list_credentials. It doesn't give exclusions or alternative tool names. The tool's use case is fairly intuitive given the sibling naming, but there's no explicit guidance.

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