Unit Mask Tool

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

No annotations are provided, so the description carries the behavioral disclosure burden. It states the key outcome ('cannot be started even manually') and a failure condition ('Refused for protected units'). It could additionally mention privilege requirements or reversibility, but the core behavior is clearly disclosed.

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 two short sentences with no filler. The main effect is front-loaded, and the important limitation about protected units is included efficiently.

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 single-parameter tool with an output schema, the description is mostly complete: it names the action, effect, and a limitation. It omits minor operational context such as required privileges or how to reverse the operation, but the tool is simple enough that this is not a major gap.

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 100% and the single parameter is already described as 'Systemd unit name.' The description adds little parameter-specific meaning beyond restating that a unit is the target, so the baseline score of 3 applies.

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 uses a specific verb and resource: 'Mask a unit so it cannot be started even manually.' It clearly distinguishes this from sibling tools like unit_start_tool and unit_unmask_tool by stating the intended effect.

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 when to use the tool: when a unit should be prevented from starting even manually. However, it does not explicitly mention alternatives such as unit_disable_tool or unit_unmask_tool, nor does it say when not to use it beyond noting protected units are refused.

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