linux_user_group_manager

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

The description discloses core behaviors: it generates commands and parses system files, but it does not clarify whether the tool actually executes commands or only displays them. With no annotations, the description should provide more transparency on side effects (e.g., does it modify files?), permissions required, or safety implications. It gives a reasonable overview but leaves uncertainty about mutability.

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 concise at about 60 words, front-loading the menu ID and primary purpose. It lists capabilities in a structured manner, but the sentence listing multiple tasks is somewhat dense and could be broken into bullets for readability. Overall, it is efficient without unnecessary words.

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?

Given the tool's complexity (nested object parameter, multiple operations, no output schema), the description is insufficiently complete. It does not explain return values (e.g., what the tool outputs after generating commands), nor does it provide examples or parameter details. The reliance on an external 'describe_tool' call indicates this description alone is incomplete for confident invocation.

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?

The input schema has three parameters (operation, distro, user) with 0% schema description coverage. The description does not explain the meaning of each parameter, valid values, or required fields beyond the schema itself. For instance, it doesn't clarify what 'operation' can be (e.g., add, modify, delete?) or how 'distro' affects command generation. This leaves the agent guessing about parameter usage.

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 that this tool is a 'User & Group Manager' that generates specific Linux commands (useradd, usermod, etc.) from a form, and lists distinct tasks like parsing /etc/passwd and /etc/group, auditing UID/GID consistency, and configuring sudo. This specificity differentiates it from sibling tools like 'linux_command_builder' and provides a clear, actionable purpose.

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 the tool's capabilities (e.g., audit UID/GID, set up sudo) which imply when to use it, but it does not explicitly state when to use this tool versus alternatives, nor does it provide any exclusions or prerequisites. The reference to 'use describe_tool for full page guidance' acknowledges additional guidance exists but does not offer direct usage guidelines.

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