arch-niri-mcp
Server Quality Checklist
Latest release: v0.1.0
- Disambiguation3/5
While getters are clearly distinct, there is overlap between niri_perform_action and specific tools like niri_set_column_width, and among the three launching tools (niri_spawn_app, arch_spawn_terminal, arch_exec_terminal_cmd) which may confuse agents. However, descriptions clarify their intents.
Naming Consistency4/5Most tools follow a clear prefix_verb_noun pattern (e.g., niri_get_windows, arch_package_query), but a few like arch_systemctl and niri_perform_action break the pattern, and there is stylistic variation (e.g., niri_take_screenshot vs niri_get_*).
Tool Count3/535 tools is large for a single server, but it serves two distinct domains (Niri DE management and Arch system administration), so each tool has a purpose. Still, it exceeds the typical 15-tool threshold and could be streamlined.
Completeness5/5The server provides thorough coverage of both Niri window manager operations and Arch system administration, including edge features like clipboard, brightness, and AUR search. No major dead ends are apparent.
Average 3.9/5 across 35 of 35 tools scored. Lowest: 2.9/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 2 commits in the last 12 weeks
- Last stable release on
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI status not available
This repository is licensed under MIT License.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
Add a glama.json file to provide metadata about your server.
If you are the author, simply .
If the server belongs to an organization, first add
glama.jsonto the root of your repository:{ "$schema": "https://glama.ai/mcp/schemas/server.json", "maintainers": [ "your-github-username" ] }Then . Browse examples.
Add related servers to improve discoverability.
How to sync the server with GitHub?
Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.
To manually sync the server, click the "Sync Server" button in the MCP server admin interface.
How is the quality score calculated?
The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).
Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.
Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).
Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.
Tool Scores
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden, but it fails to disclose that these actions mutate Niri state, may require a focused window, or could have side effects. The examples imply side effects (e.g., toggling) but do not explicitly state behavioral consequences or prerequisites.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded with the main purpose, followed by a useful list of examples. Every line adds value, though the structure could be improved with a note about additional actions or a link to documentation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a generic action tool with many possible actions, the description gives a decent sample but is not exhaustive. It doesn't mention that more actions exist or provide a way to discover them, and while an output schema exists, it doesn't need to explain returns, the missing guidance on action-specific arguments limits completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description partially compensates by explaining action_name with concrete examples and showing that args can be passed (e.g., args=['50%']). However, it does not enumerate all possible actions or the expected args for each, leaving ambiguity for many cases.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool as performing Niri layout or window actions, with a specific verb and resource. The examples distinguish it from sibling tools that handle individual actions, but it doesn't explicitly state that this is the catch-all for actions without dedicated tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no guidance on when to use this tool versus the dedicated sibling tools like niri_set_column_width, which overlaps with the 'set-column-width' example. It lacks exclusions or context for choosing this generic action tool over specific ones.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It does not mention output format, default number of lines, whether it is read-only, or how filters like errors_only behave. The only behavioral hint is 'via journalctl,' which indicates the underlying command but not the tool's own behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no fluff. It states the essential purpose efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having an output schema, the tool has no annotations, zero parameter description, and lacks usage guidance. The description is too sparse for a tool with four parameters and a potentially complex return format. More detail on filtering, defaults, and output would be needed for an agent to use it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not compensate by explaining any of the parameters (lines, unit_name, user_mode, errors_only). The parameter names are somewhat self-explanatory, but the description provides zero additional meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb ('Fetch') and resource ('systemd service or kernel logs') via journalctl. It distinguishes this tool from siblings like arch_systemctl (service management) and arch_get_system_info, which do not fetch logs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when systemd service or kernel logs are needed, but does not explicitly state when to use this tool over alternatives or mention any exclusions. It provides no context on when journalctl would be preferred over arch_systemctl or other diagnostic tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must alone convey behavior. It only restates the core function ('discover') without disclosing side effects, safety (read-only), permissions, or what happens during the scan. Since this is a discovery tool, it's likely safe, but that is not stated, leaving the agent uncertain about its behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is reasonably concise and front-loaded with the verb. It lists specific categories, earning its place, though the phrase 'installed... installed on the system' is slightly redundant and could be streamlined.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has an output schema (present but not shown), so return values are covered. The description provides a clear list of what it discovers, which is fairly specific. However, it lacks context about when to use it (already penalized in Usage Guidelines) and does not clarify what 'discover' entails (e.g., only names or full paths). Given the tool's simplicity, the description is largely adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the input schema is empty and there is nothing to explain. The baseline for 0 params is 4; the description adds no parameter-specific meaning, but none is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: discovering installed CLI utilities, terminal emulators, package managers, Wayland helpers, and desktop monitors. It uses a specific verb ('discover') and resource ('system'), but it does not explicitly differentiate it from sibling tools like arch_get_system_info or arch_package_query, so it lacks sibling differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention any alternatives, exclusions, or prerequisites. Given the large sibling set, this is a notable gap.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses the interactive and graphical nature, but omits key behavioral traits like whether the call blocks, returns immediately, requires a graphical session, or affects existing windows. No side effects or error behavior are mentioned.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the action verb, no redundant words. Every word adds value: it states what, where, and optional customization.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is adequate for a simple spawn operation, but has clear gaps: it does not mention the working_dir parameter, does not clarify behavior on failure, and does not provide usage context versus siblings. An output schema exists, so return values are not the main gap, but the missing working_dir semantics and lack of alternative guidance make it only minimally complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It explains the 'command' parameter ('Optionally pass a command to run inside the terminal window') but completely omits the 'working_dir' parameter. Thus only half of the parameters receive any meaningful explanation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Launch an interactive graphical terminal window') with a specific resource ('terminal') and environment ('inside Niri DE session'). It also provides examples of terminals (Alacritty, Kitty, Foot), which distinguishes it from generic spawn tools like niri_spawn_app and arch_exec_terminal_cmd.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance is given about when to use this tool versus alternatives. The description implies use for interactive terminals, but it does not mention exclusions or contrast with sibling tools such as niri_spawn_app or arch_exec_terminal_cmd.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states this is a query (implying read-only) but does not mention network usage for remote repositories, whether installed_only defaults to true, or any permissions required. The description is too sparse to convey potential side effects or prerequisites.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that directly states the tool's function. There is no wasted wording, and it is appropriately sized for a simple query tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having an output schema, the description is minimal for a tool with two parameters and no annotations. It lacks usage guidelines, parameter semantics, and behavioral details. Considering the simplicity of the tool, it is still under-specified for an agent to use correctly without additional inference.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description only hints at the installed_only parameter through 'search installed packages or remote repositories.' It does not explain the 'query' parameter format or the default value of installed_only. The description adds some meaning but does not compensate for the lack of schema documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Query') and clearly identifies the resource ('Arch Linux / CachyOS pacman package database') with explicit scope ('search installed packages or remote repositories'). This distinguishes it from sibling tools like arch_aur_search and arch_check_updates.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for pacman database queries but does not explicitly state when to use it over alternatives (e.g., for AUR, use arch_aur_search) or when not to use it. No exclusions or alternative tool names are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It does disclose that it captures stdout, stderr, exit code, and handles timeouts, which is useful. However, it does not mention potential safety risks (e.g., commands can modify system state) or that it runs with user privileges, leaving an important transparency gap for a tool that executes arbitrary commands.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core purpose. Every word earns its place; there is no filler or redundancy. It is as concise as possible while conveying key behavior.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is a generic command executor with a simple schema (3 fields) and an output schema, so the return values are likely covered. The description mentions command capture and timeout handling, but omits cwd semantics, safety caveats, and usage guidance. It is not severely incomplete but has notable gaps for a potentially powerful tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. The description implies the 'command' parameter ('Execute any terminal/CLI command') and mentions timeouts, which maps to 'timeout_seconds'. However, 'cwd' is not described at all, and no details are given about command syntax or argument handling, so compensation is partial.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Execute any terminal/CLI command' with a clear verb and resource, and specifies 'in the user's shell environment' for context. It distinguishes itself from the sibling tools, which are specialized for specific operations (e.g., arch_systemctl, arch_journalctl), by being the generic command runner.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus the specialized sibling tools. It does not mention alternatives, exclusions, or specific use cases (e.g., 'use for arbitrary commands; use arch_systemctl for systemd'). The only implied guidance is that it runs any command, but no explicit when/when-not guidance is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full responsibility for behavioral context. While it mentions the signal types, it does not disclose that SIGKILL is uncatchable and may leave resources unclean, that permission to kill the process may be required, or what happens on invalid/nonexistent PIDs. The destructive nature is implied but not elaborated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence with no filler. Every word contributes essential information. The structure is ideal for quick comprehension.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with an output schema and only two parameters, the description is nearly sufficient. It names the action, the target, and the signal options. However, without annotations, it lacks safety/error context that a destructive tool would benefit from, and it does not mention how to discover PIDs (sibling tool arch_process_list). It is minimally viable but not rich.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds meaning to both parameters: 'by its PID' clarifies pid's role, and 'SIGTERM or SIGKILL' constrains the signal to two allowed values, which the schema does not enumerate. However, it does not explain the behavioral difference between signals or default behavior beyond the schema's default. Schema coverage is 0%, so the description partially compensates.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Terminate'), the resource ('a running process'), and the key parameter ('by its PID'). It also specifies the signal options, distinguishing it from sibling tools like arch_process_list and arch_systemctl. The verb is specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied by the name and description: use when you need to terminate a process by PID. However, there is no explicit guidance on when to choose this over alternatives, nor any mention of how to obtain the PID (e.g., via arch_process_list). No exclusions or preconditions are stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
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. It states the core mutation (moving the window) but does not explain semantics of directions like 'first' and 'last', what happens if no window is focused, or edge cases such as moving at screen edges. This leaves significant ambiguity for a compositor operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, consisting of two short sentences that get straight to the point. The first sentence states the action and target; the second lists allowed values. No wasted words or redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity (one parameter), the description is close to sufficient, but ambiguity around 'first' and 'last' directions and missing behavior for unfocused windows make it incomplete. An output schema exists, so return values need not be explained, but the tool's edge cases remain undocumented.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides no description or enum for the 'direction' parameter (0% coverage). The description lists valid values ('left', 'right', 'up', 'down', 'first', 'last'), which is useful, but it does not explain what each direction does, especially 'first' and 'last'. This partially compensates for the schema gap but leaves semantics unclear.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific action ('Move') and resource ('focused window or column') with a direction parameter. It distinguishes itself from sibling tools like niri_move_window_to_workspace, which moves to a workspace rather than a direction, and niri_focus_window, which changes focus rather than position.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when you want to move the focused window or column directionally, but it does not explicitly state when to use this tool over alternatives, nor does it provide any exclusions or prerequisites. No mention of alternatives like niri_perform_action is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It adds some context by specifying 'currently focused' and that the workspace can be referenced by index or name, but it does not disclose side effects such as whether the view changes to the target workspace, what happens if the workspace does not exist, or whether the move is reversible. This is a mutation tool with minimal behavioral disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no redundant words. It directly states the action, subject, and target, making it highly concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter tool, the core function is described, but there are gaps: no mention of preconditions (e.g., a focused window must exist), error behavior, or side effects. An output schema exists, so return values are likely covered, but the lack of behavioral context for a mutation makes it only adequately complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema only defines workspace_ref as a string with no description, and schema description coverage is 0%. The description adds meaning by stating the reference can be by index or name, which helps the agent understand the parameter's format. However, it does not specify how to distinguish index from name or whether the string should be numeric, leaving some ambiguity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (move), the resource (currently focused window/column), and the destination (specified workspace by index or name). This distinguishes it from siblings like niri_focus_workspace (focuses workspace) and niri_move_window_direction (moves in a direction), as it uniquely targets a workspace by reference.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context: it operates on the currently focused window/column, so the agent must know that a focused window exists. However, it provides no explicit when-to-use or when-not-to-use guidance, nor does it mention alternatives beyond what sibling names imply.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of disclosing behavioral traits. It states the action can be 'get' or 'set', which implies a read vs. mutate distinction, but it does not disclose side effects, permission requirements, failure modes, or what the tool returns. This is insufficient for a tool that can alter system state via brightnessctl.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise, with a single opening sentence and two short parameter lines. It front-loads the core purpose and contains zero filler. Every sentence adds value, making it highly efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple (2 optional params, output schema exists) but the description still misses important context: prerequisites (does brightnessctl need to be installed?), error conditions, and more explicit parameter relationships (e.g., percent ignored when action=get). The output schema covers return values, but the description could be more thorough for a mutation-capable tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It provides explicit meanings for both parameters: 'action: get or set' and 'percent: Target brightness percentage integer (1-100) when action is set', which goes beyond the bare schema. However, it could be clearer about whether percent is required for 'set', or what happens if percent is omitted or invalid, so not a perfect score.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Query or adjust screen brightness using brightnessctl', with a specific verb ('Query or adjust'), resource ('screen brightness'), and mechanism ('brightnessctl'). This distinguishes it from sibling tools like arch_audio_control, fulfilling the purpose clarity requirement.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool (for brightness operations) via its primary purpose line, and the param explanations give some usage guidance (e.g., 'action: get or set'). However, it does not explicitly state when to use this tool versus alternatives (e.g., arch_audio_control for audio), or provide any exclusion conditions, so it falls short of a higher score.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must disclose behavioral traits. It reveals the OR requirement between window_id and search_query, which is useful. However, it does not disclose what happens when both are provided, when neither is provided, or how ambiguous matches are handled. While focusing is not a destructive operation, the lack of edge-case behavior is a transparency gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the main purpose, and every word contributes to understanding the tool's core function. There is no redundant or vague language.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (two optional parameters, no nested objects) and the presence of an output schema, the description covers the essential usage pattern and parameter semantics. It does not explain edge cases like what happens if neither parameter is given, but for a focus operation this is a minor omission. Overall, it is sufficiently complete for an agent to select and invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides only types and defaults (0% coverage), but the description compensates by explaining that window_id is a numeric ID and search_query matches title or app_id, with concrete examples like 'firefox', 'terminal', 'code'. It adds meaningful semantics beyond the schema, though it doesn't specify matching behavior (e.g., substring vs exact match).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Focus a window') and the resource (window in Niri), which is distinct from sibling tools like niri_focus_workspace or niri_move_window_to_workspace. It could be more explicit about being the go-to tool for focusing a specific window rather than a workspace, but the verb+resource pairing is specific enough.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides usage context by explaining how to specify the target via window_id or search_query, implying when to use this tool. However, it does not explicitly state when to use it over alternatives, nor does it mention exclusions or prerequisites such as needing to obtain window IDs from niri_get_windows. This is implied rather than clearly stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries full responsibility for disclosing behavioral traits. It only mentions switching the active workspace but does not clarify side effects, such as whether the focused window changes, what happens if the workspace reference is invalid, or whether the operation requires existing workspaces. This lack of detail is a significant gap for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that immediately states the action and parameter options. Every word earns its place, with no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter tool with an output schema, the description covers the core operation and parameter format. However, it omits important contextual details such as error behavior (e.g., what happens if the workspace does not exist) and any relationship to other tools like niri_get_workspaces, leaving the agent to assume behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides a bare 'workspace_ref' string with zero description, but the tool description compensates by specifying that it accepts an index number (e.g., '1', '2', '3') or a workspace name. This adds meaningful semantics beyond the schema, though it does not elaborate on name formats or behavior when multiple matches exist.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Switch active workspace in Niri' with a specific verb and resource. It also distinguishes itself from siblings like niri_focus_window and niri_move_window_to_workspace by focusing on workspace activation rather than window manipulation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the use case—switching workspaces—but does not explicitly state when to choose this tool over alternatives or mention any prerequisites such as querying available workspaces via niri_get_workspaces. No exclusions or when-not-to-use guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It names the underlying `wl-copy` command, which provides a small implementation detail, but it does not mention side effects like overwriting existing clipboard content or any dependencies. It is minimally transparent but not misleading.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no filler or redundant information. It covers the tool's action and implementation in eleven words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with one parameter and an output schema. The description adequately states the purpose and implies the input, which is enough for basic usage. However, it omits any prerequisites or environment requirements (e.g., needing a Wayland session), so it is not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. The phrase 'text content' directly maps to the `text` parameter and clarifies what the input should be. For a single obvious string parameter, this is sufficient.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Set') and resource ('Wayland clipboard'), with the implementation detail '`wl-copy`'. It is clearly distinguished from the sibling tool `arch_clipboard_get`, which does the opposite action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool versus alternatives like `arch_clipboard_get`. The description simply states the action without any context, prerequisites, or explicit exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It only states the action without disclosing potential side effects, such as whether the reload triggers a full application of changes, could fail on invalid config, or affects the running session. This lack of detail is a significant gap for a configuration-changing tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence: 'Reload Niri DE configuration file (`config.kdl`).' It is front-loaded and contains no unnecessary words, making it maximally concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with no parameters, and an output schema exists, so return value details are not required. The description sufficiently conveys the action and target resource. However, it could add a brief note about when reloading is needed (e.g., after editing the config) but is otherwise complete for a zero-param config reload tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, which earns a baseline of 4. The description adds no parameter details because there are none to describe, and the schema already covers the empty input object.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action with a specific verb ('Reload') and resource ('Niri DE configuration file (`config.kdl`)'). It distinguishes itself from sibling tools, which focus on querying or manipulating windows/workspaces, by uniquely targeting configuration reload.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage: reloading the config after editing it. However, it provides no explicit when-to-use guidance, no excluded scenarios, and does not mention alternatives (though no direct alternative exists among siblings). This meets the 'implied usage' threshold, but lacks explicit context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden for behavioral disclosure. It tells the agent this is a search operation, which implies a read-only network fetch, but it does not mention potential side effects like updating the yay cache or requiring network access. This is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that conveys the essential purpose without any filler. Every word contributes to understanding the tool's function.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple one-parameter schema and the presence of an output schema, the description is largely complete. It does not explain how the two repository sources are combined or whether the search is case-sensitive, but for a straightforward search tool this is a minor gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not elaborate on the 'query' parameter beyond its name and type. It does not state whether the query is a package name, a regex, or a fuzzy search term, leaving the agent without crucial semantic information for properly forming the query.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action ('Search'), the target resources ('Arch User Repository (AUR) & CachyOS software repositories'), and the method ('using yay'). This specific verb+resource+method distinguishes it from siblings like arch_package_query, which likely handles official repos.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context that this tool is for searching AUR and CachyOS repos, implying it is the right choice when those sources are needed. It does not explicitly name alternatives or exclusions, but the context is strong enough for an agent to select it appropriately.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses the underlying mechanism (notify-send), the target environment (Niri DE), and lists valid urgency values. However, it omits any mention of side effects, permissions, or failure conditions, which are relevant for a tool that interacts with the desktop environment.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences: the first clearly states the action, the second provides urgency values. Every word earns its place; there is no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple (4 params, one required) and an output schema exists, so return values need not be described. The description covers the core purpose and the parameter most likely to require clarification (urgency). The schema handles the remaining parameter details, making the description sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It only explains the 'urgency' parameter by listing allowed values, while summary, body, and icon are not described in prose. Although those parameters are somewhat self-explanatory from the schema, the description does not fully compensate for the lack of coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Send'), resource ('desktop notification'), and target ('Niri DE via notify-send'). This clearly distinguishes it from sibling tools like arch_systemctl or niri_get_workspaces, which serve different functions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies usage: use this tool when you need to send a desktop notification on Niri. There are no alternative notification tools among siblings, so explicit exclusionary guidance is not necessary, though it stops short of stating 'when not to use'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full burden. It does list valid width options, which is useful behavioral information, but it does not disclose side effects, error handling, or whether the operation is reversible. This is a minimal viable disclosure, hence a 3.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: a single statement plus a list of options. No fluff, every word earns its place, and the main verb is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter tool, the description covers purpose and parameter values, and an output schema exists for return values. However, it lacks usage context and behavioral details (e.g., side effects, error behavior), which is a noticeable gap given the absence of annotations. It is adequate but not thorough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides no description for the width parameter (0% coverage), but the description compensates by enumerating all valid values: '50%', '33.333%', '+10%', '-10%', 'switch-preset', or 'expand'. This adds significant meaning beyond the bare string type, though it does not explain the semantics of each option.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb+resource: 'Set focused column width.' This clearly distinguishes it from sibling tools like niri_focus_window or niri_move_window_direction. The listed width options further clarify the exact purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied by the tool's specificity—it is clearly for adjusting the focused column's width—but no explicit guidance on when to use it versus alternatives is given. No exclusions or prerequisites are mentioned, so it is not a clear 4 or 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It names the underlying command (wpctl) and enumerates actions that imply state changes (set_volume, toggle_mute) and a read operation (status). It does not disclose edge cases, side effects, or prerequisites, which would be valuable for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the main purpose, and every sentence provides operational detail. It avoids redundant repetition of schema fields.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given an output schema exists and the parameter count is low, the description covers all essential action types and the value semantics. It does not explain return values, but the output schema presumably covers that. The only slight omission is not explicitly stating that value is ignored for status/toggle_mute, but the example implies it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but the description adds significant meaning by specifying allowed values for action and clarifying that value is a volume percentage when action is 'set_volume'. This goes beyond the bare schema. It leaves minor gaps (e.g., value behavior for other actions) but is largely effective.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb+resource: 'Control PipeWire audio volume or muting via wpctl'. This clearly distinguishes it from sibling tools like arch_brightness_control or niri_* actions. The mention of Arch/CachyOS also narrows scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description lists the valid actions and gives an example for the value parameter, which implies usage. However, it does not explicitly state when to use this tool versus alternatives or provide exclusion criteria. For a simple control tool, this is adequate but not fully explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It communicates that the tool reads battery status, capacity, and charging state, implying a read-only behavior. However, it does not disclose return format, units, or failure behavior. The output schema covers some of this, but the description itself is thin.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that directly states what the tool does. Every word earns its place, and it is front-loaded with the verb 'Check.'
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity, zero parameters, and the presence of an output schema, the description provides sufficient context. It names the key data points returned. It could mention units or typical values, but the output schema likely fills those gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters, so the description has no parameter burden. Per the rubric, 0 parameters warrants a baseline of 4, and no additional parameter details are needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Check' and clearly identifies the resource as 'battery status, capacity level, and charging state.' This precisely distinguishes it from all sibling tools, none of which are battery-related.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for checking battery information, but provides no explicit guidance on when to use it or any alternatives. Since there are no battery-related siblings, the usage context is self-evident, but it lacks explicit when-to-use language.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It implies a read-only check, but does not explicitly state whether it refreshes package databases or has side effects. This is adequate for a simple check but not fully transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that conveys the essential purpose without any filler words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple (no params, output schema present), and the description adequately covers its scope. It could be more explicit about what constitutes 'pending updates' (e.g., official repos vs AUR), but the platform clarification helps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has zero parameters (coverage 100% vacuously), so the baseline is 4. The description adds no parameter details because none exist.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Check') and resource ('pending software updates') with platform scope ('Arch Linux / CachyOS'). It clearly distinguishes from siblings like package queries or system info tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The tool's purpose implies its usage context (checking for updates), but it does not explicitly mention when to use it instead of alternatives such as arch_package_query or arch_aur_search, and provides no exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description must fully disclose behavioral traits. It states the basic action but provides no extra context such as side effects, behavior with invalid window IDs, or whether the operation is reversible. For a destructive action like closing a window, more transparency would be expected.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence with a clear verb-first structure, directly conveying the tool's purpose and parameter behavior. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one optional parameter and an output schema, the description covers the essential usage. It does not mention edge cases like no focused window or invalid ID, but these are not critical given the schema and overall simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers only the parameter type/default with 0% description coverage. The description compensates by explaining 'window_id' as a specific window's numeric ID and implies that null/omitted targets the currently focused window, adding meaningful semantic context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Close') and clearly identifies the resource (window), distinguishing between the currently focused window and a specific window by numeric ID. This differentiates it from sibling tools like niri_focus_window or niri_move_window_to_workspace.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool (when closing a window) and clarifies two usage modes: the focused window (default) or a specific window via ID. It does not explicitly exclude alternatives or mention when not to use it, but the context is clear given the sibling tool names.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears the burden. The verb 'Get' implies a read-only operation with no side effects, but the description does not explicitly state safety or behavior details. As a getter, the risk is low, but richer context (e.g., 'does not mutate state') would improve transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler. Every word contributes to the meaning, making it highly concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no parameters and an output schema present, the description need not explain return values. It covers both aspects (focused window and monitor) and is adequate for a simple getter, though it does not mention edge cases like no focused window.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and schema coverage is 100%, so the baseline is 4. The description adds no parameter details but none are needed; it clearly defines what is being queried, which is sufficient.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool gets detailed information about the focused window and display monitor, using a specific verb ('Get') and resource. This distinguishes it from sibling tools like niri_get_windows (all windows) and niri_get_outputs (all outputs).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when focused window/monitor info is needed but does not explicitly discuss alternatives or when not to use it. No exclusion criteria are provided, but the focused scope is clear from the text.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden of behavioral disclosure. It clearly indicates a read-only operation ('List') and specifies behavioral traits such as ordering by CPU/Memory and searching by name. However, it does not explicitly note that the tool has no side effects or describe any access requirements, but the read-only nature is evident from the verb. This is adequate transparency for a simple listing tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that front-loads the primary action and resource, then adds the two key modes. Every word contributes meaning, with no filler or redundancy. This is exemplary conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple process-listing tool with two optional parameters, an existing output schema, and low complexity, the description provides sufficient context. It covers the core functionality and parameter intent, and the output schema can clarify return values. No additional detail is needed for an agent to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It effectively explains the 'search_term' parameter by mentioning 'search process by name', but it does not address the 'limit' parameter beyond the schema's default value. Since 'limit' is self-explanatory in context, the description adds partial value, but not enough to fully document all parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List') with a clear resource ('running system processes'). It also indicates two modes: ordering by CPU/Memory usage and searching by name, which fully distinguishes it from sibling tools like arch_kill_process. This is a precise and unambiguous statement of purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context (listing processes) but does not explicitly mention when to use this tool versus alternatives like arch_get_system_info or arch_kill_process. There is no stated exclusion or comparative guidance, so the usage is clear only by inference from the tool name and description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, so the description carries full burden. It provides some behavioral context, such as explaining user_mode ('True for user services, False for system-wide services') and enumerating possible actions (status, start, stop, etc.), but it does not disclose side effects, permissions, or the disruptive nature of actions like stop/restart. This is minimal but non-trivial added context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: one purpose statement followed by three parameter explanations. Every line earns its place, no filler or repetition, and the front-loaded sentence sets the context immediately.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple service management tool, the description covers all essential invocation details (actions, unit name, user vs system mode) and the output schema handles return values. However, it omits important contextual cues like potential need for root privileges or the impact of mutating actions, which would make it fully self-contained.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate entirely. It does so exceptionally: it lists allowed values for action, gives a concrete example for unit_name (e.g., 'pipewire.service'), and explains the boolean semantics of user_mode. This fully bridges the gap left by the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Manage systemd services on Arch / CachyOS', using a specific verb ('manage') and a distinct resource ('systemd services') that sets it apart from all sibling tools. It is immediately obvious what this tool does without ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage by indicating this manages systemd services, but it does not explicitly state when to use this tool versus alternatives, nor does it mention exclusions or prerequisites. It leaves the agent to infer that service management is the domain.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. The word 'Get' implies a read-only operation, and the description specifies what is retrieved (configured layouts and active index). However, it does not disclose return format, error behavior, or any other traits beyond the basic read action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that conveys the full purpose without any wasted words. It is concise and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no parameters and an output schema exists, the description adequately covers what the tool returns and why it would be used. It is complete for the tool's simplicity and fits well within the sibling context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are zero parameters, so the description does not need to add parameter semantics. According to the baseline rule for no-parameter tools, a score of 4 is appropriate despite no extra param details in the description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Get') and identifies the exact resource ('configured keyboard layouts') plus the additional detail of returning the 'current active layout index'. This clearly distinguishes it from sibling tools like niri_get_workspaces or niri_get_outputs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for retrieving keyboard layout information but does not explicitly state when to use this tool versus alternatives or provide any exclusions. The context is clear enough for a simple getter, but no explicit guidance is offered.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. The word 'List' indicates a read-only retrieval, but the description does not explicitly disclose side effects, permissions, or lack thereof. For a simple getter this is minimal but acceptable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that front-loads the action and resource, with no wasted words. Every word contributes meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter, read-only tool with an output schema present, the description adequately specifies what is listed and the data fields included. No further context is needed to select or invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters, so the description is not required to explain parameters. The baseline score of 4 applies, as there is nothing to add beyond the existing empty schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'List' and identifies the resource as 'connected display monitors (outputs)', enumerating the exact data returned (resolutions, modes, scaling, focus state). This clearly distinguishes it from sibling getters like niri_get_workspaces or niri_get_layers.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when display output information is needed, but it does not explicitly state when to use this tool versus alternatives such as niri_get_focused or niri_get_windows. No exclusions or alternative tool mentions are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. The verb 'List' implies a read-only operation, and the description mentions the output contents (workspace index, names, output monitors, active status). However, it does not disclose any additional behavior such as ordering, real-time state, or potential errors. It is adequate for a simple query but not rich in context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence: 'List all workspaces in Niri DE' immediately states the action and target, followed by a compact list of output details. There is no wasted wording or redundant information, making it highly efficient for an agent to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity (zero parameters) and the presence of an output schema, the description is sufficiently complete. It tells the agent what the tool does, what it returns, and the scope (all workspaces). The output schema provides the return-value structure, so the description does not need to detail fields. No additional context is necessary for a tool of this simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so there are no parameter semantics to clarify. According to the rubric, a baseline of 4 is appropriate for 0-parameter tools. The description does add value by clarifying the output fields, which covers the 'semantics' of what the tool returns.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'List', clearly identifies the resource as 'all workspaces in Niri DE', and enumerates the returned fields (workspace index, names, output monitors, active status). This distinguishes it from sibling tools like niri_get_windows and niri_get_outputs, which target different resources or aspects.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The context of when to use this tool is implied by its purpose: it lists all workspaces. However, there is no explicit guidance on when not to use it or how it compares to alternatives like niri_focus_workspace or niri_get_windows. The description does not provide exclusion criteria or alternative recommendations, so it stops at implied usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the full burden. It explicitly states that the tool only 'queries' data, making the read-only nature clear. Mentioning nmcli adds context about the underlying mechanism, though it does not detail output structure or potential edge cases.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that immediately conveys the purpose. It is front-loaded with the verb 'Query' and contains no filler or redundant information, making it optimally concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of a zero-param read-only query tool and the presence of an output schema, the description is sufficiently complete. It does not explain return values (handled by the output schema) and does not mention any limitations, but none are evident from the schema or sibling context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the schema is trivially complete. The description adds value by naming what will be queried, compensating for the lack of parameter definitions. The baseline for no parameters is 4, which is appropriate here.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Query' and clearly identifies the resources: active network connections, Wi-Fi, and Ethernet devices. It also names the underlying command (nmcli), distinguishing this tool from sibling system utilities that focus on other domains.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for checking network status via nmcli, but does not explicitly state when to use it versus alternatives. There are no sibling network tools, so this is a minor gap; however, no exclusions or contextual triggers are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It indicates a read-only 'List' operation and clarifies the object category, but does not disclose any additional behavioral traits such as potential errors, ordering, or requirements (e.g., running Niri session). The examples add some context but the description is minimal for a tool without annotation support.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with the verb 'List' and the resource, followed by helpful parenthetical examples. Every word earns its place and there is no redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that there are no parameters, an output schema exists, and the purpose is simple listing, the description adequately covers the tool's functionality. The examples clarify the target objects, making the tool self-explanatory. It could be slightly more explicit about what counts as 'open', but the output schema likely addresses this.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, rendering the schema trivially complete. According to the rubric, a baseline of 4 is appropriate for 0 params, and the description does not need to add parameter-specific information.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (List) and the resource (open Wayland layer-shell surfaces in Niri), with concrete examples (desktop bars, panels, quickshell, notifications) that distinguish it from sibling tools like niri_get_windows. This is specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly communicates the domain (layer-shell surfaces) through examples, which implies when to use this tool versus regular window listing tools. However, it does not explicitly mention alternatives or exclusions, though the category is distinct enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It adds the detail that it uses `wl-paste`, which hints at the underlying mechanism, but it does not explicitly state that it is read-only or discuss potential failure modes (e.g., missing Wayland session). This is adequate but minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no redundant words. It effectively communicates the tool's purpose and the use of `wl-paste` in under 15 words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (no params, an output schema exists), the description covers all necessary context: what data is retrieved, the source, and the underlying command. It is fully complete for this low-complexity tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the schema captures everything. Baseline for 0 params is 4, and the description adds no parameter information but doesn't need to.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get' and the resource 'current text content from the Wayland clipboard', also naming the underlying command `wl-paste`. This exactly differentiates it from the sibling tool `arch_clipboard_set`, which presumably sets clipboard content.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: it reads the clipboard. While it doesn't explicitly mention when not to use it or alternative tools, the purpose is immediately obvious and no other tool matches this function. The clarity of the action implies the usage scenario.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden of behavioral disclosure. The verb 'Inspect' clearly signals a read-only operation, and the listed items imply no side effects. It does not explicitly state 'does not modify anything,' but for a simple inspection tool the behavior is adequately conveyed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that immediately names the action and the specific items inspected. Every word contributes to understanding; no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no parameters and an output schema is present. The description succinctly identifies all the information categories returned, making it complete for its simple scope. No additional behavior or return details are necessary given the output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has 0 parameters, so the baseline is 4. The description adds meaning by detailing exactly what aspects of shell info are inspected, which is useful context even though no parameters exist to clarify.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Inspect' and clearly enumerates the resources: user default shell, PATH environment, active desktop session, and installed terminal emulators. This clearly distinguishes it from siblings like arch_get_system_info, which likely covers broader system details.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description conveys what the tool does, implying when it would be used (e.g., when needing shell/environment/session/terminal info). However, it provides no explicit guidance on when to choose this tool over related siblings like arch_get_system_info or arch_discover_tools, and no exclusionary context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. The verb 'Retrieve' implies a read-only operation, but it does not disclose potential delays, permission requirements, or explicitly state that it has no side effects. This is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence that front-loads the verb and lists the exact data groups. There is no fluff or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that the tool has no parameters and there is an output schema, the description is complete. It names the key data categories returned and leaves return-format details to the schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and the schema already covers this completely (100% coverage). The description adds no parameter details, but the baseline for zero parameters is 4, which is appropriate here.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Retrieve') and clearly identifies the resource: Arch Linux / CachyOS system hardware overview, OS version, kernel, CPU, GPU, memory, and uptime. This distinguishes it from sibling tools like niri_get_* (window management) and arch_get_shell_info (shell-specific).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly states what the tool does, making its use context obvious. However, it does not explicitly mention alternatives or when not to use it, so it lacks explicit exclusionary guidance but still offers clear context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. The verb 'List' clearly signals a read-only operation, and the description specifies exactly what data is returned. For a simple getter with an output schema, this is adequate transparency; it could be improved by stating that it returns all workspaces' windows with no filtering.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that efficiently conveys the action, scope, and returned fields. No wasted words or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
A zero-parameter, read-only list tool with an output schema. The description enumerates the returned fields and clarifies it covers all windows. There are no side effects or parameters to describe, and the sibling context makes the tool's role clear. The description is complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the input schema is fully covered by default. Per the baseline for 0-parameter tools, the description does not need to add parameter details. The description is sufficient.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'List' and identifies the exact resource ('all open windows in Niri DE') and enumerates returned fields (titles, app IDs, window IDs, workspace IDs, focus status). This clearly distinguishes it from sibling tools like niri_get_workspaces or niri_get_focused.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage (when a full list of windows is needed) but does not explicitly mention alternatives or exclusion cases. It does not say 'for focused window use niri_get_focused' or similar, leaving some ambiguity relative to sibling getter tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It states the action (launch) and context, but does not disclose whether the process is detached, asynchronous, or returns any status. It does not mention potential errors or side effects, which is a moderate gap for a spawning tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence with no fluff. It front-loads the action and resource, then gives examples, making it concise and easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple spawn tool with one parameter, the description is quite complete: it identifies the action, the context (Niri session), and examples. An output schema exists, so not explaining return values is acceptable. Missing details about process behavior are minor for this use case.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema only defines a string 'command', but the description adds meaning by explaining it as a desktop application or shell command, and provides concrete examples like 'kitty' and 'firefox'. This significantly clarifies what values are expected.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool launches a desktop application or shell command, with specific verb 'Launch' and resource 'desktop application or shell command'. Examples are provided, and it is easily distinguishable from sibling tools that focus on windows, workspaces, or terminal-specific commands.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context (in the Niri session) and examples, making the intended use obvious. However, it does not explicitly mention when not to use it or point to alternatives, such as arch_spawn_terminal for terminal-specific launches.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses the return value (path to saved file) and target behavior, but lacks details on file location, format, potential side effects (e.g., saving to disk), or failure conditions. More insight would improve transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three concise sentences, front-loaded with the action and immediately clarifying the parameter and return value. No unnecessary text or repetition, making it easy for an agent to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter tool, the description covers purpose, parameter semantics, and return value. The presence of an output schema reduces the need to describe return details further. Minor gaps include lack of error conditions or file path behavior, but overall it is sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter 'target' is fully explained in the description: 'screen' means entire focused monitor, 'window' means focused window only. Since the schema provides no descriptions and 0% coverage, the description fully compensates and adds meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Capture a screenshot') and the resource ('on Niri DE'), with explicit target options ('screen' or 'window'). It distinguishes itself from sibling tools, none of which are screenshot-specific, by specifying its exact purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The context is clear: this tool is for capturing screenshots. However, it does not explicitly mention when not to use it or provide alternative tool recommendations (e.g., if another tool could capture differently). It provides enough context for an agent to select it for screenshot tasks.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
GitHub Badge
Glama performs regular codebase and documentation scans to:
- Confirm that the MCP server is working as expected.
- Confirm that there are no obvious security issues.
- Evaluate tool definition quality.
Our badge communicates server capabilities, safety, and installation instructions.
Card Badge
Copy to your README.md:
Score Badge
Copy to your README.md:
Latest Blog Posts
- Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)By Om-Shree-0709 on .mcpAgent IdentityOAuth 2.1
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
MCP directory API
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/oki3505F/arch-niri-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server