macos-mcp-automation

by rzafiamy

Overview Schema Related Servers Score Discussions

TypeScript

Local

Server Quality Checklist

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

Latest release: v1.0.0
Disambiguation5/5
Each tool targets a distinct macOS feature or action, such as clipboard get/set, app lifecycle, volume control, or keyboard input. The generic `run_applescript` is explicitly for custom automation and does not overlap with the high-level wrappers, so there is no real ambiguity between tools.
Naming Consistency4/5
Most tools follow a clear verb_noun snake_case pattern (e.g., `open_app`, `set_volume`, `create_note`). The only deviation is `spotlight_search`, which is noun_verb rather than verb_noun, making it a minor inconsistency.
Tool Count4/5
With 21 tools, the server is above the typical compact range but justifiably so for a broad macOS automation suite covering clipboard, app control, display, input, browser, and Apple app integration. Each tool has a distinct purpose, so the count feels appropriate rather than bloated.
Completeness4/5
The tools cover core automation workflows: app management, keyboard/mouse simulation, clipboard, screenshots, volume/brightness, lock/sleep, file search, window/browser access, and Apple app shortcuts. Minor gaps like a `get_brightness` tool or email sending are not critical dead ends for typical automation tasks.
Average 3.9/5 across 21 of 21 tools scored. Lowest: 3.3/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 5 commits in the last 12 weeks
- No stable releases found
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI status not available
This repository is licensed under MIT License.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
Add a glama.json file to provide metadata about your server.
If you are the author, simply .
If the server belongs to an organization, first add glama.json to the root of your repository:
```
{
  "$schema": "https://glama.ai/mcp/schemas/server.json",
  "maintainers": [
    "your-github-username"
  ]
}
```
Then . Browse examples.
Add related servers to improve discoverability.

How to sync the server with GitHub?

Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.

To manually sync the server, click the "Sync Server" button in the MCP server admin interface.

How is the quality score calculated?

The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).

Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.

Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).

Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.

