hammerspoon-mcp

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

Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds that it returns exact signatures and targets API documentation, which provides useful behavioral context beyond the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences long, with the first stating the action and result and the second providing usage guidance. No redundant information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the simple 3-parameter tool with no output schema and full annotations, the description covers purpose, usage, and return characteristics sufficiently.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so all parameters are described in the schema. The description aligns with the query semantics but does not add additional parameter details, so a baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Search'), names the resource ('Hammerspoon's own API documentation'), and lists content types ('functions, methods, constants, and modules'). This clearly distinguishes it from sibling tools that perform actions like listing windows or launching apps.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly states when to use it: 'Use this before writing Lua so calls are correct the first time, rather than discovering a wrong name from a runtime error.' This gives clear timing and rationale, even without naming an alternative tool.

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

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

Annotations already indicate read-only and idempotent behavior. The description adds valuable context by specifying what information is returned (default device, volume, mute state) and why it matters for subsequent device-setting calls. No contradiction with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise sentences with no filler. The first sentence states the core functionality and output; the second provides actionable usage guidance. Every word earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-parameter, read-only listing tool, the description fully covers what the tool does, what it returns, and when to use it. No output schema is present, but the description adequately describes the output content.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, so the description carries no parameter burden. The baseline of 4 applies because there is nothing to document beyond the schema, and the description correctly focuses on behavior and output.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool lists audio output and input devices, showing default status, volume, and mute state. It distinguishes itself from siblings like hs_audio_set_device by explicitly positioning itself as the precursor to that tool.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit guidance to call this tool before hs_audio_set_device to learn exact device names. It does not mention when not to use it or alternatives, but for a simple listing tool this context is sufficient.

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

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

With no annotations provided, the description carries the full burden of transparency. It clearly discloses the three-step matching behavior (exact match, substring, list devices on no match), which is excellent. However, it does not mention potential side effects like needing system permissions or whether the change is persistent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is three concise sentences with no fluff. It is front-loaded with the core function, followed by examples and matching behavior. Every sentence adds value, making it easy to parse quickly.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with a simple schema and no output schema, the description is complete and self-contained. It explains the default behavior and error conditions (listing devices). Minor omissions like not stating whether the action returns a success indicator, but this is not critical 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.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema already provides good descriptions for both parameters (100% coverage). The tool description adds valuable detail about the exact matching semantics (exact first, case-insensitive substring) and what happens when no match is found. This goes beyond the schema, which only mentions 'substring is accepted', enriching the user's understanding.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Make an audio device the system default' with concrete examples ('headphones or a display'). It also explains the fallback matching behavior, fully distinguishing it from sibling tools like hs_audio_devices which lists devices.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The usage context is implied through the description of how devices are matched and the fallback behavior, but there is no explicit mention of when to use this tool versus alternatives like hs_audio_volume or hs_audio_devices. It relies on the reader 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.

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

With no annotations, the description carries the full burden of disclosing behavior. It mentions that a no-arg call is a safe query, but it does not explain side effects of changing volume or mute, whether changes are persistent or immediate, nor the impact on the default device. There is no mention of the direction parameter (input/output) or return format. Given it's a mutation-capable tool, this is a significant gap.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences long, front-loaded with the core function, and contains zero fluff. Every word contributes value, making it highly efficient for an agent to parse.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is relatively simple (3 optional params, no output schema). The description covers the primary read/write functionality and the safe query mode. However, it omits details about the 'direction' parameter (input/output) and what exactly is reported (volume and mute state, but no format). Given the absence of an output schema, these missing details leave the agent partially uninformed.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema already describes each parameter with acceptable clarity (coverage 67%, though all params have descriptions). The description adds relevant value by clarifying the all-optional behavior: 'Called with no arguments it only reports the current state.' This informs the agent that omitting all parameters is a query, which is not explicit in the schema alone.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's function: 'Read or change the volume and mute state of the default audio device.' This is a specific verb-resource pair that distinguishes it from sibling tools like hs_audio_devices (listing devices) and hs_media_control (media playback). 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.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides a clear usage hint: 'Called with no arguments it only reports the current state, so it is safe to use as a query.' This tells the agent when to use the tool passively versus actively changing state. However, it does not explicitly mention alternatives or exclusions, leaving some room for ambiguity among audio-related siblings.

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

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 read/change modes and the external-display failure behavior, which goes beyond the schema. Could add return format details, but the disclosure is effective.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise sentences are front-loaded with the core purpose and quickly give behavior and limitations. No waste or filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a one-parameter optional tool with no output schema, the description covers purpose, invocation mode, and a key error case. It doesn't explicitly state the return value, but 'it only reports' implies this adequately.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, and the schema already documents level as an optional 0-100 percentage. The description's '0 to 100' and 'Called with no arguments it only reports' reinforce the schema but do not add substantial new parameter semantics.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Description states 'Read or change the built-in display brightness' with specific verb+resource and a clear 0-100 scope. It distinguishes this from audio/volume and other tools by explicitly targeting the built-in display.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Clearly defines when it reads vs changes: 'Called with no arguments it only reports' and warns external displays will error. Does not explicitly name alternative tools, but context is sufficient for this simple tool.

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

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

