arch-linux-mcp

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

The description adds significant behavioral context beyond the destructiveHint annotation. It details the multi-step security workflow (e.g., checking repos, analyzing trust scores, blocking on critical issues), specifies prerequisites (sudo, paru/yay), and mentions installation behavior (--noconfirm). This enriches the agent's understanding of the tool's safety and operational traits, though it doesn't contradict the destructiveHint (true for installation).

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 front-loaded with the core purpose and uses a numbered list for the workflow, which is efficient. However, it includes some redundancy (e.g., repeating AUR details) and could be slightly tightened without losing clarity. Every sentence contributes, but minor trimming could improve conciseness.

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 (security checks, multi-step workflow) and lack of output schema, the description does well to cover behavior, constraints, and workflow. It doesn't explain return values or error handling, which is a gap, but compensates with detailed operational context. For a destructive tool with no output schema, it's reasonably complete but not exhaustive.

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?

With 100% schema description coverage, the input schema already documents the package_name parameter thoroughly. The description adds minimal extra semantics by mentioning that it 'checks official repos first, then AUR', which is implied but not detailed in the schema. This meets the baseline for high schema coverage without significant enhancement.

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 specific action ('Install a package with comprehensive security checks'), identifies the resource (packages), and distinguishes from siblings by emphasizing security-focused installation versus general package management tools like remove_packages or search_aur. It explicitly mentions the workflow and constraints, making the purpose distinct and well-defined.

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 provides explicit guidance on when to use this tool: for installing packages on Arch Linux with security checks, and when not to use it (e.g., for non-Arch systems or without sudo/AUR helpers). It implicitly suggests alternatives like search_aur for finding packages or remove_packages for uninstalling, but could be more explicit about sibling tools. The constraints (Arch Linux, sudo, AUR helpers) effectively define the usage context.

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