applescript-mcp

Server Quality Checklist

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

Latest release: v1.0.0
Disambiguation4/5
Tools are well-organized into distinct domains (e.g., Calendar, Clipboard, Finder, Mail, Messages, Notes, Notifications, Pages, Shortcuts, System), with clear purposes within each domain. Minor potential confusion exists between 'notes_create' and 'notes_createRawHtml', which both create notes but with different content formats, but descriptions clarify the distinction.
Naming Consistency5/5
Tool names follow a highly consistent verb_noun pattern throughout (e.g., calendar_add, clipboard_get_clipboard, finder_search_files). All tools use snake_case consistently, with no deviations in naming conventions, making them predictable and easy to parse.
Tool Count3/5
With 33 tools, the count is borderline high for a single server, potentially overwhelming for agents. However, given the broad scope of automating various macOS applications and system functions, the number is reasonable but could benefit from more modular organization to reduce cognitive load.
Completeness4/5
The tool set provides comprehensive coverage across multiple macOS domains, with CRUD operations for key apps like Calendar, Mail, Messages, and Notes. Minor gaps exist, such as no update or delete tools for Calendar events or Pages documents, but agents can work around these with existing tools for most workflows.
Average 3/5 across 33 of 33 tools scored.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 0 commits in the last 12 weeks
- No stable releases found
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI status not available
This repository is licensed under MIT License.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
Add a glama.json file to provide metadata about your server.
If you are the author, simply .
If the server belongs to an organization, first add glama.json to the root of your repository:
```
{
  "$schema": "https://glama.ai/mcp/schemas/server.json",
  "maintainers": [
    "your-github-username"
  ]
}
```
Then . Browse examples.
Add related servers to improve discoverability.

How to sync the server with GitHub?

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

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

How is the quality score calculated?

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

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

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

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

