The AppleScript Automation MCP server lets you control and automate your Mac through an AI assistant (like Claude) using AppleScript and macOS CLIs.
App & System Control
Launch or quit any application, identify the frontmost app, and list all running apps
Toggle Dark Mode, lock the screen, and run arbitrary AppleScript (with safety blocks preventing destructive operations like delete, erase, shutdown, restart, or trash)
Audio & Volume
Get, set, mute, or unmute system output volume
System Info
Check battery status, local IP address, current date/time, disk usage, and memory statistics
Clipboard
Read and set clipboard text
Notifications & Speech
Display macOS notification banners and speak text aloud via text-to-speech
Web & Search
Open any URL in the default browser; perform Google or YouTube searches
Screen
Take a full screenshot and save it locally
Communication
Compose pre-filled emails (opens compose window, does not auto-send), send iMessages, start FaceTime calls, and look up contacts by name
Productivity
Create notes in Apple Notes, create reminders in the Reminders app, and open Maps with directions
Photos & Media
Search the Photos library by keyword
Control Spotify (play by URI, play/pause, next/previous, now-playing) and the Music app (play/pause, next/previous, search library)
Shortcuts
List and run any installed Apple Shortcut by name, enabling Focus modes, HomeKit automations, timers, and more
Provides tools to control Apple apps (Messages, Music, Photos, Contacts, System Events, etc.) and macOS system functions (volume, dark mode, lock screen, clipboard, notifications, text-to-speech, etc.) via AppleScript.
Enables searching Google via the search_google tool, which opens a URL in the default browser or performs a search.
Allows sending iMessages via the send_imessage tool.
Allows running macOS Shortcuts by name via the run_shortcut tool, acting as an escape hatch for custom automation.
Enables searching YouTube via the search_youtube tool.
Click on "Deploy 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., "@AppleScript Automation MCP Check my battery level"
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.
A local MCP server that exposes macOS automation actions (AppleScript + a few CLIs) as tools, so any MCP client running on your Mac (Claude Desktop, Cursor, etc.) can drive them.
It runs locally over stdio — osascript needs the real machine, so this can't
be a remote/hosted server. Non-destructive only: no delete/erase/shutdown/trash.
macOS, Python 3.10+. Clone and run the installer — it sets up a venv and wires the server into Claude Desktop for you:
git clone https://github.com/anmolol117/applescript-automation-mcp.git
cd applescript-automation-mcp
bash install.shThen quit Claude Desktop completely (Cmd-Q) and reopen it. That's it — the rest of this README is for manual setup, HTTP mode, and permissions.
install.sh backs up your existing claude_desktop_config.json (to .bak) and
merges in the applescript server without touching other servers.
Related MCP server: macos-mcp
The server gives Claude the ability to act on your Mac. The bundled
mac-control skill teaches it when and how — known-good AppleScript
recipes, the lookup-then-execute pattern for music, and when to confirm
before acting. The tools work without it, but Claude reaches for them
less reliably.
install.sh builds dist/mac-control.zip. In Claude Desktop, go to
Customize → Skills → "+" and upload it, then toggle it on. Skills
install at the account level, so it follows you to claude.ai too.
To package it by hand:
cd skills && zip -r ../dist/mac-control.zip mac-controlThe zip must contain mac-control/ at the top level — zipping from the
repo root buries it under skills/ and the upload will fail.
The installed skill is a copy, not a link: pulling a new version of this repo won't update it. Re-upload after an update.
pip install -r requirements.txt # or: pip install "mcp>=1.2.0"
python server.py # sanity check; Ctrl-C to stopPython 3.10+.
Claude Desktop (local). Install into a venv, then point the config at that
venv's Python (Claude Desktop launches with a minimal environment, so bare
python3 usually won't find mcp):
python3 -m venv .venv
.venv/bin/pip install -r requirements.txtEdit ~/Library/Application Support/Claude/claude_desktop_config.json with
absolute paths for both the interpreter and the script:
{
"mcpServers": {
"applescript": {
"command": "/ABSOLUTE/PATH/applescript-automation-mcp/.venv/bin/python",
"args": ["/ABSOLUTE/PATH/applescript-automation-mcp/server.py"]
}
}
}Quit Claude Desktop completely and reopen it. Connection status and logs live under Settings → Developer. Restart after any config edit.
Other MCP clients (Cursor, etc.) take the same command/args shape.
The same file can serve over HTTP instead of stdio, for URL-based clients:
MCP_TRANSPORT=streamable-http python3 server.py
# serves at http://127.0.0.1:8000/mcpOverride MCP_HOST / MCP_PORT if needed. This still runs on your Mac —
it's a local URL, not a hosted one.
Claude custom connectors expect a public HTTPS MCP endpoint. This server
controls your Mac via osascript, so it can only ever run on your Mac — a
hosted connector on Anthropic's servers would have no Mac to control and every
tool would fail. There is no way to make this a normal hosted connector.
Two real options:
Local client (recommended). Use the stdio config above with a client that runs on your Mac (Claude Desktop, Cursor). No URL, no tunnel, nothing exposed to the internet.
Tunnel the local HTTP server (advanced, risky). Run the HTTP mode and
expose it with a tunnel (e.g. cloudflared tunnel --url http://localhost:8000
or ngrok http 8000), then give Claude the public …/mcp URL. This works
only while your Mac and the tunnel stay up, and it exposes full control of
your Mac to a public URL — anyone who reaches it can run these tools. Only
do this behind authentication you add yourself, and never leave it running.
git init && git add . && git commit -m "AppleScript automation MCP server"
git branch -M main
git remote add origin https://github.com/anmolol117/applescript-automation-mcp.git
git push -u origin mainThe repo is the source; users clone it and connect via stdio (option 1). A GitHub URL is not itself an MCP endpoint.
The first time a tool controls an app, macOS prompts for permission. Approve them, or pre-grant under System Settings → Privacy & Security:
Automation — the client app (or the terminal launching the server) must be allowed to control Messages, Notes, Mail, Spotify, Photos, Contacts, System Events, etc.
Accessibility — needed by tools that send keystrokes (search_photos).
Screen Recording — needed for screenshot.
If a tool returns a permission error, it's one of these grants.
Actions: run_applescript, open_app, close_app, set_volume, mute,
unmute, toggle_dark_mode, lock_screen, set_clipboard, notify, say,
open_url, search_google, search_youtube, screenshot, compose_mail,
send_imessage, facetime_call, create_note, create_reminder,
maps_directions, search_photos, spotify_play, spotify_control,
run_shortcut.
Read-only: frontmost_app, list_running_apps, get_volume, is_muted,
battery_status, get_ip, get_datetime, disk_usage, memory_stats,
get_clipboard, lookup_contact, now_playing, list_shortcuts.
run_applescript is the primary tool — most actions are better expressed as a
script than as a wrapper. The wrappers exist for things AppleScript can't reach
directly (screenshot, battery_status, clipboard, Shortcuts) and for the
handful of recipes worth having pinned.
Playback targets Spotify, not the Music app. spotify_play takes a Spotify
URI:
spotify_play(track_uri="spotify:track:3WFgRhgECxQYyy8Ldhk2PG")Resolve the URI first — the Spotify connector's search, or any Spotify client's
"Copy Spotify URI". spotify_control handles play/pause/next/previous, and
now_playing reports the current Spotify track.
Two things steer how a model uses this server:
The INSTRUCTIONS string in server.py, returned on initialize and in
context every session. It says the server is for executing, not
describing, and that other connectors are for lookup while this one acts.
Tool docstrings, written as triggers ("use when the user says play, put on, open…") rather than labels. This matters more than it looks — a model picks tools by matching intent against descriptions.
The bundled mac-control skill, which carries the longer recipes and user
defaults that don't fit in INSTRUCTIONS. See
Install the skill.
run_applescript refuses destructive constructs — delete, erase,
empty trash, shutdown, restart, sudo, rm -rf, diskutil. The check
strips string literals before matching, so an email body containing the word
"delete" is fine while delete note 1 is blocked.
This is a guardrail against accidents, not a security boundary. It can't see
inside do shell script, so a destructive shell command in a quoted string will
pass. Anyone who can reach this server can run arbitrary AppleScript on your
Mac — which is the whole point, and the reason not to expose it publicly.
run_shortcut is the escape hatch: build anything in the Shortcuts app —
Focus modes, HomeKit, timers — and call it by name. Input passing isn't wired
up; add -i <file> in run_shortcut if a shortcut needs input. Names must
match exactly; check with list_shortcuts first.
compose_mail opens a populated compose window via AppleScript and does
not send. It used to build a mailto: URL, which turned spaces into +
and truncated long bodies.
send_imessage uses the classic service type = iMessage selector, which can
break on some macOS versions if no iMessage account is active; check
Messages is signed in if it errors.
create_note writes to the iCloud account's "Notes" folder. The Notes body
is HTML, so line breaks are <div> wrapped rather than \n.
All AppleScript string interpolation goes through _as(), which keeps
non-ASCII intact — plain json.dumps emits \uXXXX escapes that AppleScript
doesn't decode, mangling accents and emoji.
Every tool returns {ok, output, error} and never hangs — subprocess calls
time out instead of blocking the client.
Battery charge and power source.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description states it returns battery charge and power source, which aligns with the readOnlyHint annotation. It adds minimal behavioral context beyond the annotation, such as what aspects are reported.
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?
Extremely concise and front-loaded. The single phrase conveys the tool's purpose without unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description is under-specified. It does not indicate the format or structure of the returned data (e.g., percentage, charging state), which could be helpful for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist; schema coverage is 100% with empty properties. The description adds no parameter information, which is acceptable as there are none to document.
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 'Battery charge and power source' clearly indicates the tool returns battery status and power source, which is distinct from sibling tools like disk_usage or memory_stats. However, it could be more explicit about the action (e.g., 'Get battery status').
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 on when to use this tool versus alternatives like disk_usage or memory_stats. The description does not provide context about typical use cases or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Quit an application by name.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description aligns with annotation's readOnlyHint=false, indicating mutation. However, no additional behavioral traits (e.g., force quit, permissions) are disclosed beyond what annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with no unnecessary words. Efficient and direct.
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?
Sufficient for a simple tool with one parameter and no complex output. Could mention handling of non-running apps, but not essential.
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?
With 0% schema description coverage, the description adds meaning by specifying that the 'name' parameter is the application name. Could be improved by noting exact name or bundle ID requirements.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the verb 'quit' and resource 'application' with method 'by name'. Distinguishes from siblings like 'open_app' and 'list_running_apps'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives such as 'frontmost_app' or 'list_running_apps'. Lacks context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Open a pre-filled mail compose window (does not send).
| Name | Required | Description | Default |
|---|---|---|---|
| cc | No | ||
| to | No | ||
| bcc | No | ||
| body | No | ||
| subject | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses main side effect (opens UI window) and non-sending behavior. Annotations provide readOnlyHint false, confirming mutation. No hidden behaviors mentioned.
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?
Single sentence with critical qualifier, front-loaded. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Minimal but sufficient for a simple UI tool. Lacks info on prerequisites (e.g., mail app), return values, or error handling.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% and description adds no parameter details. Parameter names are self-explanatory, but format, constraints, or usage notes are missing.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states verb 'open' and resource 'mail compose window', explicitly noting it does not send. Differentiates from send_imessage and similar tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implies usage for composing email without sending, but lacks explicit alternatives or when-not-to-use guidance. The 'does not send' clause is helpful.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a reminder in the Reminders app.
| Name | Required | Description | Default |
|---|---|---|---|
| notes | No | ||
| title | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description states 'Create', which is consistent with annotations (readOnlyHint=false). However, it adds no behavioral details beyond what annotations already indicate. There is no disclosure of side effects, permissions required, or how the reminder is created (e.g., default list, behavior with existing titles).
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 very short (one sentence), but it under-specifies the tool. Essential details about parameters and behavior are missing, making it less useful despite its brevity. It is not 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?
For a creation tool with no output schema, the description should explain what happens after creation (e.g., confirmation, return value). It does not. Given the simplicity of the tool, more context is needed to guide the 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 coverage is 0%, meaning no descriptions in the input schema. The description does not explain the parameters ('title' and 'notes') at all. The agent must infer their meaning from parameter names alone, which is insufficient for accurate invocation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Create') and resource ('reminder in the Reminders app'), clearly identifying the tool's function. No sibling tool has a similar name or purpose, so differentiation is inherent.
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 (e.g., notify, compose_mail). There is no mention of prerequisites, limitations, or context 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.
Disk usage for the startup volume.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=true. Description adds minimal behavioral info (scope: startup volume) but no details about output format or performance.
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?
Extremely concise single phrase with no wasted words. Appropriate for a zero-parameter 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?
For a simple read-only tool with no parameters and no output schema, the description covers the essential purpose. Missing units or numeric format, but not critical.
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?
No parameters exist, and schema coverage is 100%. Description cannot add parameter info, so baseline 4 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool reports disk usage for the startup volume. It uses a specific resource but lacks an explicit verb like 'get' or 'report'.
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 on when to use this tool versus alternatives. For a simple tool, guidelines are minimal but still missing explicit context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Start a FaceTime call to a phone number or email.
| Name | Required | Description | Default |
|---|---|---|---|
| target | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate non-read-only, consistent with starting a call. Description adds minimal behavioral context beyond what annotations provide; no mention of prerequisites or 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?
Single sentence, no superfluous words, efficiently communicates core 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?
For a simple tool with one parameter and no output schema, description adequately covers what the tool does and what the input represents.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but description explicitly states target can be a phone number or email, adding meaning beyond the raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description uses specific verb 'Start' and resource 'FaceTime call', clearly distinguishing it from sibling tools like send_imessage or open_url.
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 on when to use this tool vs alternatives (e.g., send_imessage, open_url). Agent must infer context from tool name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Name of the app currently in the foreground.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds no behavioral details beyond the annotation (readOnlyHint=true). It does not disclose what happens when no app is frontmost, or any edge cases. Since annotations already declare readonly, the description contributes little.
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 concise sentence with no filler. It is front-loaded with the core purpose. Slightly more context (e.g., return type) could improve it, but it is efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no parameters, no output schema, and a readonly annotation, the description is minimally adequate. It states the tool's purpose but does not specify return format or behavior in edge cases. With 39 sibling tools, more context would help disambiguate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so no parameter documentation is needed. Schema description coverage is 100% (no params), and the description appropriately avoids redundant info. Baseline 4 applies per rubric.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Name of the app currently in the foreground.' This clearly indicates the tool retrieves the current frontmost app's name. It distinguishes from sibling 'list_running_apps' by focusing on only the active app, though the description could explicitly use 'returns' or 'gets' for stronger action clarity.
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 siblings like 'list_running_apps' or 'open_app'. The description does not mention context or alternatives, leaving the agent to infer appropriate usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read the current clipboard text.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true. Description adds no extra behavioral context beyond the verb 'read'.
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?
Single sentence with no extraneous content, perfectly concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only tool with no parameters and no output schema, the description is adequate. Could mention return type but not required.
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?
No parameters, so description needs no parameter info. Baseline 4 for zero-parameter tools.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states verb 'read' and resource 'clipboard text'. Distinguishes from sibling 'set_clipboard' which writes.
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 explicit guidance on when to use vs alternatives, but name and description inherently imply read-only usage. No exclusions provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Current local date and time.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already indicates this is a safe read operation. The description adds little beyond that, but it does not contradict the annotation. It would benefit from mentioning timezone or format details.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no waste. It is appropriately sized for the tool's simplicity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of parameters, output schema, and simple nature of retrieving the current date and time, the description is sufficiently complete. It could optionally mention output format, but not required.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are no parameters, so the description does not need to add parameter-specific meaning. The schema coverage is 100%, and baseline for 0-param tools is 4.
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 'Current local date and time' clearly states the verb (get) and resource (date and time). It distinguishes itself from sibling tools like get_volume, get_clipboard, etc., which return different data.
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 explicit usage guidance or alternatives are provided, but the simplicity of the tool (no parameters) makes the context obvious. The agent can infer when to use it without much ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Local IP address on en0.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the description adds value by specifying the network interface (en0) but does not disclose other behavioral traits. No contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is both concise and front-loaded, containing no unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a parameterless read-only tool with no output schema, the description provides sufficient context: it returns the local IP on en0. No gaps given tool simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist; schema coverage is 100%. The description adds meaning by specifying the network interface, which is beyond the schema's empty properties. Baseline 4 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns the local IP address on the en0 interface, using a specific verb-resource combination. It distinguishes from siblings as no other tool concerns IP addresses.
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 (getting IP on en0) but provides no explicit guidance on when or when not to use this tool. For a simple parameterless tool, this is adequate but not explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Current system output volume (0-100).
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true. Description adds no new behavioral traits beyond the resource, but does not contradict 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?
Single sentence with no wasted words, immediately front-loads key information: resource and range.
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 no-parameter getter with no output schema, the description fully conveys what the tool returns and its range, making it 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?
No parameters; schema coverage 100% effectively. Description adds value by specifying the return value range (0-100), exceeding baseline 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?
Clearly states verb 'get' and resource 'system output volume' with range 0-100, distinguishing it from sibling tools like set_volume or mute.
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 explicit when/not to use; purpose implicitly guides usage. No alternatives mentioned, but sufficient for a simple getter.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Whether system output is muted (true/false).
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true. Description adds that it returns true/false, but minimal extra 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?
Single sentence, front-loaded, no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter read-only boolean tool, description is fully adequate. No output schema needed.
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?
No parameters, schema coverage 100%. Baseline 4 applies as description needs no param info.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it checks mute status and returns boolean. Distinguishes from sibling tools like mute/unmute which are actions.
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 explicit usage guidance, but the description implies it's a read-only check. Missing when-not or alternative scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List visible (non-background) running application names.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true, and the description adds the important detail that it lists visible (non-background) apps. It doesn't specify behavior for empty lists, but overall adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is a single 5-word sentence, front-loaded with the verb and resource. Every word adds value; no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and simple functionality, the description is mostly sufficient. It could mention the return format (e.g., list of strings) but the lack is minor.
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?
No parameters exist, so baseline is 4. The description adds no parameter info, which is acceptable for a zero-parameter tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists visible running app names with a specific verb and resource, distinguishing it from siblings like frontmost_app or background process tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The tool has no parameters and a simple purpose, but there is no explicit guidance on when to use vs alternatives such as frontmost_app or open_app; usage is implied but not stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the names of the user's installed Apple Shortcuts.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, and the description adds that only names are listed (not full details), providing useful context beyond the annotation.
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?
A single sentence that is front-loaded with the verb and resource, containing no extraneous 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 parameters, no output schema, and annotations present, the description is mostly complete. It could mention permission requirements or output structure, but for a simple read-only listing, it is adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, so the description adds value by specifying that it lists only names, aligning with the baseline expectation for zero-parameter tools.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List') and identifies the exact resource ('names of the user's installed Apple Shortcuts'), clearly stating what the tool does and distinguishing it from siblings like 'run_shortcut'.
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?
While the purpose is clear for a simple listing tool, no explicit guidance is provided on when to use it versus alternatives. The context of listing vs. running shortcuts is implied but not stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Lock the screen.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint: false. The description adds no further behavioral context such as side effects or prerequisites; it is adequate but not enhanced.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no wasted words, perfectly concise for the tool's simplicity.
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 parameterless, outputless tool, the description is complete and sufficient to inform an agent of its action.
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?
No parameters exist (100% coverage), and the description appropriately omits parameter details. Baseline 4 for zero-parameter tools.
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 'Lock the screen.' clearly states the tool's purpose with a specific verb and resource, distinguishing it from sibling tools like 'open_app' or 'mute'.
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 you want to lock the screen) but provides no explicit guidance on when to use vs alternatives or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Look up a contact by name; returns matching names with phones and emails.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=true, and the description adds value by specifying the return payload (names, phones, emails). However, it does not disclose behavior like case sensitivity, partial matching, or handling of multiple results.
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 front-loading the action and result. Every word adds value; no waste.
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 a simple tool (1 parameter, no output schema), the description adequately covers purpose and return data. It omits possible details like multiple matches or partial name matching, but is 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 coverage is 0%, so the description bears full burden for parameter meaning. It only says 'by name', adding no extra detail beyond the schema (which already shows a string parameter named 'name'). No examples or format hints.
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 it looks up a contact by name and returns matching names with phones and emails. This verb+resource combination is specific and distinguishes from all sibling tools, none of which deal with contacts.
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 contact information but provides no explicit guidance on when to use this tool versus alternatives. No exclusion criteria or context for when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Open Maps with directions to a destination.
| Name | Required | Description | Default |
|---|---|---|---|
| destination | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description mentions opening Maps with directions, which implies launching an app and a UI action, but does not disclose side effects (e.g., app focus, potential errors, or permissions). Annotations only have readOnlyHint=false, which is not contradicted, but the description adds little beyond that.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with no wasted words. It could benefit from a bit more structure (e.g., separated notes), but it is appropriately concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the tool (one required parameter, no output schema), the description is minimal but lacks details like supported destination formats, platform availability, or behavior when Maps is not installed. More context would help the agent 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?
The only parameter 'destination' has 0% schema description coverage. The tool description does not add meaning beyond the parameter name, such as expected format (e.g., address, coordinates) or examples.
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: opening Maps with directions to a destination. It uses a specific verb-resource combination ('Open Maps with directions') that distinguishes it from related sibling tools like open_app or search_google.
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. For example, open_url could also open Maps directions via URL, but no comparison or exclusion criteria are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Virtual memory statistics (vm_stat).
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=true, so the description does not need to elaborate on safety. It adds 'vm_stat' reference, which provides minor context about the underlying command, but no additional behavioral traits beyond the annotation.
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?
A single sentence with no wasted words. Front-loaded with 'Virtual memory statistics', immediately communicating the tool's 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?
For a no-parameter tool with readOnlyHint annotation, the description is complete. It explains what the tool returns, and no additional context is necessary.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are no parameters, so the schema coverage is 100%. The description does not add parameter info, but with zero parameters, the baseline is 4. It simply states the output is virtual memory statistics.
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 it provides virtual memory statistics, which is a specific verb+resource. It distinguishes from sibling tools like battery_status and disk_usage by focusing on memory.
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 explicit guidance on when to use this tool vs alternatives. While the purpose is clear, there are no exclusions or context about when it's appropriate (e.g., for monitoring memory load). The usage is implied but not stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Skip to the next track in the Music app.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=false, so the agent knows this is a mutation. The description adds that it targets 'the Music app', but does not disclose behaviors like what happens if no next track exists or if the app is closed. With annotations covering the write nature, the description provides minimal extra 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?
A single, clear sentence with no unnecessary words. It is front-loaded with the action and resource.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter tool with no output schema and straightforward action, the description provides all necessary information. No additional details are required.
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 no parameters (100% coverage), so the description does not need to explain parameters. It adds meaning by stating the action, going beyond the empty schema. The baseline for high schema coverage is 3, but the description justifies a slightly higher score by clarifying the tool's function.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Skip') and resource ('next track in the Music app'), which clearly identifies the tool's action. It distinguishes from sibling tools like music_previous by specifying direction.
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 implicitly states when to use the tool (to skip to the next track), but does not explicitly compare with alternatives or mention edge cases like reaching the end of a playlist. However, the context from sibling tools makes the usage clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Toggle play/pause in the Music app.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations show readOnlyHint=false, consistent with the state-changing action. However, the description adds no extra behavioral context (e.g., prerequisites, side effects, or behavior when already playing).
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?
Single sentence with no unnecessary words. Every word adds value; it is optimally concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple no-parameter tool, the description is adequate. However, it could mention that the Music app must be open or that it toggles the current state, adding a bit more 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?
No parameters exist, and schema coverage is trivially 100%. The description adds no param-specific info, but none is needed; the baseline for zero-parameter tools is 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'Toggle play/pause in the Music app.' It uses a specific verb and resource, distinguishing it from sibling tools like music_next or music_previous.
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 explicit guidance on when to use this tool versus alternatives. The description implies usage for toggling playback but lacks context or when-not-to-use examples.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Go to the previous track in the Music app.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=false, and the description adds the behavioral action of navigating to the previous track. It does not contradict annotations and provides the core behavior beyond the annotation's safety classification.
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?
A single, clear sentence with no unnecessary words. Perfectly concise for the simple action.
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 zero parameters and no output schema, the description fully specifies the tool's action. No additional context is needed for correct usage.
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?
No parameters exist, and schema coverage is 100% (empty schema). The description adds no parameter info as none is needed. Baseline score of 4 for zero-parameter tools 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 verb 'Go to' and the resource 'previous track in the Music app.' It effectively distinguishes from siblings like music_next (go to next track) and music_playpause (toggle playback).
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 skipping to the previous track, but does not explicitly state when to use this tool versus alternatives like music_next or music_playpause. Lacks 'when-not-to-use' guidance, relying on implied context from sibling names.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Mute system output.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description states 'Mute system output', implying a mutating action, which aligns with the readOnlyHint=false annotation. However, it does not disclose side effects (e.g., behavior when already muted, impact on volume level). The annotation covers the write nature, but the description provides no additional 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 sentence that directly states the tool's purpose with no filler. It is appropriately concise for a parameterless 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 simplicity (no parameters, no output schema), the description covers the essential functionality. It could mention the absence of return values or confirm success, but it is largely complete for its 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?
There are no parameters, so the description does not need to add meaning. The schema coverage is 100% (empty properties). Baseline for zero parameters is 4, and the description is adequate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Mute system output' uses a specific verb and resource, clearly indicating the action. It distinguishes from sibling tools like 'unmute' and 'set_volume' by directly naming the opposite action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as 'set_volume' or 'toggle_dark_mode'. Without explicit context, the agent may not know preferred use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Show a macOS notification banner.
| Name | Required | Description | Default |
|---|---|---|---|
| title | Yes | ||
| message | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description accurately describes the tool's basic behavior. Annotations already indicate readOnlyHint=false, so no contradiction. However, it does not disclose additional behavioral traits such as permission requirements, blocking behavior, or that it only works on macOS, though the platform is implied in 'macOS'.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no unnecessary words. It is highly concise and 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 the tool's simplicity (2 required string parameters, no output schema), the description is reasonably complete. It could mention that it does not return a value or that the notification is non-blocking, but the current level is sufficient for a basic notification tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, meaning the description should compensate, but it does not describe the parameters at all. The parameter names 'title' and 'message' are self-explanatory, but no additional semantics like character limits or formatting are provided.
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 'Show a macOS notification banner' clearly states the action (show) and resource (notification banner) with platform specificity (macOS). It is distinct from sibling tools like say, set_volume, etc.
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 usage guidelines are provided. The description does not indicate when to use this tool over alternatives like say or other notification-like tools, nor does it mention any prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Current track in the Music app, if playing.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotation already marks it as read-only, so the description need only add behavioral context. It includes the important conditional 'if playing,' which hints at potential null results, but does not explicitly state what happens when nothing is playing (e.g., returns null or empty).
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 short sentence that is front-loaded and contains no unnecessary words. Every part adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given zero parameters and annotations, the description is mostly adequate. However, without an output schema, it is vague about what 'current track' means (e.g., just the name or full metadata). More specificity about the return value 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?
There are no parameters, and the schema coverage is 100%. The description adds no parameter information, which is acceptable as the baseline for a parameterless tool.
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 it returns the current track in the Music app if playing, using a specific verb and resource. It distinguishes itself from sibling tools like music_playpause and music_next, which are actions, not queries.
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 wanting to know the currently playing track, but does not provide explicit guidance on when to use this tool versus alternatives like search_music_track. No exclusions or conditions are mentioned beyond 'if playing'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Launch/activate an application by name (e.g. "Safari").
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate non-read-only (readOnlyHint: false). Description says launch/activate, consistent with modification. However, no additional behavioral details like foreground behavior, error handling, or permissions required.
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?
One sentence, efficient and front-loaded. No unnecessary words. Could include a brief note on failure behavior but overall concise.
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?
Tool is simple but lacks details on return value, error cases, and behavior when app is not found. With no output schema, description should cover what the tool returns or indicates on success/failure.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 0% coverage for the single parameter 'name'. Description adds 'by name (e.g. Safari)', providing a basic example. It does not specify whether it expects display name, bundle ID, or path, so partial improvement.
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 launches/activates an application by name, with an example (Safari). It distinguishes from sibling tools like close_app and list_running_apps.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this vs alternatives like open_url or run_applescript. It is implied for launching apps by name, but lacks context about prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Open a URL (or file/URI scheme) in the default handler.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description does not disclose side effects, such as what happens if the URL is invalid or if the operation blocks. The annotation readOnlyHint=false indicates mutability, but the description adds minimal behavioral context beyond the action itself.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that effectively communicates the tool's purpose without any superfluous 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?
For a simple tool with one parameter and no output schema, the description is adequate but could be improved by noting default handler behavior, error handling, or return value.
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 sole parameter 'url' is not described beyond its name. With 0% schema description coverage, the description adds no additional meaning for the parameter, leaving the agent to infer its format and restrictions.
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 the resource ('a URL (or file/URI scheme)'). This distinguishes from siblings like 'open_app' which opens applications.
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 the tool should be used to open URLs or files in the default handler, but provides no explicit guidance on when to use this tool versus alternatives or any exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run an arbitrary AppleScript and return its result.
Destructive scripts (delete, erase, shutdown, restart, trash, etc.) are refused for safety — do those manually.
| Name | Required | Description | Default |
|---|---|---|---|
| script | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=false, and description adds that destructive scripts are refused for safety, providing useful behavioral context beyond annotations. However, other behaviors like error handling are omitted.
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?
Description is two short, front-loaded sentences with no wasted words. It efficiently conveys the primary action and a key safety note.
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 single parameter and no output schema, the description lacks details on return values, examples, or script length limits. It is adequate but not 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 coverage is 0% with no description for the 'script' parameter. The tool description does not explain what the script parameter expects (e.g., format, valid content), providing insufficient guidance.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool runs an arbitrary AppleScript and returns the result, using a specific verb and resource. It distinguishes itself from siblings as the only tool for executing AppleScript.
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?
Description mentions not to use for destructive scripts, but lacks explicit when-to-use guidance or alternatives. Usage context is implied but not fully developed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run an Apple Shortcut by name (unlocks Focus modes, HomeKit, timers, etc.).
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (readOnlyHint=false), description only adds that it 'runs' a shortcut, without disclosing side effects, permissions, or whether shortcuts require user interaction. Annotations already convey mutability.
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?
Single sentence is concise and front-loaded with the action, but parentheses add extra context without clutter.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter tool with no output schema, description provides some context (capabilities) but omits that the shortcut must exist on the device, which is a key prerequisite.
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?
Description merely restates 'by name' for the only parameter; schema coverage is 0% and no additional syntax, constraints, or examples are provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Run an Apple Shortcut by name' with specific verb and resource, and lists unlocked capabilities (Focus modes, HomeKit, timers), distinguishing it from siblings like run_applescript or open_app.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives among 37 sibling tools; lacks when-not-to-use or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Speak text aloud via text-to-speech.
| Name | Required | Description | Default |
|---|---|---|---|
| text | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=false, implying a side effect (audio output). The description does not disclose whether it plays immediately, requires permissions, or blocks execution. No behavioral details beyond the basic action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence with zero waste. Every word contributes to the core purpose. Ideal conciseness 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?
For a one-parameter tool with no output schema and no formal complexity, the description is adequate but leaves gaps: no mention of system voice defaults, blocking vs async behavior, or error cases. Could be improved with a brief note on outcomes.
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 0%, so the description bears full burden for parameter meaning. The description only repeats the purpose ('text') without clarifying format, length limits, or allowed characters. Minimal added value over the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Speak' and the resource 'text', with the specific mechanism 'via text-to-speech'. It unambiguously distinguishes from all sibling tools, none of which perform text-to-speech.
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 on when to use this tool versus alternatives or when not to. While no sibling offers similar functionality, the description lacks any context about prerequisites (e.g., audio output) or scenarios where this tool is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Capture the full screen to ~/.applescript-mcp/screenshot.png and return its path.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=false, which aligns with the mutating nature (saving a file). The description adds the file path detail but does not disclose whether existing file is overwritten or if permissions are required. Adds some value beyond annotations but not comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence that is direct and without any fluff. Every word contributes to understanding the tool's purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no parameters and no output schema, the description covers basic functionality. However, it lacks details about behavior (e.g., overwriting policy, error handling, multi-monitor handling) that an agent might need. Partially 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?
No parameters exist, and schema coverage is 100%. The description does not need to add parameter information. Baseline 4 for 0-param tools.
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 it captures the full screen to a specific file path and returns the path. The verb 'Capture' and resource 'full screen' are specific and distinguish it from sibling tools like 'battery_status' or 'close_app'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives, or any prerequisites. The description lacks context about when a screenshot is appropriate or any exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Open a Google search for the query in the browser.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses the browser-opening behavior, adding context beyond the readOnlyHint=false annotation. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that conveys the core action 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 simple tool (1 param, no output schema), the description sufficiently explains the action, though it omits what happens after the browser opens.
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?
With 0% schema coverage, the description only states 'query' without detailing format, encoding, or constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Open a Google search') and resource ('for the query in the browser'), clearly distinguishing it from sibling tools like search_youtube.
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 on when to use this tool vs alternatives (e.g., search_youtube, search_music_track) is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Open Music and search the library for a track.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=false, which aligns with 'Open Music' potentially launching the app (a side effect). However, the description does not disclose that the tool may open a separate app or modify state beyond searching. The behavioral implications are unclear.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise at 8 words and front-loaded, but it sacrifices necessary detail. Every sentence should earn its place; this one is too brief to be fully useful.
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 an output schema and only one parameter, the description is incomplete. It does not explain what the tool returns, whether it plays the track, or how the library is searched. A more complete description would include the search scope and expected outcome.
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 0%, and the description adds no meaning to the single 'query' parameter. The agent receives no guidance on the expected format, content, or constraints of the query string.
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 (search) and resource (Music library), and the verb 'search' distinguishes it from sibling tools like music_playpause or music_next. However, it could be more specific about what the tool does after searching (e.g., returns results or plays a track).
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 like music_playpause or now_playing. The description does not specify prerequisites or 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 Photos and search for a term.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=false, suggesting the tool modifies state (opens an app). The description mentions 'Open Photos' which aligns with a state change, but does not elaborate on side effects (e.g., does it close other apps? Does it affect the current focus?). Minimal behavioral disclosure beyond what annotations imply.
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 (6 words), but brevity comes at the cost of completeness. It is front-loaded but fails to earn its place by omitting essential details about behavior and return values.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple schema (1 string parameter) and no output schema, the description should clarify what the tool returns and any behavioral nuances. It does not mention whether the search yields results or just opens the app. Incomplete for an agent to confidently invoke the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single 'query' parameter is described as 'search for a term', which maps directly to the parameter name and provides basic meaning. However, with 0% schema coverage, the description adds only minimal value—no format constraints, examples, or special instructions for the query string.
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 'Open Photos and search for a term' indicates the tool launches the Photos app and performs a search, but it's unclear if it returns results or just executes the search. The verb+resource is clear enough, but the scope (what is returned) is ambiguous. Distinguishes from siblings by being Photos-specific.
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 on when to use this tool versus alternatives like search_google or search_youtube. No prerequisites or conditions mentioned. The agent must infer usage solely from the tool name and brief description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Open a YouTube search for the query in the browser.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description implies opening a browser, which is a behavioral side effect beyond the annotation (readOnlyHint=false). However, it does not disclose details like focus change or browser requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, 10 words, no fluff. Verb is front-loaded, making the purpose immediately clear.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one parameter and no output schema, the description is adequate but lacks details on return behavior (e.g., whether it opens a tab or returns a result).
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 only mentions 'the query' without adding meaning beyond the schema parameter name. With 0% schema coverage, this is insufficient to clarify format, encoding, or limitations.
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 the resource ('YouTube search'), distinguishing it from sibling tools like 'search_google'. However, it borders on tautology by repeating 'search' from the tool name.
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 on when to use this tool versus alternatives such as 'search_google' or 'search_music_track'. The agent receives no context for decision-making.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Send an iMessage to a phone number or email handle.
| Name | Required | Description | Default |
|---|---|---|---|
| message | Yes | ||
| recipient | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only provide readOnlyHint=false, which is consistent. But description lacks behavioral details like delivery guarantees, error handling, or SMS fallback. For a write tool, more context is needed.
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?
Single sentence, front-loaded, no unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Simple tool but missing critical context: network requirements, character limits, delivery confirmation. Incomplete for production 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 0%. Description adds minimal meaning: 'recipient' is phone/email, 'message' is just text. No format or constraints specified.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the verb 'Send' and resource 'iMessage', specifies recipients as phone number or email handle. Distinct from sibling tools like compose_mail or facetime_call.
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 on when to use vs alternatives. Does not mention prerequisites (e.g., Apple device), fallback behavior, or when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Replace the clipboard contents with text.
| Name | Required | Description | Default |
|---|---|---|---|
| text | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=false (write operation). Description says 'replace', implying overwrite, but no mention of side effects or permissions. No contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no wasted words. Perfectly concise 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?
Simple tool with one parameter, but lacks return value info and any behavioral caveats. Adequate but minimal.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage 0%, description only says 'with text', adding no meaning beyond schema's 'text' parameter. Needs more detail on allowed content or encoding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description uses specific verb 'replace' and resource 'clipboard contents with text', clearly distinguishing from sibling 'get_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?
No explicit when-to-use or when-not-to-use guidance, but context makes it clear for setting clipboard. Lacks alternatives mention.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Set system output volume (0-100).
| Name | Required | Description | Default |
|---|---|---|---|
| level | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false, so description confirms write operation but adds no additional behavioral context (e.g., immediate effect, permission requirements). Adequate but minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with no superfluous text. All information is relevant and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Description covers the key aspect (range) for a simple 1-param tool with no output schema. Could mention units or system-wide effect, but not essential.
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 provides no description for 'level' param (0% coverage). Description adds the valid range 0-100, which is essential meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states verb 'Set' and resource 'system output volume' with valid range (0-100). Distinguishes from siblings like get_volume, mute, unmute.
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 on when to use this tool versus alternatives like mute/unmute or adjust app-specific volume. Lacks context for appropriate usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Toggle macOS Dark Mode.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate mutation (readOnlyHint=false); description confirms toggle action but adds no further behavioral context like state feedback or prerequisites.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise single sentence with zero waste; every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter toggle tool, description is largely sufficient; could mention if any return value or visual feedback, but not critical.
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?
No parameters exist, so baseline is 4; description adds meaning by specifying the action target, though minimal.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states verb 'toggle' and resource 'macOS Dark Mode', specifically identifying its function among many sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use or behavior when dark mode is already toggled; usage is implied by the verb.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Unmute system output.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate mutability (readOnlyHint=false). Description adds no further behavioral details.
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?
Single sentence with no wasted words, perfectly sized for the simple action.
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?
Adequate for a parameterless action, though specifying what 'system output' refers to (e.g., audio) could enhance clarity.
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?
No parameters; schema coverage 100%. No need for extra description since empty.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clear verb 'Unmute' and resource 'system output' indicate the action. Distinct from sibling 'mute' and 'is_muted'.
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 on when to use this tool versus alternatives like 'mute' or 'is_muted'. Just states the action.
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.
v0.1.0battery_statusclose_appcompose_mailcreate_reminderdisk_usagefacetime_callfrontmost_appget_clipboardget_datetimeget_ipget_volumeis_mutedlist_running_appslist_shortcutslock_screenlookup_contactmaps_directionsmemory_statsmusic_nextmusic_playpausemusic_previousmutenotifynow_playingopen_appopen_urlrun_applescriptrun_shortcutsayscreenshotsearch_googlesearch_music_tracksearch_photossearch_youtubesend_imessageset_clipboardset_volumetoggle_dark_modeunmuteScored across 39 tools
Each tool has a clear, distinct purpose covering system info, app management, media, communication, and utilities. There is no overlap that would confuse an agent; even closely related tools like mute and is_muted or set_volume and get_volume are easily distinguishable by their action vs. query nature.
All tool names follow a consistent verb_noun pattern in snake_case (e.g., close_app, get_volume, send_imessage). There are no mixed conventions or abbreviations, making the naming predictable and easy to understand.
With 39 tools, the server is extensive but still well-scoped for a general macOS automation tool. While slightly high, each tool addresses a distinct operation, and the count feels appropriate for the broad domain covered.
The tool set covers many common automation tasks (system info, apps, media, messaging, clipboard, reminders, shortcuts), but it lacks tools for file operations, calendar, browser control beyond opening URLs, and system preferences beyond volume/dark mode. These gaps limit its ability to handle some typical workflows.
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
MCP connector that lets ChatGPT list, search, and run your Apple Shortcuts via a local Mac agent
Personal assistant MCP server with search, execute, packages, jobs, secrets, and integrations.
MCP server for progressive tool usage at any scale (see https://klavis.ai)
