macOS Companion MCP Server

by surendranb

Overview Schema Related Servers Score Discussions

JavaScript

Local

Server Quality Checklist

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

Latest release: v1.3.2
Disambiguation4/5
Most tools target distinct apps and actions, but there is overlap among system monitoring tools (get_system_stats, get_battery_health, run_health_audit) and storage tools (get_disk_usage, get_storage_scan) that could cause misselection without careful reading.
Naming Consistency4/5
The naming largely follows verb_noun snake_case (list_calendars, create_reminder), with minor deviations like play_pause_music (verb_verb) and get_storage_scan (noun-heavy). Overall predictable.
Tool Count2/5
40 tools is excessive for a single server, even with broad macOS scope. Many tools could be split into separate domain-specific servers (calendar, system, podcasts). This makes the surface heavy to navigate.
Completeness3/5
Core operations exist for most apps (create, read, list), but lifecycle coverage is incomplete: Calendar/Reminders/Notes lack delete, Music lacks queue control, Mail lacks folder/search operations. The podcast tools are unusually thorough, but other areas feel thin.
Average 3.7/5 across 40 of 40 tools scored. Lowest: 2.7/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 35 commits in the last 12 weeks
- Last stable release on August 15, 2026
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is failing
This repository is licensed under MIT License.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
Add a glama.json file to provide metadata about your server.
If you are the author, simply .
If the server belongs to an organization, first add glama.json to the root of your repository:
```
{
  "$schema": "https://glama.ai/mcp/schemas/server.json",
  "maintainers": [
    "your-github-username"
  ]
}
```
Then . Browse examples.
Add related servers to improve discoverability.

How to sync the server with GitHub?

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

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

How is the quality score calculated?

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

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

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

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

