jenkins_connect

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

With no annotations provided, the description carries full behavioral burden. It discloses that existing same-name sessions are disconnected first, that credentials are cached, and gives SSL and timeout defaults. This is good behavioral transparency for a connection-establishing tool.

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 efficiently structured with a concise intro and an Args block. Each sentence earns its place, though the Args block could arguably be trimmed since the schema already carries defaults, but the added semantics (URL example, token generation path) justify the length.

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?

For a connection tool with 6 parameters and an output schema present, the description covers the connection behavior, session management, and parameter semantics well. It doesn't describe the output/return value, but the output schema exists to cover that, and the tool's behavior is fairly straightforward.

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 carry the parameter documentation. It does so well, explaining each parameter including example URL format, where to generate the API token, and SSL self-signed cert behavior — meaningfully beyond the bare schema.

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 connects to a Jenkins server and creates a named session, with specific verb+resource. It distinguishes from siblings like jenkins_disconnect but doesn't explicitly name the alternative, though the purpose is distinct enough given the large sibling set.

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 explains the connection model and credential caching but doesn't explicitly contrast with sibling tools or state when to use this vs. alternatives. It implies this should be used before other operations via the session concept but doesn't say so explicitly.

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