Integrates with Apple's native Notes application to programmatically create, list, and read notes and folders.
Provides a comprehensive suite of tools for interacting with macOS system features, including file and folder dialogs, clipboard management, Finder integration, system notifications, screenshots, and utilities for image and PDF processing.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@macOS MCP Server Take a screenshot of my full screen and save it to the desktop"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
An MCP (Model Context Protocol) server for macOS system operations: file dialogs, clipboard, notifications, and Finder integration.
File Dialogs: Open file/folder pickers, save dialogs, multiple selection
Clipboard: Read and write text to system clipboard
System: Notifications, open URLs, get system info
Finder: Reveal files, open with default app, get current selection
Related MCP server: macos-computer-use-mcp
Tool | Description |
| Open file picker, return selected path |
| Open folder picker, return selected path |
| Multiple file selection |
| Save file dialog with default name |
Tool | Description |
| Get clipboard text content |
| Set clipboard text content |
Tool | Description |
| Display system notification |
| Open URL in default browser |
| Get macOS version, hostname, username |
| Get screen dimensions and scale factor |
Tool | Description |
| Reveal path in Finder |
| Open file with default app |
| Get currently selected files in Finder |
| Open file with Quick Look preview |
Tool | Description |
| Take screenshot (full screen, region, or window) |
| Screenshot to clipboard |
Tool | Description |
| Get image metadata (dimensions, format, etc.) |
| Resize image (width, height, or max size) |
| Convert between formats (jpeg, png, gif, tiff, bmp, heic) |
Tool | Description |
| Get number of pages in PDF |
| Merge multiple PDFs into one |
Tool | Description |
| Create a new note |
| List all folders |
| List notes in a folder |
| Read note content by ID |
Clone and build:
git clone https://github.com/alexlock1/macos-mcp-server.git
cd macos-mcp-server
npm install
npm run buildAdd to your MCP settings (e.g., .mcp.json or Claude Desktop config):
{
"mcpServers": {
"macos": {
"command": "node",
"args": ["/path/to/macos-mcp-server/dist/index.js"]
}
}
}macos_pick_file({
prompt: "Select a document",
fileTypes: ["pdf", "doc", "docx"]
})macos_clipboard_write({ text: "Hello, World!" })macos_notify({
title: "Task Complete",
message: "Your file has been processed",
sound: "Glass"
})macos_system_info({})
// Returns: { computerName, userName, homeDirectory, osVersion }macos_reveal_in_finder({ path: "/Users/me/Documents/report.pdf" })macos_screenshot({
path: "/tmp/screenshot.png",
fullScreen: true
})macos_image_resize({
inputPath: "/path/to/image.png",
outputPath: "/path/to/resized.png",
maxSize: 800
})macos_pdf_page_count({ path: "/path/to/document.pdf" })macos_note_create({
name: "Meeting Notes",
body: "Discussion points...",
folder: "Work"
})Node.js 18+
macOS (uses AppleScript for all operations)
All operations use AppleScript via osascript to interact with macOS system features. This provides native dialog appearances and full system integration.
MIT
Read the current text content from the system clipboard.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
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 tool reads text content, but does not disclose behavioral traits such as error handling (e.g., if clipboard is empty), permissions required, or format limitations (e.g., non-text content). This leaves gaps in understanding how the tool behaves in edge cases.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that directly states the tool's purpose with zero waste. It is appropriately sized for a simple tool with no parameters, making it easy to understand 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?
Given the tool's simplicity (0 parameters, no output schema, no annotations), the description is adequate but incomplete. It covers the basic purpose but lacks details on return values (e.g., text format, empty cases) and behavioral context, which are needed for full agent understanding despite the low 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 has 0 parameters, with 100% schema description coverage. The description does not need to add parameter details, and it appropriately avoids unnecessary information. A baseline of 4 is applied as it efficiently handles the lack of parameters without redundancy.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Read') and resource ('current text content from the system clipboard'), distinguishing it from sibling tools like 'macos_clipboard_write' (which writes) and 'macos_screenshot_clipboard' (which captures screenshots). It precisely defines what the tool does without ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for reading text from the clipboard, but does not explicitly state when to use this tool versus alternatives (e.g., 'macos_screenshot_clipboard' for image content or 'macos_get_finder_selection' for file selections). It provides basic context but lacks explicit guidance on exclusions or comparisons.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Write text content to the system clipboard.
| Name | Required | Description | Default |
|---|---|---|---|
| text | Yes | Text to copy to clipboard |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It states the basic action but doesn't describe important traits: whether this overwrites existing clipboard content, if there are size limitations, if it requires specific permissions, or what happens on success/failure. For a mutation tool with zero annotation coverage, this leaves significant gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that communicates the core purpose without unnecessary words. It's appropriately sized for a simple tool and front-loads the essential information immediately.
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 mutation tool with one parameter and no output schema, the description covers the basic purpose adequately. However, with no annotations and no output schema, it should ideally mention what happens after writing (e.g., success confirmation, error conditions) or system-specific considerations for macOS clipboard operations.
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 the single parameter 'text' well-documented in the schema. The description adds no additional parameter information beyond what's already in the structured schema. With high schema coverage, the baseline score of 3 is appropriate as the description doesn't compensate but doesn't need to.
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 ('Write') and target resource ('text content to the system clipboard'), making the purpose immediately understandable. It distinguishes from obvious siblings like 'macos_clipboard_read' by specifying the write operation, though it doesn't explicitly differentiate from all clipboard-related tools like 'macos_screenshot_clipboard'.
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 no guidance on when to use this tool versus alternatives. It doesn't mention when writing to the clipboard is appropriate compared to other clipboard operations or file operations, nor does it specify prerequisites like macOS-specific requirements or user permissions needed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the currently selected files/folders in the frontmost Finder window.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It states what the tool does but lacks behavioral details such as permissions needed, whether it requires Finder to be active, error handling, or the format of the returned data. This is a significant gap for a tool with zero annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the key information ('Get the currently selected files/folders') with no wasted words. It is appropriately sized for a simple tool with no parameters.
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 (0 parameters, no annotations, no output schema), the description is minimally complete but lacks details on behavioral aspects like return format or dependencies. It covers the basic purpose but could benefit from additional context for full agent understanding.
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 0 parameters, and schema description coverage is 100%, so no parameter information is needed. The description does not add parameter semantics, but with no parameters, the baseline is 4 as it adequately addresses the tool's purpose without unnecessary details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Get') and resource ('currently selected files/folders in the frontmost Finder window'), distinguishing it from siblings like macos_pick_file or macos_reveal_in_finder by focusing on current selection rather than user interaction or navigation.
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 when needing to retrieve the current Finder selection, but it does not explicitly state when to use this tool versus alternatives like macos_pick_file (for selecting new files) or provide exclusions. The context is clear but lacks explicit guidance on alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Convert image to another format (jpeg, png, gif, tiff, bmp, heic).
| Name | Required | Description | Default |
|---|---|---|---|
| inputPath | Yes | Path to input image | |
| outputPath | Yes | Path for output image | |
| format | Yes | Target format |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It mentions the conversion action but lacks behavioral details: it doesn't specify if it overwrites existing output files, handles errors (e.g., invalid paths), requires specific permissions, or has performance constraints. For a mutation tool with zero annotation coverage, this is a significant gap in transparency.
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, efficient sentence that front-loads the core functionality ('Convert image to another format') and includes the supported formats in parentheses. There is no wasted verbiage, repetition, or unnecessary elaboration—every word serves a clear purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (file mutation with three parameters), lack of annotations, and no output schema, the description is incomplete. It doesn't cover behavioral aspects (e.g., file overwriting, error handling), usage context, or output details. For a mutation tool, this leaves critical gaps for an AI agent to understand how 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 schema fully documents all three parameters (inputPath, outputPath, format) with descriptions and enum values. The description adds minimal value beyond the schema by listing the format options, but doesn't provide additional context like format-specific considerations or path requirements. Baseline 3 is appropriate when the schema does the heavy lifting.
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 ('Convert image') and resource ('to another format'), specifying the supported formats. It distinguishes from sibling tools like macos_image_info (inspection) and macos_image_resize (dimension change), but doesn't explicitly contrast them. 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?
No guidance is provided on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., file existence, permissions), compare with other image tools (e.g., macos_image_resize for size changes), or indicate typical workflows. The description only states what it does, not when or why to invoke it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get image metadata: dimensions, format, color space, bit depth.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Path to image file |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the tool retrieves metadata but does not cover error handling (e.g., invalid paths), performance aspects, or output format details. This leaves significant gaps for a tool that interacts with the file system.
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, efficient sentence that front-loads the core purpose ('Get image metadata') and lists specific metadata types without unnecessary words. Every part of the sentence contributes directly to understanding the tool's function.
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 low complexity (one parameter, 100% schema coverage) and lack of annotations or output schema, the description is minimally complete. It specifies what metadata is retrieved but omits details on return structure, error cases, and operational constraints, which are important for a file-based tool with no annotations.
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 description coverage is 100%, with the 'path' parameter clearly documented in the schema. The description does not add any additional meaning or context beyond what the schema provides, such as file format support or path validation rules, so it meets the baseline for adequate but minimal parameter information.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Get image metadata') and enumerates the exact types of metadata returned (dimensions, format, color space, bit depth), which distinguishes it from sibling tools like macos_image_convert or macos_image_resize that perform different operations on images.
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 no guidance on when to use this tool versus alternatives. It does not mention prerequisites (e.g., file existence), exclusions, or comparisons with other image-related tools like macos_image_convert, leaving the agent to infer usage context solely from the tool name and description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Resize an image. Specify width, height, or maxSize to maintain aspect ratio.
| Name | Required | Description | Default |
|---|---|---|---|
| inputPath | Yes | Path to input image | |
| outputPath | Yes | Path for output image | |
| width | No | Target width in pixels | |
| height | No | Target height in pixels | |
| maxSize | No | Maximum dimension (maintains aspect ratio) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. While it mentions that maxSize 'maintains aspect ratio,' it doesn't clarify what happens when both width and height are specified (does it stretch or maintain ratio?), what image formats are supported, whether the operation overwrites existing files, or what happens on errors. For a mutation tool with zero annotation coverage, this leaves significant behavioral questions unanswered.
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 extremely concise (one sentence) and front-loaded with the core purpose. Every word earns its place, with no redundant information or unnecessary elaboration.
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 an image manipulation tool with 5 parameters, no annotations, and no output schema, the description is insufficient. It doesn't explain what happens when multiple dimension parameters conflict, what image formats are supported, whether the operation is destructive to the original file, or what the output looks like. Given the complexity and lack of structured documentation elsewhere, the description should provide more complete context.
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 description coverage is 100%, so all parameters are documented in the schema. The description adds minimal value by mentioning the three dimension parameters (width, height, maxSize) and noting that maxSize maintains aspect ratio, but doesn't provide additional context beyond what's already in the schema descriptions. This meets the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Resize an image') and specifies the key parameters (width, height, maxSize) that control the operation. It distinguishes itself from sibling tools like 'macos_image_convert' by focusing specifically on resizing rather than format conversion, though it doesn't explicitly mention this distinction.
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 no guidance on when to use this tool versus alternatives like 'macos_image_convert' for format changes or other image manipulation tools. It mentions parameter options but doesn't explain trade-offs between width/height versus maxSize, or when one approach might be preferred over another.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new note in the Notes app.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Note title | |
| body | Yes | Note content | |
| folder | No | Folder name (defaults to 'Notes') |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states 'Create a new note' which implies a write operation, but doesn't describe what happens on success/failure, whether it requires specific permissions, or any side effects (e.g., if the note appears immediately in the app). For a mutation tool with zero annotation coverage, this is insufficient.
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, efficient sentence that directly states the tool's purpose without any fluff. It's front-loaded and wastes no words, making it easy to parse quickly. Every word earns its place by conveying essential 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 this is a mutation tool with no annotations and no output schema, the description is incomplete. It doesn't explain what the tool returns (e.g., success confirmation, note ID), error conditions, or behavioral details like whether the folder must exist. For a 3-parameter write operation, more context is needed to guide effective 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?
Schema description coverage is 100%, with clear descriptions for all three parameters (name, body, folder). The description adds no additional parameter semantics beyond what's in the schema, such as format constraints or examples. With high schema coverage, the baseline score of 3 is appropriate as the schema does the heavy lifting.
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 ('Create') and resource ('a new note in the Notes app'), making the purpose immediately understandable. It distinguishes from sibling tools like macos_note_list or macos_note_read by specifying creation rather than listing or reading. However, it doesn't explicitly contrast with macos_note_folders, which is a minor gap.
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 no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., Notes app must be available), when not to use it (e.g., for updating existing notes), or refer to sibling tools like macos_note_list for context. Usage is implied by the action but not explicitly defined.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all folders in the Notes app.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It states it's a list operation, implying read-only behavior, but doesn't mention permissions, rate limits, or what the output looks like (e.g., format, pagination). For a tool with zero annotation coverage, this is insufficient to inform the agent adequately.
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, clear sentence with no wasted words, front-loading the core action and resource. It's appropriately sized for a simple tool with no parameters, making it easy for an agent to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity (0 parameters, no output schema, no annotations), the description is minimally adequate but lacks depth. It explains what the tool does but doesn't cover behavioral aspects like output format or constraints, which could be helpful despite the simplicity. It's complete enough for basic use but leaves gaps in transparency.
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 0 parameters, and schema description coverage is 100%, so there's no need for parameter details in the description. The baseline for this scenario is 4, as the description appropriately doesn't add unnecessary param info, though it could theoretically note if there are implicit parameters (it doesn't).
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 ('List all folders') and target resource ('in the Notes app'), providing a specific verb+resource combination. However, it doesn't distinguish this tool from its sibling 'macos_note_list', which might also list notes or folders, so it misses full 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 no guidance on when to use this tool versus alternatives like 'macos_note_list' or other note-related tools. It lacks context about prerequisites, exclusions, or specific use cases, offering only a basic statement of function without usage direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all notes in a folder.
| Name | Required | Description | Default |
|---|---|---|---|
| folder | No | Folder name (defaults to 'Notes') |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It states what the tool does but doesn't describe return format (e.g., list structure, note metadata), pagination, error conditions, or permissions needed. For a list operation with zero annotation coverage, this leaves significant gaps in understanding how the tool behaves.
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, efficient sentence that communicates the core purpose without any wasted words. It's appropriately sized for a simple list operation and is front-loaded with the essential 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 no annotations and no output schema, the description is incomplete for a tool that presumably returns a list of notes. It doesn't explain what information is returned about each note (titles, IDs, timestamps) or the structure of the response. For a list operation that agents need to process results from, this leaves too much unspecified.
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 schema fully documents the single parameter (folder name with default). The description adds no additional parameter semantics beyond what's in the schema, but with high coverage, a baseline score of 3 is appropriate as the schema does the heavy lifting.
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 ('List') and resource ('notes in a folder'), making the purpose immediately understandable. It distinguishes from siblings like macos_note_create (create) and macos_note_read (read specific note), though it doesn't explicitly mention the distinction from macos_note_folders (which lists folders rather than notes).
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 no guidance on when to use this tool versus alternatives. It doesn't mention sibling tools like macos_note_folders (for listing folders) or macos_note_read (for reading a specific note), nor does it specify prerequisites or typical use cases beyond the basic action.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read the content of a note by its ID.
| Name | Required | Description | Default |
|---|---|---|---|
| noteId | Yes | Note ID (from macos_note_list) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the tool reads content but doesn't describe what 'content' includes (e.g., text, metadata), potential errors (e.g., if the note ID is invalid), or any side effects. This is a significant gap for a tool with no annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the core action ('Read the content of a note'). There is no wasted language, and it directly communicates the tool's function without unnecessary details.
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 complexity (a read operation with no annotations and no output schema), the description is incomplete. It doesn't explain what 'content' includes, potential return values, or error conditions. For a tool with no structured output or behavioral annotations, more context is needed to guide effective 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 input schema has 100% description coverage, with the noteId parameter documented as 'Note ID (from macos_note_list)'. The description adds no additional meaning beyond this, as it only repeats the need for a note ID without elaborating on format or constraints. 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.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Read') and resource ('content of a note'), making the purpose immediately understandable. It distinguishes from siblings like macos_note_list (which lists notes) and macos_note_create (which creates notes), though it doesn't explicitly mention these distinctions. The description is specific but could be more precise about what 'content' includes.
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 no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., needing a note ID from macos_note_list), exclusions, or comparisons to other note-related tools like macos_note_list or macos_note_folders. Usage is implied but not explicitly stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Display a macOS system notification.
| Name | Required | Description | Default |
|---|---|---|---|
| title | Yes | Notification title | |
| message | Yes | Notification message body | |
| subtitle | No | Optional subtitle | |
| sound | No | Optional sound name (e.g., 'Basso', 'Blow', 'Bottle', 'Frog', 'Funk', 'Glass', 'Hero', 'Morse', 'Ping', 'Pop', 'Purr', 'Sosumi', 'Submarine', 'Tink') |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden but only states what the tool does, not how it behaves. It lacks details on permissions needed, whether notifications are persistent or transient, user interaction requirements, or any side effects.
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, direct sentence with no wasted words. It's front-loaded and efficiently communicates the core function without unnecessary elaboration.
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 notification tool with no output schema and no annotations, the description is minimal but functional. It covers the basic purpose but lacks depth on behavioral aspects, making it adequate but with clear gaps in completeness.
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 parameters are well-documented in the schema. The description adds no additional parameter information, but the schema provides clear details, meeting the baseline for high 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 action ('Display') and resource ('macOS system notification'), making the purpose immediately understandable. It doesn't differentiate from sibling tools, but all macOS tools are distinct by function, so this is adequate.
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?
No guidance is provided on when to use this tool versus alternatives. The description is standalone with no context about prerequisites, timing, or comparison to other notification methods.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Open a URL in the default web browser.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | URL to open |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states the action but doesn't mention system permissions required (e.g., accessibility settings), whether it opens in foreground/background, potential user confirmation dialogs, or error handling for invalid URLs. This leaves significant behavioral gaps for a system-level operation.
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, efficient sentence that states the core functionality without any unnecessary words. It's front-loaded with the main action and provides just enough context about the execution environment (default web browser).
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 100% schema coverage, the description is minimally adequate. However, without annotations or output schema, it should ideally mention what constitutes success/failure or any system feedback. The description covers the basic action but lacks completeness regarding behavioral expectations and system integration details.
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 description coverage is 100% with the single 'url' parameter well-documented in the schema. The description doesn't add any parameter-specific information beyond what the schema provides, such as URL format requirements or validation rules. This meets the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Open a URL') and the target resource ('in the default web browser'), making the purpose immediately understandable. It distinguishes itself from sibling tools like 'macos_open_with_default' by specifying the browser context rather than general file opening.
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 for opening URLs in web browsers, but provides no explicit guidance on when to use this tool versus alternatives like 'macos_open_with_default' for files or other macOS-specific tools. It lacks any mention of prerequisites, exclusions, or specific scenarios where this tool is preferred.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Open a file with its default application.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Path to file to open |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden but offers minimal behavioral insight. It states the action but doesn't disclose critical traits like whether it requires specific permissions, if it launches applications visibly, potential errors for invalid paths, or system-level effects. This is inadequate for a mutation tool with zero annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that directly states the tool's purpose without unnecessary words. It's appropriately sized and front-loaded, making it easy to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (a mutation operation with no annotations or output schema), the description is incomplete. It lacks details on behavioral traits, error handling, and usage context, which are essential for safe and effective invocation in a macOS environment.
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 description adds no parameter semantics beyond what the schema provides (100% coverage). It doesn't explain path format constraints, file type handling, or edge cases. With high schema coverage, the baseline is 3, but the description doesn't compensate with additional context.
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 ('Open') and resource ('a file with its default application'), providing a specific verb+resource combination. However, it doesn't explicitly differentiate from sibling tools like 'macos_open_url' or 'macos_quick_look', which also open things but with different mechanisms or targets.
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 no guidance on when to use this tool versus alternatives. It doesn't mention when-not scenarios (e.g., for URLs use 'macos_open_url') or prerequisites (e.g., file must exist), leaving the agent to infer usage from context alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Merge multiple PDF files into one.
| Name | Required | Description | Default |
|---|---|---|---|
| inputPaths | Yes | Array of PDF file paths to merge | |
| outputPath | Yes | Path for merged output PDF |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the action 'merge' but doesn't describe what happens during merging (e.g., order preservation, page concatenation), potential side effects (e.g., file overwriting at outputPath), error conditions, or system requirements. For a mutation tool with zero annotation coverage, this leaves significant behavioral gaps.
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, efficient sentence with zero waste. It's front-loaded with the core action and resource, making it immediately scannable and appropriately sized for a simple tool. Every word earns its place without redundancy or unnecessary elaboration.
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 mutation nature (merging files) and lack of annotations or output schema, the description is incomplete. It doesn't address behavioral aspects like file handling, error cases, or output expectations. While concise, it fails to provide sufficient context for safe and effective use, especially as a write operation in a macOS environment.
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 parameters (inputPaths and outputPath) clearly documented in the schema. The description adds no additional parameter semantics beyond what the schema provides, such as format details (e.g., path requirements, file existence) or usage examples. 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.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'merge' and the resource 'PDF files', making the purpose immediately understandable. It distinguishes from sibling PDF tools like macos_pdf_page_count (which counts pages) but doesn't explicitly differentiate from non-PDF tools in the server. The description is specific but lacks explicit sibling differentiation beyond the PDF domain.
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 no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., file accessibility), when not to use it (e.g., for non-PDF files), or compare it to other PDF manipulation tools. The agent must infer usage solely from the tool name and description without explicit context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the number of pages in a PDF file.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Path to PDF file |
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 but offers minimal information. It implies a read-only operation but doesn't cover error handling (e.g., invalid paths), performance aspects (e.g., speed for large files), or output format (e.g., integer count), which are critical for an agent to use it effectively.
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, direct sentence that efficiently conveys the core functionality without unnecessary words. It is front-loaded with the essential action and resource, making it easy for an agent to parse and understand 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?
Given the lack of annotations and output schema, the description is incomplete for effective tool use. It doesn't explain what the tool returns (e.g., an integer, error messages) or behavioral nuances, leaving gaps that could hinder an agent's ability to invoke and interpret results 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 input schema has 100% description coverage, with the 'path' parameter clearly documented. The description adds no additional semantic context beyond what the schema provides, such as path format requirements (e.g., absolute vs. relative) or file size limitations, so it meets the baseline for adequate but unenhanced parameter documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Get') and resource ('number of pages in a PDF file'), making the tool's purpose immediately apparent. It distinguishes itself from sibling tools like macos_pdf_merge (which combines PDFs) and macos_image_info (which handles images), establishing a unique role within the server's toolset.
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 no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., file accessibility), exclusions (e.g., non-PDF files), or related tools like macos_pick_file for selecting files, leaving the agent to infer usage context independently.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Open a file picker dialog and return the selected file path. Returns null if cancelled.
| Name | Required | Description | Default |
|---|---|---|---|
| prompt | No | Dialog prompt text | |
| defaultLocation | No | Default directory to open in | |
| fileTypes | No | Allowed file extensions (e.g., ['txt', 'md', 'pdf']) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It discloses key behavioral traits: the tool opens a dialog (implying user interaction), returns a file path or null if cancelled, and is read-only (no mutation implied). However, it doesn't mention platform-specific constraints (macOS-only), permissions needed, or error handling beyond cancellation.
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, zero waste. The first sentence states the core purpose and outcome, the second covers the cancellation case. It's front-loaded with essential information and appropriately sized for a simple 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 the tool's low complexity (interactive file picker), 100% schema coverage, and no output schema, the description is mostly complete. It covers purpose, behavior, and edge cases (cancellation). However, it could benefit from mentioning macOS-specific context or integration with sibling tools for a perfect score.
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 schema fully documents all three parameters. The description adds no additional parameter semantics beyond what's in the schema (e.g., no examples or constraints). Baseline 3 is appropriate when the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Open a file picker dialog') and outcome ('return the selected file path'), distinguishing it from sibling tools like macos_pick_files (multiple files) and macos_pick_folder (folder selection). It uses precise verbs and specifies the resource (file path).
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 (interactive file selection) and distinguishes from macos_pick_files and macos_pick_folder by specifying single file selection. However, it lacks explicit guidance on when to use this versus alternatives like macos_get_finder_selection or macos_save_dialog, which would require more detailed comparison.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Open a file picker dialog allowing multiple selection. Returns array of paths or null if cancelled.
| Name | Required | Description | Default |
|---|---|---|---|
| prompt | No | Dialog prompt text | |
| defaultLocation | No | Default directory to open in | |
| fileTypes | No | Allowed file extensions (e.g., ['txt', 'md', 'pdf']) |
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 key behavioral traits: the tool opens a dialog, allows multiple selection, and returns paths or null on cancellation. However, it lacks details on permissions needed, UI behavior (e.g., modal vs. non-modal), error handling, or platform-specific constraints, which are important for a system-level tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose in the first clause and efficiently covers key behaviors in two sentences. Every sentence earns its place by providing essential information without redundancy, making it highly concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (3 parameters, no output schema, no annotations), the description is mostly complete: it explains what the tool does, its selection behavior, and return values. However, it could improve by mentioning platform-specific details (macOS-only) or interaction with other tools, but it adequately covers the basics 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%, so the schema already documents all parameters (prompt, defaultLocation, fileTypes). The description does not add any parameter-specific semantics beyond what the schema provides, such as examples or usage tips. Baseline 3 is appropriate as the schema handles the heavy lifting.
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 with specific verbs ('Open a file picker dialog allowing multiple selection') and resource ('array of paths'), distinguishing it from siblings like 'macos_pick_file' (singular) and 'macos_pick_folder' (folders). It explicitly mentions the return behavior, which is crucial for understanding its function.
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 by stating it 'allows multiple selection' and returns 'null if cancelled,' which helps differentiate from 'macos_pick_file' (likely single selection) and 'macos_save_dialog' (for saving). However, it does not explicitly state when to use this tool versus alternatives like 'macos_get_finder_selection' or provide exclusions, leaving some ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Open a folder picker dialog and return the selected folder path. Returns null if cancelled.
| Name | Required | Description | Default |
|---|---|---|---|
| prompt | No | Dialog prompt text | |
| defaultLocation | No | Default directory to open in |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden and does well by disclosing key behavioral traits: it opens a GUI dialog, returns a path or null on cancellation, and operates interactively. It doesn't cover error cases, permissions, or platform specifics, but provides essential operational 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?
Two sentences with zero waste: the first states the core functionality, the second covers the cancellation case. It's front-loaded with the primary purpose and appropriately sized for the tool's complexity.
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 annotations and no output schema, the description adequately covers the tool's purpose, behavior, and outcome. It could mention return format details or error handling, but for a simple dialog tool with full parameter coverage, it's reasonably 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?
Schema description coverage is 100%, so the schema already documents both parameters (prompt and defaultLocation). The description adds no additional parameter semantics beyond what the schema provides, meeting the baseline for high 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 specific action ('Open a folder picker dialog') and outcome ('return the selected folder path'), distinguishing it from sibling tools like macos_pick_file or macos_save_dialog. It precisely defines the verb+resource combination without being tautological.
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 for selecting folders via a dialog, but doesn't explicitly state when to use this tool versus alternatives like macos_pick_file (for single files) or macos_pick_files (for multiple files). No guidance on prerequisites or exclusions is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Open a file with Quick Look preview.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Path to file to preview |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It states the action but doesn't describe what Quick Look actually does (transient preview vs permanent opening), whether it requires specific permissions, what happens if the file can't be previewed, or if there are system limitations. The description is minimal and lacks important 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?
The description is a single, clear sentence that gets straight to the point with zero wasted words. It's appropriately sized for a simple tool and front-loads the essential 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?
For a tool with no annotations and no output schema, the description is insufficiently complete. It doesn't explain what Quick Look is, what the user experience will be, whether the preview is interactive, what file types are supported, or what happens on completion. The agent lacks important context to use this tool 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?
The schema has 100% description coverage with a single parameter 'path' clearly documented. The description doesn't add any parameter-specific information beyond what the schema provides, such as file format limitations or path requirements. Baseline 3 is appropriate when schema coverage is complete.
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 ('Open') and resource ('a file with Quick Look preview'), making the purpose immediately understandable. It doesn't explicitly differentiate from sibling tools like 'macos_open_with_default' or 'macos_reveal_in_finder', but the Quick Look specificity provides some implicit distinction.
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 no guidance on when to use this tool versus alternatives like 'macos_open_with_default' or 'macos_reveal_in_finder'. There's no mention of prerequisites, limitations, or typical use cases for Quick Look previews versus full application opening.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Reveal a file or folder in Finder and bring Finder to front.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Path to reveal in Finder |
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 mentions the action ('reveal', 'bring to front') but lacks details on behavioral traits such as error handling (e.g., if the path doesn't exist), permissions required, or system effects (e.g., whether it modifies files). This is a significant gap for a tool with no annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the core action ('Reveal a file or folder in Finder') and adds a secondary effect ('and bring Finder to front'). There is no wasted text, making it highly concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity (one parameter, no output schema, no annotations), the description is minimally complete but lacks depth. It covers the basic purpose but misses behavioral details like error handling or system interactions. For a tool with no annotations, more context would improve completeness.
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 description coverage is 100%, with the parameter 'path' clearly documented as 'Path to reveal in Finder'. The description adds no additional meaning beyond this, as it doesn't specify path format, validation, or examples. With high schema coverage, 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 clearly states the specific action ('Reveal a file or folder in Finder and bring Finder to front') with the resource ('file or folder'), distinguishing it from sibling tools like macos_get_finder_selection (which retrieves selection) or macos_open_with_default (which opens with an application). It uses precise verbs ('reveal', 'bring to front') that convey the exact functionality.
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 for revealing files/folders in Finder, but does not explicitly state when to use this tool versus alternatives like macos_open_with_default (for opening files) or macos_quick_look (for previewing). No exclusions or prerequisites are mentioned, leaving the context somewhat open-ended.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Open a save file dialog and return the chosen path. Returns null if cancelled.
| Name | Required | Description | Default |
|---|---|---|---|
| prompt | No | Dialog prompt text | |
| defaultName | No | Default file name | |
| defaultLocation | No | Default directory to save in |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses key behavioral traits: it opens a dialog, returns a path or null if cancelled. However, it doesn't mention platform-specific details (macOS-only), potential permissions, or UI behavior (e.g., modal blocking). This is adequate but lacks depth for a tool with no 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 a single, efficient sentence that front-loads the core action and outcome. Every word earns its place, with no redundancy or wasted text.
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 annotations, no output schema, and 3 parameters with full schema coverage, the description is minimally complete. It covers the basic operation and cancellation behavior but lacks details on return format (e.g., string path structure) or error handling, leaving gaps for an AI 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?
Schema description coverage is 100%, so the schema already documents all parameters (prompt, defaultName, defaultLocation). The description adds no additional parameter semantics beyond what's in the schema, maintaining the baseline score of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Open a save file dialog') and outcome ('return the chosen path'), distinguishing it from sibling tools like macos_pick_file (which opens a file selection dialog rather than a save dialog). It explicitly mentions the cancellation behavior, which further clarifies its purpose.
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 by specifying it's for saving files, but it doesn't explicitly state when to use this tool versus alternatives like macos_pick_file or macos_pick_folder. However, the naming and purpose make the intended use case clear (saving vs. opening files).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the current screen resolution and scale factor.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses the tool's read-only behavior ('Get') but lacks details on permissions, rate limits, or output format. It adequately indicates a safe operation but misses deeper 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?
The description is a single, efficient sentence that front-loads the purpose without unnecessary words. Every part of the sentence contributes directly to understanding the tool's function, making it appropriately sized and well-structured.
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 (0 parameters, no output schema, no annotations), the description is complete enough for basic understanding. However, it lacks details on return values or error handling, which could be helpful despite the low 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 has 0 parameters with 100% schema coverage, so the schema fully documents the lack of inputs. The description adds no parameter semantics, but this is acceptable as there are no parameters to explain, aligning with the baseline for zero parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Get') and resource ('current screen resolution and scale factor'), distinguishing it from siblings like macos_screenshot or macos_system_info. It precisely defines what the tool does without being vague or tautological.
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 for retrieving screen resolution data, but does not explicitly state when to use this tool versus alternatives like macos_system_info (which might include resolution) or provide context on prerequisites. Usage is inferred 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.
Take a screenshot and save to file. Can capture full screen, a region, or specific window.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Path to save the screenshot (png) | |
| fullScreen | No | Capture entire screen (default: interactive window selection) | |
| region | No | Capture specific region { x, y, width, height } |
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 mentions the action and capture modes but fails to disclose critical behavioral traits such as permissions needed (e.g., screen recording access), whether it overwrites existing files, error handling, or output details (e.g., success/failure indicators). This leaves significant gaps for a mutation tool with no annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the core action and lists capture modes without redundancy. Every word contributes to understanding the tool's purpose, making it appropriately sized and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (mutation with no annotations, no output schema, and nested parameters), the description is incomplete. It lacks details on behavioral aspects like permissions, file handling, errors, and output format, which are crucial for safe and effective use. The high schema coverage does not compensate for these missing contextual elements.
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 schema already documents all parameters thoroughly. The description adds minimal value beyond the schema by hinting at capture modes ('full screen, a region, or specific window'), but it does not provide additional syntax, format, or usage details for parameters. This meets the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Take a screenshot and save to file') and distinguishes it from sibling tools like 'macos_screenshot_clipboard' by specifying the file-saving behavior. It explicitly lists the capture modes (full screen, region, or specific window), making the purpose unambiguous and distinct.
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 mentioning capture modes, but it does not explicitly state when to use this tool versus alternatives like 'macos_screenshot_clipboard' (which saves to clipboard) or other image tools. It provides basic context but lacks explicit guidance on exclusions or comparisons with siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Take a screenshot and copy to clipboard (interactive selection).
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
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 mentions the interactive selection behavior, which is useful, but lacks details on permissions (e.g., screen recording access), whether it requires user interaction, error handling, or what happens if the clipboard is overwritten. For a tool with no annotation coverage, this leaves significant behavioral gaps.
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, efficient sentence that front-loads the core functionality ('Take a screenshot and copy to clipboard') and adds necessary detail ('interactive selection') without any wasted words. Every part of the 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?
Given the tool has 0 parameters, no output schema, and no annotations, the description is minimally adequate by stating the action and selection method. However, it lacks details on behavioral aspects like permissions or error handling, which are important for a screenshot tool, making it incomplete for optimal agent 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 input schema has 0 parameters with 100% coverage, so no parameter documentation is needed. The description appropriately adds context about the interactive selection process, which isn't captured in the schema, providing value beyond the structured fields.
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 ('Take a screenshot and copy to clipboard') and specifies the selection method ('interactive selection'), which distinguishes it from the sibling tool 'macos_screenshot' that likely takes a full-screen or window screenshot without specifying clipboard copying. However, it doesn't explicitly differentiate from potential other screenshot tools that might also copy to clipboard but with different selection modes.
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 when an interactive screenshot selection is needed and the result should go to the clipboard, as opposed to saving to a file. However, it doesn't explicitly state when to use this tool versus alternatives like 'macos_screenshot' (which likely saves to a file) or 'macos_clipboard_write' (for other clipboard operations), leaving some ambiguity for the agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get macOS system information: computer name, username, home directory, OS version.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
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. While 'Get' implies a read-only operation, the description doesn't specify whether this requires permissions, whether it returns real-time or cached data, what format the information comes in, or any potential limitations. For a system information tool with zero annotation coverage, this leaves significant behavioral questions unanswered.
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, efficient sentence that immediately states the purpose and enumerates the specific information retrieved. Every word serves a purpose with no redundancy or unnecessary elaboration. It's perfectly front-loaded and appropriately sized for a simple retrieval 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 the tool's simplicity (no parameters, no output schema, no annotations), the description provides adequate but minimal context. It tells what information is retrieved but doesn't address format, permissions, or behavioral characteristics. For a system information tool, additional context about return format or access requirements would be helpful but isn't critical given the straightforward nature of the operation.
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 (schema coverage 100%), so the baseline for zero parameters is 4. The description appropriately doesn't discuss parameters since none exist, which is correct for this tool configuration.
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 'Get' and the resource 'macOS system information', then specifies exactly what information is retrieved: computer name, username, home directory, and OS version. This distinguishes it from all sibling tools which perform different macOS operations like clipboard management, file operations, or image processing.
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 no guidance on when to use this tool versus alternatives. While the purpose is clear, there's no mention of prerequisites, when this tool would be appropriate versus other system information tools, or any exclusions. The agent must infer usage context from the tool name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v1.0.0macos_clipboard_readmacos_clipboard_writemacos_get_finder_selectionmacos_image_convertmacos_image_infomacos_image_resizemacos_note_createmacos_note_foldersmacos_note_listmacos_note_readmacos_notifymacos_open_urlmacos_open_with_defaultmacos_pdf_mergemacos_pdf_page_countmacos_pick_filemacos_pick_filesmacos_pick_foldermacos_quick_lookmacos_reveal_in_findermacos_save_dialogmacos_screen_resolutionmacos_screenshotmacos_screenshot_clipboardmacos_system_infoEach tool has a clearly distinct purpose with no significant overlap. Tools are organized by functional domains like clipboard, images, notes, PDFs, file operations, and system utilities, making it easy for an agent to select the right tool. For example, macos_screenshot and macos_screenshot_clipboard serve different output destinations, and macos_pick_file, macos_pick_files, and macos_pick_folder handle distinct selection types.
All tool names follow a consistent 'macos_' prefix with snake_case and a clear verb_noun pattern, such as macos_clipboard_read, macos_image_convert, and macos_note_list. This uniformity enhances readability and predictability, allowing agents to easily understand and navigate the toolset without confusion from mixed conventions.
With 25 tools, the count is on the higher side for a macOS utility server, bordering on heavy. While it covers many common macOS operations comprehensively, it might feel overwhelming or redundant in some areas, such as multiple screenshot and file picker variants. A more streamlined set could improve usability without losing core functionality.
The toolset provides complete coverage for macOS automation tasks, including CRUD operations for notes, image and PDF manipulation, file system interactions, clipboard management, and system information. There are no obvious gaps; agents can perform end-to-end workflows like creating notes, processing images, and handling files without dead ends.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Let ChatGPT, Claude & Cursor use your Mac: email, calendar, iMessage, Teams, files. Local, free.
Search, read, and write your Apple Notes from ChatGPT/Claude via a local Mac agent + MCP relay.
MCP connector that lets ChatGPT list, search, and run your Apple Shortcuts via a local Mac agent
MCP connector for iMessage & Contacts via a local Mac agent + Vercel relay
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/alexlock1/macos-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