Without annotations, the description carries the transparency burden. It explicitly mentions that calling with no arguments only reports, implying that providing the 'enabled' parameter changes the state. It also notes the keyboard light effect, but does not mention potential side effects or 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.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise, comprising two short sentences that cover the core functionality and the optional argument behavior. No redundant words or filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity, the description covers its purpose and usage with and without arguments. It does not specify the exact return format when reporting, but given the lack of an output schema and the straightforward nature, this is a minor gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The single parameter 'enabled' is clearly described in both the schema and the description: omitting it reports, providing it sets the state. The parameter semantics are fully covered with no ambiguity.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool reads or changes the caps lock state, including its keyboard light. It is specific to caps lock and distinct from sibling tools that manage other system settings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides a usage hint: 'Called with no arguments it only reports.' However, it does not explicitly explain when to use this tool versus alternatives, nor does it describe how to perform a set operation beyond the schema property.

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

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

With readOnlyHint annotation already declaring the safe read-only nature, the description adds context about the content (Lua errors/print output) and the tail behavior ('most recent lines'). However, it doesn't disclose any side effects, error handling, or return format beyond that, so it's 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.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences, each serving a distinct purpose: one states the operation, the other provides usage context. It is front-loaded and free of unnecessary detail.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple read-only tool with one optional parameter and a clear annotation, the description covers the purpose, content, and appropriate use case. It doesn't explain the returned data format, but given the simplicity and lack of output schema, this is not a major gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The parameter 'lines' is fully described in the schema ('How many trailing lines to return'), and the description adds no further parameter details. With schema coverage at 100%, the baseline of 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Return') and the resource ('the Hammerspoon console'), and specifies the scope ('the most recent lines'). It also distinguishes itself from sibling tools by explaining that this is where Lua errors and print output appear, positioning it as a distinct diagnostic tool.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description offers clear guidance on when to use the tool: 'the first place to look when a config change misbehaves.' While it doesn't explicitly list alternative tools, the context is specific enough to guide an agent toward this tool for console troubleshooting.

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

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

With no annotations present, the description bears the full burden of disclosing behavior and does so well: it reveals the read-vs-write mode distinction and warns that changing the handler 'may make macOS ask the user to confirm' — a side effect an agent needs to anticipate. It could add what the report output looks like, but for a dual-mode tool, this is strong disclosure.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three front-loaded sentences accomplish everything: stated purpose, mode explanation, and a caveat. No filler 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.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple 1-parameter tool with no annotations and no output schema, the description is largely complete. It covers purpose, invocation modes, and side effects. The only minor gap is omitting what the tool returns when reporting, but without an output schema requirement, this is a small miss.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with a clear bundleId description. The description adds value by linking the parameter to behavior via 'Omit to only report,' reinforcing the conditional nature of the argument beyond the schema alone. This pushes it slightly above the baseline-3 for full schema coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb-resource pairing: 'Report which application handles http, https, and mailto links' with the modifier 'optionally change.' It clearly covers both execution modes and the exact URL schemes in scope. The tool has no near-namesake siblings, and the description's coverage of the dual report/modify behavior fully disambiguates it.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly explains the tool's two modes with 'Called with no arguments it only reports' and how to invoke the change behavior. It provides clear when-based context for a single-argument workflow. It stops short of explicitly naming alternatives or excluded scenarios, though no sibling tool directly overlaps, so the guidance is sufficient for correct selection.

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

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 two key behaviors: it does not launch the app and it fails if the app is not running. This is significant behavioral context beyond what the title implies, though it could mention permission requirements or multi-window handling, which are common for focus operations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences long, immediately stating the core action and then adding a single, valuable clarification about the alternative. Every word earns its place, with no redundancy or irrelevant detail.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple tool with one parameter and no output schema, the description is complete. It covers the purpose, the key limitation, and the relationship to the most similar sibling (hs_launch_app), making it fully self-contained for an agent to select and invoke correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema has 100% coverage for the single 'name' parameter with a clear description ('Application name or bundle identifier'). The tool description adds no further parameter details, but per the rubric, a baseline of 3 applies when schema coverage is high, and the schema already documents the parameter sufficiently.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool brings an already-running application to the front, using a specific verb and resource. It also distinguishes itself from hs_launch_app, making its scope unmistakable.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly explains when to use this tool versus hs_launch_app, noting it never starts applications and fails if the app is not running. This provides clear guidance on appropriate usage compared to the sibling tool.

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

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

With no annotations provided, the description carries the burden of disclosing behavioral traits. It reveals that the tool brings a window to the front and returns the matched window for confirmation, but it does not mention edge-case behaviors such as what happens when both id and title are provided or when multiple titles match. This leaves some ambiguity in behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two short, front-loaded sentences. It states the main action upfront, then clarifies selection and return value. Every sentence earns its place with no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple focus operation, the description covers the return value, which is essential because no output schema exists. It omits potential error cases and parameter precedence, but given the tool's low complexity, it is adequately complete for an agent to use it effectively.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description reinforces that id is an exact match and title is a substring, but these details are already present in the schema. It adds no new semantic information about parameter precedence or required combinations.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific action ('Bring a window to the front') with a clear resource ('a window') and distinguishes itself from siblings like hs_focus_app (focus app) and hs_move_window (move window). The selection method (id or title substring) is also explicitly outlined.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context for when to use the tool: when you need to bring a specific window to the front and want to confirm the chosen window via the return value. It does not explicitly name alternative tools or exclusions, but the purpose is sufficiently specific relative to sibling tools.

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

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