Tool Scores

Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It states the action but doesn't disclose behavioral traits such as permissions required (e.g., user consent, accessibility settings), side effects (e.g., app opens in foreground, may trigger notifications), or limitations (e.g., rate limits, app availability). This leaves the agent guessing about execution risks.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is brief and front-loaded with the core action. However, the bracketed prefix '[System control and information]' is redundant and doesn't add value, slightly reducing efficiency. It's otherwise concise with no wasted sentences.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations, no output schema, and a single parameter with full schema coverage, the description is incomplete. It fails to address key contextual aspects like what happens on launch (success/failure feedback), error conditions, or system dependencies, making it inadequate for safe agent use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with the parameter 'name' documented as 'Application name'. The description adds no meaning beyond this, such as format examples (e.g., 'Safari', 'com.apple.Safari'), validation rules, or how it resolves ambiguities. Baseline 3 is appropriate since the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the action ('Launch') and resource ('an application'), but it's vague about scope and lacks specificity. The prefix '[System control and information]' is generic and doesn't clarify what 'system' refers to (e.g., macOS, OS-level). It doesn't distinguish from sibling tools like 'system_quit_app' or 'system_get_frontmost_app' beyond the verb.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., app must be installed), exclusions (e.g., cannot launch system processes), or compare to siblings like 'shortcuts_run_shortcut' for automation. The description offers no context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. 'Send a system notification' implies a write operation that likely requires permissions and may have side effects (e.g., user disruption), but the description doesn't disclose behavioral traits like authentication needs, rate limits, or what happens when notifications are sent. It's minimally descriptive for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with just two words in brackets and three words outside: '[Notification management] Send a system notification'. It's front-loaded and wastes no words, though this brevity contributes to gaps in other dimensions. Every sentence (or phrase here) earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given this is a mutation tool with no annotations and no output schema, the description is incomplete. It doesn't explain what a 'system notification' entails, who receives it, potential errors, or return values. For a tool that likely interacts with user interfaces or permissions, more context is needed for effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all parameters (title, message, sound) with descriptions and defaults. The description adds no additional meaning beyond what's in the schema, such as formatting constraints or examples. Baseline 3 is appropriate when the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Send a system notification' states the verb ('send') and resource ('system notification'), but it's vague about what constitutes a 'system notification' and doesn't differentiate from sibling tools like 'notifications_toggle_do_not_disturb'. It's clear enough to understand the basic action but lacks specificity about the notification target or system scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites, context for sending notifications, or compare to other notification-related tools. Without any usage context, an agent must infer based on the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It states the action ('Add a new event') but doesn't cover permissions needed, whether the operation is idempotent, error conditions, or what happens on success. For a mutation tool with zero annotation coverage, this leaves significant behavioral gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is brief and front-loaded with the core action. The bracketed prefix is slightly redundant but doesn't significantly impact efficiency. It could be more polished but avoids unnecessary verbosity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with no annotations and no output schema, the description is inadequate. It doesn't explain what happens after adding the event, what permissions are required, or potential side effects. The context demands more completeness given the tool's complexity and lack of structured metadata.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema fully documents all 4 parameters. The description adds no parameter-specific information beyond what's in the schema, meeting the baseline expectation but not providing additional semantic context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Add') and resource ('new event to Calendar'), making the purpose unambiguous. However, it doesn't differentiate from sibling tools like 'calendar_list' beyond the basic operation type, and the bracketed prefix '[Calendar operations]' adds minimal value.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites, appropriate contexts, or exclusions, leaving the agent with no usage framework beyond the basic operation implied by the name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states the action ('Clear clipboard content') but doesn't mention side effects (e.g., permanent deletion, system permissions required, or error handling). For a mutation tool with zero annotation coverage, this is a significant gap in transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is brief ('Clear clipboard content') and front-loaded, but it's overly concise to the point of being vague—it could benefit from slightly more detail without becoming verbose. The bracketed text '[Clipboard management operations]' adds minimal value and feels extraneous.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (a mutation operation with no annotations and no output schema), the description is incomplete. It lacks details on behavior, outcomes, or error conditions, making it inadequate for safe and effective use by an AI agent in this context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0 parameters with 100% coverage, so no parameter documentation is needed. The description doesn't add param info, which is acceptable here, but it doesn't fully compensate for other gaps, so a baseline 4 is assigned as it meets the minimum for zero-param tools.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Clear') and resource ('clipboard content'), making the purpose specific and understandable. However, it doesn't explicitly differentiate from sibling tools like 'clipboard_get_clipboard' or 'clipboard_set_clipboard' beyond the verb, which prevents a perfect score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as 'clipboard_set_clipboard' (which might overwrite content) or other clipboard operations. The description lacks context, prerequisites, or exclusions, offering minimal usage direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It states what the tool does but doesn't describe important behavioral aspects: whether this overwrites existing clipboard content, what format the content should be in, whether there are size limitations, or what happens after execution. For a mutation tool with zero annotation coverage, this is insufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise at just two words ('Set clipboard content'), which is appropriate for a simple tool. However, the bracketed prefix '[Clipboard management operations]' adds unnecessary noise without providing useful information, slightly reducing efficiency.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with no annotations and no output schema, the description is inadequate. It doesn't explain what happens after execution, whether the operation is reversible, what permissions are needed, or what format the content should be in. Given the tool's potential to affect system state, more context is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already fully documents the single 'content' parameter. The description adds no additional parameter information beyond what's in the schema. This meets the baseline expectation when schema coverage is high, but doesn't provide extra value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Set') and resource ('clipboard content'), making the purpose immediately understandable. It distinguishes from sibling clipboard_clear_clipboard and clipboard_get_clipboard by specifying the 'set' operation. However, it doesn't fully differentiate from iterm_paste_clipboard which also interacts with clipboard content.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention when to choose clipboard_set_clipboard over iterm_paste_clipboard or other clipboard-related operations, nor does it specify prerequisites or appropriate contexts for setting clipboard content.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It states the basic function but lacks critical details: it doesn't specify what happens if no files are found, whether the search is recursive, what file attributes are returned, or if there are any limitations (e.g., search depth, file types). For a search tool with zero annotation coverage, this leaves significant gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise—a single, efficient sentence that directly states the tool's function. It's front-loaded with the core purpose and wastes no words. This is an excellent example of brevity without sacrificing clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (search operation with 2 parameters), no annotations, and no output schema, the description is incomplete. It doesn't explain what the tool returns (e.g., file paths, metadata), error conditions, or behavioral nuances. For a search tool, this leaves the agent guessing about the output format and operational details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents both parameters (query and location) with descriptions. The description adds no additional parameter semantics beyond what's in the schema. The baseline score of 3 reflects adequate coverage by the schema alone, with no extra value from the description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose as searching for files by name, specifying both the verb ('Search') and resource ('files'). It distinguishes from some siblings like finder_get_selected_files (which retrieves selected files) but doesn't explicitly differentiate from notes_search or messages_search_messages, which are similar search operations in different domains.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention when to prefer this over other search tools (like notes_search) or when to use it in conjunction with other file operations (like finder_get_selected_files). There's no context about prerequisites or typical use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It states the basic action but lacks critical information: whether this executes commands synchronously or asynchronously, what happens with command output, error handling, security implications, or any side effects. The description doesn't compensate for the missing annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with just two brief phrases. While efficient, the bracketed prefix '[iTerm terminal operations]' adds minimal value and could be considered slightly redundant given the tool name already indicates iTerm functionality.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a command execution tool with no annotations and no output schema, the description is inadequate. It doesn't explain what happens after command execution, how output is handled, error conditions, or security considerations. The description should provide more context given the tool's potential complexity and impact.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already fully documents both parameters. The description doesn't add any meaningful parameter semantics beyond what's in the schema - it mentions 'command' but provides no additional context about command syntax, restrictions, or the implications of the newWindow parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Run a command') and target ('in iTerm'), providing a specific verb+resource combination. However, it doesn't distinguish this tool from its sibling 'iterm_paste_clipboard', which also performs iTerm operations but with different functionality.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. There's no mention of when to choose 'iterm_run' over 'iterm_paste_clipboard' or other terminal/system tools, nor any context about prerequisites or typical use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. While 'Create a new email' implies a write/mutation operation, the description doesn't disclose important behavioral traits such as whether this requires Mail.app to be running, what permissions are needed, whether the email is saved as a draft or sent immediately, or what happens on success/failure. This leaves significant gaps for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise at just one sentence with no wasted words. It's front-loaded with the core purpose. However, the bracketed '[Mail operations]' prefix adds minimal value and could be considered slightly redundant given the tool name already includes 'mail_'.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with no annotations and no output schema, the description is incomplete. It doesn't explain what happens after creation (does it return the created email ID? does it open in Mail.app?), what errors might occur, or behavioral constraints. The 100% schema coverage helps with parameters, but overall context for using this tool effectively is lacking.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, with all three parameters (recipient, subject, body) clearly documented in the schema. The description adds no additional parameter information beyond what's already in the schema, so it meets the baseline of 3 for high schema coverage situations.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Create a new email') and the target resource ('in Mail.app'), providing a specific verb+resource combination. However, it doesn't distinguish this tool from sibling tools like 'messages_compose_message' or 'notes_create', which perform similar creation operations in different applications.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. There's no mention of when this tool is appropriate, what prerequisites might be needed, or how it differs from similar sibling tools like 'messages_compose_message' for composing messages in a different app.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It states this is a 'Get' operation but doesn't clarify whether it returns a single email or multiple matches, what happens on no matches, whether it's read-only (implied but not explicit), or any performance/rate limit considerations. The description adds minimal behavioral context beyond the basic operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that gets straight to the point. The bracketed '[Mail operations]' prefix is slightly redundant but not wasteful. The sentence structure is clear and front-loaded with the core functionality.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a search/retrieval tool with 7 parameters and no output schema, the description is minimally adequate. It identifies the tool's purpose but lacks important context about return behavior (single vs multiple results, empty result handling), relationship to sibling tools, and operational constraints. The 100% schema coverage helps, but the description itself is incomplete for optimal agent usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, providing clear documentation for all 7 parameters. The description adds no additional parameter semantics beyond what's already in the schema. According to scoring rules, when schema_description_coverage is high (>80%), the baseline is 3 even with no param info in the description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Get a specific email by search criteria from Mail.app'. It specifies the verb ('Get'), resource ('email'), and scope ('from Mail.app'), making the function unambiguous. However, it doesn't explicitly differentiate from sibling 'mail_list_emails', which appears to be a broader listing tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like 'mail_list_emails' or 'mail_create_email'. It mentions search criteria but doesn't clarify whether this is for retrieving a single matching email versus multiple results, or what happens when multiple emails match the criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions that the tool can 'automatically send a message without user confirmation' (via the 'auto' parameter), which hints at a potentially destructive action, but it doesn't disclose other critical behaviors such as permissions required, error handling, or side effects (e.g., app launching). This leaves gaps in understanding the tool's operational context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded, stating the core functionality in a single sentence. It efficiently covers the two modes of operation (opening with pre-filled message or auto-sending). There's no wasted text, though it could be slightly more structured to separate the two use cases explicitly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (3 parameters, no output schema, no annotations), the description is minimally adequate. It explains the basic action but lacks details on behavioral traits, usage context, and output expectations. Without annotations or an output schema, the description should do more to cover these gaps, but it meets a bare minimum for understanding the tool's intent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the input schema already documents all parameters ('recipient', 'body', 'auto') with clear descriptions. The description adds no additional meaning beyond what the schema provides, such as format examples or constraints. Baseline 3 is appropriate as the schema handles the heavy lifting, but the description doesn't compensate with extra insights.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Open Messages app with a pre-filled message to a recipient or automatically send a message.' It specifies the verb ('Open Messages app' or 'send a message'), resource ('Messages app'), and scope ('iMessage operations'), though it doesn't explicitly differentiate from sibling tools like 'messages_get_messages' or 'messages_list_chats' beyond the general 'iMessage operations' context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It mentions 'iMessage operations' but doesn't specify scenarios, prerequisites, or exclusions. For example, it doesn't clarify if this is for new messages only or if it interacts with existing chats, nor does it compare to other messaging tools in the sibling list.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions 'iMessage operations' but doesn't specify permissions needed, rate limits, or what 'Get messages' entails (e.g., retrieval scope, format, or potential side effects). This leaves significant gaps for a tool that accesses personal data.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise with just one sentence, front-loading the core purpose. However, it could be more structured by explicitly separating the tool's scope from behavioral notes, though it avoids unnecessary verbosity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of accessing personal messages and the lack of annotations or output schema, the description is insufficient. It doesn't cover critical aspects like data format, error handling, or privacy implications, making it incomplete for safe and effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, with the 'limit' parameter fully documented. The description adds no additional parameter information beyond what's in the schema, so it meets the baseline score of 3 for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Get') and resource ('messages from the Messages app'), making the purpose unambiguous. However, it doesn't differentiate from sibling tools like 'messages_list_chats' or 'messages_search_messages', which prevents a perfect score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like 'messages_list_chats' or 'messages_search_messages'. The description only states what it does, not when it's appropriate, leaving the agent to infer usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states it's a list operation, implying read-only behavior, but doesn't mention permissions, rate limits, pagination, or what 'available' means (e.g., recent chats, all chats). This leaves significant gaps for a tool that accesses personal data.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with a single, front-loaded sentence that directly states the tool's purpose. There is no wasted verbiage or redundancy, making it efficient and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of accessing personal messaging data, no annotations, and no output schema, the description is incomplete. It lacks details on behavioral traits (e.g., privacy implications, data format), usage context, and output expectations, leaving the agent under-informed for safe and effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema fully documents the single parameter. The description adds no parameter-specific information beyond what's in the schema, resulting in a baseline score of 3. No additional value is provided to compensate for or enhance the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('List') and resource ('available iMessage and SMS chats'), making the purpose immediately understandable. It specifies the scope (iMessage and SMS chats) but doesn't differentiate from sibling tools like 'messages_get_messages' or 'messages_search_messages', which prevents a perfect score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like 'messages_get_messages' or 'messages_search_messages'. It lacks context about use cases, prerequisites, or exclusions, leaving the agent without direction on tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It mentions the search functionality but fails to describe key behaviors such as whether the search is case-sensitive, how results are ordered, if there are rate limits, or what the output format looks like. This leaves significant gaps for an agent to understand how to use it effectively.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the core functionality with no wasted words. It uses brackets for context ('[iMessage operations]') and clearly states the action and criteria, making it easy to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of a search tool with 5 parameters, no annotations, and no output schema, the description is incomplete. It lacks details on behavioral traits, result formatting, and usage context, leaving the agent with insufficient information to operate the tool confidently beyond basic parameter input.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all parameters thoroughly. The description adds minimal value by implying text and sender filtering, but doesn't provide additional semantics beyond what's in the schema. This meets the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Search') and resource ('messages') with specific criteria ('containing specific text or from a specific sender'), making the purpose immediately understandable. However, it doesn't explicitly differentiate from sibling tools like 'messages_get_messages' or 'messages_list_chats', which prevents a perfect score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like 'messages_get_messages' or 'messages_list_chats', nor does it mention prerequisites or exclusions. It merely states what the tool does without contextual usage advice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. While it mentions 'optional formatting,' it doesn't describe what happens after creation (e.g., where the note is stored, if it's immediately saved, permissions required, or error conditions). For a mutation tool with zero annotation coverage, this is insufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that gets straight to the point. It's appropriately sized for the tool's complexity, though it could be slightly more informative given the lack of annotations and output schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with no annotations and no output schema, the description is inadequate. It doesn't explain what the tool returns, error handling, or behavioral nuances. The context signals show nested objects and required parameters, but the description doesn't address these complexities.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all parameters thoroughly. The description adds minimal value by mentioning 'optional formatting' which hints at the 'format' parameter, but doesn't provide additional context beyond what's in the schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Create a new note') and resource ('note'), and specifies it's for Apple Notes operations. However, it doesn't differentiate from its sibling 'notes_createRawHtml' which presumably creates notes with raw HTML instead of markdown-like formatting.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like 'notes_createRawHtml' or other note-related tools. There's no mention of prerequisites, constraints, or typical use cases beyond the basic function.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states the tool creates a note, implying a write operation, but doesn't cover permissions, side effects (e.g., if it overwrites existing notes), error handling, or response format. This leaves significant gaps in understanding how the tool behaves beyond its basic function.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the key information ('Create a new note with direct HTML content') without unnecessary words. It earns its place by clearly stating the tool's purpose in a compact form, making it easy to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of a write operation with no annotations and no output schema, the description is insufficient. It doesn't explain what happens after creation (e.g., returns a note ID or confirmation), error conditions, or integration with other tools like 'notes_list'. For a mutation tool, more behavioral context is needed to ensure safe and effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, with clear documentation for both parameters ('title' and 'html'). The description adds minimal value by mentioning 'direct HTML content', which aligns with the 'html' parameter but doesn't provide additional context like formatting examples or constraints. This meets the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Create'), resource ('a new note'), and method ('with direct HTML content'), making the purpose specific and understandable. However, it doesn't explicitly differentiate from its sibling 'notes_create', which might create a similar note but potentially with different input formats, leaving some ambiguity about when to choose one over the other.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like 'notes_create' or other note-related tools. It lacks context about prerequisites, such as whether the user needs to be authenticated or in a specific app state, and doesn't mention any exclusions or typical use cases for HTML-based note creation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions the action ('List') but does not cover critical aspects such as whether the operation is read-only, if it requires permissions, how results are returned (e.g., pagination, format), or any rate limits. The description is too vague to adequately inform an agent about behavioral traits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded in a single sentence, efficiently conveying the core functionality without unnecessary details. However, it could be slightly improved by structuring it to better highlight key usage points, such as emphasizing the optional nature of the folder parameter.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of annotations and output schema, the description is incomplete for effective tool use. It fails to address behavioral aspects like safety, return format, or error handling, and does not differentiate from sibling tools. For a list operation with no structured support, more contextual detail is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds minimal semantic context by noting the folder parameter is optional and for listing notes from a specific folder, but the input schema already provides 100% coverage with a clear description ('Optional folder name to list notes from'). Thus, the description does not significantly enhance parameter understanding beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('List') and resource ('notes'), specifying it can list all notes or notes in a specific folder. However, it does not explicitly distinguish this tool from sibling tools like 'notes_search' or 'notes_get', which might offer overlapping or alternative functionality for retrieving notes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides minimal guidance by mentioning the optional folder parameter, but it does not specify when to use this tool versus alternatives such as 'notes_search' (for filtered searches) or 'notes_get' (for retrieving a specific note). No explicit when-not-to-use or prerequisite information is included.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. While 'Search' implies a read-only operation, the description doesn't specify whether this requires authentication, what happens with empty results, whether there are rate limits, or what the return format looks like. For a search tool with zero annotation coverage, this is insufficient 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with just one sentence that directly states the tool's purpose. There's no wasted language or unnecessary elaboration, making it highly efficient 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.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a search tool with 4 parameters and no output schema, the description is inadequate. It doesn't explain what the search returns (just notes matching text), doesn't mention search scope (title and body as indicated in schema but not in description), and provides no context about the search behavior or limitations. With no annotations and no output schema, more completeness is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already fully documents all four parameters. The description mentions 'specific text' which aligns with the 'query' parameter, but adds no additional semantic context beyond what's already in the schema descriptions. This meets the baseline expectation when schema coverage is complete.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose as 'Search for notes containing specific text', which includes a specific verb ('Search') and resource ('notes'). It distinguishes from sibling tools like 'notes_list' by specifying search functionality, though it doesn't explicitly differentiate from 'notes_get' which retrieves specific notes by ID rather than searching by content.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention when to choose this over 'notes_list' (which lists all notes) or 'notes_get' (which retrieves a specific note by ID), nor does it provide any context about prerequisites or exclusions for using this search functionality.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden but only states it creates a document with plain text. It doesn't disclose behavioral traits like permissions needed, whether the document is saved automatically, error conditions, or what happens on success/failure. This is inadequate for a mutation tool with zero annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is brief and front-loaded with the core purpose. It uses only one sentence without unnecessary details, though it could be slightly more informative without losing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with no annotations and no output schema, the description is incomplete. It doesn't explain what the tool returns, error handling, or important behavioral aspects like where the document is saved or if it requires specific permissions, leaving significant gaps for the agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents the single 'content' parameter. The description adds minimal value by repeating 'plain text content (no formatting)' but doesn't provide additional semantics like length limits, encoding, or examples beyond what the schema states.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Create') and resource ('new Pages document'), specifying it's for Pages document operations. It distinguishes from other tools by focusing on document creation rather than retrieval or other operations, though it doesn't explicitly differentiate from similar tools like notes_create.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. The description mentions 'plain text content (no formatting)' but doesn't explain when to choose this over formatted options or other document creation tools, leaving the agent without usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It mentions the list operation and optional limit but lacks critical behavioral details: whether this is a read-only operation, if it requires permissions, how results are ordered/formatted, pagination handling, or error conditions. For a list tool with zero annotation coverage, this is insufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the core purpose. However, the bracketed prefix '[Shortcuts operations]' is redundant with the tool name and could be removed for better conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations, no output schema, and a simple parameter, the description is incomplete. It doesn't explain what a 'shortcut' is in this context, the format of returned data, or any behavioral traits. For a tool that likely returns structured data, more context is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with the single parameter ('limit') fully documented in the schema. The description adds no additional meaning beyond restating 'optional limit' from the schema. Baseline 3 is appropriate when the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('List') and resource ('all available shortcuts'), making the purpose unambiguous. However, it doesn't distinguish this tool from potential sibling list operations (like 'notes_list' or 'mail_list_emails') beyond the domain specificity implied by 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.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites, context (e.g., when listing is needed), or compare with other shortcuts tools (like 'shortcuts_run_shortcut'). The optional limit is noted but without rationale.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. 'Quit an application' implies a destructive action but doesn't specify consequences (e.g., unsaved data loss), permissions needed, or system impacts. The force parameter hints at behavioral nuance but isn't explained in the description itself.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise ('Quit an application') and front-loaded. The bracketed prefix '[System control and information]' provides context but could be considered slightly redundant with the tool name. Overall, it's efficient with minimal waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive system control tool with no annotations and no output schema, the description is insufficient. It doesn't explain what 'quit' entails operationally, success/failure conditions, or return values. The agent lacks critical context needed to use this tool safely and effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, providing complete parameter documentation. The description adds no parameter semantics beyond what's in the schema (name=application name, force=force quit). This meets the baseline for high schema coverage but doesn't enhance understanding (e.g., what constitutes a valid application name).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Quit an application' clearly states the verb (quit) and resource (application), making the purpose immediately understandable. It distinguishes from siblings like system_launch_app (launch vs quit) and system_get_frontmost_app (get vs quit). However, it doesn't specify scope (e.g., frontmost app vs any app) which prevents a perfect score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., app must be running), when force quitting is appropriate, or compare to other system control tools. The agent must infer usage from the tool name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states the action ('Set system volume') but fails to mention critical details like required permissions (e.g., admin rights), side effects (e.g., immediate volume change), or error conditions (e.g., invalid level handling). This is a significant gap for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise and front-loaded with the essential action ('Set system volume') in a single, efficient phrase. There is no wasted language, making it easy to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (a mutation operation with no annotations or output schema) and low schema coverage, the description is incomplete. It lacks details on behavioral traits, error handling, return values, or system-specific constraints, making it inadequate for safe and effective use by an AI agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description mentions 'system volume' but adds no meaning beyond what the input schema provides (a 'level' parameter with range 0-100). With 0% schema description coverage, it partially compensates by implying the parameter relates to volume, yet it doesn't explain units (e.g., percentage), default behavior, or interpretation of the level value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with a specific verb ('Set') and resource ('system volume'), making it immediately understandable. However, it doesn't distinguish itself from potential sibling tools (though none are directly related to volume control in the provided list), preventing a perfect score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, prerequisites, or context. It lacks any mention of when-not-to-use scenarios or comparisons with other system control tools, leaving usage entirely implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions listing events for today but fails to describe key traits like whether it requires authentication, how it handles errors, the format of returned events, or any rate limits. This leaves significant gaps in understanding the tool's behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise—a single sentence that directly states the tool's function without unnecessary words. It is front-loaded and efficient, making it easy to grasp quickly, which is ideal for clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of calendar operations and the lack of annotations and output schema, the description is incomplete. It does not explain what 'events' entail, how results are structured, or potential limitations, leaving the agent with insufficient information to use the tool effectively in varied contexts.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0 parameters with 100% coverage, so no parameter details are needed. The description adds context by specifying 'for today', which implies a temporal scope not captured in the schema. This extra semantic information justifies a score above the baseline of 3 for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('List all events') and resource ('for today'), making the purpose specific and understandable. However, it does not explicitly differentiate from sibling tools like 'calendar_add', which serves a different purpose (adding events), so it falls short of a perfect score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, such as other calendar-related tools or date-specific queries. It lacks context on prerequisites, exclusions, or comparisons with siblings, leaving usage unclear beyond the basic stated purpose.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the action ('Get') but doesn't describe what happens if the clipboard is empty, whether it requires specific permissions, or what format the content is returned in. For a tool with no annotation coverage, this leaves significant behavioral gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with just one sentence, front-loading the core action ('Get current clipboard content') without any wasted words. The bracketed context '[Clipboard management operations]' is minimal and doesn't detract from clarity. Every part of the description earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple tool (1 parameter, no output schema, no annotations), the description is minimally adequate. It covers the basic purpose but lacks details on behavioral aspects like error handling or return format. For a read operation with no annotations, it should ideally provide more context about what 'Get' entails (e.g., returns text or file paths as specified).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, with the 'type' parameter fully documented (enum values and default). The description adds no additional parameter semantics beyond what the schema provides, such as explaining the difference between 'text' and 'file_paths' content types. Baseline 3 is appropriate since the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Get') and resource ('current clipboard content'), making the purpose immediately understandable. It distinguishes from sibling tools like clipboard_clear_clipboard and clipboard_set_clipboard by focusing on retrieval rather than modification. However, it doesn't explicitly differentiate from other read operations like finder_get_selected_files or notes_get.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention when to choose this over other clipboard tools (e.g., clipboard_set_clipboard for writing) or other data retrieval tools. The context is implied (clipboard management), but no explicit usage scenarios or exclusions are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It states the action but lacks details on permissions needed, what happens if no files are selected, whether it returns paths or file objects, or any error conditions. This is inadequate for a tool with zero annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise and front-loaded in a single sentence, with zero wasted words. It efficiently communicates the core purpose without unnecessary elaboration, making it easy to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of annotations and output schema, the description is incomplete. It doesn't explain what the tool returns (e.g., file paths, metadata), error handling, or dependencies like requiring Finder to be active. For a tool with no structured data support, this leaves significant gaps in understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has 0 parameters with 100% schema description coverage, so the schema fully documents the lack of inputs. The description doesn't need to add parameter details, and it correctly implies no inputs are required by not mentioning any. A baseline of 4 is appropriate for zero-parameter tools.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Get') and resource ('currently selected files in Finder'), making the tool's purpose immediately understandable. However, it doesn't explicitly differentiate from sibling tools like 'finder_search_files' or 'finder_quick_look_file', which prevents a perfect score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., Finder must be open), exclusions, or comparisons to other file-related tools in the sibling list, leaving usage context unclear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It states the tool previews a file, implying a read-only operation, but doesn't disclose behavioral traits like whether it opens a temporary window, requires specific permissions, has limitations (e.g., file size), or what happens on errors. This leaves gaps for safe and effective use.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise at one sentence, front-loading the key action ('Preview a file') and method ('using Quick Look'). There is no wasted text, and every word contributes to understanding the tool's purpose efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity (one parameter, no output schema, no annotations), the description is minimally adequate. It covers the basic purpose but lacks details on usage, behavior, and output. Without annotations or output schema, more context on what the preview entails would improve completeness for safe agent invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, with the 'path' parameter documented as 'File path to preview'. The description adds no additional meaning beyond this, such as path format examples or constraints. With high schema coverage, the baseline score of 3 is appropriate, as the schema adequately covers parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Preview a file') and the method ('using Quick Look'), with the resource being a file. It specifies the tool's purpose as a preview operation rather than opening or editing. However, it doesn't explicitly differentiate from potential siblings like 'finder_get_selected_files' or 'finder_search_files', which have different purposes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., file must exist), exclusions (e.g., unsupported file types), or compare it to other file operations in the sibling list. The user must infer usage from the purpose alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It implies a write operation ('Paste') but doesn't specify whether this requires iTerm to be active, if it pastes into the current session, or what happens on failure. This leaves significant gaps in understanding the tool's behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that directly conveys the tool's function without any unnecessary words. It's front-loaded with the core action and target, making it easy to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of annotations and output schema, the description is incomplete for a tool that performs a write operation. It doesn't address potential side effects, error conditions, or what success looks like, which are critical for an AI agent to use it correctly in context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has 0 parameters, and the schema description coverage is 100%, so there's no need for parameter details in the description. The baseline for this scenario is 4, as the description appropriately avoids redundant information about non-existent parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Paste clipboard content') and target ('into iTerm'), making the tool's purpose immediately understandable. However, it doesn't explicitly differentiate from sibling tools like 'clipboard_get_clipboard' or 'iterm_run', which would require a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like 'clipboard_set_clipboard' or 'iterm_run', nor does it mention prerequisites such as having iTerm open or clipboard content available. It only states what the tool does, not when it's appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states it's a list operation, implying read-only behavior, but doesn't specify whether it requires permissions, how it handles errors, or what the output format looks like (e.g., list of email summaries vs. full content). For a tool with zero annotation coverage, this leaves significant gaps in understanding its behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the core purpose ('List emails from a specified mailbox in Mail.app'). There's no wasted text, and it's 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.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (4 parameters, no output schema, no annotations), the description is minimally adequate. It states the purpose but lacks details on behavioral traits, usage context, and output format. With no output schema, the description should ideally hint at what's returned, but it doesn't, leaving gaps in completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, meaning all parameters are documented in the input schema. The description doesn't add any additional meaning beyond what's in the schema (e.g., it doesn't explain interactions between parameters like 'unreadOnly' and 'count'). With high schema coverage, the baseline score of 3 is appropriate as the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('List emails') and target resource ('from a specified mailbox in Mail.app'), providing a specific verb+resource combination. However, it doesn't explicitly differentiate from sibling tools like 'mail_get_email' or 'mail_create_email' beyond the 'list' action, which is why it doesn't reach a perfect score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention when to choose this over 'mail_get_email' for retrieving specific emails or 'mail_create_email' for creating emails, nor does it specify any prerequisites or exclusions for usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the action ('Get a specific note') but doesn't cover critical aspects like error handling (e.g., what happens if the title doesn't exist), permissions, or return format. This leaves gaps for a tool that likely interacts with user data.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the core action ('Get a specific note') and specifies the method ('by title'). There is no wasted text, and it's appropriately sized for a simple retrieval tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity (2 parameters, no output schema) and high schema coverage, the description is minimally adequate. However, without annotations or output schema, it should ideally clarify behavioral traits like error cases or return format, but it doesn't, leaving some contextual gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, with clear docs for 'title' (required) and 'folder' (optional). The description adds minimal value beyond this, only implying that 'title' is the primary lookup key. No additional syntax or constraints are provided, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Get') and resource ('a specific note'), and specifies the retrieval method ('by title'), making the purpose unambiguous. However, it doesn't differentiate from sibling tools like 'notes_list' or 'notes_search', which also retrieve notes but with different approaches.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like 'notes_list' (for listing all notes) or 'notes_search' (for searching by content). It lacks context about prerequisites, such as needing the exact note title, or exclusions, like not handling partial matches.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states the action ('Toggle') but doesn't explain what 'dark mode' entails, whether it requires permissions, if it's reversible, or what the expected outcome is, leaving significant gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with a single sentence that front-loads the key information ('Toggle system dark mode'), making it efficient and easy to parse without any wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (a system control action) and lack of annotations or output schema, the description is incomplete. It doesn't explain what 'dark mode' means, how the toggle works, or what to expect after invocation, leaving the agent with insufficient context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has 0 parameters, and schema description coverage is 100%, so no parameter information is needed. The description appropriately doesn't discuss parameters, earning a baseline score of 4 for not adding unnecessary details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Toggle') and resource ('system dark mode'), making the purpose immediately understandable. However, it doesn't differentiate from sibling tools like 'notifications_toggle_do_not_disturb' or 'system_volume' beyond the specific resource, so it's not a perfect 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives or any context for its application. It lacks explicit when/when-not statements or references to sibling tools, leaving usage unclear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions 'Toggle Do Not Disturb mode', implying a state change, but doesn't clarify if this requires permissions, what the default state is, whether it's reversible, or any side effects like notifications being suppressed. This leaves significant gaps for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the key action ('Toggle Do Not Disturb mode') and adds a useful detail ('using keyboard shortcut') without any fluff. Every word earns its place, making it highly concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (simple toggle with no parameters) and no output schema, the description is minimally adequate. It states what the tool does but lacks details on behavioral aspects like permissions or effects, which are important for a mutation tool with no annotations. This makes it complete enough for basic use but with clear gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has 0 parameters, and schema description coverage is 100%, so there's no need for parameter details in the description. The baseline for 0 parameters is 4, as the description appropriately doesn't waste space on non-existent parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Toggle') and resource ('Do Not Disturb mode'), making the purpose specific and understandable. However, it doesn't distinguish this tool from its sibling 'notifications_send_notification' or other notification-related tools, which prevents a perfect score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions 'using keyboard shortcut', which provides some implied context for when to use this tool (e.g., for quick toggling via shortcuts). However, it lacks explicit guidance on when to choose this over alternatives, such as manual toggling or other notification tools, and doesn't specify 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.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states the action ('Get') but doesn't clarify if this requires permissions, how frequently it can be called, what the return format looks like, or potential side effects. This leaves significant gaps for a system tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with a single sentence that front-loads the key information ('Get battery level and charging status'). There is no wasted text, and the bracketed prefix '[System control and information]' efficiently categorizes the tool without verbosity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity (0 parameters, no output schema) and the description's clear purpose, it is minimally adequate. However, the lack of annotations and output schema means the description should ideally provide more behavioral context (e.g., return format, permissions), which is missing, keeping it at a baseline level.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has 0 parameters with 100% schema description coverage, so the schema fully documents the input requirements. The description doesn't need to add parameter details, and it appropriately avoids redundancy, earning a baseline score for zero-parameter tools.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with specific verbs ('Get') and resources ('battery level and charging status'), making it immediately understandable. However, it doesn't explicitly differentiate from sibling tools like 'system_get_frontmost_app' or 'system_volume', which prevents a perfect score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives or in what context it should be invoked. It lacks any mention of prerequisites, timing considerations, or comparisons to other system tools, leaving usage entirely implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the tool retrieves information ('Get'), implying it is read-only, but does not clarify permissions, potential errors (e.g., if no frontmost app exists), or response format. For a tool with zero annotation coverage, this leaves significant behavioral gaps unaddressed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise and front-loaded, consisting of a single sentence that directly states the tool's purpose. There is no wasted language or redundancy, making it efficient and easy for an agent to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (0 parameters, no output schema), the description is minimally adequate. It explains what the tool does but lacks details on behavioral aspects like error handling or return values. Without annotations or output schema, the description should ideally provide more context, but it meets the basic requirement for a simple read operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has 0 parameters, and schema description coverage is 100%, so no parameter documentation is needed. The description does not add parameter details beyond the schema, but with no parameters, this is acceptable. A baseline of 4 is appropriate as the description does not need to compensate for any parameter gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Get') and resource ('name of the frontmost application'), making the purpose specific and understandable. It distinguishes itself from siblings like 'system_launch_app' or 'system_quit_app' by focusing on information retrieval rather than control. However, it lacks explicit differentiation from other system tools (e.g., 'system_get_battery_status'), which slightly reduces clarity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention prerequisites (e.g., needing frontmost app permissions), exclusions, or comparisons to similar tools like 'system_get_battery_status'. Without such context, the agent must infer usage based on the tool name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses that the tool runs shortcuts in the background using 'Shortcuts Events,' which adds useful behavioral context about execution mode. However, it lacks details on permissions, error handling, or output format, leaving gaps for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded, consisting of two sentences that efficiently convey the core functionality and key behavioral trait. Every sentence adds value without redundancy, making it easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations and no output schema, the description is moderately complete for a tool with two parameters. It covers the basic action and execution mode but lacks details on prerequisites, error cases, or return values, which are important for a tool that performs mutations (running shortcuts).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents both parameters ('name' and 'input'). The description adds marginal value by noting that input is 'optional,' but does not provide additional semantics beyond what the schema specifies (e.g., format of input or examples). Baseline 3 is appropriate given high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Run a shortcut with optional input.' It specifies the verb ('run') and resource ('shortcut'), but does not differentiate it from sibling tools like 'shortcuts_list_shortcuts' beyond the basic action. It's not tautological, as it adds operational context beyond the name.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context by mentioning 'optional input' and that it 'runs in background without opening the app,' but it does not explicitly state when to use this tool versus alternatives (e.g., compared to 'shortcuts_list_shortcuts' or other execution methods). No exclusions or clear alternatives are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

GitHub Badge

Glama performs regular codebase and documentation scans to:

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

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

Card Badge

Copy to your README.md:

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

Score Badge

Copy to your README.md:

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

Latest Blog Posts

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

MCP directory API

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

curl -X GET 'https://glama.ai/api/mcp/v1/servers/joshrutkowski/applescript-mcp'

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