Tool Scores

Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavioral traits. It only states 'Retrieves the body text' without mentioning whether the response includes metadata, formatting, or error behavior (e.g., what happens if the note is not found). The 'by title or ID' claim also introduces ambiguity about the expected input format, reducing transparency.
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 sentence, front-loaded with the verb, and contains no redundant phrasing. It earns conciseness points for efficiency, though the ambiguous 'by title or ID' phrase slightly detracts from perfect 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?
For a simple retrieval tool with one parameter and no annotations, the description is too sparse. It omits return value expectations, error cases, and how to obtain a valid ID (e.g., via list_notes). Given the low complexity, some of this context is necessary for an agent to use the tool confidently.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 100% coverage for the single parameter 'id', described as 'Note ID'. The description adds 'by title or ID', which suggests the parameter might also accept a title, contradicting the schema. This is more harmful than helpful, as it introduces semantic ambiguity rather than clarifying the parameter's meaning.
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 'Retrieves' with the resource 'a note' and specifies 'body text', which distinguishes it from sibling tools like list_notes and update_note. However, the claim 'by title or ID' is inconsistent with the input schema, which only accepts an 'id' parameter, creating potential confusion about the actual lookup method.
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 list_notes, nor does it mention prerequisites like obtaining the note ID first. There are no exclusions or alternative recommendations, leaving the agent without context for proper 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, the description must convey safety and mutation semantics. It claims 'safely prunes' but doesn't disclose that data is permanently deleted, whether permissions are required, or the scope of the cleanup. The term 'safely' is vague and unsupported. For a deletes data, more transparency is expected.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no wasted words. It clearly states the action and purpose in a compact form, earning full marks for 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 destructive tool with no annotations and no output schema, the description is incomplete. It lacks details on the effect of each target, whether the operation is reversible, and what the return value indicates. The simplicity of the tool doesn't excuse the missing safety-related context.
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 descriptions cover 100% of the parameter ('targets' with enum values), so the baseline is 3. The description adds minimal context by grouping targets into 'cache folders' and 'trash', but it doesn't explain specific enum values like 'derived_data' or 'package_caches'. No additional syntax or format details are provided 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 uses specific verbs ('prunes', 'empties') and names the resources ('cache folders', 'trash'), clearly indicating a disk cleanup action. It is distinct from the read-only sibling tools like get_disk_usage, though it doesn't explicitly differentiate itself.
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 on when to use this tool versus alternatives. It doesn't mention prerequisites, when not to use it, or any exclusions. The presence of sibling tools like get_disk_usage and run_health_audit suggests related actions, but no comparison is 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?
No annotations are provided, and the description only states 'Kills a process' without disclosing consequences such as irreversibility, potential data loss, permission requirements, or behavior when both pid and name are supplied. This is a destructive action, but the description offers no warnings or side-effect details.
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?
Single sentence, no filler, front-loaded with the action. However, it omits critical usage and behavioral details, making it slightly under-sized for a destructive tool.
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 output schema and no annotations, the description must explain return values, error cases, and edge conditions, but it is silent on these. With two optional parameters, it does not clarify what happens if neither is given.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with each parameter having a basic description, so the baseline is 3. The description's 'by PID or name' confirms either can be used but adds no semantics about precedence, wildcard matching, or behavior when both are provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Specific verb 'kills' with resource 'process' and scope 'by PID or name' clearly differentiates from sibling tools like restart_service and get_process_list. The description conveys the exact action and the two alternative input methods without ambiguity.
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 explicit guidance on when to use this tool vs alternatives like restart_service. The description provides no context for selection or exclusion criteria, leaving the agent to infer from 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 the full burden of disclosing behavior. It states a mutation ('marks as completed') but does not explain side effects such as irreversibility, status changes, notifications, or required permissions. This is a significant gap for a state-changing 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 sentence with zero wasted words. It is clear and front-loaded, meeting the standard for concise and effective writing.
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?
Although the tool is simple with one parameter and no output schema, the description is incomplete. It lacks detail about what 'completed' entails, any side effects, or expected behavior. For a mutation tool with no annotations, more context is necessary for an agent to invoke it safely.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage with one parameter 'id' described as 'Reminder unique ID'. The description adds no additional semantic meaning beyond the schema, so the baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Marks a reminder as completed' uses a specific verb ('marks') and resource ('reminder') with a clear action ('as completed'). This distinguishes it from sibling tools like create_reminder and get_reminders, which handle creation and retrieval.
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 offers no guidance on when to use this tool versus alternatives (e.g., create_reminder or get_reminders). It does not state prerequisites, intended context, or exclusions. Usage is only implied by the tool's name and simple action.
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?
Annotations are absent, so the description carries full responsibility for disclosing side effects and behavioral traits. It only states the action 'creates' without detailing permissions, potential errors, reversibility, or any data modifications beyond the obvious.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence with no redundant content. Every word serves the purpose, making it highly efficient and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Without annotations or an output schema, the description leaves out critical context such as return values, error conditions, or behaviors when optional parameters are omitted. For a mutation tool, this is a significant gap, making the description incomplete for an agent to fully anticipate outcomes.
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 for all four parameters, so the baseline is 3. The tool description adds no extra meaning about parameters or their interplay, relying entirely on the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Creates') and the resource ('a new reminder in Apple Reminders'), distinguishing it from sibling tools like get_reminders and complete_reminder. The verb and resource are specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. The description does not mention any prerequisites, contexts, or exclusions relative to similar tools like create_calendar_event or get_reminders.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits, but it only says 'Returns local disk usage statistics' without detailing what statistics are included, whether they are real-time, system-wide, or per-volume, or what the return format looks like. This is insufficient for an agent to predict system impact or output.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that directly states the tool's core function with no filler or repetition. It is appropriately sized for a zero-parameter read operation.
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 simplicity of the tool (no parameters, no output schema), the description meets the minimum viability but leaves unspecified what 'disk usage statistics' includes, which could cause ambiguity. With siblings like 'get_storage_scan' present, more detail on the scope or format would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the baseline is 4 per the rubric. The description does not need to explain parameter semantics, and the schema coverage is 100% (empty object), so there is no gap.
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 uses a specific verb 'Returns' and names the resource 'local disk usage statistics', making it clear what the tool does. It does not explicitly distinguish from the sibling tool 'get_storage_scan', but the name and description align well enough to infer the function.
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 'get_storage_scan' or 'run_disk_cleanup'. The description only states what it does, leaving the agent to infer appropriate use cases without exclusions or 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, the description carries the full burden of behavioral disclosure. It implies a read-only scan but does not state whether it is safe, what it returns, or any side effects like performance impact. The lack of detail leaves the agent guessing about 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 one concise sentence, front-loaded with the core action 'Deep storage scan' and then specifying what it covers. Every word contributes meaning, with no redundancy or filler.
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 no-parameter tool, the purpose is clear and the simplicity of the schema reduces the burden on the description. However, it lacks usage differentiation from siblings and behavioral transparency, making it only minimally complete for agent decision-making.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and the schema is empty, so the baseline is 4 per the rubric. The description adds contextual meaning by explaining the scan scope, but there is no parameter information to clarify 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 states a specific action ('Deep storage scan') and resource ('storage'), listing the concrete scope (home directory sizes, caches, local snapshots). It is clear and not a tautology, but it does not explicitly differentiate from sibling tools like get_disk_usage, though 'deep' implies more comprehensive coverage.
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 get_disk_usage or run_disk_cleanup. The description only explains what the tool does, not the appropriate context 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, the description carries the full burden of behavioral disclosure. It merely states the basic action without mentioning side effects (shortcuts can perform arbitrary operations), whether the tool waits for completion, or what happens if the shortcut fails. This is a significant gap for a tool that executes user-defined code.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that is front-loaded with the action and resource. No filler or redundant 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?
There is no output schema and no annotations, so the description must explain return behavior, error handling, and the role of the optional input. It does none of these, leaving the agent with incomplete information about a tool that executes arbitrary 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 coverage is 100%, and the parameter descriptions already explain 'name' and 'input'. The description adds no extra meaning beyond 'by name', which is redundant with the schema. The optional 'input' parameter is not mentioned, but the baseline of 3 applies due to complete schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Runs' with the resource 'Apple/Siri Shortcut by name', making the tool's purpose explicit. It distinguishes itself from sibling tool list_shortcuts, which only lists shortcuts.
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 does not clarify whether this generic shortcut runner should be preferred over dedicated tools like run_health_audit or run_disk_cleanup, nor does it mention any exclusions or prerequisites.
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 bears full responsibility for disclosing behavioral traits. It does not mention potential side effects (e.g., service interruption), required permissions, or failure modes, which are important for a mutating action like restarting a service.
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, compact sentence that front-loads the action and resource. Every word contributes meaning, with no redundant or filler content.
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?
The tool has a simple signature with one well-documented parameter, and the description conveys the core operation. However, because the tool mutates system state and there is no output schema or annotation, the lack of behavioral and usage context leaves the description minimally viable rather than fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with the 'service' parameter already documented as a service name with an example. The description adds no additional semantic detail beyond identifying the target as a launchd service, which is already implied by the tool's purpose.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Restarts') with a clear resource ('macOS launchd service') and specifies the method ('using launchctl'). It clearly distinguishes this tool from sibling tools, none of which target launchd services.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool versus alternatives, nor any prerequisites or exclusions. The description only states what the tool does, leaving the agent to infer appropriate usage situations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It states the action but does not disclose side effects, failure modes, or whether the Messages app opens or sends directly. For a mutation tool, this lack of behavioral detail is a gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no fluff, and front-loaded with the primary verb and resource. Every word 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?
For a simple two-parameter tool, the description is adequate but lacks usage context. It does not mention alternatives or when to prefer this over send_email. The schema covers parameters well, but the tool's role relative to siblings is not clarified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage with descriptions for both 'to' and 'message'. The description adds no extra meaning beyond the schema, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Sends'), the resource ('iMessage/SMS'), and the medium ('via Messages app'). This distinguishes it from sibling tool send_email, making the purpose unambiguous.
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 send_email. The description implies it is for text messaging but does not explicitly state exclusions or prerequisites, leaving the agent to infer usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must fully disclose behavioral traits. It only states the basic fetch action and time range, without addressing potential side effects, permissions, rate limits, or response characteristics. This leaves significant uncertainty for the agent.
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 one concise sentence that front-loads the core action. The parenthetical '(using accli)' is slightly cryptic and does not add meaningful value for the agent, but the overall structure is efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter read tool, the description is adequate but lacks clarity on what the returned data looks like (e.g., event objects, count, ordering) since no output schema is provided. There is also no mention of error cases or restrictions. The description is minimally sufficient but not rich.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides 100% coverage with clear descriptions for both 'from' and 'to' parameters. The description adds no additional parameter-specific details, so it 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb "Fetches" with a clear resource "calendar events" and a scoping condition "for a given time range". This distinguishes it from sibling tools like create_calendar_event and list_calendars, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for retrieving events within a specified time range, which provides some context. However, it does not explicitly mention when to use it versus alternatives such as create_calendar_event or list_calendars, nor does it state any exclusions or prerequisites. The guidance is implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full responsibility for behavioral disclosure. It states the tool 'sends' an email, but does not mention potential side effects, permission requirements, whether it opens the Mail UI, or if sending is immediate. 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 a single, front-loaded sentence that is concise and free of unnecessary detail. Every word contributes to understanding the tool's core function.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a simple tool with three fully described parameters and no output schema. The description sufficiently conveys the tool's purpose and scope, though it lacks any mention of behavioral constraints or prerequisites. Given the simplicity, it is largely complete for an agent to invoke correctly.
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 each parameter (to, subject, body) having its own description. The tool description adds no extra parameter meaning beyond what the schema provides, 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Composes and sends an email via Apple Mail' clearly identifies the action (composing/sending), the resource (email), and the implementation (Apple Mail). It distinguishes from sibling tool send_imessage, which handles a different messaging channel.
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 send_imessage, nor any exclusions or prerequisites. It only implies the general use case of sending an email, but lacks explicit context or comparison to siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It only states that it creates an event and mentions using 'accli', but does not reveal side effects (e.g., whether it modifies any existing events), permission requirements, or reversibility. This is minimal information 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 sentence with zero waste. It conveys the essential purpose immediately and efficiently. Every word adds value, and the parenthetical mention of 'accli' gives useful implementation context without bloating the text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple create operation with a well-documented schema, the one-sentence description provides a basic level of completeness. However, there is no output schema, and the description does not explain return values, error behaviors, or any additional context about calendar selection or requirements. This is adequate but leaves 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 for all six parameters, so the baseline is 3. The description itself adds no additional parameter semantics, but it does not need to since the schema already documents each field with examples.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Creates a new event in Apple Calendar'. The verb 'Creates' is specific, and the resource is unambiguous. It distinguishes from sibling tools like get_calendar_events by focusing on the create action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage (when you need to add a calendar event) but provides no explicit guidance on when to use it versus alternatives. It lacks exclusions or mention of related tools for viewing or listing events, but the simple name makes the intended use reasonably clear.
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 communicates a read-only operation but does not disclose behavior when nothing is playing, whether permissions are needed, or any potential error conditions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that front-loads the core action and result. Every word is purposeful, with no unnecessary detail or filler.
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?
The tool has no output schema, so the description should ideally specify what 'playback state' and 'active track metadata' include (e.g., playing/paused, title/artist/album). It provides only a high-level summary, but for a zero-parameter getter this is minimally adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and the schema description coverage is 100%, so there is no parameter information needed. The baseline of 4 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Returns') and a specific resource ('current playback state and active track metadata in Apple Music'). It clearly distinguishes itself from sibling control tools like play_pause_music, skip_music_track, and play_playlist by being the only state-query 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?
There is no guidance on when to use this tool versus alternatives like play_playlist or get_recent_podcast_episodes. The description merely states what the tool does, leaving the agent to infer that it should be used when playback state is needed.
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 disclosing behavioral traits. It only states the basic action and does not mention side effects, behavior at the start/end of a queue, whether playback is affected, or other consequences. This lack of detail leaves the agent uncertain about the tool's full impact.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no wasted words. It efficiently conveys the essential action and parameter direction.
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?
The tool is simple with one parameter and no output schema. However, the description lacks important context such as queue boundary behavior or whether the tool starts playback, which are relevant for a music control action. While not overly complex, the missing behavioral details reduce 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?
The input schema fully describes the 'direction' parameter with an enum and a short description. The description adds minimal value beyond mapping 'next'/'previous' to the intended behavior, but since schema coverage is 100%, the parameter meaning is already clear.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Skips') and the resource ('track in Apple Music'), and specifies the direction parameter ('next or previous'). This distinguishes it from sibling music tools like play_pause_music or set_music_volume, which handle different actions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use this tool (when you want to change tracks), but it does not explicitly contrast with alternatives or mention edge cases. Since sibling tools are different actions, the usage context is clear but not elaborated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden. It discloses that only 'active' reminders are fetched, implying filtering of completed ones, but does not define 'active' or mention default list behavior, return format, or permissions. This is minimal but not misleading.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no redundant words. It efficiently conveys the tool's purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read tool with one optional parameter, the description is adequate but leaves gaps: it does not define 'active', whether all lists are included by default, or what the return structure looks like. The schema covers the parameter, but the lack of output schema and behavioral detail makes it only minimally complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for the single optional parameter 'list', and its description clarifies it filters reminders by list name. The tool description adds no additional parameter detail, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool fetches active reminders from Apple Reminders, using a specific verb (fetches) and resource. It distinguishes from sibling tools like create_reminder and complete_reminder by focusing on read-only retrieval.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for reading reminders but does not explicitly state when to use it versus alternatives or mention exclusions. Sibling names suggest the distinction, but no direct guidance is 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, the description carries the full burden of disclosure. It states 'fetches' which suggests a read-only operation, but does not clarify whether the email is marked as read, what 'recent' means (time window or count), or what 'details' are returned. This leaves ambiguity about side effects and output structure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that says exactly what the tool does without unnecessary repetition or filler. It is well-structured and front-loaded with the verb.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple, parameterless tool, the description communicates the core functionality adequately. However, it lacks specifics on output format (what fields constitute 'details') and the meaning of 'recent', which would improve completeness given there is no output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema is empty, so there are no parameters to describe. The description's phrase 'recent unread email details' effectively implies the scope of the operation, earning a baseline 4 for tools with zero parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('fetches') and identifies the exact resource ('recent unread email details from Apple Mail'), making the tool's function immediately clear. It is clearly distinct from sibling tools like send_email, which sends rather than reads messages.
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 context of retrieving unread emails is stated, but there is no explicit guidance on when to use this tool versus alternatives or any exclusions. The presence of sibling tools like send_email implies this is the read counterpart, but that is not explicitly stated.
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 lists what is audited but gives no indication of read-only behavior, potential side effects, runtime duration, or system impact. As a health audit it's likely safe, but the agent cannot infer this from the description alone.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that immediately states the tool's purpose and enumerates its coverage in a compact list. Every word earns its place without redundancy.
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?
The description adequately communicates scope with zero parameters, but with no output schema or annotations, it fails to mention what the audit returns, how results are presented, or any caveats (e.g., time to run, permission requirements). This is adequate but has clear gaps for a complex aggregate tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the schema provides complete coverage. The description adds no parameter details, but no parameters exist to elaborate on. The baseline of 4 for zero-parameter tools is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'run' and clearly identifies the resource as a comprehensive health audit covering compute, memory, storage, battery, SSD wear, and startup items. It distinguishes itself from sibling tools like get_disk_usage or get_battery_health by presenting a broader aggregate scope.
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?
Usage is implied as 'when you want an overall health check' due to the word 'comprehensive' and the listed components, but there is no explicit guidance on when to prefer this over individual sibling tools or any exclusions. The description doesn't name alternatives or provide context for decision-making.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of disclosing behavior. It mentions saving to a temp WAV file and returning specific metadata, which adds transparency. However, it does not disclose whether the temp file persists, if microphone permissions are required, or any blocking behavior, so it is only partially transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that front-loads the action, specifies the output, and contains no filler. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter tool with no output schema, the description covers the core behavior and return values. It could mention caveats like whether the temp file is cleaned up or how the microphone is chosen, but overall it is sufficiently complete given the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema fully describes the duration parameter (default 5, max 30), covering 100% of parameter semantics. The description adds no extra parameter information, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool records an audio clip via microphone and saves it as a temp WAV file, with specific return values (path, duration, sample rate). This distinguishes it from siblings like capture_camera_snapshot and get_ambient_noise.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool (recording audio from microphone) but does not explicitly state context, prerequisites, or alternatives. It does not mention how it differs from get_ambient_noise, leaving usage guidance implied rather than clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden for behavioral disclosure. It correctly indicates a mutation via 'Creates', but does not elaborate on side effects (e.g., default folder behavior) or any required permissions. Basic transparency is present, but no additional context beyond the operation itself.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single clear sentence with no superfluous words. It is front-loaded with the core action and resource, making it highly scannable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple create operation with fully described parameters and no output schema, the description is adequate. It could be argued that mentioning the folder default or return value would help, but it is not essential for such a straightforward tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema fully documents title, body, and folder. The description adds no parameter-specific meaning, thus the baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Creates' with the resource 'a new note in Apple Notes', clearly distinguishing it from sibling tools like update_note, list_notes, and get_note. It precisely states the action and target.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for creating a new note, but it does not explicitly state when to use this tool versus alternatives like update_note. No mention of exclusions or preferred scenarios, relying on the obvious semantics of 'creates'.
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 the core action (records via microphone, measures noise) and the return data, but does not mention whether audio is stored, whether microphone permission is required, or failure scenarios. It is not misleading but lacks depth expected for a hardware-accessing 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 two sentences: the first states the action, the second states the return values. It is concise, front-loaded, and contains no filler or redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one optional parameter and no output schema, the description provides essential return information (average dB, peak dB, classification) and the core functionality. It does not detail classification thresholds or microphone permissions, but the overall context is adequate for typical 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 only parameter, duration, is fully described in the input schema with default and max values. The tool description adds no additional meaning about this parameter, so the baseline of 3 applies since schema coverage is 100%.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool records an audio sample via microphone and measures ambient noise in decibels, returning specific metrics. This explicitly differentiates it from sibling tools like capture_audio, which likely only records audio without analysis.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when ambient noise levels are needed, but it does not explicitly state when to use this tool over alternatives such as capture_audio, nor does it mention exclusions or prerequisites. The intended use case is reasonably clear from the purpose but lacks direct guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden, but it only states the action and scope. It implies a read-only operation, yet does not disclose output format, ordering, or whether disabled or hidden shortcuts are included. Minimal but not misleading.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no filler or redundant detail. It front-loads the action and includes the necessary scope.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a parameterless, simple listing tool, the description is largely complete. It does not describe the return format, but the verb 'Lists' reasonably implies a list of shortcuts. No output schema exists, so additional detail would be helpful but not essential.
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?
There are no parameters, so the description does not need to add parameter details. The baseline of 4 applies because there is nothing to compensate for.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Lists') with a clear resource ('all Siri/Apple Shortcuts configured on the system'). It clearly distinguishes from sibling tool 'run_shortcut' by describing listing rather than execution.
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 neither mentions related tools like run_shortcut nor gives context such as 'use when you need an overview of installed shortcuts'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits. 'Toggles' clearly indicates a mutating action that changes playback state, which is useful. However, it does not explain what happens if no music is currently loaded or whether it affects the current track only, leaving some ambiguity about edge cases.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence: 'Toggles playback state of Apple Music'. Every word is meaningful, with no redundant phrasing or filler. It conveys the essential action and target in the most economical way possible.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter toggle with no output schema, the description captures the core behavior adequately. It lacks mention of related tools like get_music_state or play_playlist, which could be relevant for context, but given the simplicity of the operation, it is reasonably complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and the schema is an empty object, so schema coverage is trivially 100%. The description correctly implies no arguments are needed, and since there are no parameters to document, the description adds no unnecessary parameter details. Baseline for 0 params is 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Toggles') and clearly identifies the resource ('playback state of Apple Music'). This distinguishes it from sibling tools like play_playlist (starts a specific playlist) and skip_music_track (advances to next track), 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 does not mention that get_music_state could be used to check current state before toggling, nor does it explain the difference between toggling music and playing a specific playlist. There is no contextual hint or exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It states the core action ('Plays') but does not disclose side effects, prerequisites, or error behavior. For a simple play command, this is minimally adequate but lacks detail.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with no wasted words. It conveys the essential purpose and parameter focus efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one parameter and no output schema, the description plus schema is mostly complete. It does not explain what happens on success/failure, but this is a lightweight action that likely returns a standard result. Slight gap in behavioral detail prevents a 5.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage with the parameter 'name' described as 'Playlist name'. The description adds no extra parameter meaning beyond what the schema provides, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Plays a specific Apple Music playlist by name' uses a specific verb and resource, clearly distinguishing it from sibling tools like play_pause_music (toggle playback) and play_podcast_episode (podcasts).
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 (when you want to play a specific named playlist) but does not explicitly mention alternatives or exclusions. It relies on the sibling tool names to hint at differentiation, which is only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses that the operation is an append, not an overwrite, which is valuable. However, it omits details about error behavior (e.g., if the note does not exist), side effects, or return value. This is a baseline disclosure 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, front-loaded sentence that conveys the essential action and resource. Every word earns its place, with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple 2-parameter tool with no output schema, the description plus schema is largely sufficient. It clearly differentiates from siblings and explains the append behavior. Minor gaps include behavior on missing note or return value, but these are not critical given the low complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for both parameters ('Note ID' and 'Text to append'). The description adds little beyond the schema, but the schema is already clear. The baseline of 3 applies since the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Appends content') and the resource ('existing note in Apple Notes'), making it specific and distinguishable from sibling tools like create_note (new note) and get_note (read). The verb 'appends' precisely defines the operation.
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: you need an existing note ID and want to add text. However, it does not explicitly contrast with alternatives like create_note or mention when not to use it. The guidance is clear but implicit, warranting a score of 3.
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 of behavioral disclosure. It does disclose the return format (base64 data URL) and implementation (imagesnap), which is useful. However, it lacks information about required camera permissions, potential side effects (e.g., camera indicator light), error behavior, or an explicit safety profile. The non-destructive nature is implied but not stated.
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 two sentences long and front-loaded with the primary action. It efficiently includes the implementation, return format, and use cases without redundancy. Every sentence adds value, 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.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (two optional parameters, no output schema), the description covers the essential aspects: action, return format, and use cases. It could be more complete by adding prerequisites or error conditions, but for a straightforward snapshot tool, the provided context is sufficient for an agent to select and invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already provides clear descriptions for both parameters (delay warmup and JPEG quality with enum values). The description does not add parameter-specific detail beyond what the schema offers, so the baseline score of 3 is appropriate. The mention of JPEG output aligns with the quality parameter but does not enhance its meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Takes a photo') with a clear resource ('built-in camera via imagesnap') and output format ('JPEG as base64 data URL'). It distinguishes itself from sibling tools like capture_audio by specifying the camera rather than audio. The listed use cases (ambient light sensing, health PPG read, presence detection) further clarify its intended purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'Use:' clause explicitly lists three concrete scenarios for when this tool is appropriate, providing clear context. It does not mention exclusions or alternatives, but the use cases are specific enough to guide an agent. No sibling tool directly overlaps in purpose, so this level of guidance is adequate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It adds value by specifying the output fields, but it does not disclose side effects, permission requirements, or whether it is a read-only operation. The verb 'get' implies a non-mutating action, but this is not explicitly stated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that is front-loaded with the primary purpose ('Detailed battery status') and enumerates the key output fields. Every word earns its place with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (zero parameters, no output schema), the description is largely complete. It names the output fields, which is sufficient for an agent to know what will be returned. It could optionally mention that this is a read-only, no-side-effect operation, but that is not strictly necessary for a simple getter.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters, so there are no parameter semantics to explain. The description correctly adds no parameter information, which aligns with the schema. The baseline for 0-parameter tools is 4, and the description neither confuses nor contradicts the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'get' with resource 'battery health' and lists concrete output fields (cycle count, max capacity, condition). It clearly distinguishes itself from all sibling tools by focusing solely on battery status, and no other sibling covers battery health.
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 usage context is implied by the name and description: the tool is for retrieving battery health details. However, it does not explicitly mention when to use it versus alternatives, nor does it provide any exclusion criteria. With no competing battery tool in siblings, this is adequate but not explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of disclosure. It clearly implies a read-only operation, but it does not mention whether permissions are needed, what 'resource usage' includes (CPU, memory, etc.), or whether the list is restricted to the current user. The description is minimal but adequate for a simple list operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler. It efficiently conveys the essential action and scope in just eight words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no parameters, no output schema, and a simple read-only function, the description provides the core purpose. It could be slightly more explicit about the returned data structure (e.g., list of process names with CPU/memory percentages), but the mention of 'resource usage' gives sufficient context for an agent to understand the tool's role.
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 no parameters, so the schema is fully covered (100% vacuously). According to the rubric, 0 params grants a baseline of 4. The description does not need to add parameter details since there are none.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Lists') and resource ('active running processes') with a qualifier ('with resource usage'). It clearly distinguishes itself from sibling tools like kill_process (which terminates processes) and get_system_stats (which provides overall system metrics).
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 by stating the tool lists processes, so an agent can infer when to call it. However, it does not explicitly discuss alternatives (e.g., get_system_stats for overall stats) or provide exclusions, leaving room for ambiguity in edge cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It clearly states what data is returned, but it does not mention whether any permissions are required, whether the data is a real-time snapshot, or any other behavioral characteristics. This is adequate for a read-only tool but adds no extra context beyond the 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, front-loaded sentence that immediately states the action ('Gets') and the list of metrics. Every word is informative, with no filler or redundant content. It achieves maximum clarity in minimal space.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the tool (no parameters, no output schema), the description fully covers what the tool does. It lists all the metrics returned, which is sufficient for an agent to decide when to use it. A minor gap is the lack of detail on the format or granularity of the data, but this is not critical for a system stats snapshot tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and the schema is empty. The baseline for zero parameters is 4, and since the description does not need to explain any parameters, it fully satisfies the requirement. The description adds no parameter-specific semantics because none exist.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function with a specific verb 'Gets' and enumerates the exact system metrics (CPU load, memory pressure, battery metrics, thermal level, hung processes). This distinguishes it from sibling tools like get_battery_health and get_process_list, which target individual metrics, by presenting it as a comprehensive system stats snapshot.
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 through the list of metrics, but provides no explicit guidance on when to prefer this tool over more specific siblings such as get_disk_usage or get_process_list. There is no mention of trade-offs or exclusions, so the usage context is left to the user's inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of disclosing behavior. It clearly states the core function (listing names) but does not mention any additional traits such as permissions, return format, or whether subscribed calendars are included. The behavior is minimal and non-destructive, so this is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no unnecessary words. It conveys the entire purpose efficiently, earning a perfect score for conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the tool (no params, no output schema, clear purpose), the description is nearly complete. It could explicitly state the return type (e.g., list of strings), but the phrase 'calendar names' sufficiently implies this. Overall, sufficient for the tool's trivial nature.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and the schema is empty with 100% coverage. The description adds no parameter info, but none is needed. Baseline for 0 parameters is 4, which is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Lists') and resource ('calendar names') with scope ('available in the Apple Calendar app'), clearly distinguishing it from sibling tools like get_calendar_events and create_calendar_event.
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 by stating it lists all available calendar names, but it does not explicitly state when to use this vs alternatives or provide prerequisites or contextual guidance. It is self-evident enough for a simple tool, but lacks direct instructions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It states the main action (opening URL in default browser) but does not disclose details such as whether it returns success/failure, whether it blocks, or what happens on invalid URLs. For a simple side-effecting tool, this is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with zero filler. Every word contributes to understanding the tool's purpose, making it appropriately concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter, no output schema, no annotations), the description sufficiently covers the essential context: what the tool does and what it acts on. It could mention error behavior or return value, but these are not necessary for basic usage, making the description complete enough.
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 'URL to open' for the single parameter, so the schema already fully documents the parameter. The tool description adds no additional semantic value beyond the schema, hence the baseline score of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Opens a URL in the default browser' uses a specific verb ('opens') and resource ('URL'), clearly stating the tool's function. It is distinct from all sibling tools, none of which perform URL opening, so it differentiates itself effectively.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies when to use this tool (whenever a URL needs to be opened), and there is no alternative among siblings that would require explicit exclusions. No prerequisites or conditions are mentioned, but the tool is simple enough that the context is self-evident.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description is the only source of behavioral disclosure. It states the effect (sets volume) and the range, but does not disclose side effects, prerequisites, or whether the volume is absolute or relative. This is adequate for a straightforward setter but lacks depth.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence consisting of exactly 7 words. It conveys the purpose and range without any wasted words or fluff. Ideal conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one scalar parameter and no output schema, the description is sufficient. It names the target, the action, and the valid range. It could mention prerequisites like 'Apple Music must be playing', but the lack of such detail is not a major gap for this complexity level.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides a full description of the 'volume' parameter with type, min, max, and a 'Volume level' description (100% coverage). The tool description adds the '0 to 100' context, but this duplicates schema constraints. No additional semantic depth is provided beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Sets'), the target resource ('Apple Music volume'), and the valid range ('0 to 100'). This distinguishes it from sibling music controls like play/pause/skip and get_music_state.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use it: whenever the user wants to adjust Apple Music volume. It does not explicitly mention alternatives or exclusions, but there is no other volume-setting sibling tool, so context is clear enough for a simple setter.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It honestly reveals that data comes from a local cache and requires a prior open/play action, which is non-obvious. It also states the return contains speaker-attributed text with timestamps, giving the user a clear expectation of output.
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 exactly two sentences, front-loaded with the primary action and purpose. Every sentence adds essential information (what the tool does, the output format, and the key prerequisite) with no wasted words or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 2-parameter tool with no output schema, the description sufficiently covers purpose, prerequisites, and return value. It does not mention possible errors or alternatives, but the tool is simple enough that the provided context is nearly complete. The reference in the schema to get_recent_podcast_episodes helps with context, though the description itself could have been even more explicit about the source of transcriptId.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already has 100% coverage for both parameters, including detailed explanations for transcriptId and includeTimestamps. The description does not add any additional parameter semantics beyond what the schema provides, 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific action and resource: 'Retrieves the full transcript for an episode from the local Apple Podcasts TTML cache.' It distinguishes itself from sibling tools like get_recent_podcast_episodes (which lists episodes) and play_podcast_episode (which plays audio) by focusing on the transcript retrieval function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear prerequisite: 'Requires the episode to have been opened/played at least once so the transcript file was cached locally.' This implicitly tells the user when to use this tool and what condition must be met. It does not explicitly mention alternatives, but the precondition is valuable contextual guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses return fields, clarifies that transcriptId is a path fragment and episodeId is an Apple store track id, and notes the 'once cached' requirement for transcripts. 'Lists' implies a read-only operation, though an explicit read-only statement would be stronger.
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 three sentences with no filler: purpose, returned fields, and downstream usage. It is front-loaded and every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, so the description compensates by enumerating the returned fields and downstream tool links. It could mention ordering or pagination, but the limit parameter is already documented in the schema. Overall, it is sufficiently complete for a listing tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 100% description coverage for all 5 parameters, so the baseline is 3. The description only summarizes filters ('release date range and/or title query') without adding new semantic detail beyond the schema's already-rich parameter descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool 'Lists podcast episodes from MTLibrary.sqlite' with optional filters, giving a specific verb, resource, and scope. It distinguishes itself from siblings like get_podcast_transcript and open_podcast_episode by focusing on episode listing/querying.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear downstream guidance: 'Pass a title to open_podcast_episode, and transcriptId to get_podcast_transcript once cached,' implying this tool is the episode discovery source. It lacks explicit when-not-to-use instructions but gives sufficient context for typical usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must carry the full burden of behavioral disclosure. It states the tool lists all open tab URLs and titles, implying a read-only operation, but provides no additional context about limitations (e.g., private windows, permissions, or error behavior). The description is accurate but minimal, lacking any extra behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that conveys all essential information without any wasted words. It is front-loaded with the main action and resource, making it easy to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a simple tool with no parameters and no output schema. The description adequately explains what it returns (URLs and titles of open Safari tabs). While it doesn't specify the return format, the simplicity of the tool and the clarity of the description make it sufficiently complete for an agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and the schema coverage is 100% (trivially). Per rubric, a baseline of 4 is appropriate. The description adds no parameter information because none exists, so it fully aligns with the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function with a specific verb ('Lists') and resource ('open tab URLs and titles in Safari'). It is unambiguous and easily distinguished from sibling tools, which cover calendars, reminders, notes, music, email, and system operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies a clear use case: retrieving current Safari tab information. There are no similar sibling tools that would create ambiguity, so explicit alternatives are unnecessary. The context is clear enough for an agent to select this tool when needing Safari tab data.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the full burden. It clearly indicates a read-only operation ('Lists'), but does not disclose details such as output format, permissions required, or how the two categories are combined. This is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that directly states the tool's function with no wasted words. It is front-loaded and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple, zero-parameter tool, the description states the core function clearly. However, without an output schema, it does not specify whether login items and LaunchAgents are returned separately or combined, and it omits any mention of return format or structure. Still, the essentials are present.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and schema coverage is 100% (empty schema), so the baseline score is 4. The description adds no parameter-specific info because there are none; it focuses entirely on the tool's purpose.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Lists macOS login items and LaunchAgents' with a specific verb and resource. It distinguishes from all sibling tools, none of which address startup items.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implicitly provides context for when to use this tool—whenever one needs to inspect macOS login items or LaunchAgents. No exclusions or alternatives are mentioned, but the clear scope makes usage unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of disclosing behavior. It explicitly states the returned fields (titles, IDs, folders), making output predictable. The verb 'Lists' signals a read-only, non-destructive action, though it does not explicitly say so or mention any permissions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence of about 10 words, front-loaded with the action verb and no redundancy. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with no parameters and no output schema, the description fully covers what the agent needs to know: it returns titles, IDs, and folders of notes. No other context is necessary.
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 no parameters (empty schema), so the description cannot add parameter-level meaning. The baseline of 4 for zero-parameter tools applies, as no compensation is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists titles, IDs, and folders of notes in Apple Notes. The verb 'Lists' is specific and the resource scope is unambiguous, distinguishing it from sibling tools like get_note, create_note, and update_note.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the use case (enumerating notes) clearly through the verb and output fields, but it does not explicitly mention alternatives or when not to use it. However, the context is obvious for a zero-parameter list operation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of behavioral disclosure. It adds valuable transparency by warning that the MTLibrary play_state column is unreliable and suggesting the playhead field for verification. This is a meaningful caveat beyond the basic action, though it doesn't cover side effects or error conditions.
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?
Two sentences with no filler: the first states the core function, the second provides a critical verification tip. This is an efficient and well-structured description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter tool, the description is complete. It explains what the tool does and includes a caveat that helps the agent verify success. Given the absence of an output schema, no further return-value explanation is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the baseline is 4. The description doesn't need to explain parameter semantics and instead focuses on the action and verification note, which is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action ('Pauses') on a specific resource ('Apple Podcasts playback') and the method ('via the Controls menu bar item'). This distinguishes it from sibling tools like play_podcast_episode and play_pause_music.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The context is clear: it's specifically for pausing Apple Podcasts. While it doesn't explicitly state when not to use it or name alternatives like play_pause_music, the mention of using get_recent_podcast_episodes for verification provides a useful cross-reference, although not as an alternative for the pausing action itself.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations to rely on, the description carries full behavioral burden and succeeds: it discloses the AX-discovery mechanism, explains that the play pill position varies per page and is never hardcoded, describes the ~15s TTML cache polling, and states the return values. This is exemplary transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, front-loaded with the main action. Every sentence adds value: what it does, how it does it, and what it returns. The parenthetical about AX-discovery is slightly verbose but serves a purpose (justifying the non-hardcoded approach). No waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no parameters, no output schema, and no annotations, the description covers all necessary aspects: the action, the mechanism (including potential timeout), the return values, and the prerequisite. It also links to the downstream tool (get_podcast_transcript), making it contextually complete within its ecosystem.
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, so per the rubric the baseline is 4. The description doesn't add parameter-specific semantics (none exist), but it adds contextual meaning by explaining what the tool does and its outputs, which is sufficient.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Plays the currently open episode page in Apple Podcasts' using a specific mechanism (AX-discovers the play pill). It distinguishes this from sibling tools like open_podcast_episode (which opens the page) and pause_podcast_episode (which pauses), making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives an explicit prerequisite: 'Requires open_podcast_episode to have been called first.' It also explains the relationship to get_podcast_transcript by returning the transcript path and transcriptId. However, it does not explicitly state when not to use or list alternatives, so it falls short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. It discloses the verified UI flow ('Cmd+F, clipboard-paste the title (keystroke typing corrupts punctuation)'), warns about exactness ('top search result is what gets opened'), and mentions the clipboard method, giving the agent critical knowledge about how the tool operates and its quirks.
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?
Three sentences, no filler. The first sentence states the purpose, the second explains the verified UI flow, and the third gives usage order. Each sentence earns its place, and the description is front-loaded with the core function.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with one parameter, no annotations, and no output schema, this description is fully complete. It covers the source of the title, the exact UI mechanics, the prerequisite workflow, and the behavior of opening the top search result. No critical information is missing.
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 schema already provides 100% coverage for the single 'title' parameter, including its source and exactness requirement. The description adds a practical nuance: 'The title should be fairly exact' and clarifies the consequence of exact matching ('top search result is what gets opened'), enriching the parameter's semantic meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool 'Searches Apple Podcasts for an episode title... and opens its episode page', using a specific verb (searches, opens) and resource (Apple Podcasts episode page). It distinguishes itself from sibling 'play_podcast_episode' by focusing on opening the episode page rather than playing it.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Use before play_podcast_episode', indicating the intended workflow and position relative to a sibling tool. It also specifies the source of the title ('from get_recent_podcast_episodes'), providing clear context on when to apply this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

GitHub Badge

Glama performs regular codebase and documentation scans to:

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

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

Card Badge

Copy to your README.md:

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

Score Badge

Copy to your README.md:

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

Latest Blog Posts

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

MCP directory API

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

curl -X GET 'https://glama.ai/api/mcp/v1/servers/surendranb/macos-mcp'

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