With no annotations, the description fully assumes the transparency burden and excels. It discloses a non-obvious behavioral trait: the result reports actual landing via 'arrived=false with landedOn set', explaining the macOS auto-rearrange edge case. This is verified, not assumed, adding significant value.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is three compact sentences: purpose, result behavior, and a brief 'Verified, not assumed' tagline. Every sentence contributes meaning, with no repetition or filler, making it highly efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite lacking an output schema, the description explains the key return semantics (arrived/landedOn). It does not specify what happens if both id and position are provided or if neither is given, leaving a minor ambiguity given the parameters are optional.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema already contains detailed descriptions for both id and position, covering 100% of parameters. The description essentially restates these details without adding new semantic insight, so it meets the baseline but does not exceed it.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's function: 'Switch to another macOS desktop' with a specific verb and resource. It distinguishes the tool from siblings by mentioning 'by its id from hs_list_spaces or by its 1-based position', making it evident this is for changing Spaces, not listing them.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context on how to use the tool (via id or position), implicitly indicating it is for switching desktops. However, it does not explicitly contrast with alternatives like hs_list_spaces or clarify behavior when both id and position are given, which are optional.

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

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

Annotations already declare readOnlyHint and idempotentHint, so the description doesn't need to restate safety. It adds useful behavior: 'report its version' and the diagnostic role. No contradiction with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with the core action and followed by usage guidance. Every word earns its place; no fluff or repetition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple health-check tool with no parameters and no output schema, the description covers what it does, when to use it, and what it reports. It is complete for its complexity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes zero parameters, so there is nothing to explain. Baseline 4 applies; the description doesn't need to compensate for incomplete schema coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb 'Verify' with a clear resource (Hammerspoon connection) and output (version). It distinguishes itself from sibling tools by being a health check, not a window/app/notification tool.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states when to use: 'Call this first when any other tool fails.' Also explains the rationale—distinguishing setup problems from tool problems—which is actionable guidance for an agent.

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

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

With no annotations provided, the description carries full burden and delivers: it discloses the three behavioral modes (prevent sleep, allow sleep, report state without args). It goes beyond the schema by confirming the side-effect-free no-argument read-back behavior. Could add permission requirements or timeout semantics, but for a simple toggle this is thorough.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with the core action, and every word adds value. The use-case sentence earns its place by guiding invocation timing, with zero fluff or redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with one optional boolean parameter, no output schema, no enums, and no nested objects, the description fully covers the behavioral surface area. It explains the action, the state-reporting invocation, and when it's useful—nothing missing for an agent to use it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%—the single boolean 'awake' parameter is fully documented in the schema ('True to prevent sleep, false to allow it'), so the baseline of 3 applies. The description's mention of the no-arg behavior is a nice confirmation but doesn't add novel parameter syntax beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Clear verb+resource+scope: 'Stop the Mac from sleeping, or let it sleep again' precisely describes the action on the resource. It distinguishes the no-argument behavior ('reports the current state') and doesn't overlap with any sibling like hs_machine_status or hs_lock_screen.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides a concrete use-case ('Useful before a long build or download') that signals when an agent should call this tool. It implicitly covers the state-reporting usage pattern, though it doesn't name specific alternatives—though no sibling tool directly overlaps, so no exclusion is strictly needed.

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

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

No annotations are provided, so the description carries full burden. It discloses the key behavior (launch or focus), which adds value beyond the schema. However, it does not mention what happens if the app is not found or if there are permission issues, but for a simple launcher 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.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences, front-loaded with the action, and includes an example. No wasted words; every part earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple one-parameter tool with no output schema, the description covers the essential purpose and parameter semantics. It lacks details on error handling or launch failure, but the tool is simple enough that the description is largely complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema covers 100% of the parameter with its own description. The tool description adds meaningful guidance by specifying that the name should match what appears in Finder and giving the example 'Safari', which enriches the schema's bare description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's function: launch an application by name, or focus it if already running. It uses a specific verb ('launch') with a resource ('application') and explicitly mentions the dual behavior that distinguishes it from siblings like hs_focus_app.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies when to use this tool: when you want to start an app, or bring it to the foreground if it is running. It does not explicitly name alternatives, but the sibling tool list includes hs_focus_app, and the 'or focus' wording gives clear context without formal exclusions.

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

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

Annotations already declare readOnlyHint and idempotentHint, so the safe read-only nature is covered. The description adds value by disclosing the specific output fields (pid, bundle identifier, window count, frontmost), which are not part of the annotations. This gives the agent a clear expectation of the tool's behavior beyond what structured data provides.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, well-structured sentence that front-loads the action ('List running applications') and lists the key output fields without unnecessary verbosity. Every word adds value, making it highly concise and easy to parse.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple read-only listing tool with good annotations and full schema coverage, the description is largely complete. It specifies the output fields but does not mention any default ordering, sort behavior, or whether the list is filtered by default. Given the low complexity, this is a minor gap, so a score of 4 reflects that it is almost complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 100% coverage for the single optional parameter, with a clear description of the query parameter's filtering behavior. The tool description does not add any additional parameter context, so the baseline score of 3 is appropriate given the schema already fully documents the parameter.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool lists running applications, which is a specific verb and resource. It distinguishes itself from siblings like hs_list_windows by specifying the output fields (pid, bundle identifier, window count, frontmost). This makes the purpose unambiguous and differentiates from other list/focus tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage by listing what the tool returns, but it does not explicitly state when to use this tool versus alternatives such as hs_list_windows or hs_focus_app. There are no exclusions or alternative suggestions, leaving the usage context 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.

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

