jenkins_disable_node

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

No annotations are provided, so the description carries full burden for behavioral disclosure. The description states it's a mutation (takes node offline) but doesn't disclose whether this requires elevated permissions, whether it's reversible (via jenkins_enable_node, which is inferable from siblings but not stated), or what the output/response looks like. The reversible aspect could be mentioned as behavioral context but is absent.

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 - a single sentence plus three concise parameter lines. No wasted words. It's appropriately sized for a simple tool. Slight deduction because the parameter list is somewhat redundant with the schema (which lists the same parameter names), though the semantic add-ons do add value.

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 and only 3 params, so it's not complex. The description covers the mutation action, the reason semantics, and session context. However, for a mutating operation with no annotations, it doesn't fully disclose whether there are side effects (e.g., jobs failing, in-flight builds affected) or permissions required. Adequate but with modest gaps for a mutation tool.

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 parameters have no schema descriptions. The description compensates reasonably: it defines node_name ('Node to disable'), reason ('Reason for taking offline (displayed in Jenkins UI)'), and session_name ('Jenkins session to use'). Each parameter gets a meaningful one-line explanation that adds value beyond the bare type definitions in the 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 action: 'Take a Jenkins node/agent offline with a reason message.' The verb 'Take offline' combined with the 'node/agent' resource is specific and clear. It distinguishes from sibling tools like jenkins_enable_node and jenkins_get_node_info by focusing on the offline/disabling action, though it doesn't explicitly reference siblings.

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 context (disabling a node with a reason) but provides no explicit guidance on when to use this tool versus alternatives (e.g., jenkins_quiet_down for whole-server shutdown). There's no mention of when NOT to use it or prerequisites like being connected to a Jenkins session. The session_name parameter hints at connection requirements but isn't explained.

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