omarchy-mcp

by hlsitechio

Overview Schema Related Servers Score Discussions

TypeScript

Local

Server Quality Checklist

Profile completionA complete profile improves this server's visibility in search results.

Latest release: v0.1.0
Disambiguation4/5
Most tools have clearly distinct purposes with detailed descriptions, but the sheer number creates some overlaps such as window_snap vs self_window_snap and layout_swap_windows vs window_swap. While these are functionally different, an agent may struggle to pick the right one in ambiguous situations.
Naming Consistency4/5
The majority of tools follow a consistent verb_noun pattern (e.g., wifi_toggle, theme_set, window_close). Minor deviations exist, such as noun-based names like system_info and omarchy_version_info, but the style remains predictable and clear throughout the set.
Tool Count1/5
With 108 tools, this server vastly exceeds any reasonable tool count for an MCP server. Even for a broad desktop environment, the number is overwhelming and will likely lead to tool-selection errors and increased latency. The scope is far beyond the typical 3-15 tools that are considered well-scoped.
Completeness4/5
The tool set covers an impressive range of desktop operations: themes, backgrounds, windows, audio, wifi, bluetooth, notifications, plugins, and more. There are minor gaps like explicit workspace creation, but hypr_dispatch offers flexibility. Overall, the surface is quite complete for the domain, with only a few missing lifecycle operations.
Average 3.8/5 across 108 of 108 tools scored. Lowest: 2.8/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 11 commits in the last 12 weeks
- No stable releases found
- 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.json to 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 the full burden. It clarifies the input constraints (no shell strings or URLs) and the launch/focus behavior, but it does not disclose side effects, prerequisites (e.g., terminal requirements), error behavior, or what happens in edge cases. A launch/focus tool typically has non-destructive behavior, but that is not stated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that front-loads the primary action and includes a key constraint. Every word serves a purpose; there is no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 4 parameters, no annotations, and no output schema, the description is under-specified. It omits details on cwd and reuse semantics, the exact list of supported commands, and error handling or return behavior. The agent lacks enough context to make robust call decisions without consulting the schema and possibly other sources.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description mentions 'argv array' and 'exact app ID', which maps to the args and command parameters, giving some meaning beyond the schema. However, with 0% schema description coverage, it fails to explain cwd and reuse, and does not enumerate the supported commands. The agent must open the schema to understand all parameter usage, which the description should compensate for.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states what the tool does: launch a supported local TUI or focus an existing matching window, with an explicit constraint against shell strings and URLs. This is specific and avoids confusion with generic launch tools, but it does not name sibling tools, so differentiation is implicit rather than explicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use for TUIs only ('supported local TUI') but provides no explicit guidance on when to use this tool versus alternatives like launch_app or local_utility_open. No exclusions or conditions are stated, leaving the agent to infer the selection criteria.
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 must carry the full behavioral burden. It mentions the tool 'verify[ies] geometry changed', which is a useful signal, but it does not disclose side effects, whether the operation is reversible, or what happens if the target window is not found. The phrase 'locked address target' is ambiguous and unexplained, reducing transparency further.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, tightly worded sentence that front-loads the primary action and adds a behavioral verification step. It contains no filler or repetition, making it a model of conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of annotations, no output schema, and only partial parameter explanation, the description is not complete enough for an agent to confidently call the tool. It does not cover usage context, parameter semantics for all inputs, or potential pitfalls. The presence of many window-related siblings increases the need for differentiation, which is absent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must clarify parameter meaning. It only hints that 'address' is the locked target, but leaves 'match' and 'direction' unexplained. 'Direction' is obvious from the enum, but 'match' is entirely unclear. This is insufficient for safe invocation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('swap') and resource ('a tiled window with its neighbor'), and adds a unique detail about using a 'locked address target' and verifying geometry change. This is clear for a knowledgeable agent, though it doesn't explicitly differentiate from the sibling 'layout_swap_windows', which likely has a similar purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does 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 exclusions, prerequisites, or distinct scenarios (e.g., tiled vs floating windows, other swap tools like 'layout_swap_windows'). An agent must infer usage from context alone.
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 behavioral disclosure burden. It does disclose that region/windows modes require interactive selection (potentially blocking) and that 'save returns and verifies a PNG path' and 'copy writes only to the clipboard'—these are useful traits. However, it omits any behavior for the 'slurp' action and does not explain what 'smart' mode does or how fullscreen behaves. It also doesn't mention side effects (e.g., clipboard overwrite) or return values for copy/slurp, so coverage is partial.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact—two sentences—and the first sentence immediately states the primary action. The second sentence efficiently bundles mode and action behaviors. It is front-loaded and without fluff. Minor point: the phrase 'region/windows require an interactive selection' could be read as covering both modes clearly, but it's slightly ambiguous whether 'windows' refers to the 'windows' enum value or the OS windows; still, the overall structure is effective.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given only two parameters with enums, no output schema, and no annotations, the description ought to fully specify all behaviors. It covers save/copy distinctions and notes interactive selection for two modes, but leaves 'smart' and 'fullscreen' undefined and 'slurp' entirely missing. Return types for copy and slurp are not described. This is insufficient for an agent to confidently choose and invoke the tool across all valid modes and actions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must explain both parameters. It clarifies that 'region/windows' modes interactively select an area and that 'save' returns a verified path while 'copy' goes to clipboard. However, it leaves the 'smart' and 'fullscreen' modes unexplained, and the 'slurp' action is completely unmentioned. The description adds some value but does not adequately compensate for the missing schema descriptions of half the enum options.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Take a screenshot.' It also begins to distinguish modes (region/windows require selection) and actions (save vs copy), which gives the agent a concrete sense of scope. However, it never explicitly names sibling tools like capture_region_clipboard to differentiate them, so the purpose is clear but sibling separation is left indirect.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no explicit guidance on when to use this tool versus alternatives. It mentions that 'region/windows require an interactive selection' as a caution, but does not state that for a quick region capture to clipboard, one should use capture_region_clipboard, or that fullscreen/smart are the defaults for automated capture. There is no when/why routing, leaving the agent to infer usage from the enum values.
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 behavioral disclosure. It states the core action and mentions verification ('Verified with fresh geometry afterwards'), which adds a small behavioral detail. However, it does not disclose side effects, required permissions, error handling for invalid positions, or impact on other layout properties. This is insufficient for a mutating tool with zero annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no filler. The core action is front-loaded, and the verification note adds a useful detail. It is appropriately sized for the tool's simplicity, though the second sentence could be seen as slightly tangential.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no annotations and no output schema, the description is thin. It leaves unanswered questions: What happens if positions are out of range? Does it return anything? What is the 'fresh geometry' verification exactly? Given the complexity is moderate (swapping two positions), more context about error handling and expected results would be needed for an agent to call it safely.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides no descriptions (coverage 0%), so the description must compensate. It clarifies that a and b are positions in layout_order (1-based), which is crucial meaning beyond bare integer parameters. However, it does not explain the 1-20 range or behavior for out-of-bounds values. It adds key context but not completeness.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: exchange the placement order of two windows, using positions in layout_order as the identifier. It specifies the resource (grid/master placement) and the method (1-based positions). However, it doesn't explicitly name a sibling alternative, so it's strong but not at the level of differentiating itself from tools like window_swap.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no explicit when-to-use or when-not-to-use guidance. While the phrase 'by their positions in layout_order' suggests this is for layout order manipulation, it does not clarify when to prefer this over window_swap (which might swap by ID) or layout_tomaster. An agent would have to infer usage from the description alone.
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 burden. It mentions verification that the OSD opened, which implies a return status or check. The word 'safe' hints at non-destructiveness but is vague. It does not disclose side effects, permissions, or whether it blocks. This is minimal but not absent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that front-loads the core action and includes a key behavioral detail (verification). No wasted words, appropriate length for the tool's simplicity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 4 optional parameters and no output schema, the description is insufficient. It does not specify whether message and progress are mutually exclusive, the meaning of icon choices, the effect of durationMs, or the exact return value (though verification is implied). An agent would be unsure how to combine parameters or what to expect in return.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does 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 mentions 'message or 0-100 progress value', clarifying the message and progress parameters, but it does not explain icon or durationMs, nor how message and progress interact (e.g., mutually exclusive). It adds partial meaning but fails to cover the full parameter set.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool displays an Omarchy OSD either as a message or a progress value, and verifies it opened. This is a specific verb+resource combination. While it doesn't explicitly differentiate from siblings like notification_send or display_text_size, the 'Omarchy OSD' context is distinctive enough.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives, such as whether to use it over notification_send for transient on-screen feedback, or any conditions that would make it inappropriate. The description only states what it does, not when to prefer it.
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 disclosure burden. It discloses that installation is followed by verification and that enableDangerous is required, but does not describe failure handling, side effects, or permission details beyond the flag. Some behavioral context is present but incomplete.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences with no wasted words. The core action and a key prerequisite are front-loaded, making it easy to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a mutation tool with no annotations and no output schema, and the description leaves out important context like verification failure behavior, package source scope, and interaction with the system. Given the presence of related siblings, more detail would help an agent decide and call correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does 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 does not explain what 'packages' means (e.g., names, formats, sources), leaving the single parameter semantically underdefined beyond the schema pattern and length constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (Install) and resource (packages through Omarchy), plus a verification step. It clearly indicates installing packages, but does not explicitly distinguish from sibling pkg_add_aur, leaving some ambiguity about scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Mentions the prerequisite 'Requires enableDangerous' but gives no guidance on when to use this tool versus siblings like pkg_add_aur or update_system. No explicit criteria or exclusions 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 provided, the description carries the full burden of behavioral disclosure. It does reveal several behaviors: defaults to dry-run, refuses critical first-party services and active bars, and performs state verification. However, it does not explain the consequences of dry-run false, what the verification entails, or any error behaviors. It provides some transparency but leaves significant gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that packs the main action, the default behavior, and key constraints. It's efficient and avoids unnecessary filler. The structure is clean, though not perfectly ideal (e.g., the 'verify' clause could be clearer), earning a 4.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no annotations, no output schema, and 0% schema description coverage, the description needs to be thorough. It misses critical information: the meaning of 'reversible', what the verification actually reports, the response format (even if no output schema, a statement about return values would help), and prerequisites for 'discovered' plugins. The description is too sparse for an agent to call this reliably without guessing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does 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 mentions 'dry-run' explicitly (the dryRun parameter's default) but does not clarify the semantics of the required 'id' parameter beyond the schema's pattern. It implies id refers to a 'discovered' plugin, but doesn't explain how to obtain or identify it. The description adds minimal value for parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific action ('Disable a reversible local plugin') and its verification aspect ('verify catalog/bar state'), distinguishing it from sibling tools like enable or clone. However, the phrase 'reversible local plugin' is ambiguous (whether it means the plugin is reversible or the operation is reversible), and the verification is somewhat unspecific, so it doesn't fully achieve the precision of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does 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 alternatives. It does not mention plugin_local_enable or other related tools, and there is no 'Use this when...' or 'For enabling, use X instead.' The only contextual clue is the refusal of critical first-party services and active bars, which is a constraint, not usage direction.
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 does disclose two safety behaviors: paths and numeric arguments are bounded, and existing outputs are never overwritten. However, it does not mention error handling, permissions, side effects, or what happens on invalid input. While it provides some useful guarantees, it is not comprehensive for a tool that creates files.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise: two short sentences, front-loaded with the core action. It contains zero fluff and efficiently communicates the main purpose and two key constraints.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (8 parameters, no output schema), the description is severely incomplete. It fails to explain parameter meanings, expected output content, error behavior, or any example usage. An agent would not be able to call this tool correctly without additional information or external knowledge.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate, but it does not explain any of the 8 parameters (mode, trim, width, height, invert, threshold, input, output). The generic note that 'numeric arguments are bounded' adds no meaning to individual parameters. An agent cannot infer the semantics of 'trim' or 'threshold' from this description, making it critically inadequate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool converts an absolute local PNG or SVG to a new .txt file, specifying input formats and output type. It is unambiguous about the primary function and distinguishes itself from any potential sibling by the resource (image) and output (.txt).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no explicit guidance on when to use this tool versus alternatives, nor does it mention any conditions or exclusions. It implies usage for local images but does not address scenarios like remote images or other conversion tools. There is no 'when to use' or 'when not to use' context.
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 must fully disclose behavior. It clearly states what the tool does not do (URLs, shell commands, file creation, installer fallbacks) and that the file must be 'existing readable', but it does not disclose whether the editor opens asynchronously, what happens if the file is not found or unreadable, whether any modifications are allowed, or the return/result behavior. This is only partial transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the primary action, and the exclusions are efficiently packed into the second sentence. Every word adds value, and it is appropriately sized for the tool's simplicity. It earns its length without padding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that there are no annotations, no output schema, and only one parameter, the description should be nearly self-sufficient. However, it omits critical operational details: error handling for missing/unreadable files, whether the tool blocks or returns immediately, whether the editor is persistent, and any prerequisites (like the editor being configured). An agent is left guessing about failure modes and side effects.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the description does not add any meaning to the single 'path' parameter. It does not specify that 'path' must be a filesystem path, how to format it, or any constraints beyond what the schema already includes. The description mentions 'local file' but does not tie that explicitly to the parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Open'), a precise resource ('one existing readable local file'), and the method ('through Omarchy's configured editor'). It also excludes non-file inputs (URLs, shell commands) and clearly distinguishes itself from sibling tools like local_utility_open or local_tui_launch by focusing on file opening. This is unambiguous and sets it apart.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides exclusions ('No URLs, shell commands, file creation, or installer fallbacks') which implicitly define when not to use it, but it does not explicitly name alternatives or state the typical use case (e.g., 'Use this to open config files'). The usage context is implied through the title and exclusions, but the description lacks a direct comparison to sibling 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?
With no annotations, the description must disclose behavior. It states that a backup is created (implying the operation is destructive but reversible) and that 'enableDangerous' is required. However, it doesn't explicitly state that existing settings will be overwritten or that the backup is the only restore path, leaving some ambiguity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
All three sentences are short and purposeful: the first states the core action, the second adds a safety note about backups, and the third states a prerequisite. It is front-loaded and efficient with no unnecessary detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the action, the backup side-effect, and the permission gate, which is adequate for a simple tool with a single enum parameter and no output schema. However, it doesn't mention return values, post-conditions, or explicitly note that the reset is destructive (beyond implying it via the backup). Given the simplicity, this is decent but not thorough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description should explain the 'target' parameter. It merely says 'one known Omarchy configuration target' without listing or explaining the allowed enum values (e.g., 'chromium', 'hyprland'). The agent knows there's an enum from the schema but not what each value refers to, so the description adds minimal semantic value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Reset') and the resource ('configuration target'), and notes it applies to a 'known' set, hinting at the enum. However, it doesn't explicitly differentiate from the sibling tool 'omarchy_default_set', which could also deal with defaults, so it's clear but not fully distinguishing.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions a prerequisite ('Requires enableDangerous') but gives no guidance on when to use this tool versus alternatives like 'omarchy_default_set' or 'omarchy_defaults'. It doesn't state conditions or exclusions, leaving the agent to infer usage.
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 of behavioral disclosure. It does add a key behavior: it verifies shell.json afterwards, which is beyond the schema. However, it omits side effects, reversibility, permission requirements, and what happens if verification fails, leaving gaps in the safety profile.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is front-loaded with the primary action and includes the verification detail. There is no fluff or redundant phrasing; every word serves a purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one enum parameter and no output schema, the description is partially complete. It covers the core action and verification but lacks context on when to use it, potential failure modes, and behavioral expectations beyond verification, leaving an agent without full guidance.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate for parameter semantics. It only loosely references 'exact screen edge,' which mirrors the enum values but adds no new meaning or usage details. The agent gains little beyond the schema's own enum definition.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Move' and the resource 'bar', with a specific action of moving to an exact screen edge. It does not explicitly differentiate from sibling tools like bar_visibility_set or bar_transparency_set, but the purpose is unambiguous. The verification step adds specificity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does 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 prerequisites, context, or exclusions. An agent would have no indication of when to choose this over bar_visibility_set or bar_widget_move.
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 behavioral disclosure. It states that the tool moves and verifies the final location, but does not disclose what 'verify' means (e.g., whether it returns a success flag, the new position, or an error), nor any side effects like requiring the widget to exist or whether the operation is reversible. This is a significant gap for a mutation tool without annotations or an output schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, direct sentence that leads with the action and primary target. There is no extraneous information, and the core purpose is communicated efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has three required parameters, no output schema, and no annotations, so the description should fully explain behavior and return expectations. It only states the action and verification intent, leaving unclear what the verification result looks like, how errors are handled, and how the index interacts with existing widget order. For a mutation tool, this lacks critical operational context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 33% (only 'id' has a description). The tool description does not compensate for the missing parameter semantics. It rephrases 'section' and 'index' as 'exact bar section/index' but adds no detail about valid values, ordering, or relationships (e.g., whether index is relative to other widgets). The description adds minimal value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Move', the resource 'an existing widget', and the target location 'exact bar section/index', and includes verification. This is specific and distinguishes the tool from siblings like bar_visibility_set or bar_position_set, which operate on the bar itself rather than individual widgets. The word 'verified' in the title further clarifies the expected outcome.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no explicit guidance on when to use this tool versus alternatives. It doesn't mention that this is for repositioning widgets within the bar, nor does it contrast with plugin_local_enable/disable or other widget-related operations. An agent must infer usage from the tool name and schema alone.
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 for behavioral disclosure. It mentions 'persistent rfkill-aware' and 'verify the adapter state,' which hints at using rfkill and checking state, but does not explain side effects (e.g., whether this disconnects active devices, requires root privileges, or what happens if the adapter is already in the requested state). It also does not indicate whether the command is blocking or asynchronous. This is thin coverage for a state-changing 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no filler. It front-loads the key information: the command is persistent, rfkill-aware, and verifies state. Every word contributes meaning, and there is no redundant phrasing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple toggle with a single enum parameter, the description covers the core action, but it omits details that would help an agent anticipate results: what the tool returns (e.g., success status, new state), error conditions (e.g., adapter not present), and whether it affects ongoing connections. The mention of 'verify the adapter state' hints at a return value, but it is not explicit. Given the low parameter count and lack of output schema, a complete description should specify the return format and potential failures.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter is 'state' with an enum of on/off, which is self-explanatory. The schema already defines the allowed values, and the parameter name makes the intent clear. However, schema_description_coverage is 0%, and the description does not explicitly map 'on' to enable and 'off' to disable. Since the enum is obvious, the description adds little value, but it does not hinder understanding. A score of 3 reflects that the schema covers the semantics adequately, and the description doesn't need to add much.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description says 'Bluetooth power command' but doesn't explicitly state that it turns Bluetooth on or off. The tool name and title provide this context, but the description alone is somewhat vague. It clearly references Bluetooth power and mentions 'verify the adapter state,' which suggests a state-change operation. It distinguishes from siblings like bluetooth_status (read-only) and bluetooth_connect (connection management), though it doesn't name them. Overall, the purpose is clear enough but could be more explicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool vs. alternatives such as bluetooth_status or bluetooth_connect. The description does not mention prerequisites (e.g., whether Bluetooth hardware must be present) or indicate that this is the tool for toggling power. There is no mention of when not to use it. An agent has to infer that this is the toggle tool from the name and schema.
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 discloses the post-action reporting of the measured value, which is useful. However, it does not mention any side effects (e.g., permanent changes to brightness, OSD behavior, or persistence) or dependencies like permission requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that front-loads the main action and adds the reporting detail. No filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description mentions reporting a measured value, but since there is no output schema, it should clarify what that value is (e.g., brightness percentage) and any error conditions. More importantly, it completely omits explanation of the 'change' parameter, leaving agents unable to correctly invoke the adjustment portion. Completeness is inadequate for the tool's dual read/adjust capability.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has a single 'change' parameter with zero description coverage (0%), and the tool description does not explain what this parameter means or how to use it. Agents cannot infer from the description whether 'change' expects absolute values, deltas, or the enum strings 'off'/'on'. This is a critical gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description states specific verb ('Read or adjust') and resource ('brightness on the focused display'), and clarifies it reports the measured value afterwards. Clearly distinguishes from siblings like keyboard_backlight by naming 'display' and its action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides context that the tool acts on the focused display, but does not explicitly state when to use it versus alternatives (e.g., read-only vs. adjustment scenarios, or when keyboard_backlight should be used instead). No exclusions or conditions are 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?
With no annotations provided, the description carries the full burden. It mentions that an optional Files directory is 'validated and always opens a new window', which is useful, and implies focus behavior when no directory is given. However, it does not disclose failure modes (e.g., invalid directory, missing utility), permissions needed, or return behavior. It also leaves ambiguity around how 'reuse' interacts with About vs Files. This is insufficient for a tool with no 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no redundancy. The first sentence states the primary purpose and mode, the second adds the key exception for directory. Key information is front-loaded; there is no filler or repetition of schema details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 3 parameters (1 required), no output schema, and no annotations, the description lacks necessary context: error handling, prerequisites (e.g., whether About/Files must be installed), behavior when reuse=false, and interaction between directory and reuse. It covers the main happy path but omits edge cases and failure behavior, leaving agents to guess.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 33% (only 'reuse' has a description). The description adds meaning for 'directory' (validated, opens new window) and partially clarifies 'reuse' (focus existing exact-class when no directory). However, it does not explicitly explain the 'target' enum values beyond naming About and Files, which is somewhat covered by the first sentence. Given the low schema coverage, the description compensates only partially and leaves some interplay ambiguous (e.g., what happens when reuse=false and directory is absent).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: opening About or Files using local installed commands, or focusing an exact existing class. It specifies the exact targets (About, Files) and the two modes (open vs focus), which distinguishes it from generic launchers like launch_app or local_config_open. The phrase 'local installed commands' adds clarity about the mechanism.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly compare to sibling tools like local_config_open or local_tui_launch, nor provide when-to-use versus when-not-to-use guidance. It implies usage for About/Files but offers no exclusion criteria or alternative recommendations. The mention of focusing an existing class is behavioral, not guidance. Agents must infer when this is the right tool.
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 behavioral disclosure. It mentions 'safe non-sudo flags' but does not explicitly state that the operation is read-only, describe the output format, or indicate any side effects. This is insufficient for a tool with zero annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with the action verb front-loaded. Every word earns its place, and there is no redundant or filler content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter tool, the description is minimally acceptable but lacks specificity. It does not enumerate what 'debug/system information' includes, nor does it differentiate from overlapping sibling tools. Given the lack of an output schema, more detail on the expected output would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the schema coverage is trivially 100% and the baseline score is 4. The description does not introduce any ambiguity regarding parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Print' and the resource 'Omarchy debug/system information', making the tool's purpose understandable. However, it does not explicitly distinguish it from siblings like health_check or system_resource_stats, which could also provide system information.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. The mention of 'safe non-sudo flags' implies a use case for non-privileged debugging, but it lacks explicit when-to-use or when-not-to-use instructions.
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 responsibility for behavioral disclosure. It does disclose key behaviors: it preserves mute state, reports measured default before and after, and supports dry-run. However, it does not clarify the nature of a dry-run (e.g., whether it performs an actual switch or only simulates), nor does it mention side effects, reversibility, or error conditions. This is adequate but not comprehensive for a mutation-style tool with no annotation safety hints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (one sentence) and well-structured. It leads with the primary action, then adds the significant behavior (preserving mute state), then the reporting aspect, and finally the dry-run mention. It avoids unnecessary words and front-loads the core functionality. While it could be slightly more structured with bullet points, it is efficient and readable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Although this is a simple tool with one boolean parameter and no nested objects, it lacks an output schema and annotations. The description states it reports 'measured default before and after' but does not describe the format or structure of that report. It also does not define what constitutes an 'available output' or how failures are handled. Given the absence of annotation context and output schema, the description provides the main action but misses important details about return values and edge cases, making it only moderately complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has one parameter (dryRun) with a default but no description, and the description coverage is 0%. The description only states 'Supports dry-run', which does not explain the parameter's semantics—what dry-run does (e.g., simulate without changing state) or its effect on the output. The name 'dryRun' is self-explanatory to some extent, but given the lack of schema documentation, the description should clarify the behavior. It falls short of what an agent needs to understand the parameter's impact.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb ('Cycle'), resource ('audio output'), and scope ('next available'), plus a distinctive behavioral guarantee ('preserving mute state'). It also specifies the output behavior ('report the measured default before and after'). This distinguishes it from related tools like audio_device_set_default (which sets a specific device) and audio_devices (which lists devices). The purpose is unambiguous and differentiated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly state when to use this tool versus alternatives. It implies usage for cycling through outputs but does not mention conditions such as 'when you want the next output' or 'instead of audio_device_set_default'. With a large sibling list including audio_device_set_default and media_source_switch, explicit routing guidance would be valuable. The description lacks any 'when to use' or 'when not to use' cues.
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 of behavioral disclosure. It does mention that it 'verify[ies] the resulting state', which is a behavioral trait beyond a simple setter. However, it doesn't disclose side effects, permission requirements, error handling, or the format of the verified result. More transparency would be expected 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence with no extraneous words. The core action is front-loaded, followed by the verification detail. It's appropriately concise for a simple tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and no annotations, the description should specify what the tool returns (e.g., confirmation status, success message) and how errors are conveyed. It only says 'verify the resulting state' without detailing the verification outcome, error conditions, or edge cases. For a setter that verifies, this is under-specified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage for the single boolean 'enabled', and the description does not explicitly explain that true means DND on and false means off. While the name is suggestive, the description does not articulate the parameter's meaning or expected values, leaving it to inference.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Set'), the resource ('Omarchy notification silencing'), and an additional behavior ('verify the resulting state'). This differentiates it from notification_dnd_status (presumably read-only) and other notification tools. The verb+resource pair 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 Guidelines2/5
Does 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 like notification_dnd_status or notification_dnd. There is no mention of 'use this to change DND state' or any exclusions. The context implies it's for setting, but no explicit routing is given.
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 responsibility. It discloses persistence ('remember') and verification ('verify the active profile afterwards'), which are valuable. However, it does not mention potential side effects, error conditions, or what happens if a profile is unsupported on the current hardware.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, well-structured sentence with no filler. The action, persistence, and verification are all stated efficiently, and the information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple setter with a clear schema and no output schema, the description covers the core action, persistence, and verification. It lacks any mention of return values, error handling, or edge cases (e.g., unsupported profile on a given source). Given the tool's low complexity, this is adequate but not exhaustive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does 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 maps 'detected, AC, or battery' to the source parameter but does not explain the 'profile' enum values (power-saver, balanced, performance) or their implications. The agent gets enum names but no behavioral or performance context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb ('Set') and resource ('power profile') with the nuance of 'remember' and 'verify'. It distinguishes from the sibling powerprofiles_list by focusing on setting, though it doesn't explicitely name the sibling.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It implies usage for setting profiles across power sources but does not mention when not to use it or alternative tools. The context of 'detected, AC, or battery' gives some situational guidance, but no explicit exclusions or comparator 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 carries the full burden of behavioral disclosure. It says 'Resolve and verify' but doesn't explain what happens if the theme is not found, whether it is read-only, or what the return value is. There is no mention of side effects, errors, or output format. The description is too sparse to reliably inform an agent of expected 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no fluff. The main action is front-loaded, and the constraint is stated directly. Every word earns its place, making it easily parseable by an agent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and no annotations, the description is the only source of information. It does not specify what the tool returns (e.g., a path string), error behavior, or how it relates to other theme tools. Given that it resolves a directory, an agent needs to know the return format and failure modes to use it correctly. The description falls short of that.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does 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 says 'Slugs only', which aligns with the schema's pattern but doesn't add meaning beyond the pattern. It doesn't clarify what the 'name' parameter represents beyond being a slug, nor does it explain any edge cases (e.g., invalid slugs). The description adds minimal value over the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the verb 'Resolve and verify' and the resource 'local installed theme directory'. It also adds a critical constraint: 'Slugs only; no URLs, installation, or downloads.' This clearly differentiates it from sibling tools like theme_list (lists themes) and theme_set (changes theme). The purpose is unambiguous and specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear input constraints ('Slugs only; no URLs, installation, or downloads') but does not explicitly state when to use this tool versus alternatives. It doesn't say 'use this to get the directory path for a theme slug' or contrast it with theme_list. The constraints imply usage but fall short of explicit when/when-not guidance.
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 present, so the description carries the full disclosure burden. It discloses that the operation is long-running and gated, which is meaningful. However, it omits what the workflow actually changes (system packages, configs, whether a restart occurs) and what the return/result looks like — significant gaps for a dangerous mutation 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tight sentences with the time cost and gating requirement front-loaded. Zero wasted words and every sentence earns its place. Perfectly sized for what it does disclose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a heavy, gated, multi-minute mutation tool with no annotations and no output schema, this description is thin. An agent would not know the scope of the workflow, whether it is destructive/reversible, or what a successful outcome looks like. The cost and gating signals help but leave the operational envelope largely unspecified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and an empty input schema, so there is no parameter surface for the description to illuminate. The description correctly adds nothing about parameters, matching the baseline for a parameterless tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource ('Run the full Omarchy update workflow'), which clearly distinguishes it from sibling read-only tools like omarchy_version_info, health_check, and system_info that report status rather than performing updates. The purpose is unambiguous, though 'full workflow' is somewhat abstract about what exactly gets updated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides useful cost and gating context — 'can take many minutes' and 'requires enableDangerous' — which signals when it may be appropriate to invoke. However, it names no alternatives and gives no explicit when-to-use vs when-not-to-use guidance, such as checking version status first with omarchy_version_info or avoiding updates during active sessions.
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?
The description adds 'Read-only,' which is a behavioral trait beyond any annotations (since none provided). However, it doesn't disclose more about the output format or any side effects. Given no annotations, the description carries the full burden, and it covers safety but not other behaviors that an agent might need.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two short sentences that state the purpose and the read-only nature. It's front-loaded and contains no fluff, perfectly sized for such a simple tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While the tool is simple, the absence of an output schema means the description should at least hint at what is returned. It only says 'list known Bluetooth devices,' without mentioning the format or fields (e.g., names, addresses). This leaves the agent to guess the output structure. Given the lack of annotations and output schema, the description is somewhat incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does 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 doesn't need to explain any parameters, and it doesn't; this is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (list) and resource (known Bluetooth devices), and it's distinct from siblings like bluetooth_connect or bluetooth_toggle because it's about listing. However, it doesn't explicitly differentiate from other listing tools, but that's not necessary. The purpose is clear and specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance about when to use this vs other Bluetooth tools; it doesn't mention alternatives or conditions. The description is purely declarative and leaves the agent to infer when this tool is appropriate.
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 of behavioral disclosure. It implies a read-only status query but does not explicitly state that it has no side effects, nor does it mention any permissions or response characteristics. For a simple getter, this is minimally adequate but lacks depth.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that front-loads the action and target. There is no unnecessary wording, and it is perfectly sized for the simplicity of the tool. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no parameters, no output schema, and no annotations, the description should provide enough context for an agent to understand what it returns and when to use it. It states the primary outputs ('workspaces' and 'focused window') but leaves ambiguity about the exact format and scope (e.g., 'current' could mean all workspaces or just the active one). Without an output schema, more detail would be helpful.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so there is nothing for the description to clarify. The input schema is empty, which fully defines the parameter space. The description does not need to add parameter details, and the baseline for zero parameters is 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear action ('Get') and resource ('current Hyprland workspaces and the focused window'). It is specific and not a tautology. However, it does not explicitly differentiate from sibling tools like desktop_status or window_list, which may overlap in function, so it loses a point for lack of distinction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does 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 such as desktop_status, window_list, or window_focus. There is no mention of context, prerequisites, or exclusions. An agent would have to infer its appropriateness solely from the purpose.
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 behavioral burden. It clearly states the toggle action and default/target behavior. However, it does not disclose edge cases (e.g., behavior when window already in requested state, error handling for invalid address/match, or any side effects). This is minimal but acceptable for a simple toggle 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
One concise sentence that front-loads the core action, then states the default and the parameter option. No filler, and every clause contributes to usability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with two optional parameters and no output schema, the description covers the essential operation and target selection. However, given the large sibling set of window manipulation tools, it lacks differentiation guidance, and parameter semantics are underspecified. It is adequate but not complete for an agent to confidently choose this tool over similar ones.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must explain the parameters. It mentions 'address/match' as alternatives but does not define what each means or their format (e.g., regex vs. exact ID). This leaves ambiguity for the agent on which to use and how to construct it. The description adds minimal semantic value beyond the schema's bare property names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Toggle') and resource ('a window between floating and tiling'), which is clear and unambiguous. It also clarifies the default target (focused window) and the parameter alternative, distinguishing it from other window-related tools in the sibling list that focus on resizing, fullscreen, or closing.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does 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 only explains the default vs. explicit target selection, which is parameter usage, not tool selection. Among many window manipulation siblings (e.g., window_fullscreen, window_snap), there is no mention of conditions or exclusions.
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 does disclose a behavioral trait: reporting the PipeWire sink state before and after the action, which is useful. However, it does not mention any potential side effects (e.g., persistence, sink selection) or permissions. The reporting behavior is a positive addition, but coverage of side effects is incomplete.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that front-loads the core actions and the reporting behavior. Every word contributes to the meaning, with no redundant filler. It is appropriately compact for a tool with two parameters.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no output schema and no annotations, and the description fails to explain what exactly the 'report' contains (e.g., volume level, mute status). It also does not contextualize how this tool differs from closely related siblings like audio_output_switch or speaker_tuning_status. Given the tool's low complexity, this is a notable gap but not severe.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 50% (only 'step' has a description). The tool description does not add meaning beyond the schema; it repeats the action values ('raise, lower, toggle mute') already present in the enum, and does not explain 'step' further. Since coverage is moderate, the description should compensate for the undocumented 'action' parameter, but it adds no new insight, making it insufficient.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool raises, lowers, or toggles mute on output volume and reports the PipeWire sink state. It identifies the specific resource (output volume) and the action set, effectively distinguishing it from audio-related siblings like audio_sink_availability or audio_devices.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for adjusting volume, but provides no explicit guidance on when to use this tool versus the many audio-related siblings (e.g., audio_output_switch, audio_device_set_default). There are no exclusions or comparisons to alternatives, leaving the agent to infer the appropriate 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 burden. It discloses that the operation writes to shell.json ('then verify shell.json') and warns against blind toggling, which indicates a mutating action with a verification step. However, it does not detail side effects, reversibility, or failure modes, leaving some ambiguity for a write 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise—two short sentences with zero fluff. It front-loads the core action ('Set bar transparency explicitly') and adds one necessary instruction (verify). Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-boolean-parameter tool with a mutating operation, the description provides essential context (explicit setting, verification) but lacks details like return values (no output schema), prerequisite conditions, or what 'transparent' precisely changes. It is minimally complete but could be enhanced with specifics about the effect on the bar.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. It mentions 'transparent' in the context of setting transparency explicitly, which hints at the parameter's meaning but does not explicitly define true/false semantics (e.g., true = transparent, false = opaque). The parameter name is self-explanatory, so this is adequate but not thorough.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb and resource: 'Set bar transparency explicitly', which is specific and not a tautology. It also adds a secondary instruction to verify shell.json, clarifying the operation's scope. However, it does not explicitly differentiate from sibling tools like bar_visibility_set or bar_position_set, though the resource (transparency) is distinct.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'never toggle blindly' gives a warning about usage style (set explicitly rather than toggle), but it does not provide explicit when-to-use vs alternatives or exclusions. It implies the tool is for setting absolute transparency rather than toggling, which is helpful, but lacks concrete context on when to choose this tool over others.
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 behavioral disclosure. It only says 'Launch a supported desktop app via Omarchy' and mentions the URL limitation, but does not reveal what happens on success or failure, whether the launch is synchronous, what side effects occur, or what the return value (if any) looks like. For a mutation-like action, this is insufficient 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: one sentence for purpose plus a short clause for the URL constraint. It front-loads the core action and avoids any redundant phrasing. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is relatively simple (2 parameters, one enum-defined, one optional url), and the schema covers parameter details. However, the description does not clarify the expected outcome (e.g., no output schema, no mention of return values), any preconditions, or how errors are surfaced. An agent might call it correctly but not know what to expect, making it incomplete for full context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already fully documents both parameters: the app enum lists supported values, and the url parameter includes a description ('Optional URL for browser only'). The description adds no new information beyond what the schema provides—it merely restates the URL constraint. Given 100% schema coverage, the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Launch') and a resource ('supported desktop app via Omarchy'), clarifying both the action and the platform. It also distinguishes itself from sibling tools like local_utility_open by specifying 'desktop app' and restricting URLs to browsers, making its purpose 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/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives a clear context (launching desktop apps) and notes the URL constraint for browsers, but it does not explicitly explain when to choose this tool over alternatives like local_utility_open, local_tui_launch, or local_config_open. There is no 'when not to use' guidance or mention of alternatives, leaving some inference to the agent.
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 burden. It says 'Debug view', implying a non-mutating inspection, but does not explicitly state that no modifications occur. It explains the meaning of position 1 in different modes, which is useful behavioral context. However, it does not disclose output format or whether any side effects exist, leaving some ambiguity for a mutation-averse agent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences with no filler. The core purpose is front-loaded, and the positional nuance is added compactly. Every word contributes information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only debug view with no parameters and no output schema, the description adequately covers what the agent needs to understand the tool's function and the meaning of the positional indices. It could explicitly note that it is read-only, but 'Debug view' strongly implies that. Overall, complete enough 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/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the schema is trivially covered. The description adds meaning about what is returned (placement order with titles) and the significance of positions, which is beyond the empty schema. Baseline 4 for no parameters is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool shows 'the placement order (and titles) of tiled windows on the active workspace' — a specific verb (show) and resource (window order). It adds contextual detail about position meaning that helps distinguish it from a generic window listing, though it does not explicitly compare to siblings like window_list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. It does not mention 'use when you need the order' or exclude window_list, layout_mode, etc. The phrase 'Debug view' implies it is for diagnostics, but there is no explicit when/when-not guidance.
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, the description carries the full burden of behavioral disclosure. It transparently lists the actions (float, pin, resize, position) and adds that it 'verifies the result' and 'targets by address' with 'no focus stealing'. This goes beyond the basic names and provides operational details. However, it does not discuss potential side effects, error handling, or permission requirements, which would make it more complete.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise but its structure is somewhat disjointed. The phrase 'corner: tl=tr/bl=br or center' is cryptic and appears to be a shorthand that may confuse agents (e.g., 'tr/bl' suggests a range rather than a list). While it front-loads the primary action, the ambiguous notation and abrupt shift to behavioral notes reduce clarity. It is not bloated, but it could be better organized.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 5 parameters and no output schema, the description is incomplete. It explains the overall workflow but does not cover defaults (e.g., width 1300, height 900, margin 0), the meaning of 'verify the result', or what happens if the target window cannot be found. Given the complexity and the need to guide an agent on successful invocation, this level of detail is insufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 40%, with only 'pin' and 'corner' having descriptions; width, height, and margin are undocumented. The description repeats corner values ('tl=tr/bl=br or center') but adds little beyond the schema. It mentions resizing but does not explain the dimensions or margin behavior, leaving these parameters under-specified even though the description should compensate for the low schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: to float, pin, resize, and position the agent's own host window to a corner of a monitor. It explicitly identifies the resource as 'OUR OWN host window (found via PID lock)', distinguishing it from general window snapping. The verb sequence and resource make the tool's function 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/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage by focusing on 'OUR OWN host window', but it does not explicitly state when to use this tool versus alternatives like 'window_snap' or other layout tools. No direct comparison or exclusion is provided. While the context signals the intended use case, explicit guidance on when not to use it or when a sibling tool would be preferable is missing.
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 must carry the full behavioral burden. It does mention the process of resolving and verifying focus before injecting keys, and that it uses wtype. However, it fails to disclose error handling (e.g., what happens if focus verification fails), potential side effects (e.g., sending destructive keys like Ctrl+Q), or any permissions/requirements. This 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long, front-loaded with the purpose and key format, then a usage example. Every sentence adds value and there is no fluff. The structure is clean and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has three parameters and no output schema, so the description should cover parameter semantics, error behavior, and return values. It explains only the 'keys' parameter and gives a use case, but omits explanation of 'match' and 'address', what happens on success/failure, and any return information. This is insufficient for a tool of this complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is only 33% (only 'keys' has a description). The description adds valuable detail for the 'keys' parameter, explaining the format and providing examples. However, it completely omits explanation of 'match' and 'address' parameters, leaving them undefined. Given the low coverage, the description should compensate for these gaps but does not, resulting in a low score.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific capability: injecting keyboard shortcuts into any window, with the process of resolving and verifying focus first. It distinguishes itself from siblings like window_focus (which only focuses) by mentioning key injection via wtype, and provides concrete examples of valid key sequences. This makes the purpose 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/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly suggests a use case: 'For menus and TUI navigation (e.g. ctrl+p in opencode)', which gives clear context on when to use it. However, it does not mention when not to use it or contrast with alternatives such as window_focus or hypr_dispatch, so it lacks exclusions.
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 must disclose behavior, and it does disclose determinism, refusal to overwrite output, and avoidance of interactive menus. However, it does not clarify whether the original file is modified or a new file is created, what the output path is, or error handling. While useful, this is insufficient for a mutation-like tool without annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, compact sentence that front-loads the core purpose and includes two key behavioral constraints. It is efficient and wastes no words, though it could add parameter details without sacrificing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 3 required parameters, no output schema, and no annotations, this description is incomplete. It does not specify how output location is determined, what the resolution presets mean, error conditions, or any prerequisites. It is below the minimum viable level for a transcode tool that an agent must use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the tool description does not explain the meaning of 'format' or 'resolution' beyond their enum values. The input parameter is implied by 'absolute local media path', but the relationship between format and resolution (e.g., which resolutions apply to video vs. image) and what 'high' vs. 'low' mean is unclear. This leaves an agent guessing.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('transcode') and the resource ('one absolute local media path'), and it distinguishes itself from all siblings, none of which perform transcoding. The mention of 'using Omarchy' and the explicit refusals add specificity, making the purpose 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/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use it (transcoding media files) and there are no apparent alternative tools for this task among the siblings, so it doesn't need exclusion guidance. However, it does not provide explicit 'when to use' or 'when not to use' conditions, which would have earned a 5.
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, the description carries the full burden. It discloses that it updates agent state, performs before/after verification, supports dry-run, and does not invoke the install-and-launch setter. These are meaningful behavioral traits that go beyond a simple 'set' statement, though it does not discuss potential side effects or failure modes.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded with the core action, then adds key details (verification, state update, dry-run) without extraneous language. It is immediately scannable and every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While the description covers the core function, it lacks information on how the tool selects which default to set (since there are no parameters) and what the expected outcome looks like. The absence of an output schema heightens this gap, as the agent cannot infer return values or success criteria beyond the vague 'before/after verification'.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has no parameters (empty object), so the description does not need to explain parameters. The baseline for zero parameters is 4, and the description does not introduce any parameter-related confusion; it even implies that the tool operates on a broad category of defaults rather than a specific named one.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it sets defaults for browsers, editors, terminals, or coding agents, which is a specific action. However, it does not explicitly differentiate itself from sibling tools like 'omarchy_defaults' (which likely lists defaults), though the setter intent is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives. It does not mention, for example, that 'omarchy_defaults' should be used to view current defaults, or when this setter is appropriate. The description focuses on how it works, not when to choose it.
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 present, so the description carries the full burden of behavioral disclosure. It does disclose the gating requirement and the post-install verification step, which is useful. However, for a risky operation that builds and runs user-contributed AUR build scripts, it omits any warning about untrusted PKGBUILDs, failure/rollback behavior, or what happens when verification fails — meaningful gaps given zero annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with zero wasted words: purpose is front-loaded in sentence one, and the gating prerequisite in sentence two. Every word earns its place; this is appropriately sized for the information it conveys.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a system-mutating operation with no output schema and no annotations, the description covers the core contract (what, how, verification, gate) but leaves important gaps: what 'verified' means in the result, failure behavior, whether installation is atomic, and how this interacts with pkg_add/update_system. Adequate but not complete for a risky install operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% and the description gives no parameter-specific information. The single 'packages' array's semantics are only inferable from the phrase 'Install AUR packages' — an agent can guess it is the list of package names, but there is no explanation of the name format, the min/max bounds, or the unusual '@' character permitted by the pattern. With no schema descriptions, the description should compensate but does not.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (Install), resource (AUR packages), and channel (through Omarchy), plus a verification step ('then verify that all are present'). The 'AUR' qualifier clearly distinguishes this from the sibling pkg_add, which presumably handles non-AUR packages, so an agent can tell them apart.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides a clear gating prerequisite ('Requires enableDangerous') that conditions when the tool may be invoked. However, it does not explicitly contrast with the sibling pkg_add or update_system, nor state when to prefer those alternatives for non-AUR packages or system updates. The 'AUR packages' scope implies the distinction but never confirms it.
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 discloses several behaviors: it refuses collisions (doesn't overwrite), verifies discovery/activation after cloning, and defaults to dry-run (does not actually clone unless dryRun=false). However, it does not disclose what happens on failure (e.g., error behavior), what 'verified' means operationally, or whether the operation is reversible. More detail would improve transparency, but the given behaviors are meaningful.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two efficient sentences front-load the core operation (clone from packaged files) and key constraints (collision refusal, verification, dry-run default). No filler words; every clause adds information. The structure makes it easy to scan and understand quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and no annotations, the description provides a reasonable overview but leaves gaps: it doesn't specify the return value or error conditions, doesn't detail what 'verified' entails, and doesn't mention side effects beyond file creation. For a tool that performs a filesystem operation, clarifying outcomes (e.g., success/failure messages, logs) would be valuable. It is adequate but not fully complete for an agent to predict the result.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does 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 indirectly references dryRun via 'Defaults to dry-run' and implies sourceId refers to a plugin identifier, but it does not explain the format, constraints, or how it relates to the packaged files. The description does not clarify what sourceId values are valid or how to obtain them, leaving the agent to infer from the schema's pattern. This is insufficient given zero schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (clone), the resource (stock non-service UI plugin), the source (packaged files), the destination (user's plugin directory), and two key behaviors (refusing collisions, verifying discovery/activation). This is distinct from sibling tools like plugin_validate, plugin_list, and plugin_local_enable, which handle validation, listing, and enabling respectively.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context: it's for cloning stock non-service UI plugins, and it defaults to dry-run, which suggests a safe preview before committing. However, it does not explicitly state when to prefer this over alternatives (e.g., plugin_local_enable for existing plugins, or plugin_validate for checking plugin integrity). The exclusion of service plugins and the collision refusal are useful but not framed as 'use this instead of X'.
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 verification step ('verify it appears in the reminder store'), which is a useful behavioral detail. However, it does not mention error handling, success/failure signals, or side effects like whether setting a new reminder overwrites an existing one. Given the absence of annotations, more behavioral context would be expected, but the verification detail saves it from being lower.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no wasted words. It front-loads the primary action, then specifies the delay, and finally mentions the verification step. Everything present is informative and contributes directly to tool usage.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with only two parameters and no output schema, the description covers the core function but leaves gaps. It does not state what the tool returns (if anything), nor clarify interaction with related reminder tools (e.g., does it clear previous reminders?). Given no annotations or output schema, a bit more detail on return behavior or side effects would make it more complete, but it's adequate for basic invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does 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 hints at the 'minutes' parameter via 'after N minutes' and does not mention the 'message' parameter at all. Given the schema already contains the field names, the description adds minimal value: it clarifies that minutes refer to a delay, but message remains undocumented.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Set'), the resource ('notification reminder'), the delay parameter ('after N minutes'), and a distinguishing behavior ('verify it appears in the reminder store'). This differentiates it from sibling tools reminder_show and reminder_clear, which display and clear reminders respectively.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool (when you want to set a reminder), but it does not explicitly contrast with sibling tools like reminder_show or reminder_clear, nor does it mention any prerequisites or scenarios where this tool should not be used. It's adequately clear for straightforward use but lacks explicit routing guidance.
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?
The description discloses that it reports geometry before and after, which is a useful behavioral trait. With no annotations provided, the description carries the full burden of disclosure. It does not mention potential failure modes (e.g., no active overlay), reversibility of the action, or whether the resize is relative or absolute. It gives some transparency but leaves notable gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, front-loaded with the primary action, and contains no redundancy or irrelevant detail. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with one parameter and no output schema, the description is adequate but leaves gaps: it does not specify the format or units of the reported geometry, nor does it clarify prerequisites (e.g., what happens if no webcam overlay is active). The ambiguity in the action parameter also remains unresolved. Overall, it is minimally sufficient but not thorough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has a single 'action' parameter with enum values, but the description provides zero explanation of these values. No distinction is made between relative ('smaller'/'larger') versus absolute ('small'/'medium'/'large') meanings, which is ambiguous. Since schema description coverage is 0%, the description needed to compensate but did not.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb (resize), a specific resource (active screen-recording webcam overlay), and a distinct behavioral outcome (report geometry before/after). This clearly differentiates it from window_resize and other sibling 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/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage by naming the resource ('active screen-recording webcam overlay'), which suggests it should only be used during active recording. However, it provides no explicit guidance about when not to use it or alternatives, relying on the agent to infer context from the name and sibling list.
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 disclosure. It only states the action without mentioning side effects, idempotency, whether focus movement is relative, or any failure conditions. It does not contradict annotations (none exist), but it adds no extra behavioral context beyond the action itself.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with zero filler. It front-loads the core action and direction, making it immediately scannable. No unnecessary details are included, and it is appropriately sized for a one-parameter tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one enum parameter and no output schema, the description covers the essential purpose and action. It does not explicitly explain that 'neighboring' is relative to the current focus, but that is implied by the term. Given the low complexity and absence of annotations, the description is sufficiently complete, though it could briefly note that it operates on the currently focused window.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage with a clear enum description ('l=left r=right u=up d=down'). The description does not add any meaning beyond the schema, so the baseline of 3 applies. Since the schema fully documents the single parameter, this is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Move focus') and resource ('neighboring window') with a directional qualifier. It clearly differentiates from sibling tools like window_close or window_swap by specifying the focus action. The title reinforces this, and the phrase 'neighboring window' implies relative to the currently focused window, which is 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/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context (navigating focus between windows) but provides no explicit guidance on when to use this tool versus alternatives like window_swap or window_snap. There are no exclusions or conditions stated, so an agent must infer applicability from its own reasoning.
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 burden of behavioral disclosure. It discloses one key behavior: an empty result means no battery is installed. However, it does not mention whether the operation is read-only, whether it has side effects, or what the formatted output looks like. This is a minimal but useful behavioral note, given the tool's simplicity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences with no redundancy. The primary purpose is front-loaded, and the edge-case caveat is presented immediately after. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple (no params, no output schema) and the description covers its purpose and a notable edge case. However, it does not explain the format of the returned battery status or any potential prerequisites (e.g., whether a battery must be present). For a status tool among many similar siblings, this is adequate but not exhaustive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the schema provides no parameter documentation. The description does not need to compensate for parameter coverage. Baseline for 0 params is 4, and the description doesn't introduce any misleading parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Return') and the resource ('Omarchy's formatted battery status'). It distinguishes itself from sibling status tools like wifi_status and bluetooth_status by explicitly targeting battery. The verb and resource are 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 Guidelines2/5
Does 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 conditions, alternatives, or exclusions. For a simple status query, usage is implied but not stated explicitly, leaving the agent to infer when this is appropriate.
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, the description must carry the behavioral burden. It discloses that the operation is non-blocking ('without blocking the MCP request'), that the result is copied locally to the clipboard, and crucially that the content is 'not returned to the model'. These are key safety and privacy-relevant behaviors. However, it does not specify the return value on success, failure, or cancellation, leaving some gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long, front-loaded with the primary action, and contains no redundant information. Each statement earns its place: the launch behavior, the non-blocking nature, the local copy, and the privacy note.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter tool with no output schema, the description is mostly complete: it explains the action and that the content is not returned. But it leaves the agent guessing about what the tool actually returns (e.g., a status or nothing) and what happens on user cancellation. This ambiguity could affect how the agent handles the response.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already provides the enum values 'text' and 'qr'. The description adds meaning by tying 'text' to OCR and 'qr' to a 'sensitive QR value', which is helpful. However, it does not explicitly state that the 'kind' parameter selects between these two modes, and the schema alone would already convey the allowed choices.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'Launch Omarchy's interactive region selector' and specifies the resource: capturing text or QR codes to the clipboard. It distinguishes itself from sibling tools like capture_screenshot by explicitly mentioning OCR and QR values. The purpose is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not provide any guidance on when to use this tool versus alternatives such as capture_screenshot. It implies an interactive selector that requires user input, but there is no explicit mention of when to prefer this over other capture methods or about prerequisites. No exclusions or alternative routing 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 present, so the description carries the burden. It explicitly labels the operation as a read and mentions using only local predicates and kernel state, implying non-destructive and self-contained behavior. However, it does not disclose the return format, whether results are aggregated or per-item, or any potential performance implications.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, well-structured sentence that front-loads the purpose. It lists the scope compactly and includes the technical constraint ('using only local Omarchy predicates and kernel state') without waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no parameters and no output schema, the description covers the main purpose but leaves out key details: what exactly is returned (aggregate readiness, per-item status, booleans?), and how an agent should interpret the result. It also does not clarify the relationship to more granular sibling tools, which is relevant for correct usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the baseline is 4. The description appropriately omits parameter details since none exist. It does not need to add anything beyond the schema, which is already trivially complete.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Read') and lists the concrete resources it covers (battery/power, external-monitor, backlight, hybrid-GPU, hibernation readiness). This clearly distinguishes it from sibling tools like battery_status or brightness_display, which focus on individual aspects.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. There are numerous sibling tools that overlap (battery_status, powerprofiles_list, brightness_display, etc.), but the description does not mention any selection criteria or 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 bears full responsibility for disclosure. It mentions the syntax constraints ('Expression must start with 'hl.' and only use the safe allow-listed charset'), but it does not describe the behavioral implications of dispatching, such as potential side effects, error handling, or whether the operation is read-only or mutating. The term 'dispatcher' implies execution, but the description lacks clarity on outcomes.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two sentences that deliver the core purpose, a critical constraint, an example, and a target audience. There is zero fluff, and the key information is front-loaded. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's generic nature and single parameter, the description is minimally adequate but lacks details on return values, error behavior, and how to construct valid expressions beyond the single example. The absence of an output schema increases the need for explanation, but the description does not cover what the agent should expect from a successful dispatch. It is sufficient for a power user but incomplete for a cautious agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides only a name and minLength for 'expression', with 0% description coverage. The description partially compensates by providing a concrete example ('dsp.focus({ monitor = '+1' })') and imposing additional constraints (must start with 'hl.', safe allow-listed charset). This adds meaning beyond the schema, but it does not fully elaborate on the full range of accepted expressions or the Lua API structure.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Run any Hyprland dispatcher via the Omarchy Lua API.' It uses a specific verb ('Run') and identifies the resource ('Hyprland dispatcher'). While it doesn't explicitly differentiate from siblings, no sibling has a similar generic purpose, so it appears unique. The example further clarifies the intent.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use it: 'For power users / creative layouts.' It implies a niche use case but does not explicitly state when not to use it or mention alternatives. Since there are no directly related siblings, this level of guidance is adequate.
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 carry the full burden of behavioral disclosure. It does state that it 'switches' the active workspace and mentions that it 'Returns the layout's own confirmation,' but it does not elaborate on side effects, reversibility, or any prerequisites. The phrase 'layout's own confirmation' is vague and leaves the return format unspecified. This is acceptable for a simple tool but lacks the depth expected 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences totaling roughly 45 words. The primary action is front-loaded, followed immediately by the mode definitions, and the return behavior is stated in the second sentence. There is no fluff or redundancy; every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one parameter, the description covers the core usage and return behavior. However, it does not specify the exact format of the confirmation or mention potential errors or edge cases. Given the lack of an output schema and annotations, an agent might need additional context to handle unexpected responses. The description is adequate but not exhaustive for a tool in a large sibling set where branching behavior could matter.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate for the parameter. It does so effectively by explaining the two allowed values: 'grid' and 'master' with detailed parenthetical descriptions. This adds meaning beyond the raw enum and helps an agent understand the semantic impact of each choice. The parameter name 'mode' is self-evident, and the description fully covers its meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: switching the active workspace between the two layout modes 'grid' and 'master'. It describes each mode in concrete terms (deterministic row-major cells vs. first window full-height left column), making the action unambiguous and distinct from other layout-related siblings like layout_togglesplit or layout_grid.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains what the tool does but gives no explicit guidance on when to use it versus alternative layout tools. Sibling tools such as layout_grid, layout_tomaster, and layout_togglesplit exist, yet the description does not mention them or specify conditions that would favor one over another. The usage context is implied (when you want to switch between grid and master), but no exclusion criteria or alternative recommendations are provided.
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 behavioral burden. It discloses that the tool is safe (title), returns an ID, and intentionally disables clicking, remote images, and arbitrary notify-send options. This is valuable, though it does not mention any side effects like persistence or blocking behavior. Overall, it gives a clear safety profile without contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no filler. The first sentence front-loads the core purpose and return value; the second lists exclusions. Every word serves a purpose, 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.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Without annotations or an output schema, and with sparse parameter descriptions, the definition is incomplete. It does not explain the meaning of glyph or urgency, nor does it mention that the returned ID could be used with notification_dismiss or notification_time. The safety exclusions are useful, but an agent still lacks enough context to confidently craft a correct call beyond the required headline.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is only 25% (only headline has a description). The tool description adds no parameter-level meaning for glyph, urgency, or description. The unsupported-features note hints at safety but does not explain what each parameter controls. Given the low coverage, the description fails to compensate, leaving parameter semantics largely inferred from names and types.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action (send), the resource (local desktop notification), and the return value (daemon-assigned ID). It also explicitly lists what is unsupported, distinguishing it from more permissive notification tools. The title reinforces the safe scope, making the tool's purpose 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/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this is for sending local notifications, but it does not explicitly point to alternatives like notification_dismiss or osd_show, nor does it state when not to use this tool. The unsupported features give some guardrails, but there is no clear 'use X instead' guidance for other notification-related sibling 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?
With no annotations, the description carries the burden of disclosure. It does disclose two key behaviors: it starts a non-interactive recording and verifies the recorder process. It also states it never opens a region picker. However, it omits other behavioral context such as prerequisites (e.g., whether a recording is already active), side effects on existing recordings, or permission requirements, making it incomplete.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no redundancy. The core purpose and key behavioral constraint are front-loaded, and every word adds value. It is an exemplary model of concise, clear description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 6 parameters, no output schema, and no annotations, the description is far too sparse. It does not explain what the return value represents, how parameters interact, or any preconditions. An agent would struggle to use it correctly without additional context, making it inadequate for its complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 17%, so the description must compensate by explaining parameter meanings. The description does not mention any parameter (webcam, resolution, audio, etc.). It only describes the tool's overall action, leaving the agent to guess what each parameter does from names and defaults alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Start'), a clear resource ('full-screen recording'), and adds a distinctive constraint ('non-interactive', 'Never opens a region picker'). This cleanly separates it from siblings like capture_screenshot or capture_region_clipboard without needing to inspect schemas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly states what the tool does NOT do ('Never opens a region picker'), which is an exclusion that guides an agent toward this full-screen, non-interactive tool versus region-based alternatives. However, it does not explicitly name the alternative tools or state when not to use it, so it falls short of a 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?
With no annotations, the description must carry the full behavioral burden. It discloses the multi-step process (float, pin, resize, position, verify) and the targeting methods (address or substring match). However, it does not disclose potential failure modes, reversibility, or side effects on the window's state (e.g., whether it persists across sessions). Verification is mentioned but not what happens on failure. Thus it covers core behavior but lacks depth.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences (plus an example) with no unnecessary words. The action is front-loaded, the targeting method is explained, and the default size and a usage example are provided. Every sentence adds value and is easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an 8-parameter tool with no output schema and no annotations, the description covers the core purpose and gives an example, but it does not explain the margin parameter, the effects of pin (beyond the schema description), or behavior when the window is not found. The default size hints at width/height, but corner values and margin semantics are left to the schema (which lack descriptions). While the example reduces some ambiguity, the tool complexity suggests more context would be beneficial.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 50% (pin, match, address, monitor have descriptions; width, height, corner, margin do not). The description adds meaning for match (substring, example 'chrome') and corner (via example 'br'), and clarifies default size (1300x900) which informs width/height defaults. However, it does not elaborate on width, height, margin, or the corner value meanings themselves. It partially compensates for the missing schema descriptions but leaves the numeric parameters underexplained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'Float + pin + resize + position ANY window to a corner of the focused monitor, then verify on-screen.' It specifies the verb (snap/position), resource (any window), and the precise outcome (corner of focused monitor). It also distinguishes from the sibling self_window_snap by targeting ANY window, and provides a concrete example that clarifies the use case.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives a clear usage example (launch_app then window_snap) implying when to use this tool for positioning a window. However, it does not explicitly state when NOT to use it or mention alternatives like window_resize or window_float_toggle for simpler operations. The context is clear but exclusionary guidance is absent.
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 discloses that the tool writes to disk and verifies the change, which is useful. However, it does not mention permissions, reversibility, or side effects. Given the mutation nature, this is a moderate gap, not severe.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence that conveys the action and verification step without any wasted words. Ideal conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has a single simple parameter and no output schema. The description explains the action and a side-effect (verification), which is sufficient for an agent to call it correctly. No missing critical information for a straightforward setter.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema only defines a boolean 'visible' with no description (0% coverage). The description explicitly maps the parameter to show/hide, giving it clear semantics. This fully compensates for the missing schema description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: to show or hide the bar and verify the on-disk flag. This is specific to the bar's visibility and distinguishes it from sibling tools like bar_state (which likely reads state) and bar_position_set/bar_transparency_set (which modify other attributes).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives. The description implies it is a setter, but does not mention bar_state or other bar-related tools, nor any conditions for choosing this tool over them.
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 burden of behavioral disclosure. It discloses that set/reset supports dry-run and verifies every queryable post-state, which is valuable. However, it does not clarify what 'preview' does, whether read/preview have side effects, or any permission/authorization needs. This is partial but not comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the primary actions and resource, and the second sentence adds relevant detail about dry-run and verification. No filler or redundancy; each sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool supports multiple actions (read, preview, set, reset) with zero parameters, which is ambiguous: how does 'set' work without parameters? The description does not explain the mechanism (e.g., interactive prompt, default values, external config). With no output schema or annotations, the agent is left guessing about return values and side effects. This is a significant gap for a multi-action tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are zero parameters, and schema coverage is trivially 100%. Per the baseline for 0-parameter tools, the description does not need to explain parameters. It adds no parameter semantics, but since there are none, this is acceptable and the baseline score of 4 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description specifies concrete actions (read, preview, set, reset) on a specific resource (Omarchy's coordinated shell/GTK/terminal text size). This clearly distinguishes it from related font tools (font_set, font_list) which deal with fonts rather than text size. The verb+resource combination is precise.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage (for adjusting text size) but does not explicitly state when to use this tool versus alternatives or any exclusions. There is no mention of when not to use it, nor does it reference sibling tools. Guidance is minimal and left to inference.
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 of behavioral disclosure. It implies a read-only listing operation, but does not explicitly state that it has no side effects, nor does it mention return format or any constraints. For a zero-parameter list tool, the minimal description is somewhat 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, extremely concise, and the core action 'List' is front-loaded. Every word earns its place, with no fluff or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (zero parameters, no output schema), the description is complete enough. It specifies the exact scope (monospace fonts, terminal/UI in Omarchy). While it does not detail the output format, that is not critical for a list-only tool and is a minor gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and schema coverage is 100% trivially. Since there are no parameters, the description does not need to add parameter details. The baseline of 4 is appropriate because there is nothing missing.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific action 'List' with the concrete resource 'monospace fonts available for the terminal/UI in Omarchy'. It clearly differentiates from siblings like theme_list (theme fonts) and font_set (set a font), avoiding ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does 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 such as font_set. While being a list operation is implicitly useful before setting a font, the description does not explicitly state that relationship or any exclusions.
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, the description must carry the behavioral burden. It explicitly states the operation is read-only ('Read', 'without changing it'), which is the key behavioral trait. It also provides a concrete semantic detail ('Idle enabled means normal idle behavior is allowed') that adds value beyond a generic read. It does not cover output format or errors, but for a simple non-destructive read, this is reasonably 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no filler. The primary purpose and read-only nature are front-loaded in the first sentence, and the second sentence adds a relevant, specific nuance about the 'idle' feature. Every word earns its place; the description is clear and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and no annotations, the description should convey what an agent can expect. It states a 'normalized enabled/disabled state' but does not specify the return format (e.g., boolean, string, enum) or any edge-case behavior. For a simple read tool with one enums parameter, this is adequate but leaves the response format open. A short note on the return value would make it complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description needs to compensate. It mentions 'an allow-listed Omarchy feature' which refers to the 'feature' parameter, but it does not elaborate on the parameter's meaning, the allowable values (though the enum in the schema covers that), or the implication of 'normalized' state. The description adds almost no parameter-specific semantics beyond what the schema already provides via the enum list.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Read') and clearly identifies the resource ('normalized enabled/disabled state for an allow-listed Omarchy feature') while explicitly stating it does not change anything. This distinguishes it from mutation tools like toggle_feature and omarchy_default_set, and from version info siblings, so the purpose is unambiguous and non-tautological.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'without changing it' implies this is for querying rather than mutating, and the contrast with the sibling toggle_feature is implicit. However, the description does not explicitly state when to use this tool versus alternatives (e.g., 'use this to check status before toggling') or mention any prerequisites. Guidance is present but largely inferred.
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 explicitly states 'Read-only,' which is a key behavioral trait for a status tool and signals non-mutation. However, it does not disclose potential error conditions, output format, or whether it might return partial data (e.g., if service is not installed). For a simple read, 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, tightly worded sentence that front-loads the action ('Read') and the specific state components. No filler or redundancy; every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite lacking an output schema, the description enumerates the specific state dimensions (installation, service, virtual-sink, default-sink, hardware-match), giving the agent a clear picture of the returned information. It does not explain terms like 'hardware-match' or describe output format, but for a status read tool this is reasonably complete given its simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and the schema is trivially 100% covered. Per the baseline rule for 0-parameter tools, a score of 4 applies. The description adds no parameter details because there are none to explain; this is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Read') and a precise resource ('Omarchy speaker-tuning ... state') while enumerating the exact components (installation, service, virtual-sink, default-sink, hardware-match). This clearly distinguishes it from sibling tools like audio_sink_availability or hardware_readiness, which focus on different aspects.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does 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. There are many related status tools (e.g., audio_sink_availability, hardware_readiness), but the description does not mention conditions or exclusions. The agent must infer its use case from the resource name alone.
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 must disclose behavioral traits. It states that the tool mutates state (switches background) and reports the resulting path. However, it omits potential side effects (e.g., whether the change persists, whether it wraps around, or what happens if no next background exists). The basic behavior is clear, but some transparency is missing.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence that front-loads the action and result. There is no wasted wording, and the structure is clear and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no parameters and no output schema, the description is mostly complete. It conveys the core action and the return value. However, it does not specify what happens if there is no next background (e.g., an error or no-op), which could leave an agent uncertain in edge cases. Given the simplicity, this minor gap is acceptable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the description does not need to explain parameter meanings. The baseline for 0 params is 4, and the description appropriately adds no unnecessary parameter detail. The action is self-contained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Switch to the next background'), the scope ('for the current theme'), and the output ('report the resulting path'). This is a distinct, actionable purpose that differentiates it from sibling tools like theme_set or background_set_local.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no explicit guidance on when to use this tool versus alternatives. It does not mention when to avoid it, nor does it contrast with tools like background_set_local or theme_list. The usage is implied by the name and description but not articulated.
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. The verb 'List' clearly implies a read-only operation. However, it does not disclose return format, ordering, or potential error handling (e.g., if no themes exist). It provides minimal behavioral context beyond the action itself.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence with zero filler. It immediately states what the tool does and nothing more. Perfectly concise for a zero-parameter list operation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter list tool with no output schema, the description is mostly sufficient. It does not clarify the nature of the returned items (e.g., names, identifiers, metadata), but given the simple scope, the basic description is adequate for an agent to call it. Slightly more detail on output would push it to a 5.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Zero parameters exist, so the baseline is 4 according to calibration. The description correctly avoids redundant parameter details. No added value is needed for parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('list') and resource ('all available Omarchy themes'). It clearly distinguishes itself from sibling tools like theme_current (which shows the current theme) and theme_set (which applies a theme). The phrase 'all available' clarifies breadth.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides no guidance on when to use this tool versus alternatives like theme_current or theme_set. It does not mention that this tool is for discovering options while other tools handle inspection or application. No exclusions or context are given.
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, the description carries the full burden of behavioral disclosure. It explicitly warns that turning off 'may disconnect the MCP client,' a critical side effect. It also mentions that it 'verify[ies] the radio state afterwards,' adding behavioral context beyond the simple action. The description does not cover idempotency or error cases, but for a simple toggle this is sufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, both immediately informative. The main action is front-loaded, and the side-effect warning is placed clearly. No filler or redundant content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter toggle with no output schema, the description covers the core action, the verification step, and a critical side effect. It does not specify the exact return format, but the hint of verification implies a state report, which is adequate. Overall complete enough for an agent to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, so the description must compensate. The single parameter 'state' has an enum of on/off, and the description repeats 'on or off' without explicitly mapping to the parameter or explaining any subtleties. The values are self-evident, so the description adds only marginal meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Turn Wi-Fi on or off') and the resource (Wi-Fi radio), and adds a verification step that makes the purpose even more specific. It is easily distinguishable from sibling tools like wifi_status or wifi_list based on the clear verb-resource pair.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus related siblings such as wifi_status, wifi_list, or wifi_connect. The description does not mention alternatives or exclusions, leaving the agent to infer usage solely from the name and generic descriptions.
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 behavioral burden. It discloses that it toggles fullscreen/maximized and uses the focused window by default, but it leaves ambiguity about whether 'toggle' means switching between states or setting a specific mode, and it doesn't state behavior when no window is focused or how address/match interact. Partial 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that front-loads the purpose and includes only the essential targeting info. No wasted words, perfectly structured for quick comprehension.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no annotations and no output schema, the description is markedly incomplete. It omits critical details like the exact semantics of address vs match, what happens if no window is focused or found, and whether the mode sets or toggles state. These gaps make it hard for an agent to call correctly in edge cases.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does 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 mode parameter ('fullscreen (real) or maximized (fake)') and that address/match are for explicit targeting, but it doesn't define their formats, precedence, or difference. This is a partial compensation but leaves the agent guessing on key parameter details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Toggle') and the resource ('fullscreen/maximized') with a helpful qualifier ('real vs fake'). It also explains default targeting ('Defaults to the focused window') and an alternative explicit target. This distinguishes it from sibling window tools like window_snap or window_resize, making the purpose immediately clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides clear usage context: defaults to focused window and that address/match can target a specific window. However, it doesn't mention when not to use this tool or name an alternative among the many window-related siblings, so it stops short of explicit routing guidance.
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, the description carries the full burden of behavioral disclosure. It explicitly states 'Read-only', which is a key transparency point indicating no state modification. However, it does not elaborate on what happens when the cache is missing, outdated, or how 'verify' manifests in the result (e.g., return format). The explicit read-only declaration is strong, but more detail would be safer.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences with no filler. It front-loads the action ('Verify') and immediately scopes it to the current theme's cache, then adds the read-only flag. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Without an output schema, the description should compensate by explaining what the tool returns or how the status is represented. It states what is checked (rows, source signature, generated files) but does not describe the output shape, status codes, or interpretation. While it is a low-complexity tool with no parameters, the missing return-value semantics leave some ambiguity for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters, and schema description coverage is trivially 100%. Per the baseline rule for no-parameter tools, a score of 4 is appropriate because the description does not need to add parameter-specific semantics. No parameter-related information is missing.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action (verify), the resource (current theme's background thumbnail cache), and the objects checked (rows, source signature, generated files). It distinguishes itself from build-type siblings like 'background_thumbnail_cache_build' by emphasizing read-only verification, so an agent can differentiate it 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 Guidelines2/5
Does 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 its alternatives. The description does not mention related tools like 'background_thumbnail_cache_build' or 'background_set_local', nor does it advise on conditions (e.g., 'Use when you only need to check cache status without modifying it'). The implication of 'verify' and 'read-only' is present but not 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 provided, so the description bears the full burden. It discloses that the tool mutates state ('Change') and that it triggers a verification step. However, it does not mention side effects, permission requirements, error handling (e.g., invalid font names), or whether the change persists. This is minimal coverage 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
One concise sentence that is front-loaded with the core action, then the source and verification. Zero filler, every word is functional.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given one parameter, no output schema, and no annotations, the description covers the essential flow but omits return value expectations and error conditions. The reference to font_list and font_current provides context, yet an agent is left to infer what happens on success or failure. This is a simple tool, so the gap is moderate but acceptable at a baseline level.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already provides 100% coverage with the parameter description 'Font name from font_list'. The tool description reinforces this by saying 'using a value from font_list', which adds a bit of procedural context but does not introduce new semantics beyond the schema. Baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description states a specific verb 'Change', the resource 'Omarchy's font', and the source of valid values ('from font_list'). The verification step is also mentioned, clearly differentiating this from font_list (listing) and font_current (checking). The title adds the 'UI' context, making the purpose 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/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies a workflow: obtain a value from font_list, then set the font, then verify with font_current. This gives the agent a clear sequence and signals the dependence on font_list for valid names. However, it does not explicitly state when not to use this tool (e.g., 'use font_current to view, font_list to list'), so it misses explicit exclusions.
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 full burden of behavioral disclosure. It proactively states that mutations are 'bounded' with measurement and rollback if the expected level isn't observed, and mentions dry-run support. This gives agents a clear safety profile, though it doesn't cover return formats or failure modes beyond rollback.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with no verbosity. The primary purpose is front-loaded, and the second sentence efficiently adds critical behavioral details (bounded mutations, dry-run). Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (no params, no output schema, no annotations), the description covers basic functionality and safety but leaves gaps: the exact action taken on 'adjust' without a parameter, the return value of a read, and any preconditions beyond 'detected'. More detail would improve completeness, especially for an agent without structured fallback.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero properties and 100% schema description coverage, so a baseline of 4 applies. However, the description fails to clarify how the tool behaves with no parameters—specifically, how 'adjust' is enacted without a target level. Does it toggle, cycle, or use a default? This ambiguity reduces the score below baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool's purpose: reading or adjusting a keyboard-backlight LED. It uses specific verbs ('Read or adjust') and a specific resource ('detected keyboard-backlight LED'). This distinguishes it from sibling tools like brightness_display or audio_volume, which target different hardware.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage (controlling keyboard backlight) but offers no explicit guidance on when to prefer this tool over alternatives. There are no exclusions, comparisons, or conditions mentioned, leaving the agent to infer applicability from the name and sibling 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 zero annotations, the description carries the full disclosure burden. It discloses the primary side effect (overrides grid dimensions on the workspace) and the revert behavior for omitting both params. But it stays silent on what happens to existing windows/cells when the grid is forced, whether the change is persistent or transient, and what occurs when only one of cols/rows is passed. Adequate core disclosure, missing mutation detail.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no waste. The action and example are front-loaded; the reset instruction follows immediately. Every clause earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple 2-param mutation tool with no annotations and no output schema, the description covers purpose and the all-or-none reset. The notable missing piece is partial-parameter behavior (single col or single row), which an agent would likely attempt. Slightly under-specified for a mutation with zero annotation backing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does 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 'C x R' and '4x4' framing maps implicitly to cols=rows, but the description never names the parameters and leaves a key semantic gap: behavior is defined only for 'both provided' and 'both omitted.' What passing only cols with rows omitted does is undocumented in both schema and description. Partial compensation, clear gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('force an explicit C x R cell grid') applied to a concrete resource ('the active workspace') with a worked example (4x4). The C x R framing directly ties to the cols/rows parameters, and the tool reads as distinct from siblings like layout_mode, layout_togglesplit, and layout_order. Purpose is 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/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Conveys the clear trigger for use — forcing a fixed grid — and gives a reset path ('omit both to return to aspect-aware auto sizing') that doubles as a when-not. However, it names no sibling alternatives (e.g., workspace_layout, layout_preselect, agent_grid) and gives no explicit exclusion of when another layout tool should win. Clear context without formal exclusions places it at 4.
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 full responsibility for behavioral disclosure. It correctly implies a read-only search operation but does not mention any side effects (none expected), return format, pagination behavior, or how the catalog is structured. It adds minimal behavioral context beyond the obvious 'search' action, so a 3 is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, direct and front-loaded. The first sentence states the core function with no waste, and the second gives a practical reason to use it. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description explains the purpose and use case but does not specify what the returned data looks like (no output schema). Since this is a search tool with three optional parameters, an agent might benefit from knowing whether it returns matching command names, full details, or only routes/arguments. The mention of 'machine-readable' hints at structured output but leaves details ambiguous. Overall, adequate but with a notable gap in expected return shape.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 67%: group and query have descriptions, but limit does not. The description adds no parameter-specific detail, so it does not compensate for the missing limit description. However, the schema already provides reasonable context for the two documented parameters and the limit's constraints (default, min, max) are self-explanatory. Description adds little value beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'search' and the resource 'machine-readable command catalog from the installed Omarchy version', which distinguishes it from sibling tools like theme_list or wifi_status. It also ties the purpose to a concrete use case (discovering routes/arguments before adding/troubleshooting wrappers), making its role 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/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear use scenario ('before adding or troubleshooting a wrapper') that implies when to invoke this tool. It does not explicitly name alternative tools or state when not to use it, but given its unique search functionality among the many siblings, the guidance is effective for an agent to decide to use it.
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 full burden of disclosing behavior. It explicitly states that symlink roots are rejected and that nothing is installed or downloaded, which signals side-effect freedom and a specific constraint. However, it does not describe the return format (success/failure indication, error messages) or validation criteria beyond schema compliance, so transparency is good but not exhaustive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences with no waste. The primary action is front-loaded, and the additional behavioral details (symlink rejection, no install/download) are concise and valuable. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple single-parameter tool with no output schema, the description covers the essential purpose and side effects. However, it omits any indication of the result format (e.g., validation errors, exit codes) or what constitutes a successful validation. Given the lack of annotations, a slightly richer description (e.g., 'returns a list of schema violations') would be more complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter 'folder' already has a 100% schema description ('Absolute path or path relative to the MCP server working directory'). The tool description adds 'local plugin folder', which is redundant with the schema. It does not provide additional meaning or usage details beyond what the schema offers, so it meets the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('validate'), a concrete resource ('local plugin folder'), and the target ('Omarchy's manifest schema'). It is clearly distinct from sibling tools like plugin_list or plugin_local_enable, which have different purposes (listing, enabling, etc.). No 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/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states what the tool does but gives no explicit guidance on when to use it versus alternatives or when not to use it. Context is implied: validation is likely a pre-check before enabling or modifying a plugin, but that linkage is not stated. It does not mention exclusions or alternative 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?
With no annotations, the description carries the full burden. It discloses that the tool uses specialized toggle routes and verifies final state, which adds some behavioral insight beyond a simple toggle. However, it does not mention side effects, error conditions, reversibility, or prerequisites (e.g., permissions, availability of Omarchy 4). For a mutation tool, this is a moderate 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with no fluff. The action and resource are front-loaded, and the second sentence adds relevant behavioral context. Every clause earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple (two enums, no output schema), and the description covers the core action and verification. However, it does not specify what the tool returns (e.g., final state, confirmation, error) or how errors are handled, which an agent would need for correct invocation. Since annotations are absent and there is no output schema, this is a notable gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does 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 lists the three features and the toggle/on/off states, which maps directly to the enums in the schema. It adds context that these are Omarchy-specific and mentions 'specialized toggle routes', but it does not explain default behavior (e.g., default state is toggle, which is in the schema) or provide additional semantics beyond the enum names. It adds some value but mostly restates the structure.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action (toggle/enable/disable) applied to a specific resource (nightlight, screensaver, suspend availability) and adds a distinguishing detail ('Handles Omarchy 4's specialized toggle routes and verifies final state') that separates it from generic toggles like wifi_toggle or mic_mute_toggle. An agent can immediately recognize the scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly scopes the tool to three named features, which implies it is the right choice for those and not for wifi/bluetooth or other toggles. However, it does not explicitly name an alternative or state a 'when not to use' condition, leaving the agent to infer based on sibling names. This is clear context but lacks explicit exclusions.
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 tool is 'read-only', which is a key behavioral trait and adds value beyond the schema. However, it does not mention any other aspects like permission requirements or response format, which could be relevant but are not critical for a simple status query.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that states the action first, followed by the read-only clarification. Every word earns its place, with no redundancy or wasted effort.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only status tool with no parameters and no output schema, the description adequately covers what it reports and its side-effect-free nature. Nothing critical is missing for an agent to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and the schema is empty (coverage 100% but trivially so). Per instructions, a baseline of 4 applies for 0 parameters, and the description correctly omits any parameter details since there are none to explain.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'report' and the resource 'Wi-Fi radio state and active Wi-Fi connection names', making its purpose specific and easily distinguishable from sibling tools like wifi_toggle, wifi_list, and wifi_connect.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance is provided on when to use this tool versus alternatives. While the purpose is clear, the description does not mention alternative tools or conditions for choosing one over another, leaving this to the agent's inference.
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?
Despite having no annotations, the description explicitly declares 'Read-only' which clearly signals a non-mutating operation. It also discloses that it respects 'Omarchy speaker-tuning exclusions', which is a specific behavior that filters results. This adds meaningful transparency beyond a bare 'list sinks' description, though it does not detail what the exclusions are or how they are applied.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that front-loads the action and resource, then adds the availability attribute and the exclusion qualifier. Every word earns its place; there is no fluff or repetition of the tool name. It is an exemplar of conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only listing tool with no parameters and no output schema, the description is largely complete: it states what is listed (sinks), what about them (port availability), and adds the filtering context (exclusions). It does not describe the return format or list the exclusions, but these are minor for a tool of this simplicity. The 'read-only' remark covers safety.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so the schema is empty and there is nothing for the description to clarify. According to the rubric, a baseline of 4 is appropriate for parameterless tools. The description does not introduce any parameter-related confusion.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('List'), a clear resource ('local PulseAudio/PipeWire sinks'), and the key attribute ('whether their ports are available'). It also adds a distinctive qualifier ('respecting Omarchy speaker-tuning exclusions') that differentiates it from generic audio device listing tools. This is precise and immediately understandable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no explicit guidance on when to use this tool versus its numerous audio-related siblings (e.g., audio_devices, speaker_tuning_status, audio_output_switch). The read-only nature implies a query before switching, but the description does not state this or name any alternatives. An agent would have to infer the appropriate usage context from the name and siblings.
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 behavioral burden. It discloses the read-only nature, which is a key behavioral trait, but does not mention potential failure modes, required permissions, or side effects (though there likely are none). For a simple read query, the description is adequate but leaves some unknowns like error conditions and exact return formatting.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence with no wasted words. The verb 'Report' is front-loaded, and all outputs are listed compactly. This is appropriately sized for the task.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter read-only tool, the description covers the key aspects: what it reports and the read-only safety. It does not detail return formats or error handling, but given the simplicity and lack of an output schema, it is reasonably complete. The absence of sibling differentiation is a minor gap, but not critical here.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are zero parameters, so the schema is trivially 100% covered. Per the rubric, a baseline of 4 is appropriate when no parameters exist; the description does not need to add parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb ('Report') and resource ('current background'), and enumerates the exact data returned: canonical local path, source, MIME, dimensions, and size. This distinguishes it from siblings like background_set_local (which modifies) and theme_bg_next (which changes theme).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies it is for querying rather than modifying ('Read-only'), but it does not explicitly name alternatives or conditions for when to use this tool versus siblings. The read-only hint gives some context, but without mention of when to prefer this over, say, background_thumbnail_cache_status, usage guidance is only implicit.
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 full burden. It discloses a key behavior: the tool verifies BlueZ state after the operation, which warns the agent that it performs a post-check. It also implies state mutation (connect/disconnect). It doesn't mention error handling or side effects like disconnection of other devices, but the verification step is a meaningful 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, front-loaded with the primary verb and resource, and includes the verification step without fluff. Every word earns its place, and it's highly scannable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with two parameters and no output schema, the description covers the core operation and the post-verification behavior. It doesn't describe return values or typical failures, but given the tool's simplicity and the lack of an output schema, it's reasonably complete. Slightly more on expected outcomes would push it to a 5.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. It maps 'address' to 'MAC address' and 'action' to 'connect/disconnect', which adds meaning beyond the raw schema enum and regex. However, it doesn't elaborate on address format (though schema has a pattern) or explain the action enum values beyond their names. Adequate for a simple 2-parameter tool, but not thorough.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Connect to or disconnect') and resource ('a known device by MAC address'), clearly distinguishing from siblings like bluetooth_toggle which toggles the adapter rather than targeting a specific device. It includes the verification step, adding purpose nuance. However, it doesn't explicitly contrast with bluetooth_toggle or bluetooth_devices, leaving some differentiation implicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context: connecting to a specific known device by MAC address, as opposed to toggling the adapter (bluetooth_toggle) or listing devices (bluetooth_devices). It says 'known device' which hints at previously paired devices. However, it doesn't explicitly state when not to use this tool or mention alternatives by name, so there's room for clearer routing.
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?
Annotations are absent, so the description carries the full burden of behavioral disclosure. It describes the core action (moving a window to the master slot) and the resulting layout, but does not mention side effects, error behavior, or prerequisites beyond 'master mode'. It doesn't state what happens if the index is invalid or if the current layout is not in master mode, which is a notable gap for a layout-modifying 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is front-loaded with the condition ('In master mode') and efficiently conveys the purpose and behavior. Every word earns its place; there is no redundant or vague text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter tool with no output schema and no annotations, the description provides sufficient information to call it correctly: it states the mode, the effect, and the parameter meaning. It relies on layout_order for ordering details, which is a reasonable dependency. It could mention error conditions, but that is not critical for a simple layout operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does 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 that 'index' refers to the Nth window and points to layout_order for ordering, adding meaning beyond the bare integer field. It does not explicitly state 1-based indexing, but the schema's minimum of 1 implies it. This is a solid compensation 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/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('move'), resource ('the Nth window'), and the specific action ('into the full-height left column') with a clear effect on the layout. It references layout_order for window ordering, and implicitly distinguishes from sibling tools like layout_swap_windows (which swaps) and layout_grid (which sets grid layout). The purpose is 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/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description specifies the context ('In master mode') but does not explicitly state when to use this tool over alternatives like layout_swap_windows or layout_grid. It neither mentions when not to use it nor names alternative tools. The guidance is implied rather than explicit, leaving the agent to infer the appropriate use case.
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 behavioral burden. It discloses the 'visible' scope and substring matching, but does not specify whether all matching notifications are dismissed, whether case-sensitivity applies (only in schema), or any side effects. The operation implies destructive action, but this is not explicitly stated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no waste. The core action and condition are front-loaded, making it immediately understandable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one parameter and no output schema, the description is largely sufficient. It covers the operation and its condition. Minor gaps (e.g., whether all matches are dismissed, case-sensitivity only in schema) exist but do not seriously impede correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the parameter description ('Case-sensitive headline substring') already provides the meaning. The tool description's reference to 'supplied substring' adds no additional semantic value beyond what the schema offers. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (dismiss), the target (visible notifications), and the matching condition (headline contains substring). It is specific and distinguishes from sibling notification tools like notification_send, notification_time, and notification_dnd_set, which operate on different aspects.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies its usage context by restricting to 'visible notifications' and matching on headline, which sets clear conditions for invocation. However, it does not explicitly mention when to prefer this over other notification tools, though the intent is fairly obvious from the action. It lacks explicit exclusions or alternatives.
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 of behavioral disclosure. It adds useful transparency by stating that the tool is offline ('Does not use weather or network services'), which sets expectations. However, it does not describe the exact behavior—e.g., whether a persistent or transient notification is shown, or any side effects—which is a notable gap for a tool with zero 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is exactly two sentences with zero redundancy. The key information—what it shows and what it does not depend on—is front-loaded and efficiently delivered. Every word earns its place, making it concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter tool with no output schema and a straightforward purpose, this description is largely complete. It states the action, the resource, and a relevant limitation. It does not mention return values or side effects, but given the simplicity, these omissions are minor and do not impede a correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the schema is empty and there is nothing to explain about parameter formats or meanings. Per the rubric, a baseline of 4 is appropriate for a tool with no parameters, and no additional description is needed beyond the absence of inputs.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb ('Show') and a specific resource ('Omarchy's local current time and date notification'). It distinguishes itself from weather or network-based notifications with the explicit 'Does not use weather or network services.' This is precise and leaves no ambiguity about the tool's function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage (when you need to display the local time/date notification) but does not explicitly state when to use this tool versus alternative notification methods or the sibling notification_send tool. No exclusions or alternatives are provided, leaving the guidance to inference.
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 behavioral burden. It discloses that the stop is 'graceful' and that verification occurs (recorder exited, MP4 exists), which gives some insight into side effects and success criteria. However, it omits error handling, what happens if no recording is active, or potential return values.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single efficient sentence that explicitly states the action and the verification steps. No filler, and the key information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a no-parameter tool without an output schema, the description is reasonably complete: it states the action and intended postconditions. It does not describe return values or error scenarios, but these are not strictly necessary given the simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and schema coverage is 100% (vacuously). Per the rubric, 0 params sets a baseline of 4. The description does not need to explain parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('stop') and resource ('active recording') and includes secondary verification ('verify that the recorder exited and its MP4 exists'), which clearly differentiates from siblings like screenrecording_start and screenrecording_status.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It implies usage (stop an active recording) but does not explicitly say when to use versus alternatives, nor mention prerequisites like 'only when a recording is active' or reference the companion start tool. The purpose is clear enough but guidance on context is missing.
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 clarifies that it returns the theme name, not a detailed object, but does not disclose side effects (expectedly none), error cases, or response format. The added detail 'name of the currently applied' is useful but minimal for a read-only getter.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no wasted words. It conveys the exact action and scope efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter getter with no output schema, the description is sufficiently complete. It states what is returned (the theme name) and the selectable scope (currently applied). Lacks explicit mention of return type, but it's implied. The simplicity of the tool does not demand more.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are 0 parameters, so schema description coverage is trivially 100%. Baseline for 0 params is 4, and the description correctly adds no parameter-related information since none exist. No deduction needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb ('Show') and resource ('name of the currently applied Omarchy theme'), which distinguishes it from theme_list (list all) and theme_set (set theme). The specificity of 'currently applied' makes the purpose 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/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The purpose is implied by the name and description, but no explicit guidance is given on when to use this tool versus alternatives like theme_list or theme_set. The description does not mention any conditions, exclusions, or comparison to siblings.
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 that it applies a theme and verifies it, indicating a state change, but does not mention side effects, permissions, reversibility, or failure behavior. For a mutating tool, this is a moderate 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence that states the action and verification step with no redundant words. It is appropriately sized for a one-parameter tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple apply tool with one parameter and no output schema, the description covers the core action and verification. It lacks details on error handling or prerequisites (e.g., must have theme_list populated), but these are minor for such a straightforward operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%; the parameter description already explains that 'name' is a display name or slug from theme_list. The tool description adds minimal extra meaning, mainly reinforcing the source. Baseline 3 is appropriate since the schema handles the semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'Apply' and the resource 'theme from theme_list', and includes a verification step. This distinguishes it from siblings like theme_list (which lists themes) and theme_current (which shows the current theme), so an agent can tell this is the mutating, apply-specific tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the theme must come from theme_list and mentions verifying afterwards, giving a clear workflow. However, it does not explicitly state when not to use this tool (e.g., for background themes) or name alternatives, though 'from theme_list' provides implicit routing.
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 full behavioral burden, and it explicitly labels the operation 'Read-only' — a meaningful safety disclosure next to many mutation siblings. It also adds specifics about what is captured (stable node IDs, current defaults) that go beyond a generic 'list devices.' It stops short of describing rate limits or output size, but for a read-only enumeration the disclosure is solid.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single dense sentence that front-loads the core action and scope ('List PipeWire/PulseAudio output sinks...'), then packs the return details. Every word earns its place; no fluff or repetition of the title.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Complexity is low (no params) and the description thoroughly covers the scope of devices and fields returned. However, there is no output schema, and the description does not describe the shape or format of the returned data, so an agent cannot anticipate whether results come as a flat list, keyed by node ID, etc. For a pure enumeration tool, the response shape is the main gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are zero parameters, so the baseline is 4 and there is no schema gap to compensate for. The description still clarifies what the tool will surface in its (unspecified) response, which is all an agent needs given there is nothing to configure.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb (List), a concrete resource (PipeWire/PulseAudio output sinks and real input sources), and enumerates exactly what is returned (node IDs, availability, ports, mute state, defaults). Mentioning 'output sinks' vs 'input sources' distinguishes it from siblings like audio_sink_availability, which is narrower, and from setter tools like audio_device_set_default.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The read-only framing and the enumeration verb imply when to use it, but the description gives no explicit 'use this when' context and names no alternatives even though closely related siblings exist (audio_sink_availability, audio_output_switch, media_source_switch). An agent must infer that this is the general listing tool rather than being told when to prefer it over audio_sink_availability.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Given that no annotations are provided, the description carries the full burden of behavioral disclosure, and it does so well. It explicitly states the side effects: 'move active streams through Omarchy' (affecting currently active audio streams), 'verify the default' (validation), and 'roll back on mismatch' (error handling). It also mentions support for dry-run, which is a crucial safety feature. This exceeds typical descriptions by providing a clear picture of what happens during execution.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no wasted words. The primary action is stated first, followed by the key behavioral details and a note on dry-run. Every sentence adds essential information; there is no filler or repetition. This is an exemplar of concise, structured tool documentation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool that modifies system state and has no output schema, the description covers the needed behavioral context: what it does, stream migration, verification, rollback, and dry-run support. It does not explicitly reference how to obtain the enumerated names (e.g., via audio_devices), but this is reasonably implied by 'exactly enumerated' and the presence of sibling tools. Given no annotations, the description is thorough enough for an agent to use it correctly, though it could benefit from an explicit note about prerequisite enumeration.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 0%, meaning the description must explain parameters, but it does so only minimally. The phrase 'exactly enumerated local output sink or input source' hints that 'name' must match an existing device from an enumeration, and 'kind' is sink or source. However, it does not clarify the 'dryRun' parameter beyond mentioning 'Supports dry-run.' The description adds little over the schema's enum and pattern, failing to fully compensate for the lack of per-parameter documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action—'Select an exactly enumerated local output sink or input source'—and further specifies the workflow (move streams, verify, roll back). This clearly distinguishes it from sibling tools like audio_output_switch or media_source_switch, which likely handle temporary switching rather than setting a persistent default. The verb 'select' and resource 'default audio device' are precise 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/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use this tool: when you have an 'exactly enumerated' device name, suggesting you should first list devices (e.g., via audio_devices). However, it does not explicitly mention alternatives or when not to use it, such as switching output temporarily vs. setting a default. The guidance is implied but not explicit, leaving some ambiguity about the appropriate context relative to similar tools.
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 behavioral disclosure burden. It clearly states 'read-only snapshot,' indicating no side effects or mutations. This is sufficient for a simple state inspection tool, though it doesn't mention any edge cases or potential costs beyond that.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that front-loads the essential purpose ('read-only snapshot') before adding usage guidance. Every word earns its place with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a parameterless tool without an output schema, the description sufficiently covers what the agent needs to know: the tool's purpose, the specific data it returns (monitors, workspaces, focused window), and when to call it. Minor omission: it doesn't describe the exact output format, but this is acceptable given no output schema and the simplicity of the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the baseline score of 4 applies. The description adds no parameter-related information, but none is needed since the schema is empty and the tool takes no inputs.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear purpose: a read-only snapshot of the desktop (monitors, workspaces, focused window). While it doesn't explicitly name sibling tools it differs from, the content description (composite of desktop state) implicitly differentiates it from window-focused tools like window_list or workspace_layout.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage context: 'Call this before/after window operations to see actual state.' This tells the agent when to use it, but doesn't mention alternatives or scenarios when another tool would be preferable, leaving some ambiguity.
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 provided, so description carries burden. It discloses the key trait of being non-mutating, but doesn't describe return format, potential errors, or state representation. Given simplicity, a 3 is fair.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single concise sentence, front-loads the action and resource, then clarifies non-mutating nature. No waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Overall simple tool, no output schema, so description should specify return value format; it doesn't. It's clear it reads a state but not what that state looks like. For a status tool, this is a minor gap, but completeness could be better.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters to document; schema is empty with 100% coverage vacuously. Per rule, baseline 4 for 0 parameters. Description adds nothing parameter-specific, which is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource: 'Read the Omarchy shell notification-silencing state'. Explicitly says 'without changing it' distinguishing it from mutating siblings like notification_dnd_set.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'without changing it' implies this is for reading status vs. setting, but doesn't name alternatives explicitly. Still, clear context that it's a read operation, and the sibling set includes notification_dnd_set for changes.
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 discloses a critical behavioral trait: the tool does not just act — it VERIFIES on-screen and returns a verdict with correction hints, meaning failures are surfaced rather than silently succeeding. It stops short of stating permission requirements, failure modes, or side effects on the existing focused window, but covers the essential behavioral contract.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Four tight sentences, front-loaded with the primary action and verification trait, followed by return-value disclosure and a concrete example. No filler or redundant restating of the title. The structure lets an agent grasp the core behavior in the first sentence.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, so the description correctly explains return values (landed window geometry plus a verdict with correction hints). It covers purpose, verification behavior, and return contract for a moderate-complexity tool. It could add failure/fallback behavior and permission notes, but under the absence of annotations it covers the needed ground well.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With schema coverage at 75%, the schema already documents command, refocus, and args well. The description adds value above the schema by clarifying direction semantics via the example (direction='d' opens below the focused window) and illustrating how direction pairs with the command parameter. This is a modest but genuine addition beyond the enum definition.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific compound action — preselect a split direction and launch a command — then names the distinguishing trait: on-screen verification that the window actually tiled. This clearly separates it from sibling tools like layout_preselect (preselects without launching) and launch_app (launches without split control). The concrete example (direction='d', app='terminal') reinforces the intent.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies its use case (launch an app into a preselected split and verify) but provides no explicit when/when-not guidance or named alternatives. Given the large sibling set of layout tools (layout_togglesplit, layout_preselect, window_snap, layout_mode), an agent gets no direct help distinguishing optimal choice beyond the implied launch+verify behavior.
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?
Explicitly states 'Read-only', which is a key behavioral trait, and specifies the two outputs (activity status and file measurement). While no annotations exist, the read-only declaration covers the main side-effect concern. It does not mention permissions or exact return format, but that is less critical for a read-only 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, focused sentence that front-loads the purpose ('Report...') and appends the read-only note. No wasted words, highly efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is adequate for a simple status tool, but 'measure the current output file' is ambiguous—it does not clarify whether it returns file size, duration, or path. Without an output schema, this ambiguity is not resolved, leaving a minor gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and schema coverage is 100%. The description adds no parameter-specific details, but none are needed; baseline of 4 applies for zero-parameter tools.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Report whether gpu-screen-recorder is active') and a measurable ('measure the current output file'), clearly distinguishing it from sibling start/stop tools by emphasizing the status and read-only nature.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies its use case as a status check but does not explicitly contrast with screenrecording_start or screenrecording_stop. No when-not-to-use guidance or alternatives are provided; usage is left to inference.
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 burden of disclosing behavior. It mentions validation, symlink confirmation, and the 'never downloads or copies' side effect, which adds some transparency. However, it does not describe error behavior on invalid input, permission requirements, or whether the previous background is overwritten, leaving notable gaps 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with zero filler. It front-loads the purpose, then adds the key constraint ('Never downloads or copies files') without redundancy. Every phrase earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter tool with no output schema or annotations, the description covers the essential aspects: what it does, the type of input, and a key behavioral constraint (no downloads). It stops short of explaining failure modes or return format, but the 'confirm symlink' hint partially addresses output. Overall it is nearly complete for an agent to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite 0% schema description coverage, the description adds critical meaning to the sole 'path' parameter by specifying it must be an 'absolute local image'. This goes beyond the schema's generic pattern/length constraints and clarifies what kind of path is valid, effectively compensating for the lack of schema description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Set'), a clear resource ('local background'), and adds distinguishing constraints: 'strictly validated absolute local image' and 'confirm the Omarchy state symlink'. This clearly differentiates it from sibling tools like theme_bg_next (cycling) or background_current_details (querying) and leaves no ambiguity about what the tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides implicit usage context: it is for local images only and explicitly says 'Never downloads or copies files', which signals that remote or non-local sources are out of scope. It does not explicitly name alternatives or state when not to use it, but the local-only constraint is enough to guide an agent away from this tool for network operations.
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 discloses that the tool verifies signature, rows, and output files, which adds behavioral context. However, it does not mention whether the build is destructive, whether it overwrites existing files, or any permissions required. The verification detail is useful but not comprehensive, so a 3 reflects the partial 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that leads with the core action and includes the verification step. It is concise, front-loaded, and every phrase adds value. No filler or repetition exists.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no parameters and no output schema, the description covers the essential purpose and the verification behavior. It is complete enough to guide an agent on invocation, though it does not elaborate on potential side effects or typical usage scenarios. Still, given the simplicity, it is well within the acceptable range.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and no output schema. The description does not need to explain parameter semantics since there are none. The baseline for zero parameters is 4, and the description adds no unnecessary parameter information, fulfilling the requirement without redundancy.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the action (build), the resource (current-theme thumbnails), and the method (through Omarchy), plus a verification step. This makes it clear what the tool does and differentiates it from siblings like background_thumbnail_cache_status, which is about status rather than building.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly conveys the context: building thumbnails for the current theme. While it does not explicitly mention alternatives or exclusions, the intent is unambiguous, and the sibling status tool is naturally understood as the complementary check. A score of 4 is appropriate because it provides clear context without explicit when-not guidance.
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 full burden of behavioral disclosure. It clearly states that the tool does not change anything, which is a key non-mutation guarantee. It enumerates the specific state aspects read, which is transparent about scope. However, it does not disclose response format or any potential side effects (though none might exist), which is a minor 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that immediately conveys the action ('Read') and the object (bar state aspects), ending with the crucial non-mutation note. Every word earns its place with zero fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only tool with no parameters and no output schema, the description lists the main state aspects an agent would need to know. It does not specify the structure or format of the returned data, but given the tool's simplicity, this is a minor omission. The description is adequate for an agent to decide whether to call it and what it will return.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the schema coverage is vacuous (100% by default). Per the rubric, 0 parameters set a baseline of 4. The description correctly avoids inventing parameters and focuses on the read aspects, which is appropriate for a parameterless getter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Read' and clearly enumerates the resource aspects: visibility, position, transparency, active bar, and widget layout. It explicitly states 'without changing anything', which distinguishes it from the setter siblings (bar_visibility_set, bar_position_set, etc.). This makes the purpose unambiguous and well-differentiated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool should be used for reading state (as opposed to changing it), but it does not explicitly name alternatives or provide conditions for selection. Since the sibling setter tools are obvious, the guidance is implicit but not spelled out, leaving some room for interpretation. A more explicit 'To modify bar settings, use bar_*_set' would have strengthened this dimension.
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 states what it diagnoses but does not disclose whether the tool makes any changes, returns a report, or has side effects. The read-only nature of a health check is implied but not explicit. It also mentions 'the destructive-tool gate' ambiguously. There is no contradiction with annotations (none exist), but the description leaves room for behavioral uncertainty.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences. The first lists the diagnostic scope without fluff, and the second provides a clear usage instruction. All sentences are front-loaded and earn their place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a diagnostic tool with a single optional parameter and no output schema, the description covers the purpose and when to use it. It does not specify the output format or what success/failure looks like, but that is not essential for a health check. It could mention that it is non-destructive, but overall it is fairly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema fully describes the only parameter 'live' with its own description. The tool description adds no additional meaning to the parameter. With 100% schema coverage, the baseline of 3 is appropriate; the description does not need to reiterate parameter details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Diagnose' and enumerates the exact resources it checks: local dependencies, Omarchy/Hyprland runtime access, custom grid-layout installation, and the destructive-tool gate. This makes the tool's purpose unambiguous and distinguishes it from the many sibling tools that perform specific actions (e.g., theme_set, window_focus).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly tells the agent when to use it: 'Use this first when tools are failing.' This is a clear, actionable trigger condition. While it doesn't mention alternatives, the instruction to use it first implies it's the initial diagnostic step, which is sufficient guidance for a health check.
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, the description fully discloses behavior: it can read or modify state, uses persistent Hyprland state, includes verification and rollback, and supports dry-run. This goes beyond a simple action statement and gives an agent confidence about side effects and safety.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, with the primary action front-loaded, followed by two valuable caveats (verification/rollback and dry-run). Every word earns its place; no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter, no-output-schema tool, the description covers the action, state persistence, safety mechanisms (verification/rollback), and dry-run. It is sufficient for an agent to invoke correctly, though it could be more explicit about prerequisites like permissions, but that is a minor gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and schema coverage is trivially 100%. The baseline for no parameters is 4, and the description does not need to add parameter details since none exist. No gap to compensate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Read or explicitly enable/disable') and a specific resource ('locally detected touchpad or touchscreen'), making the purpose unmistakable. It also adds context about using Omarchy's persistent Hyprland state, which differentiates it from generic input commands.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides context about the state, verification, rollback, and dry-run, but does not explicitly state when to use this tool versus any alternative. No exclusions are given, and no sibling tool is named, so usage guidance is implied rather than 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?
With no annotations provided, the description carries the full burden. It discloses that the action is a state-changing flip, but does not state what happens if there is no split active, whether it affects only the active workspace or all splits, or any side effects. For a mutation tool with zero annotation coverage, this is a slight gap but not severe given the tool's simplicity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one concise sentence with zero waste. The action verb and target are front-loaded, and every word contributes meaning. This is exemplary for a simple tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no parameters, no output schema, and a clear single-purpose action, the description is mostly complete. The only minor gap is the lack of clarification about the state when no split exists (e.g., idempotent, error, or auto-create). However, this is not critical for the tool's core function, and the context signals indicate a simple tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the baseline is 4 per the rubric. The schema is perfectly covered (no properties to describe), and the description does not need to add parameter semantics. It adds nothing extra, but nothing is missing.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Flip'), a specific resource ('split orientation of the active workspace'), and the exact transformation ('horizontal <-> vertical'). This clearly distinguishes it from other layout-related tools like layout_mode or workspace_layout, and leaves no ambiguity about what the tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the use case: toggling split orientation when a split is active. It does not explicitly mention exclusions or alternative tools, but given the simple nature of the tool and the clear action, the context is evident. It could benefit from a note about what happens if no split exists, but that is more behavioral than usage guidance.
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. It discloses that the tool toggles mute and reports state before and after, revealing its side effect and observable outcome. It does not mention edge cases like failure modes or permissions, but for a simple toggle this is adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that front-loads the action and clearly specifies the reporting behavior. It is concise with no filler, earning every word.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter tool with no output schema, the description explains the essential behavior (toggle and report state). It could specify what the 'state' output looks like or whether it returns a value, but the description is otherwise self-contained given the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters, so there is nothing to document. Per rubric, a zero-parameter tool gets a baseline of 4. The description appropriately makes no parameter claims.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb ('Toggle') and resource ('microphone mute'), and adds the detail that it reports the PipeWire source state before and after. This distinguishes it from other audio tools like audio_volume or audio_device_set_default, which have different purposes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage (when you want to mute/unmute the mic) but does not explicitly contrast with alternatives or state when not to use it. There is no mention of alternative tools, though the name and description make the primary use case obvious. This is a clear but unguided description.
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 full burden. It clearly states 'Read' and adds the behavioral note 'No selectors or applications are launched', which reassures the agent about side effects. This is more transparent than a bare read description and covers the key behavioral aspect.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no wasted words. It front-loads the verb and resource, then adds the safety note. This is ideal conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no parameters and no output schema, the description is complete enough. It explains what is read and explicitly states that nothing is launched. The only omission is the return format, but for a read-only defaults tool this is unlikely to hinder correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the baseline is 4 as per the rubric. The description adds no parameter-specific info because there are none, but it doesn't need to. The schema coverage is 100% (empty schema), so nothing is missing.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The verb 'Read' is specific and the resource is clearly enumerated: 'current browser, editor, terminal, and coding-agent defaults plus locally available supported choices'. This distinguishes it from its sibling 'omarchy_default_set' which likely sets defaults. The description is unambiguous and captures the tool's 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/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this is for reading defaults, but it does not explicitly state when to use it versus other tools, such as 'omarchy_default_set' for changing defaults. It provides no exclusions or alternative suggestions. For a simple read-only tool, the guidance is adequate but not explicit.
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 full burden and it delivers useful disclosures: 'sanitized manifest' promises filtered/privacy-cleaned output, and 'No URLs or network access are used' establishes the operation as fully local and offline. This goes beyond the schema, though it could have additionally noted the absence of side effects on plugin state.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence with zero waste: the verb and scope are front-loaded, the return contents are listed, and the offline safety note closes it. Every clause carries information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter read-only inspection tool with no output schema, the description is reasonably complete: it lists the manifest, runtime state, and bar location as return contents and covers the safety profile. It is slightly thin on what 'sanitized manifest' contains, but this is adequate for an agent to call the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the description does not explain the id parameter or where its value comes from. It is inferable that id refers to the already-discovered (plugin_list) plugin, but the description does not state the source of the id or confirm the format beyond the schema pattern. Marginal value added over what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb+resource ('Inspect one already-discovered local plugin') and enumerates exactly what is examined: sanitized manifest, runtime state, and bar location. The 'already-discovered local' qualifier distinguishes it from plugin_list, plugin_validate, and the enable/disable/clone siblings, so an agent can tell this tool apart without opening its schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description makes the usage context clear: this is for inspecting a plugin that has already been discovered, implying the agent should call plugin_list first. It doesn't explicitly name alternatives or give a when-not-to-use rule, but the 'already-discovered' qualifier plus the sibling set (plugin_validate for validation, plugin_local_enable/disable for state changes) conveys the intended workflow adequately.
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?
Annotations are absent, so the description carries the full burden. It discloses the mechanism (PID ancestry) and the outcome (report the window), but does not describe the return format, potential failure modes, or whether the operation is strictly read-only. The description offers some insight but leaves gaps that could matter for correct consumption.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no filler. The core action is front-loaded, followed by the purpose. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (no params, no output schema), the description covers the purpose, method, and use case well. The only notable omission is the exact output type (e.g., window ID string, numeric PID, or object), which could confuse an agent expecting a specific format, but this is a minor gap for a self-identification tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and an empty schema. The baseline is 4 for no parameters, and the description correctly does not add parametric details. There is nothing to compensate for.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Resolve and report') and resource ('the terminal window this agent is running in'), and explains the method (walking PID ancestry). It clearly distinguishes from sibling window tools that operate on arbitrary windows, not the agent's own identity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly identifies the use case: 'locks our identity for tools that move/resize us.' This tells the agent when to invoke it. However, it doesn't mention alternatives or when not to use it, but for a zero-parameter utility the guidance is adequate.
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 takes on the full burden. It discloses the read-only nature and the operations performed (scan, de-duplicate, select strongest signal/security). This is transparent about behavior and side effects (none), though it does not detail output format or edge cases like no networks found.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that states the core action first and includes all key details without redundancy. Every word contributes to understanding the tool's purpose and behavior.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the low complexity (no parameters, no output schema), the description adequately conveys what the tool does and its read-only guarantee. It includes the key output characteristics (strongest signal/security) but could be slightly more explicit about the list format. Overall it is sufficient for an agent to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and the schema coverage is 100% (trivially). The baseline for no parameters is 4, and the description does not need to add parameter meaning since none exist. It correctly implies no input is required.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Scan visible networks'), the resource (networks), and adds specific behavior (de-duplicate SSIDs, show strongest signal/security). It distinguishes itself from siblings like wifi_status and wifi_connect by focusing on listing all visible networks rather than current status or connecting.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for listing available networks but does not explicitly mention alternatives like wifi_connect or wifi_status. The 'Read-only' statement hints at safety but does not provide clear when/when-not guidance or name sibling tools for selection.
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 discloses that the resize is relative ('relative=true is implied') and explains the effect of positive/negative x. However, it does not mention the effect of y, behavior when both are zero, or failure modes (e.g., no matching window). It gives core behavior but not exhaustive detail.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, tightly packed with useful information: the core operation, an example, the implied mode, and optional targeting with a safety note. No wasted words; the critical information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple 4-parameter tool with no output schema and no annotations, the description covers the essential aspects: relative resize semantics, explicit target selection, and a practical safety tip. It is slightly lacking in edge-case behavior (e.g., y-axis effect, zero deltas), but overall it provides what an agent needs to use the tool correctly in most situations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 50% (only match and address have descriptions). The description adds meaning to x and y by explaining they are pixel deltas and provides an example. It also clarifies the precedence between address and match ('wins over match'), which is not fully stated in the schema. This compensates well for the coverage gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Resize') and resource ('window') with the key concept 'pixel deltas' and gives a concrete example ('x=100 grows right side, x=-100 shrinks'). It also clarifies the implied 'relative=true', distinguishing it from absolute-resize tools. This clearly differentiates it from sibling tools like window_snap or window_focus.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains the default use (focused window) and provides guidance for when to pass an explicit target ('Optionally pass address/match to resize an explicit window instead of the focused one (safer with follow_mouse=1)'). This gives a clear use case and a safety tip, though it doesn't explicitly name alternatives or when NOT to use it.
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 discloses the core behavior (moving a window, optionally following focus) but does not elaborate on side effects, possible failures, or the precise effect of 'follow' (e.g., whether focus switches to the moved window). It is minimally adequate but lacks depth for a mutation 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences (20 words), front-loading the core action in the first sentence and then clarifying defaults and target selection in the second. There is no redundant phrasing or filler; every word adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a move operation with 4 parameters and no output schema, the description covers the essential points: the action, default target, and how to override it. It does not mention edge cases like invalid workspace values or the exact meaning of 'follow', but it provides enough for an agent to call the tool correctly in typical scenarios. Given the lack of annotations, a bit more behavioral detail would be ideal, but the current level is adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does 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 purpose of 'address/match' as alternatives for an explicit target, and 'optionally following focus' corresponds to the 'follow' parameter. It does not explain the 'workspace' syntax (e.g., 'special:' or 'previous') but that is partially inferred from the schema pattern. Overall, it adds meaningful context for the optional parameters, which is valuable given the lack of schema docs.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Move a window to another workspace') with the resource and verb clearly identified. It distinguishes the tool from siblings like 'window_focus' by focusing on moving rather than focusing, and mentions the optional follow behavior and explicit target via address/match, which further clarifies its role.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides usage context: it explains the default target (focused window) and how to specify an explicit target with address/match. However, it does not mention alternative tools or explicitly state when to prefer this tool over siblings. The guidance is sufficient for the common use case but lacks explicit exclusions.
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 must carry the transparency burden. It discloses that the tool verifies tiledLayout after switching, which is a useful behavioral trait. However, it does not mention side effects, persistence, error behavior, or any state changes beyond the layout switch. The description adds some value but leaves out important behavioral details for an unannotated 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences: the first states the core action and options, the second provides usage guidance. No wasted words, information is front-loaded, and the structure is logical and easy to parse. Perfectly concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple setter tool with only 2 parameters and no output schema, the description covers the main action, the parameter semantics, and situational guidance. What is missing is error handling details and explicit side effects, but these are minor given the tool's simplicity. Overall, it is sufficiently complete for an agent to call it correctly in most cases.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 50% (workspace has a description, layout does not). The description enumerates the four layout options explicitly, adding semantic meaning to the enum. It also clarifies that workspace defaults to the active workspace, which is not fully stated in the schema's description. This compensates well for the schema gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Switch') and resource ('workspace') with the exact options (MCP grid, Hyprland dwindle, master, scrolling) and the verification step ('verify tiledLayout'). It clearly differentiates from sibling tools by mentioning specific use cases for dwindle and omarchy-grid, making the tool's purpose 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/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides explicit guidance on when to use specific layout options ('Use dwindle before layout_preselect/open_window_split; use omarchy-grid for deterministic grids'), which helps an agent decide among the enum values. However, it does not explicitly state when to prefer this tool over sibling layout tools like layout_mode or layout_grid, though the context is largely implicit. This is good but not exhaustive.
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 full burden of behavioral disclosure. It states that the tool 'Launches independent Omarchy TUI windows, assigns sparse/exact cells in lua:omarchy-grid, and verifies each final class/workspace/geometry.' This discloses the side effects (window launching) and verification process. It also mentions the default to next_empty workspace to avoid displacement. However, it does not address error handling, prerequisite requirements, or what happens on failure. For a launch tool with zero annotations, this is above-average transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded, opening with the core purpose and then giving two clear usage patterns. Each sentence adds value: the purpose, the homogeneous syntax, the mixed syntax, the underlying behavior (launches, assigns, verifies), and the workspace safety default. It is slightly longer than necessary but every clause carries useful information. A minor redundancy is 'ONE-CALL' which is roughly restated by 'orchestration,' but overall it is well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex tool with 9 parameters and nested placement objects (though listed as non-nested in signals), the description covers the two primary use cases and the essential behavior. It does not mention the `dry_run` parameter (which validates without launching) or `focus_workspace`, but these are well-documented in the schema. The lack of an output schema means the 'verifies' behavior is not fully explained, but the description provides enough to understand the tool's effect. It is complete for an agent to decide whether and how to call it, though a few optional parameters could have been mentioned.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 67% (6 of 9 parameters have descriptions), but the description adds meaningful semantic value beyond the schema. It explains the relationship between agent/cols/rows and how count defaults to cols*rows, clarifies the dual modes (homogeneous vs placements), and provides a concrete placement example. It does not individually explain every parameter, but it clarifies the core usage patterns that the schema alone does not convey, such as how to build a mixed grid and the workspace default behavior.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description leads with 'ONE-CALL agent workspace orchestration' and immediately gives concrete examples ('open a 2x2 OpenCode grid', mixed placements). It clearly states the verb (launch/orchestrate), resource (grid of coding agents), and the two distinct modes (homogeneous vs mixed). The tool is unambiguously distinct from sibling tools like layout_grid or window_* which handle window management, not agent orchestration.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage patterns for both homogeneous (agent, cols, rows, count) and mixed (placements) modes, with a concrete example for each. It also clarifies that count defaults to all cells and that workspace defaults to next_empty to avoid displacing existing tasks. It does not explicitly state when not to use this tool vs alternatives, but the tool's purpose is so distinct that the usage context is clear. The guidance is strong but lacks an explicit 'use instead of' note.
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. It explicitly states 'Read-only', which is the critical side-effect disclosure for a status tool. It also specifies it targets the 'default' adapter, which is meaningful context. It does not describe the return format (e.g., boolean) or error handling, but for a simple read-only status check, this is sufficient 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, compact sentence that states the action, target, and safety trait. It is front-loaded with the core purpose and contains zero filler words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no parameters and no output schema, the description conveys everything essential: what it reports, on which adapter, and that it has no side effects. The agent can correctly invoke it without further clarification.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are zero parameters, and the input schema is empty. The baseline for 0 parameters is 4, and the description correctly avoids adding unnecessary parameter details. No compensation is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Report'), a specific resource ('the default Bluetooth adapter'), and the exact outcome ('whether it is powered'). It is immediately distinguishable from sibling tools like bluetooth_toggle, bluetooth_devices, and bluetooth_connect, which represent different actions on Bluetooth hardware.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage as a status check (read-only), but does not explicitly mention when to use it instead of alternatives like bluetooth_toggle or bluetooth_devices. The user must infer that this is for querying power state only, making the guidance implicit rather than explicit.
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, the description carries the full burden. It discloses that the operation is read-only ('Read'), fully local, and does not hit the network, which are key behavioral traits. It does not describe error conditions or output format, but for a simple info tool this is 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
One concise sentence that front-loads the core action and data points, with no filler. Efficient and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given 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 no output schema, the description enumerates all the data points returned (version, channels, timestamp), giving the agent sufficient context to interpret the call. No essential information is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Tool has zero parameters; per baseline, score is 4. Description adds no parameter details since none exist, but the schema coverage is 100% (empty).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb 'Read' and enumerates the exact data points (version, active channel, mirror/package channel, timestamp of last upgrade), making its purpose unambiguous and distinguishing it from general info tools like system_info.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit when/when-not guidance or named alternatives. Only a note that it is fully local and does not check remote updates, implying it is for local version info but not stating when to prefer it over update_system or system_info.
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 full burden of behavioral disclosure. It explicitly states 'Read-only,' which clearly informs the agent that this tool will not modify state. It also describes the output action ('list' and 'mark the active one'), which is adequate for a simple read operation. No hidden behaviors are omitted, though it does not detail output formatting or error cases, which are minor for this 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, consisting of two short sentences that convey all necessary information without redundancy. Every word earns its place: the action, the object, and the safety attribute are all present. It is front-loaded with the core purpose and then adds the read-only qualifier.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no parameters, no output schema, and minimal complexity, the description is complete. An agent can correctly invoke this tool and understand what it will do: list profiles and identify the active one. No additional context is necessary for correct use, and the read-only note covers safety.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and the schema description coverage is 100% (empty schema). As per the baseline for 0 parameters, a score of 4 is appropriate because there are no parameters to document, and the description adds no extra parameter semantics needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'List profiles and mark the active one.' It names the resource (profiles) and the specific behavior (marking active), which distinguishes it from the sibling powerprofiles_set. The purpose is unambiguous and directly tied to the tool name and title.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly mention when to use this tool versus powerprofiles_set or other alternatives. It implies a read-only query use case via 'Read-only,' but does not explicitly state 'to change profiles, use powerprofiles_set' or any exclusions. Some guidance is inherent but not explicit, leaving the agent to infer 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?
With no annotations, the description carries the full burden of behavioral disclosure. It explicitly states that it clears all reminders and verifies emptiness, which conveys the destructive nature and the verification step. This is transparent and provides adequate context for a simple 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that front-loads the primary action (clear all reminders) and then adds the verification step. There is no wasted wording, 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.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter, no-output-schema tool, the description is complete. It tells the agent exactly what will happen (clear all reminders) and the verification that follows. No additional context is necessary for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and the schema coverage is 100% (no properties). Per rubric, baseline for 0 params is 4, and no additional parameter description is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the action (clear) and the resource (all pending reminders), and specifies verification of an empty store. It easily distinguishes this from sibling tools like reminder_set and reminder_show, which perform different operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage (when you want to remove all reminders) but does not explicitly contrast with alternatives or provide exclusions. It lacks explicit guidance on when not to use it or mention of alternative tools, so it falls at the 'implied usage' level.
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?
Since no annotations are provided, the description carries the full burden of behavioral disclosure. 'List' implies a read-only operation, and 'pending desktop reminders' specifies scope, but it does not explicitly state that the tool has no side effects or that it doesn't modify anything. For a simple read tool, this is sufficient but could be more explicit about non-mutation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no wasted words. The action is front-loaded and the output format is mentioned at the end. Perfectly concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter tool with no output schema, the description provides the necessary information: what it does (list), what it lists (pending desktop reminders), and the output format (structured JSON). No additional context is required for an agent to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the schema coverage is trivially 100%. Per the baseline for zero-parameter tools, a score of 4 is appropriate; there is nothing to document.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List') and resource ('pending desktop reminders'), and specifies the output format ('structured JSON'). It clearly distinguishes from sibling tools like reminder_set and reminder_clear, which mutate state. A single sentence conveys exactly what the tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly state when to use this tool versus alternatives, but the context is clear: it's a read-only query for reminders. It doesn't mention any prerequisites or exclusions, but for a zero-parameter tool with a single obvious purpose, the implied usage is sufficient. A 4 reflects clear context without explicit alternatives.
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, the description carries full responsibility. It explicitly states 'Read-only and offline,' which conveys that the tool has no side effects and works without network. This is valuable disclosure, though it doesn't detail return format or exact content beyond the listed metrics.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that front-loads the action ('Read') and resource, with zero fluff. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only tool with no parameters and no output schema, the description covers all necessary information: what it reads, that it's read-only and offline. An agent can invoke it without any further clarification.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so schema coverage is trivially 100%. No parameter explanation is needed, and the baseline for 0 params is 4. The description adds no parameter info, which is appropriate here.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Read' and the resource: Omarchy CPU/memory statistics plus local load averages and uptime. It distinguishes itself from siblings like system_info and health_check by focusing on resource metrics, making it 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/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for retrieving resource statistics but provides no explicit guidance on when to prefer this tool over alternatives like system_info or health_check. The 'Read-only and offline' hint suggests safety, but there is no direct comparison to siblings.
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 burden. The verb 'List' implies a non-destructive read operation, but the description doesn't explicitly state that it has no side effects, nor does it disclose any limitations (e.g., sorting, live state, workspace scope). It adds some context by specifying the fields returned, but remains implicit about behavioral guarantees.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence that packs the purpose, the data returned, and a usage hint without any filler. Front-loaded with the action and resource, making it instantly scannable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple parameter-less listing tool with no output schema, the description is complete. It tells the agent what the tool returns (class, title, pid, workspace, geometry) and when to use it, leaving no gaps for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does 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 there is nothing to document. Per the calibration baseline for 0-parameter tools, a 4 is appropriate; the description correctly avoids inventing parameter details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'List', the resource 'all mapped windows', and enumerates the attributes returned (class, title, pid, workspace, geometry). It distinguishes itself from the many sibling window-related tools by being the listing operation that precedes actions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly instructs when to use it: 'Use to identify targets before acting.' This gives clear temporal context. However, it doesn't name specific alternatives (like self_window_info for the current window) or state when not to use it, so it falls short of a full 5.
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, the description carries the behavioral disclosure burden. It transparently mentions the state-changing cycle, optional playback transfer, before/after status evidence, and dry-run support. It does not detail failure behavior or reversibility, but the key traits are covered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, well-structured sentence that front-loads the core action and integrates optional behaviors and safeguards without redundancy or wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with two optional parameters and no output schema, the description covers the purpose, parameters, and key behavioral traits. It could be more explicit about what 'transferring playback' entails, but overall it provides everything needed for an agent to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description maps 'direction' to 'forward/backward' and explicitly mentions 'dry-run', giving both parameters meaning that the schema (0% coverage) lacks. This compensates for the absence of schema descriptions and clarifies the parameter's purpose.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb 'Cycle' and resource 'active local MPRIS media source' with direction 'forward/backward', making its function unmistakable. It also includes the distinctive trait of providing 'before/after shell status evidence', which sets it apart from any sibling tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It clearly implies usage context by specifying 'active local MPRIS media source', indicating when the tool is applicable. It does not name alternative tools, but no sibling performs media source cycling, so this is acceptable. It could explicitly state exclusions (e.g., when no MPRIS source is active), but the context is sufficient.
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 full burden of behavioral disclosure. It explicitly says 'Read', which signals a non-destructive operation, and states the output is 'structured JSON', setting expectations for the return format. It lists the content categories, making the behavior transparent for a simple read tool. It does not mention potential errors or side effects, but for a read operation this is minor.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, tightly written sentence that front-loads the core purpose ('Read Omarchy's monitor panel protocol') and then lists the relevant fields. There is no extraneous information – every word earns its place. It is both concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (no parameters, no output schema), the description provides a thorough overview of the returned data (brightness, display state, mirroring, scaling, geometry). This is sufficient for an agent to know what to expect, though it could optionally mention whether the JSON has a specific nesting or if any fields are optional. Overall, it is complete enough for a read-only status tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and the schema coverage is 100% (empty schema). Since there are no parameters to document, the baseline score of 4 is appropriate. The description does not need to explain parameter semantics as none exist.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Read') and a clear resource ('Omarchy's monitor panel protocol') and enumerates the exact data fields it returns (brightness, displays, mirroring, scaling, geometry). This distinctly separates it from sibling read tools like `system_info` or `hypr_status`, which cover broader system state.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly conveys that this tool is for reading monitor panel state, implying it should be used when that information is required. However, it does not explicitly mention alternatives, exclusions, or situations where a different tool (e.g., `brightness_display` for adjusting brightness) would be more appropriate. The context is clear but lacks explicit routing guidance.
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, the description carries the full burden of behavioral disclosure. It transparently states that no install, update, or network access occurs, which conveys that this is a safe, read-only operation. It adds useful context about what the tool does NOT do, which is valuable for an agent deciding whether to call it. However, it doesn't elaborate on the 'state' field or any potential side effects like reading local files, though that seems minor for a list 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with zero fluff. The primary action and scope ('List locally discovered plugins and their state') is front-loaded in the first sentence, and the second sentence adds a crucial safety constraint. Every word earns its place; it is appropriately minimal and structured for quick scanning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a list tool with no parameters and no output schema, the description provides the essential context: what it lists, the scope (locally discovered), and the side-effect-free nature. It doesn't describe the return format (e.g., whether it includes names, paths, versions), but that is likely inferable from the tool's purpose and sibling tools. Given the tool's simplicity, this is nearly complete, though a brief note on output structure would make it a 5.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and an empty input schema, which is fully covered by the schema (100%). The description doesn't need to add parameter details since there are none. The baseline for 0-parameter tools is 4, and the description correctly avoids introducing fictional parameters. No deduction is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb ('List'), resource ('locally discovered plugins'), and scope ('and their state'). It distinguishes itself from sibling plugin tools (plugin_local_detail, plugin_local_enable, etc.) by focusing on listing rather than modifying, and explicitly notes it does not install/update. An agent can immediately understand what this tool does and how it differs from others.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'This performs no install, update, or network access' provides clear exclusion criteria, implicitly telling the agent to use this tool when a read-only overview is needed and to use other tools for mutations. While it doesn't name specific alternative tools, the negative constraints effectively communicate when to use this tool. A slightly more explicit pointer to plugin_local_detail or plugin_validate would make it a 5.
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 full burden and does well: it discloses the dry-run default (non-destructive behavior unless dryRun=false) and the refusal of bar replacements. It is a state-mutating operation, so disclosing the dry-run default is meaningful. It stops short of describing what happens on conflict with an already-enabled plugin or the exact failure/return behavior, which a 5 would require.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences with zero filler. The core purpose is front-loaded, followed immediately by the placement constraint and then the dry-run default. Every sentence earns its place and the most decision-relevant information appears first.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 3 parameters, a nested placement object, no annotations, and no output schema, the description covers the essential call semantics: what it targets, the placement requirement/refusal, and the dry-run default. It does not disclose the success/error response shape or behavior on repeated/conflicting enable attempts, which is the main remaining gap for a mutation tool of this complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does 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 maps to the placement parameter ('Bar widgets require an exact section/index') and to the dryRun flag ('Defaults to dry-run'). The id parameter is the plugin identifier, which is implied well enough by the stated purpose. This covers the meaningful semantics of the parameters without needing to repeat the enum values already in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb-resource pair ('Enable an already-discovered plugin') and the qualifier 'already-discovered' cleanly separates it from the discovery flow and the plugin_list/plugin_validate siblings. The bar-widget constraint adds precision about what the tool does and does not accept. Purpose is 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/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives actionable usage context: bar widgets must supply an exact section/index, and bar replacements are refused. This tells an agent when to pass placement and when the call will be rejected. It does not explicitly name alternative tools or the condition for choosing this over the sibling plugin tools, but the enable-vs-validate/clone/disable distinction is reasonably clear from 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?
With no annotations provided, the description carries the full burden. It explicitly discloses the destructive consequence of reboot/shutdown by stating they 'terminate the desktop session' and the permission requirement. This is honest and sufficient for a power action, though it doesn't describe other side effects like unsaved work loss.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, information-dense sentence that front-loads the availability of 'lock' and then states the critical constraint. No filler, every clause earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given 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 the primary caveat (dangerous actions require permission). It doesn't describe return values, but that is acceptable for a mutation tool with no output schema. The agent has enough information to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does 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 adds meaning to the enum values by explaining that lock is safe and always available, while reboot and shutdown are dangerous and gated. This provides the key semantic distinction beyond the raw enum names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The title explicitly states 'Lock, reboot, or shut down' and the description names all three actions. It also distinguishes their availability ('Lock is always available') and the prerequisite for reboot/shutdown, making the tool's purpose unmistakable and distinct from any sibling tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear usage context: lock can always be used, while reboot/shutdown require enableDangerous because they end the desktop session. This implicitly tells the agent when it is appropriate to use each action, though no alternatives are mentioned (there are none among siblings).
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. It discloses that the tool activates a connection and verifies it becomes active, and explicitly states it does not accept or create passwords. This covers the main behavioral aspects. It does not mention potential side effects (e.g., disconnecting current network) or failure modes, but for a simple activation tool this level of detail is reasonable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no filler. The primary action (activate and verify) is front-loaded, and the second sentence adds a key limitation (no passwords). Every word contributes to understanding the tool's function and constraints.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter tool with no output schema and no annotations, the description is sufficiently complete: it explains what the tool does, what input it needs, and a critical constraint. It does not cover error conditions or prerequisites, but those are not essential for basic usage. The verification step is mentioned, adding expectation about behavior. Overall, it fills the gaps that would otherwise require external context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema for 'ssid' already has a description ('Saved connection name'), giving 100% coverage. The tool description adds clarification that this is the NetworkManager connection name, not a broadcast SSID, and reinforces the password limitation. This adds some meaning beyond the schema, so a score above the baseline of 3 is justified.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('activate'), a specific resource ('NetworkManager Wi-Fi connection'), and the input (connection name). It also clarifies it operates on saved connections only, distinguishing it from tools that create or toggle Wi-Fi. This is a clear, unambiguous 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/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implicitly communicates when to use this tool: when you want to activate an already-saved NetworkManager connection. It does not explicitly name alternatives (e.g., wifi_toggle, wifi_status) or provide exclusions, but the context is clear enough for an agent to infer it is not for creating new connections or handling passwords. No explicit guidance on when not to use it, but the restriction to saved connections and the password limitation provide adequate 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. It discloses a key behavioral trait: the tool 'REFUSES to close this agent's own host terminal either way,' which is critical guard behavior. It also implies a fallback to the focused window when parameters are omitted. It does not mention failure modes or return values, but for a simple close action, the disclosed guard and selection behavior are sufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, each earning its place: the action and selection method, the critical guard, and the prerequisite. Information is front-loaded (action first), and there is no filler. The description is compact yet covers essentials.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple nature of the tool (2 optional params, no output schema), the description covers what the tool does, how to select a target, the guard, and the prerequisite check. It doesn't specify failure behavior when no window matches or missing focused window, but that is a minor gap. Overall it provides a coherent picture for an agent to call correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must explain the parameters, and it does: it states selection 'by explicit address/match,' and clarifies that if omitted, the focused window is used. This gives meaning to both 'match' and 'address' beyond their raw schema names. It doesn't specify precedence or format, but for a typical tool it's sufficient. Sincest it says 'or' it implies either can be used.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('Close') and resource ('a window') with explicit selection methods: by 'explicit address/match' or 'the currently focused window if omitted.' It also names a notable guard ('REFUSES to close this agent's own host terminal'), which makes the tool's scope unambiguous. While it doesn't name a specific sibling, it is clearly distinct from other window actions like window_focus or window_resize.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives clear when-to-use guidance: 'Check window_list/desktop_status to pick a target first,' which sets a prerequisite and implies the tool is for closing already-identified windows. It does not explicitly state when not to use it or name alternatives, but the focus on selection via list/status is valuable context. Lacks an explicit exclusion of alternatives, hence not a 5.
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, the description carries the burden of behavioral disclosure. It transparently describes the resolution, verification, and typing process, and notes the 'One-shot' nature and submit behavior. It omits details about failure handling, but the core behavior is well covered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences plus an example convey the full purpose and process with no wasted words. The most important information is front-loaded, 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/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity and lack of annotation or output schema, the description provides a solid overview. It covers the core actions, default behavior, and example usage. Minor gaps like error handling and exact return behavior could be added, but the description is sufficient for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although schema coverage is 100%, the description adds meaning by explaining how match/address resolve the target, the role of submit, and the default when no target is given. It also provides an example that illustrates parameter usage, adding value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'One-shot text input to ANY window' and details the process of resolving, focusing, and typing. It clearly differentiates from sibling tools like window_focus by emphasizing the typing action and providing an example.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives usage context by explaining the default behavior when no target is given and provides an example of talking to another agent. It does not explicitly name alternatives or exclusions, but the purpose is clear enough that an agent can infer when to use it.
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?
Since no annotations are provided, the description carries the full disclosure burden. It states the behavioral effect: the next opened window will occupy the chosen side. This is clear and direct. It does not mention whether the preselect resets after use or if it overrides prior settings, but for a simple one-shot state setter, this level of transparency is adequate. The example reinforces the behavior. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long and front-loaded with the core purpose. The first sentence states the action and effect; the second provides a concrete usage example. Every word earns its place. There is no redundant phrasing or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with a single enum parameter and no output schema, the description is complete. It explains what the tool does, when to use it (before opening a window), and provides an example. There is no missing information an agent would need to invoke it correctly. The simplicity of the tool does not demand more.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema defines the 'direction' parameter as an enum with values 'l', 'r', 'u', 'd' but provides no descriptions. The description adds semantic meaning by giving an example: 'preselect 'r' then open a terminal to get a right-hand split,' which clarifies that 'r' means right. It implicitly suggests the other letters map to left, up, down. While not exhaustive, it compensates for the 0% schema coverage adequately for a simple enum.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Choose which side of the focused tile the NEXT opened window will occupy.' This is specific about the verb (choose), resource (focused tile), and effect (next opened window placement). It distinguishes itself from siblings like open_window_split (which actually opens a split) and layout_mode (which sets layout type). The purpose is unambiguous and directly tied to the tool's name and title.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit usage guidance: 'Chain with open_window for split layouts' and provides a concrete example: 'preselect 'r' then open a terminal to get a right-hand split.' This tells the agent exactly when to use the tool (before opening a window) and how it fits into a workflow. While it doesn't explicitly list alternatives, the chaining instruction makes the intended context clear and actionable.
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:

[![Omarchy-MCP MCP server](https://glama.ai/mcp/servers/hlsitechio/Omarchy-MCP/badges/card.svg)](https://glama.ai/mcp/servers/hlsitechio/Omarchy-MCP)

Score Badge

Copy to your README.md:

[![Omarchy-MCP MCP server](https://glama.ai/mcp/servers/hlsitechio/Omarchy-MCP/badges/score.svg)](https://glama.ai/mcp/servers/hlsitechio/Omarchy-MCP)

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

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/hlsitechio/Omarchy-MCP'

If you have feedback or need assistance with the MCP directory API, please join our Discord server