Tool Scores

Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry behavioral transparency. It merely states 'Opens a web URL link' without noting potential side effects, prerequisites (e.g., browser installation), or whether it blocks or returns a status. This is a minimal disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with 14 words, immediately stating the core action and supported browsers. No filler or redundant details are present.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple action with a fully documented schema, the description is minimally viable but lacks context about failure modes, return behavior, or when to prefer this over sibling tools like run_applescript or open_app. This is a clear gap for an unannotated tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already fully describes both parameters (url and browser) with 100% coverage. The description adds little beyond restating the browser options ('Safari, or Chrome'), which duplicates the enum values. It provides no additional semantics such as URL format expectations or default-browser behavior.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the tool 'Opens a web URL link in the default browser, Safari, or Chrome,' clearly indicating a specific verb ('Opens') and resource (web URL) with browser options. This distinguishes it from sibling tools like open_app, which open applications rather than URLs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no explicit when-to-use guidance, alternatives, or exclusions. It only describes the action and browser choices, leaving the agent to infer appropriate usage from the tool name and schema.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It reveals that the tool simulates key presses and lists supported keys/modifiers, but it does not disclose potential side effects (e.g., triggering shortcuts that could be destructive), required permissions, or whether the input is directed to the active application. This is basic transparency but lacks depth.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence that front-loads the action. It is concise with no filler or redundancy, earning a top score.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple input tool, the description is minimally viable given the rich schema. However, it omits any mention of return behavior, side effects, or when to use this instead of sibling tools. The lack of annotations means the description should compensate, but it does not fully do so, leaving it adequate but incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers 100% of parameters with descriptions, so the baseline is 3. The description's list of keys (enter, tab, space, escape, backspace) adds some examples but is actually less comprehensive than the schema's key description, which also includes 'c' and 'v'. Modifiers are already enumerated in the schema's enum, so the description adds no new meaning beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool simulates key presses with a specific list of keys and modifiers, using the verb 'Simulates' and the resource 'key'. It is distinct from sibling tools like type_text, but it does not explicitly differentiate itself from them, so it misses the highest score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool versus alternatives. It does not mention any exclusions, prerequisites, or scenarios where it is preferred over type_text or other input tools. Usage is merely implied by the action description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. However, it only states the basic function and does not mention important behavioral traits such as potential destructive side effects, permission requirements, or error behavior. For a tool that executes arbitrary code, 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that is front-loaded with the core action. It contains no unnecessary information and is appropriately sized for the tool's simplicity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no output schema and no annotations, and the description does not explain what the tool returns, how errors are handled, or what side effects may occur. Given the arbitrary code execution nature of the tool, the description is incomplete for an agent to use it reliably.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage for the single parameter 'script', which is described as 'The raw AppleScript code to execute on macOS.' The description adds no additional meaning beyond what the schema already provides, matching the baseline for full schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool executes raw AppleScript code on macOS for custom system automation. It uses a specific verb ('Executes') and resource ('raw AppleScript code'), effectively distinguishing it from sibling tools which perform specific system actions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance is provided on when to use this tool versus alternative sibling tools. The phrase 'custom system automation' implies it is intended for tasks not covered by the specific automation tools, but no explicit alternatives or exclusions are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits, but it only states the action and range. It does not mention side effects (e.g., system-wide change), permissions, or failure conditions. The range is already in the schema, so the description adds no behavioral context beyond the action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that is concise and free of filler. Every word contributes to defining the tool's action and scope.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter tool, the description is minimally adequate, but it lacks behavioral details such as whether the volume change affects the default output device or requires permissions. The gaps are not severe but exist, especially with no annotations or output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% (volume parameter fully specified with type, min, max, and description). The description repeats '0 to 100' but adds no new meaning. Baseline 3 applies because the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Sets') and resource ('macOS audio output volume') with clear scope ('percentage 0 to 100'). It unambiguously distinguishes itself from the sibling tool get_volume, which reads volume.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when the user wants to change the volume, but it does not explicitly mention alternatives or exclusions. Since there is a get_volume sibling, the contrast is obvious but not stated. No when-not-to-use guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full behavioral burden. It states the action (copying text) but does not disclose side effects like overwriting existing clipboard content or any platform-specific requirements beyond 'macOS.' For a simple mutation tool, this is acceptable but not fully transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence that immediately states the action and target. No unnecessary words or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with one parameter and no output schema. The description adequately explains the core function, though it lacks usage guidance and explicit side-effect disclosure. For this simple tool, it is reasonably complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with the sole parameter 'text' fully described in the schema. The description adds no additional meaning beyond the schema, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly uses the specific verb 'Copies' with a specific resource 'text string to the macOS system clipboard.' This distinguishes it from sibling tools like clipboard_get and type_text.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as clipboard_get or type_text. It does not mention any exclusions or preferred contexts, leaving the agent to infer usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It states a read operation but does not disclose any potential limitations, side effects, or prerequisites. For instance, it doesn't mention whether the tool could fail or what happens when there is no active window.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence that immediately states what the tool does. It is concise and well-structured with no redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no parameters and no output schema, the description covers the essential return information (application name and window title). It is sufficiently complete for a simple getter, though it could mention edge cases like empty windows or error conditions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters, so there is nothing to document. The description correctly does not attempt to add parameter details, aligning with the baseline for parameterless tools.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the action ('Gets') and the resource (application name and window title of the frontmost active window). It is unambiguous and distinct from sibling tools about opening or closing apps, making it easy to understand the tool's purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given about when to use this tool versus alternatives like listing apps or getting browser tabs. The usage context is implied as a simple getter, but there are no explicit conditions, prerequisites, or exclusions mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses the platform (macOS) and the presentation style (banner), which is useful context. However, it does not mention potential permission requirements, transient nature of the banner, or any side effects. Since no annotations exist, the description carries the burden but leaves some gaps in behavioral transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that states the action and key elements without any filler. Every word contributes to understanding the tool's purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity and the full schema, the description covers the essential purpose and content. It lacks information about permissions or return values, but for a display notification tool these are less critical and the overall context is adequately complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides full descriptions for all three parameters and a default for title, so the description adds little beyond restating the fields. With 100% schema coverage, the baseline of 3 is appropriate, and the description does not enrich parameter understanding further.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Displays') and a clear resource ('native macOS banner notification'), which clearly distinguishes it from sibling tools like clipboard or app control. It also lists the content types (title, subtitle, body text), making the tool's function unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for showing user-facing notifications but provides no explicit guidance on when to use this tool versus alternatives, nor any exclusions or prerequisites. It is serviceable but does not actively guide the agent on decision-making.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries responsibility for behavioral disclosure. It communicates both normal quit and force-close modes, but does not warn about potential unsaved-data loss, permissions, or behavior if the app is not running. This is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one concise sentence with no filler; every phrase ('Quits or force-closes', 'running macOS application', 'by name') earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter tool, the description covers the core operation and selection criterion (app name), and the schema documents the optional force flag. It lacks minor context about no-op/error behavior, but is otherwise sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already describes both parameters fully (100% coverage), so the description need not add parameter details. It adds no significant semantics beyond the schema's 'Whether to force quit' and app name description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Quits or force-closes'), the target ('a running macOS application'), and the method ('by name'). It effectively distinguishes the tool from sibling tools like open_app and list_apps.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for terminating applications, but it does not explicitly state when to prefer it over alternatives (e.g., run_applescript or open_app) or when not to use force quit. No exclusions or alternative tool references are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of disclosure. It states the action and its instantaneous nature, but does not mention potential side effects, security implications, or session requirements. For a simple lock action, this is adequate but not detailed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that delivers the essential information without wasted words. It is front-loaded with the action and object.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity—no parameters, no output schema, and a straightforward action—the one-line description is fully complete. No additional context is necessary for an agent to understand what invoking this tool does.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, and the schema confirms this with 100% coverage of an empty object. Per the baseline for 0-parameter tools, a score of 4 is appropriate since there is no parameter information to add.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific action: 'Instantly locks the macOS user screen.' This is a direct, unambiguous verb+resource statement that distinguishes it from siblings like sleep_mac, which has a different effect.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. The description does not mention exclusions, prerequisites, or comparisons to related tools such as sleep_mac.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full burden. It states the core behavior (adjusting up/down by steps) but does not mention potential side effects (e.g., if the brightness range is clamped), permission requirements, or impact on connected displays. For a simple tool this is adequate, but it lacks some nuanced behavioral disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficiently worded sentence that immediately states the core functionality. There is no redundant or filler content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with two well-documented parameters and no output schema, the description covers the essential behavior. It does not explain edge cases (e.g., behavior at minimum/maximum brightness) or return values, but such details are not critical for a basic adjustment action. The description is sufficient for an agent to select and invoke the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%: both 'direction' and 'steps' have descriptions in the schema. The tool description adds nothing beyond rephrasing the same information. Since the schema already fully documents the parameters, the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'adjusts' with a clear resource 'screen brightness' and specifies the action scope ('up or down by a specified number of steps'). This clearly distinguishes it from sibling tools like set_volume or get_volume, which are for audio.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The tool provides clear context: it is for adjusting screen brightness incrementally. There are no alternative brightness tools among siblings, so there is no ambiguity about when to use it. It does not explicitly state exclusions, but the purpose is straightforward and the context makes usage obvious.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden of behavioral disclosure. It does clarify that the tool only drafts (does not send) and that it opens Apple Mail, but it does not mention whether Apple Mail must already be running, or any side effects like app activation. This is adequate but not 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that front-loads the core purpose and immediately lists the optional parameters. No unnecessary words or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with three optional parameters and no output schema, the description provides sufficient context about what the tool does and what inputs it accepts. It could mention behavior when all parameters are omitted, but that is minor given the simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description goes beyond the schema by explicitly listing all three parameters ('recipient', 'subject line', 'body message content') and reinforcing they are optional, which adds meaningful context for the agent.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Drafts and opens an email in Apple Mail' with specific optional parameters (recipient, subject, body). It uses a specific verb ('drafts' and 'opens') and names the target resource (Apple Mail email), which distinguishes it from sibling tools like 'create_note' that operate on different content.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for composing email drafts but does not explicitly state when to use it versus alternatives or when not to use it. There is no direct sibling email tool, so the usage context is somewhat implied rather than explicitly guided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits. It states it 'creates and saves a new note,' but does not mention potential side effects, dependencies (e.g., Apple Notes must be running), or behavior on duplicate titles. For a straightforward creation action, this is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is direct and correctly front-loaded with the action and resource. There is no filler or wasted words, making it highly efficient for an AI agent to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is low complexity with 3 simple parameters and no output schema. The description covers the core functionality, but it does not mention what happens on success or failure (e.g., return value). Since the operation is a simple create, this is a minor gap, making the description mostly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for all three parameters. The description's mention of 'title, body content, and optional folder' only restates what the schema already provides, adding no extra semantic meaning. Baseline 3 is appropriate since the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific action ('Creates and saves a new note') on a specific resource ('native Apple Notes application'). It also lists the key components (title, body, optional folder), making it easy to distinguish from sibling tools like create_email_draft.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context: this tool is used for creating a note in Apple Notes. While it doesn't explicitly mention alternatives or when-not-to-use, the purpose implies its primary use case. It lacks explicit exclusions or comparisons to similar tools like run_applescript, so a score of 4 is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. The verb 'Retrieves' implies a read-only operation, and the description specifies the data types returned (titles and URLs). However, it does not mention edge cases such as browser unavailability or empty results, nor does it explicitly state non-destructiveness.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that directly states the purpose and scope. Every word earns its place, with no redundant qualifiers or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one optional parameter and no output schema, the description is fairly complete. It tells the agent what will be retrieved (titles and URLs) and the browser options. The lack of an output schema might make the exact response format unclear, but given the low complexity, the description is adequate for selection and basic invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already provides a description for the 'browser' parameter ('Which browser tabs to fetch') and a default value of 'both'. The tool description does not add additional semantic detail beyond restating the available options. Since schema coverage is 100%, the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Retrieves') and identifies the exact resource ('all open browser tab titles and URLs') along with the scope ('from Safari, Chrome, or both'). This clearly distinguishes the tool from siblings like open_browser_url, which opens URLs rather than retrieving tabs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description makes it clear when to use this tool: when you need to fetch browser tab information. It explicitly names the included browsers and the 'both' option, but does not mention alternatives or exclusions. Since no direct sibling performs a similar function, this is adequate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It adds a key behavioral detail by specifying 'visible' applications, which distinguishes from all running apps. However, it does not disclose whether minimized windows count as visible, what the return format is, or whether the list contains names, bundle IDs, or other identifiers. This leaves some behavioral transparency gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that immediately states the action and scope. It contains no redundant words or fluff, making it highly efficient and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with one optional parameter and no output schema, the description is mostly complete for an agent to understand the operation. It clearly states what is listed (visible apps) and the platform (macOS). However, it does not describe the return value structure, which could be important for downstream processing, but this is a minor gap for such a straightforward tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already has 100% coverage for the single parameter 'onlyVisible' with a clear description. The tool description does not add any extra meaning about this parameter beyond what the schema provides. Baseline of 3 applies since schema coverage is high and the description does not contribute additional parameter context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Lists' and identifies the resource as 'all currently open visible user applications running on macOS,' which precisely states what the tool does. It distinguishes itself from sibling tools like open_app, quit_app, and get_active_window by focusing on enumerating all open visible apps rather than manipulating or querying a single app.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies a clear use case: when an agent needs to know which user applications are currently open and visible on macOS. It does not explicitly mention alternatives or exclusions, but the context is clear given the simple list-oriented function.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description carries the burden of disclosing behavior. It does add value by specifying 'or brings to front', indicating behavior when the app is already running. However, it does not mention error conditions, permissions, or what happens when the app name is invalid, leaving some gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence that conveys the action, resource, and examples without any filler. Every word earns its place, making it highly efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter tool with no output schema, the description covers the core behavior (launch/focus) and provides examples. It lacks mention of error handling or prerequisite actions like listing apps, but the tool is simple enough that this is acceptable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a clear appName description, but the tool description adds concrete examples (Safari, Mail, Terminal, Spotify) that clarify what constitutes a valid app name. This goes beyond the schema and helps resolve ambiguity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific action ('Launches or brings to front') on a specific resource ('a macOS application by name'), with concrete examples (Safari, Mail). This directly distinguishes it from sibling tools like quit_app (opposite action) and list_apps (different purpose).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context: use this when you need to open or focus a macOS app by its name. However, it does not explicitly state when not to use it or mention alternative tools like list_apps for discovering names, so guidance is only implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must convey the tool's behavioral profile. It accurately notes the use of the Spotlight index via mdfind, which implies a read-only search operation and reliance on indexed data. However, it does not disclose details like result format (file paths), potential staleness of the index, or that it only returns paths, leaving some behavioral ambiguity. The addition of 'mdfind' provides moderate value beyond a generic search statement.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that efficiently conveys the tool's purpose and mechanism. No filler or redundant language; every word adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the tool (one required param, three total), no output schema, and no annotations, the description sufficiently covers the core functionality. It explains what it searches, how (Spotlight/mdfind), and via the schema covers parameter semantics. It could mention that results are file paths, but this is largely implied. Overall, it is complete for a straightforward search tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage for all three parameters with clear descriptions. The tool description adds no new parameter-specific details beyond what the schema already defines. Baseline of 3 applies because the schema fully documents the parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Searches') and a clear resource ('macOS file system for files using Spotlight index (mdfind)'). It clearly distinguishes from all sibling tools, none of which perform file search. The mention of 'mdfind' further reinforces the exact mechanism.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for searching files on macOS, and since no sibling tool offers similar search functionality, the intended use is clear. However, it does not explicitly mention when not to use it or alternative approaches, but the context makes the purpose unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It states the core behavior (typing text at the cursor) but does not disclose potential failure modes such as requiring an active text field or handling of special characters.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, tightly written sentence with no redundant information. Every word adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter tool with no output schema, the description adequately explains what it does and where. It is complete for typical use, though it could benefit from noting the need for an active input field.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description fully covers the only parameter (text: 'The text content to simulate typing'), and the description adds no additional parameter semantics beyond contextualizing the action.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Simulates keyboard typing') and identifies the resource ('active text cursor position'), clearly distinguishing it from sibling tools like press_key_combination and clipboard_set.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'at the active text cursor position' provides clear context for when to use the tool, implying a text input field must be focused. However, it does not explicitly mention when not to use it or name alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of disclosing behavior. It clearly states the system will be put to sleep, which is the core side effect. It does not mention immediate execution or lack of confirmation, but for a zero-parameter, low-risk action the transparency is adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler. Every word contributes to the meaning, making it appropriately sized for a trivial tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no parameters, no output schema, and no annotations, the description fully covers the necessary information. A user or agent can understand exactly what action will be performed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and 100% schema coverage (empty object). Since there are no parameters to explain, the description need not add parameter details; the baseline for zero-parameter tools is 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Puts the macOS system to sleep' uses a specific verb ('puts') and a clear resource ('macOS system to sleep'). It unambiguously states the tool's action and is distinct from sibling tools like lock_screen.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given about when to use this tool versus alternatives such as lock_screen or other system controls. The description only states what it does, without offering context or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses important behavioral details: it operates 'silently' and returns the result as an image. However, it does not mention potential permissions (e.g., screen recording access) or any side effects, leaving some behavioral aspects undisclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that immediately conveys the action and outcome. There is no redundancy or filler, making it highly efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a no-parameter tool with no output schema, the description covers the core behavior and return format sufficiently. It tells the agent exactly what to expect without needing further elaboration.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and the schema is empty, so the description has no parameter meaning to add. With no parameters, the baseline is 4, and the description adequately avoids fabricating parameter details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('captures') and the resource ('desktop screenshot'), and specifies the output ('returns it to the client as an image'). It is unambiguous and distinct from sibling tools, which focus on other system actions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the primary use case (taking a screenshot) but does not explicitly state when to use it relative to other tools or any exclusions. No alternatives are mentioned, so guidance is implicit rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description serves as the main behavioral disclosure. It clearly states a read operation, implying no modification to the clipboard. However, it does not mention edge cases such as empty clipboard or non-text content, which would provide fuller transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no wasted words. It immediately states the action and target, making it optimally concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's extreme simplicity (no parameters, no annotations, no output schema), the one-sentence description fully covers what the tool does. There is no missing information required for an agent to select and invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and the schema coverage is effectively 100% (empty schema is fully covered). Per guidelines, a baseline of 4 is appropriate since there are no parameter details to elaborate on.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Reads') and identifies the exact resource ('text content currently stored in the macOS system clipboard'). It clearly distinguishes from sibling tools like clipboard_set, which would write to the clipboard.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The intended usage is implied by the tool name and description, but there is no explicit guidance about when to use this tool versus alternatives like clipboard_set or run_applescript. No exclusions or alternative references are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. The verb 'Gets' clearly indicates a read-only operation with no side effects, and the mention of 'percentage' discloses the output unit. It does not explicitly state that it does not modify state, but the phrasing is sufficient for a simple read tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with zero wasted words. It delivers all necessary information compactly and is easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a low-complexity tool with no parameters and no output schema. The description tells the agent exactly what it does and what it returns (volume percentage), making it fully self-contained for correct invocation and interpretation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema is empty with 0 parameters, so schema coverage is 100% and there is nothing for the description to add. Per the baseline rule for 0-param tools, a score of 4 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Gets') and a clear resource ('current macOS audio output volume percentage'). It unambiguously distinguishes this from its sibling tool set_volume, making its purpose immediately obvious.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool (when you need the current volume), but it does not explicitly state alternatives or exclusions. With a simple getter, usage context is fairly obvious, but there is no explicit 'use this instead of set_volume' guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

GitHub Badge

Glama performs regular codebase and documentation scans to:

Confirm that the MCP server is working as expected.
Confirm that there are no obvious security issues.
Evaluate tool definition quality.

Our badge communicates server capabilities, safety, and installation instructions.

Card Badge

Copy to your README.md:

[![macos_mcp MCP server](https://glama.ai/mcp/servers/rzafiamy/macos_mcp/badges/card.svg)](https://glama.ai/mcp/servers/rzafiamy/macos_mcp)

Score Badge

Copy to your README.md:

[![macos_mcp MCP server](https://glama.ai/mcp/servers/rzafiamy/macos_mcp/badges/score.svg)](https://glama.ai/mcp/servers/rzafiamy/macos_mcp)

Latest Blog Posts

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

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/rzafiamy/macos_mcp'

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