Annotations already declare readOnlyHint and idempotentHint, covering the safety profile. The description adds value by specifying that only names are listed and that these shortcuts are user-authored automations, giving the agent useful behavioral context beyond the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences, front-loaded with the core action. Every sentence earns its place, and there is no redundant repetition of the title or schema.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple, zero-parameter, read-only list tool with strong annotations, the description is complete enough. It clearly states what is returned (shortcut names) and why they matter, with no missing behavioral or safety information.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters and the schema coverage is 100%, so there are no parameter details to clarify. Per the baseline for zero-parameter tools, this is adequate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('List') and a clear resource ('the user's macOS Shortcuts by name'), making the tool's function immediately obvious. It also differentiates from sibling tools like hs_run_shortcut by emphasizing listing rather than executing.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides useful context about shortcuts being user-authored and machine-specific, implying when they matter. However, it does not explicitly state when to use this tool versus alternatives such as hs_run_shortcut, nor does it mention 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.

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

The readOnlyHint and idempotentHint annotations already signal safety, and the description adds useful edge-case behavior: fullscreen app spaces have no position, while user desktops use a 1-based position matching Ctrl+N shortcuts. This goes beyond what annotations alone provide.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two tightly written sentences front-load the main purpose and then clarify an important semantic detail. Every sentence earns its place with no redundant filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-parameter, read-only listing tool with strong annotations, this description is complete: it states the resource, scope across screens, key output fields, current-space indicator, and the position edge case. No output schema exists, but the description sufficiently explains what the caller needs to know.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

This tool has zero parameters, so the baseline is 4. The description does not need to explain parameter semantics since the input schema is empty and schema coverage is 100%.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: 'List macOS Spaces across all screens'. It clearly identifies output fields (id, type, current) and distinguishes Spaces from sibling tools like hs_list_windows and hs_screens.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives clear context about when to use this tool: whenever you need to enumerate macOS Spaces, identify the current space, or resolve the meaning of 'desktop 2'. It does not explicitly name alternatives or exclusions, so it falls short of full alternative guidance.

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

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

Annotations already declare readOnlyHint and idempotentHint, covering the safety profile. The description adds useful behavioral nuance: names repeat across languages (fourteen Eddys) and gender is reported only 'where the system reports it', signaling potential missing data. This exceeds the baseline but stops short of describing output format in depth.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, fully front-loaded: the first states purpose and fields, the second adds a caveat and cross-reference. No filler 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.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-parameter read-only list tool with no output schema, the description covers the essential return fields and a critical usage caveat (duplicate names), plus a forward pointer to hs_speak. No missing context is needed for effective invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has zero parameters, so the baseline is 4. The description adds no parameter syntax but also needs none. Its note about the identifier and ambiguity pertains to output usage, not input, so no deductions are warranted.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states a specific action ('List') and a specific resource ('installed speech synthesiser voices'), enumerating the fields returned (name, language, gender, full identifier). It stands apart from sibling tools like hs_speak, which uses voices, by focusing on enumeration and metadata.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides explicit usage guidance: when names are ambiguous, use the identifier with hs_speak. This gives a clear when-to-use scenario and cross-reference to an alternative, fulfilling the 'explicit when/when-not/alternatives' criterion.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so no safety risk. The description adds behavioral context by specifying that it lists 'every visible window' (excluding hidden/minimized ones) and includes the specific attributes returned, which is useful beyond the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences long, front-loaded with the primary action and output, and ends with a clear prerequisite note. Every sentence earns its place with no redundancy or extraneous detail.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple read-only list operation with one optional parameter, the description fully explains what the tool returns, the scope (visible windows), and the typical use case (prerequisite for hs_focus_window/hs_move_window). No output schema is needed because the return fields are explicitly listed.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema contains a complete description for the only parameter (app) with case-insensitive substring filtering, covering 100% of parameters. The tool description itself does not add further parameter details, but the schema description is sufficient, so a baseline of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('List') and resource ('every visible window') and enumerates the exact return fields (id, owning application, title, frame, screen). It clearly differentiates from sibling tools like hs_list_apps and hs_screens by stating it returns window-level data with ids used for focus/move operations.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit guidance is given: 'Window ids are what hs_focus_window and hs_move_window operate on, so call this first.' This tells the agent when to use this tool (as a prerequisite for window manipulation) and explains the relationship to alternative tools, making the usage context unmistakable.

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

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

No annotations exist, so description fully owns behavioral disclosure. It clearly states the side effect (locks screen), reassures that applications keep running and nothing is closed, and declares it safe anytime. This is excellent transparency for a no-parameter action.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise sentences, front-loaded with the core action, then reassurance. No wasted words, no redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-parameter, no-output-schema tool, the description covers all essential aspects: what it does, how, and safety implications. Complete and self-sufficient.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has zero parameters, so schema coverage is 100% and no parameter documentation is needed. Description adds context about the action itself, which is sufficient.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Description explicitly states the tool locks the Mac immediately, compares to pressing the lock shortcut, and clarifies scope (no apps closed). This is clear and distinct from all sibling tools, none of which perform locking.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides clear usage context: safe to invoke at any time because applications continue running. Does not explicitly mention when not to use or name alternatives, but given uniqueness and zero params, it is adequate.

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

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

The annotations already declare readOnlyHint and idempotentHint, which are the essential safety traits. The description adds useful context: it mentions that fields are null when hardware doesn't provide them, which is important for handling missing data. It doesn't mention any side effects, but given the read-only and idempotent annotations, this is sufficient. No contradiction.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, well-structured sentence that front-loads the purpose ('One call for the state of the machine') and then lists the specific fields. It is concise, without redundancy, and every detail adds value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with no parameters and no output schema, the description is quite complete: it lists the expected outputs and handles the edge case of null fields. The only gap is that it doesn't describe the output format (e.g., a JSON object or dict), but the list of fields implies the structure. Given the tool's simplicity, this is adequate.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, so the description need not explain any. As per the rubric, zero parameters earns a baseline of 4. The description does not add confusion and aligns with the empty schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: to report the overall state of the machine, and enumerates the specific fields it returns (host name, OS version, idle time, battery, display, wifi, audio). This distinguishes it from sibling tools like hs_audio_volume or hs_brightness which deal with individual settings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies this is a one-call status check, and the list of returned fields provides clear context for when it would be useful (e.g., checking battery or wifi). It does not explicitly state when not to use it or mention alternatives, but with zero parameters and a broad status purpose, it's clear it should be used when a quick overall snapshot is needed rather than querying individual systems.

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

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

With no annotations, the description carries the full burden. It transparently describes the behavior as equivalent to pressing a keyboard media key, and notes it affects the current media-owning application. It does not detail edge cases (e.g., no media playing) or permissions, but for a simple key press, the disclosure 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.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences, front-loaded with the core action, and contains no redundant information. Every clause adds value: what it sends, its scope, and its effect. Excellent conciseness and structure.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple tool with one parameter and no output schema, the description is complete: it explains the effect, scope, and behavior. It could mention what happens if no media is playing or that there is no return value, but that is not necessary for this kind of fire-and-forget action. The presence of sibling hs_music_control could have been clarified, but overall it is sufficient.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema has 100% coverage (param 'action' has enum and description). The tool description adds some semantics by enumerating effect for play/pause and next/previous but omits 'fast' and 'rewind' from the list. This adds marginal value beyond the schema, but since the schema already defines valid values, the baseline of 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool sends a system media key and lists specific actions (play/pause, next, previous). It also clarifies it acts on whichever app owns media playback. It's specific and unambiguous, though it doesn't explicitly distinguish itself from the sibling hs_music_control or other media-related tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage context (system-wide media keys) and mentions it works with any app, but it does not explicitly state when to use this tool versus alternatives like hs_music_control. There is no mention of exclusions or when not to use. 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.

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

With no annotations, the description discloses important behavior: the returned frame is the real placement read after the move settles, and adjusted=true indicates deviation. It also states that omitted fields retain their current value, which is non-obvious. This adds transparency beyond the schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence that front-loads the action and includes necessary details about return behavior and prerequisites. No unnecessary words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool has 5 parameters, no output schema, and no annotations, so the description must cover behavior. It does: it explains the return frame, the adjusted flag, and references hs_screens for coordinate space. It also implies the id source via schema. This is sufficient for an agent to use the tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is only 20% (only id has a description). The description adds units ('in screen pixels') and explains that omitted fields keep their values, giving meaning to optionality. It doesn't enumerate each parameter but provides sufficient context for x, y, width, height.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states the tool 'Set the position and/or size of a window by id'—a specific verb (set) and resource (window) with scope (position/size). It distinguishes itself from sibling tools like hs_focus_window (focus) and hs_window_layout (layout) by focusing on move/resize. The mention of 'by id' further clarifies its operation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It provides context: 'Omitted fields keep their current value' explains how to use optional parameters. It also advises using hs_screens for coordinate space, a prerequisite for correct usage. However, it doesn't explicitly state when to use this vs alternatives, but the purpose is distinct enough.

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

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

With no annotations, the description carries the full burden and discloses important behaviors: the reported state is read back after the action settles, and it errors rather than auto-launching the app. It could additionally describe the exact returned state shape or side effects, but it provides solid guidance for a simple control action.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is three focused sentences, front-loaded with the core purpose and followed by usage and behavior guidance. Every sentence earns its place; there is no redundant repetition of schema information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is simple with only two enum parameters, and the description provides usage differentiation, target scope, and behavioral expectations. Since there is no output schema, mentioning that the state is read back helps, though exact return fields are not specified; overall it is sufficiently complete for effective selection and invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema already provides full coverage with enumerated values and descriptions for both player and action. The description adds context by naming Spotify/Music and listing actions, but it does not add detailed per-parameter semantics beyond the schema, so the baseline of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states specific actions ('Play, pause, or skip') and specific targets ('Spotify or the Music app'), making the tool's purpose immediately clear. The phrase 'Use this instead of hs_media_control' also differentiates it from a closely related sibling tool.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explicitly says when to use this tool over hs_media_control ('when more than one player could respond to a media key') and gives a behavioral constraint ('Errors rather than launching the app if it is not already running'), which helps the agent decide if 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.

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

The readOnlyHint annotation marks the tool as read-only. The description adds a significant non-obvious behavior beyond the annotation: non-running players are reported as such and are not launched. This enriches the behavioral model, but it doesn't disclose potential error cases or return format, so a perfect score is not reached.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise sentences deliver the exact purpose and a critical safety note without any fluff. Every word earns its place, and the most important information is front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a one-parameter, read-only query tool with no output schema, the description covers the feature set, edge-case behavior (non-running player), and the practical benefit (safe to call). Nothing important is missing given the tool's simplicity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%: the only parameter 'player' has a description ('Ask one player only. Omit to report both.') and an enum. The tool description adds no extra parameter details beyond what the schema already offers, so the baseline of 3 is used.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Report') and details the exact data ('current track, artist, album, position, and playback state') for the two players, clearly stating the tool's scope. It doesn't explicitly contrast with sibling tools like hs_music_control or hs_media_control, so it misses the top score for sibling differentiation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides a useful usage hint: 'A player that is not running is reported as such rather than being launched, so this is safe to call as a plain query.' This implies it is a non-side-effecting query tool, but it never states when to pick this over alternatives. Usage context is implied rather than explicitly defined, so a 3 is appropriate.

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

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

The readOnlyHint annotation already communicates non-destructiveness. The description adds meaningful behavioral context beyond that: reachability is a routing check, not a ping, returns instantly, and does not prove the host is up. This helps set expectations and prevents misuse.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with the main purpose, and every clause carries meaning. The key caveat about reachability is placed in the second sentence without redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the low complexity (one optional parameter, read-only annotation, no output schema), the description is complete. It covers the default behavior, the optional behavior, and the important limitation of reachability checks.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3. The description adds extra semantic value by clarifying the host parameter is optional and by explaining what reachability actually means (routing check, not a ping). This goes beyond the schema's simple 'Hostname to check reachability for.'

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Report') and enumerates exact resources: primary network interface, IP addresses, router, current wifi network, and optional host reachability. This clearly differentiates it from more targeted sibling tools like hs_wifi.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The context of use is implied rather than explicitly stated: it reports network state and optionally checks host reachability. It provides a useful caveat that reachability is not a ping and answers instantly, but it does not explicitly say when to prefer this over alternatives such as hs_wifi or a ping-like tool.

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

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

No annotations provided, so description carries full burden. Discloses delivery limitation with Focus modes, explains what posted=true means, and contrasts with hs_notify's no-trace behavior. This is rich behavioral context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, front-loaded with purpose, then caveat, then usage guidance. No fluff.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema and no annotations, the description explains the key delivery caveat and alternative usage. Leaves minimal gaps—mostly the tool is simple and schema covers parameters.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema has 100% coverage with descriptions for all three parameters. Description adds contextual caveats but does not redefine parameter meaning, so baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States 'Post a real macOS notification' with a clear verb and resource. Explicitly contrasts with hs_notify, distinguishing scope and delivery mechanism.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides explicit when-to-use ('when the user should see something after stepping away') and when-not-to-use ('use hs_notify instead for transient on-screen message'), naming the alternative.

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

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

With no annotations, the description carries full burden. It discloses 'transient' and 'without stealing focus,' providing some behavioral context. However, it does not mention whether the tool blocks, returns immediately, or handles errors. This is a moderate transparency level, offering more than a bare verb but stopping short of full disclosure.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two concise sentences: the first states the core function, the second adds usage context. Every word earns its place, with no redundancy or filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity, full schema coverage of both parameters, and no output schema, the description is quite complete. It explains the purpose and ideal use case. A minor gap is the lack of explicit mention of the duration parameter's effect, but the schema already specifies this.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, with both 'text' and 'seconds' documented in the input schema. The description itself adds no extra parameter-specific meaning, so it relies on the schema for parameter semantics, which meets the baseline.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with 'Display a transient alert on screen through Hammerspoon,' which uses a specific verb (Display) and resource (transient alert) with a clear scope. This clearly distinguishes hs_notify from sibling tools like hs_list_windows or hs_console_tail, which handle different concerns.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The phrase 'Useful for telling the user something without stealing focus' provides clear context for when to use this tool. While it doesn't name alternative tools or explicitly say when not to use it, the context is sufficient given that none of the siblings serve a similar notification purpose.

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

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

With no annotations, the description must carry the full burden. It discloses the result behavior ('The result names the application that actually received the URL') and mentions error cases ('Errors when nothing handles the scheme or macOS refuses'). It does not discuss side effects like app foregrounding or permissions, but for a URL-opening tool 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.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences, front-loaded with the primary action, and uses no filler. Every sentence adds value: the first states the core function and option, the second explains the result and errors while pointing to a sibling tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given two simple parameters, full schema coverage, and no output schema, the description covers all necessary aspects: what it does, how to use it (including the optional parameter), what it returns, and error behavior. The pointer to hs_list_apps completes the workflow.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% as both parameters already have detailed descriptions in the schema. The tool description adds a cross-reference to hs_list_apps for bundle ids, but otherwise repeats schema content. Per the rubric, baseline is 3 since schema covers parameters well.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb and resource: 'Open a URL' with the option to specify a bundle id. It distinguishes from siblings like hs_launch_app (which opens apps without URLs) and hs_list_apps (which lists apps). The purpose 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.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It provides context for when to use it (open a URL by default handler or specific app) and gives an explicit alternative reference ('Use hs_list_apps to find bundle ids'). It also mentions error conditions. However, it does not explicitly state when NOT to use it (e.g., when launching an app directly without a URL), though the sibling scope makes this implicit.

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

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

Annotations already declare readOnlyHint and idempotentHint, covering safety. The description adds specific behavioral details not in annotations, such as listing free space for volumes and whether a camera is in use. It lacks discussion of permissions or latency, but for a read-only list operation, 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.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, fully front-loaded with the core action in the first sentence, and the second provides illustrative use cases. No redundant wording or filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the simplicity (no parameters, no output schema, read-only), the description fully covers what the tool does and what it returns. It even anticipates common questions, making it self-contained for an agent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, so the schema trivially covers everything. The description explains what will be returned, which serves as the semantic content. Baseline for 0 params is 4, and the description adds value by specifying the output categories.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool lists USB devices, cameras (including usage status), and mounted volumes with free space, and provides concrete example questions it answers. This distinctly differentiates it from sibling tools like hs_machine_status or hs_network.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives practical use cases ('Answers questions like whether an external drive is mounted or whether the webcam is active'), which implies when to use it. It doesn't explicitly mention alternatives, but the examples provide sufficient context for typical scenarios.

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

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

The description fully discloses the reload scheduling mechanism, the reset of all in-memory state, and the specific interaction with hs_speak (stopping speech and the crash risk if a callback occurs post-reload). This is highly transparent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise (two sentences) and well-structured, covering purpose, usage, and important side effects without unnecessary verbosity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the lack of parameters and output schema, the description thoroughly covers the tool's behavior, scheduling, and edge case with hs_speak, making it complete for the user to understand the tool's implications.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has no parameters, and the description appropriately omits any parameter-related details. There is nothing to explain, so the description fully addresses what the schema provides (an empty schema).

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's function (reload ~/.hammerspoon/init.lua) and specifies when to use it ('after editing the user configuration'). It also explains the purpose of the scheduling and side effects, leaving no ambiguity.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly instructs when to use the tool ('Use after editing the user configuration') and warns about the reset of in-memory state and the speech callback crash risk, providing clear guidance on appropriate usage.

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

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

No annotations are provided, so the description carries full burden. It discloses the background execution, lack of input passing, and that it reports only start, not output. It also mentions failure logs to console. However, it doesn't state if the shortcut can be destructive or require permissions. The behavior is reasonably transparent for a run tool, but there is room for more context (e.g., what happens if shortcut doesn't exist, whether it's blocking).

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise: three sentences that cover purpose, key constraints, and prerequisite. Every sentence adds value: what it does, what it doesn't do (no input), and what to do first. No fluff or repetition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (one parameter, no output schema) and the absence of annotations, the description covers the essential behavior: what it does, how to use it correctly (list first), and what to expect (background start, console logs for failures). It could mention error handling for invalid names, but that's a minor gap. Overall, it is sufficiently complete for a basic run tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%: the parameter 'name' is described as 'Shortcut name from hs_list_shortcuts. A substring is accepted.' The description adds that input cannot be passed and that calling hs_list_shortcuts first is recommended, reinforcing the expected value of the parameter. It also clarifies that a substring is acceptable, which adds nuance beyond the schema's simple string type.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action: 'Run one of the user's macOS Shortcuts by name.' It specifies the resource (user's macOS Shortcuts) and the verb (run), and explicitly differentiates from sibling tools by noting input cannot be passed and that it runs in background. This is distinct from hs_list_shortcuts (listing) and hs_console_tail (viewing logs).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit guidance: 'Call hs_list_shortcuts first to get exact names.' It also explains the tool's limitations (no input, background execution, failure logging to console) and directs to hs_console_tail for errors. This implicitly tells when to use this tool vs alternatives (e.g., use list first, then run; use console tail for debugging).

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

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

Annotations already declare readOnlyHint and idempotentHint, so the description doesn't need to restate them. It adds behavioral detail about coordinate frames (excludes/includes menu bar and Dock), which helps the agent interpret results correctly. Minor gap: no explicit mention of return format, but the frame explanation mitigates this.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences pack purpose, frame semantics, and usage guidance without redundancy. Every word earns its place, and the structure front-loads the main action clearly.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple no-parameter list tool, the description covers what it does, the key output distinction (frame vs fullFrame), and how to apply the result. No output schema exists, but the description sufficiently explains the meaningful data, making it complete for the agent's needs.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has zero parameters, so the baseline is 4. The description adds no parameter-specific info because none exist, but it does explain output semantics that relate to how the tool would be used, which indirectly supports parameter understanding for downstream calls.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states 'List connected screens' with specific verb and resource, and distinguishes from siblings like hs_list_windows by focusing on screens and coordinate frames. The mention of 'frame' and 'fullFrame' adds precision beyond the title.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states a use case: 'Use these bounds when computing arguments for hs_move_window.' This gives clear context for when to use the tool. It doesn't name alternatives, but the tool is unique among siblings for screen listing, so exclusions are less necessary.

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

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

With no annotations, the description carries the burden of disclosing side effects. It mentions persistence and namespacing, which implies potential writes, but does not address error handling, rate limits, or consequences of overwriting keys. This is acceptable 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.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise and well-structured in two sentences. It covers the core purpose, durability, namespacing, and value constraints without unnecessary detail, making it easy to parse.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description provides sufficient context for the tool's simple functionality, including persistence, namespacing, and type constraints. It does not explain each action (get/set/delete/list) but the schema covers those, making the description complete enough for use.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema already provides descriptions for each parameter (action, key, value). The description adds useful context about key namespacing and JSON-compatibility, which augments the schema without redundancy. This extra information justifies above-baseline scoring.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's function: storing small values that survive restarts for persistence between sessions. It differentiates from sibling tools by specifying its role as a key-value store, and the namespacing detail distinguishes it from potential interference with user settings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies when to use this tool—when needing durable storage across sessions—but does not explicitly contrast with alternatives or state when not to use it. However, given the unique nature of the tool among siblings, the context is sufficient for a typical agent.

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

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

With no annotations, the description must disclose behavior on its own. It does so by noting the non-blocking return ('Returns as soon as speech starts') and the interrupt behavior on repeated calls. This goes beyond merely stating 'speak text' and gives the agent actionable behavioral context. It could mention resource requirements (e.g., audio output) but the purpose makes that obvious.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences, front-loaded with the core purpose and followed by two critical behavioral traits. No redundant or filler words; every clause earns its place. It is both concise and informative.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (3 params, all documented, no output schema, no annotations), the description covers the essential aspects: purpose, return timing, and interrupt behavior. It misses minor context like potential error states or prerequisites, but these are not critical for such a straightforward tool. It is adequate for correct selection and invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, with each parameter (text, rate, voice) having descriptive comments. The tool description itself adds no parameter-level detail beyond the schema, so the baseline of 3 applies. It doesn't enhance or contradict the schema, but also doesn't need to given the high schema coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Say something out loud through the Mac speech synthesiser.' It uses a specific verb ('say') and resource ('Mac speech synthesiser'), and the behavioral note about returning early and interrupting distinguishes it from hypothetical alternatives. It is unambiguous and distinct from sibling tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies when to use it (to speak text aloud) and includes an explicit usage note: 'Calling again interrupts whatever is currently being spoken.' It doesn't discuss alternatives or exclusion cases, but given the tool's unique function (speech output) among siblings, sufficient guidance is provided.

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

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

The description is consistent with the readOnlyHint annotation and adds important behavioral context: it never returns the contents of text fields or documents, and each node carries a path usable with hs_ui_press. This gives the agent a clear safety and boundary expectation beyond what annotations alone provide.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is three tight sentences: the first establishes the core action, the second states the practical use case, and the third covers boundary and next step. No wasted words, no redundant repetition of the schema.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool is a read-only inspection utility with a full schema and no output schema, the description adequately explains return shape: structure and labels only, nodes with paths, and nothing from text fields or documents. It gives enough context for an agent to select the tool and understand what it will receive.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the existing parameter descriptions already carry the load for app, role, depth, limit, and contains. The tool description adds framing around the tree structure and filtering intent, but it does not itself provide additional parameter-level details, so the baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Read') and resource ('application's accessibility tree'), enumerates the elements it returns, and explains the practical purpose: finding what is clickable. It clearly distinguishes itself from sibling tools because it is about inspecting the UI structure rather than controlling windows, apps, audio, or media.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly says this is the way to discover what is clickable in an app and what each element is called, giving clear when-to-use context. It doesn't mention explicit exclusions or alternatives, though no listed sibling is an obvious substitute.

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

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

Beyond the readOnlyHint annotation, the description adds valuable behavioral context about the meaning of radio state and scanned flag, explaining edge cases like radio off or scan failure. This provides operational transparency that helps the agent interpret results correctly.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences, front-loaded with the main output, and adds clarifying edge-case details without unnecessary verbosity. Every sentence adds value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-parameter, read-only tool with no output schema, the description adequately covers the returned information and clarifies ambiguous states. It lacks explicit mention of the network list format, but the core outputs are sufficiently explained.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There are zero parameters, so the schema is trivially complete. The description does not need to explain parameters, and since the baseline is 4 for no parameters, this is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool reports wifi radio state, current network, and scans for available networks. It specifies exactly what information is provided and distinguishes this from general network tools by focusing on wifi-specific details.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explains what the tool does but provides no guidance on when to use it versus alternatives like hs_network, nor any exclusions or prerequisites. Usage context is only implied by the tool name and mention of wifi.

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

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 meaningful behavioral traits: the tool defaults to the focused window and respects the menu bar and Dock insets. It does not cover error handling, permissions, or reversibility, but for a simple window-snapping action these are less critical. The disclosed behaviors add value beyond the schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise sentences that are front-loaded with the primary action. Every word serves a purpose: examples clarify presets, the screen-size note explains the benefit, and the default/inset behaviors are essential context. No redundant or filler content.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple action tool without an output schema, the description provides sufficient context: what it does, how positions are computed, default target, and screen boundary handling. It could mention edge cases (e.g., invalid window ID), but these are not essential for a basic layout preset operation. The tool feels adequately specified.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with descriptive parameter text, especially for windowId and screenIndex. The description reiterates the windowId default (focused window) but does not add new parameter-level detail beyond what the schema already states. Since the schema fully documents all parameters, a baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states it snaps a window to a named position, provides specific preset examples (left-half, quarter-top-left), and distinguishes itself from coordinate-based tools by emphasizing that it computes positions from screen size, eliminating the need for pixel arithmetic. This makes the tool's purpose unambiguous and differentiates it from siblings like hs_move_window.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description conveys the intended use case (preset layout snapshots) and notes that it defaults to the focused window, which is helpful. It stops short of explicitly stating when to use this tool versus hs_move_window or other alternatives, but the 'no pixel arithmetic needed' phrasing implies a simpler, preset-driven approach. This is clear context without explicit exclusions.

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