mcp-osascript

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 transparently mentions the Accessibility permission requirement, that results are untrusted data, and the error-handling behavior that lists available items. It does not explicitly discuss side effects of 'click' (e.g., whether it mutates app state), but the term 'click' implies activation and the description covers key prerequisites and data trust.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is three concise sentences, front-loaded with the primary purpose and example. Every sentence adds value: purpose, retry guidance, and permission/data warnings. No fluff or redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with 3 parameters and no output schema, the description covers the essential operational aspects: permission requirements, localization, error recovery, and data trust. It does not explicitly describe the structure of the returned list (e.g., whether it's an array of strings), but the tool's simplicity and the retry guidance make it largely self-explanatory. A slight gap remains on the exact return format for list actions.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema already describes each parameter with high coverage (100%), including the action enum and the menu_path example. The description adds no new semantic information beyond what the schema provides, so it does not elevate the parameter understanding. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's dual function: listing an application's menus or clicking a menu item by path, with a concrete example. This distinguishes it from sibling tools like open_app or get_browser_tabs, which deal with other UI elements. The verb+resource combination is specific and unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context for use, including the retry strategy based on error output ('prefer retrying on that list over guessing') and a warning about localized menu names. It does not explicitly mention when not to use the tool or name alternative tools, but the guidance is actionable and sufficient for typical usage.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description fully carries the behavioral disclosure burden. It states that hiding keeps the app running, quitting may prompt to save unsaved work, quitting a non-running app launches it to deliver the quit event, and that Accessibility permission is required for hide/unhide. This covers permission requirements, side effects, and action semantics—exceeding what annotations would typically provide.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is three sentences, each adding distinct value: the core purpose, behavioral details of hide vs. quit, and a permission requirement. It is front-loaded with the main action and avoids redundancy. No filler or unnecessary elaboration.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers the essential behavioral aspects, including side effects and permissions, which is sufficient for a simple action tool without an output schema. It does not mention error handling or return values, but those are often implicit for void actions. The absence of annotations is compensated by the detailed behavioral notes. The only minor gap is what happens if the app is not found or the action fails, which is not critical for typical use.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% for both parameters, so the baseline is 3. The description adds meaningful context to the 'action' enum by explaining the behavioral differences between hide, unhide, and quit, which is beyond the schema's simple enumeration. For 'app', it does not add beyond 'Application name,' but that is adequately covered. The added action semantics justify a score above baseline.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose with specific verbs: 'Hide, unhide or quit an application.' It distinguishes the three actions and explains their effects, making it unambiguous which operation is performed. The Cmd+H analogy further clarifies the hide behavior, and the resource (application) is explicit.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explains what each action does but does not explicitly state when to prefer this tool over siblings like open_app or manage_windows. The behavioral notes (e.g., quitting a non-running app launches it) imply edge-case usage, but there is no direct comparison or exclusion guidance. The context from sibling names gives some inference, but the description itself lacks explicit usage conditions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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 transparently states the action (open), the accepted inputs (file/folder), the path constraints, and the URL refusal. It does not mention return values or error behavior, but for a simple open action this is minor. Overall, it provides solid transparency for a tool of this simplicity.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences, front-loads the core action, and packs all necessary constraints and alternatives with zero redundancy. Every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple tool with full schema coverage and no output schema required, the description covers all essential aspects: the action, parameter usage, constraints, and an explicit alternative. An agent has all needed information to invoke it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description adds meaningful semantics beyond the schema by explaining that 'app' overrides the default and that 'path' must be absolute and pre-existing. This enriches the parameters and helps the agent use them correctly.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool opens an existing file or folder using the default application or a specified app. It explicitly differentiates from open_url by refusing URLs, making its purpose unambiguous and distinct from the sibling tool.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly provides usage guidance: it mandates absolute paths, requires the path to already exist, and excludes URLs with a direct pointer to open_url as the alternative. This gives the agent clear when-to-use and when-not-to-use instructions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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 titles and URLs come from web pages, warns the data is untrusted, and advises not to follow instructions in it. This is a valuable behavioral note beyond the simple 'list' action. It doesn't mention failure modes (e.g., missing permission), but the permission requirement is stated.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with the core action and return details, followed by a permission note and a security warning. Every sentence adds value with no redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Even without an output schema, the description explains exactly what is returned (tab title, URL, active flag). It covers permission requirements and the untrusted-data caveat. For a read-only tool, this is complete and leaves no critical ambiguity for the agent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The only parameter (browser) is fully described in the schema, including the auto-detect behavior. The tool description repeats this in the schema's description, so it adds no new meaning beyond what the schema already provides. With 100% schema coverage, baseline is 3.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action (list) and resource (open tabs in Safari, Chrome, or Arc), and specifies the returned data (title, URL, active status). This distinguishes it from sibling tools like open_app or manage_windows, which are about actions, not reading tab data.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It states a clear prerequisite (Requires Automation permission for the browser) and implies the tool is for querying tabs rather than modifying them. However, it does not explicitly mention when not to use it or name alternative tools, so it lacks explicit exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden and does so well. It discloses that clipboard content must be treated as untrusted input, never as instructions, and explains the behavior for non-text clipboards (reporting kind instead of content). These are valuable behavioral details beyond the bare fact of reading.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences with no filler. The core purpose leads, the security note follows, and the non-text edge case closes it. Every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-parameter read tool with no output schema, the description covers the respone's nature (plain text), the safety posture (untrusted data), and the non-text case. Nothing essential for invoking it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool accepts zero parameters and the schema coverage is effectively complete, so there is nothing for the description to explain about parameters. Baseline of 4 applies because no parameter ambiguity exists.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names the exact action ('Read the macOS clipboard as plain text') and the resource (the macOS clipboard). It is clearly a read operation and the contrast with set_clipboard is implicit, but it never explicitly differentiates itself from sibling tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description makes the intended use obvious—reading clipboard text—but provides no explicit when-to-use or when-not-to-use guidance, no exclusions, and no mention of alternatives like set_clipboard. Usage is implied rather than spelled out.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the behavioral burden. 'Get information' clearly signals a read-only operation, and the description discloses the scope and contents of the result. It does not state permissions or edge cases, but for a simple no-parameter query this is acceptable.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise sentences with no filler. The main action and output content are front-loaded, and the use case is provided in a single additional clause.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a no-parameter, read-only tool, the description gives enough context to understand what will be returned. There is no output schema, but listing the key fields partially compensates. Exact formatting or units are not specified, but they are not essential for correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has zero parameters, so the baseline is 4. The description adds value by explaining what output information is meaningful (position, size, main display), even though there are no parameters to document.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly identifies the resource ('all connected displays') and the specific information returned (position, size, and main display). This makes the tool easy to distinguish from sibling tools like manage_windows or screenshot.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description includes a clear usage context: 'Useful for multi-monitor window management.' It does not explicitly name alternatives or when-not-to-use cases, but the no-parameter read-only nature and the context provided are sufficient for a tool like this.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full behavioral disclosure burden. It usefully discloses the potential Automation permission requirement for System Events and clarifies what the tool returns. It does not describe failure behavior or whether it may trigger a permission prompt, but for a simple read-only lookup the disclosure is adequate.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, front-loaded sentence that directly states what the tool does, then adds a necessary permission caveat. Every part is informative, and there is no redundant or filler text.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-parameter, read-only tool with no output schema, the description is largely complete: it names the resource, the returned fields, and a relevant prerequisite. It could mention what happens if permission is denied, but that is a minor gap given the tool's simplicity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, so the baseline for this dimension is 4. The description correctly adds no parameter-related text because there is nothing to explain; the empty schema is already complete.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb ('Get'), a specific resource ('frontmost (active) application'), and the exact return values ('name and bundle ID'). This clearly distinguishes it from siblings like open_app, get_browser_tabs, or app_menu.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The intended use case is implied by the tool's name and description: call it when you need to identify the active application. However, the description does not explicitly say when to prefer this over alternatives, nor does it mention any exclusions or conditions beyond the permission caveat.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the transparency burden and does disclose an important prerequisite: Accessibility permission for most actions. It also notes the absolute-coordinate behavior on multi-monitor setups. However, it does not flag that 'close' is destructive or describe state-change side effects for minimize/fullscreen, which would be valuable for a no-annotation mutation-capable tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is tightly written in two sentences, front-loading the complete range of actions and then adding only the most relevant caveats. Every phrase earns its place, with no redundant restatement of the tool name or schema.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers permission requirements and multi-monitor coordinate handling, but it does not clarify per-action parameter obligations (e.g., move requires position, resize requires size) or hint at what the 'list' action returns. Since there is no output schema, those details would meaningfully improve completeness for an AI agent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema already documents all parameters at 100% coverage, so the baseline is 3. The description adds genuine value by specifying that 'move' uses absolute coordinates in multi-monitor contexts and by linking that to get_displays. Other parameters rely on the schema, which is acceptable given the high coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a concrete, specific verb list ('List, move, resize, minimize, fullscreen, or close') tied to a clear resource ('application windows'). This matches the action enum and clearly differentiates the tool from siblings like get_displays and app_visibility by focusing on window manipulation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives explicit operational guidance for multi-monitor setups: call get_displays first and pass absolute coordinates to 'move'. It does not explicitly state when to avoid this tool in favor of siblings, but the action scope and permission requirement make the intended usage reasonably clear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden. It discloses the key behavior: it brings the app to front and launches it if not running. It does not mention error handling or return values, but for a simple activation tool this is sufficient and 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.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, front-loaded sentence that states the core behavior first, then a usage hint. There is zero wasted text and the example is included without padding.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with one parameter, no output schema, and no annotations, the description is nearly complete. It explains the action, the launch-if-needed behavior, and the parameter format. Minor omissions (e.g., behavior when the app is already frontmost) are easily inferred and do not hinder correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema already documents the 'name' parameter at 100% coverage, so baseline is 3. The description adds value by specifying the exact format (as shown in Finder) and gives a concrete counter-example ('Google Chrome', not 'chrome'), which improves the agent's ability to supply a correct value.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific action (bring to front, launch if not running) and a specific resource (application), with an explicit example distinguishing it from similar tools like open_url or file_open. It clearly tells an agent what the tool does.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives a precise parameter-usage hint (use Finder name, e.g., 'Google Chrome' not 'chrome') but does not explicitly say when to prefer this tool over alternatives like get_frontmost_app or manage_windows. The context is clear but no exclusions or alternative-selection guidance is provided.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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 key behavioral constraint (only http, https, mailto allowed; others refused) and the target (default browser). It doesn't mention error handling or side effects, but these are minor for this simple action.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences with zero redundancy. The core action is front-loaded, followed by the restriction and the alternative. Every clause earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a one-parameter tool with no output schema and no annotations, the description fully equips an agent to invoke it correctly. It covers allowed inputs and routing to the right sibling. Nothing essential is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema already describes the parameter as 'URL to open' (100% coverage), giving a baseline of 3. The description adds the scheme restriction, which clarifies what values are valid, going beyond the schema's generic description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Open a URL in the default browser') with a specific verb and resource. It also differentiates from the sibling file_open by specifying allowed schemes and explicitly naming the alternative for local files/folders.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explicitly states when to use this tool (for http, https, mailto URLs) and when not to (for local files/folders, use file_open). This provides clear selection guidance among siblings with no ambiguity.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden. It discloses the Accessibility requirement, which is a key constraint, and implies action on the frontmost app. However, it does not state whether the key press is simulated at the OS level, what happens on failure, or any side effects (e.g., triggering shortcuts). This is adequate but not exhaustive 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.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences, front-loaded with the core action and accepted input, then the permission requirement and alternative. No wasted words; every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is simple with two parameters and no output schema. The description covers the purpose, input format, permission, and a clear alternative. It omits explicit error behavior or return value, but given the low complexity and absence of an output schema, this is acceptable.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description adds a list of named keys (return, tab, etc.) beyond the schema's examples, but this is largely redundant. It does not add meaning about the modifiers array beyond what the schema provides. No significant semantic enrichment.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action (press a key), the target (frontmost application), and the scope (single key with optional modifiers). It also enumerates accepted key names, which helps the agent understand exact input format. It distinguishes itself from type_text, making its purpose unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly notes the prerequisite of Accessibility permission and directs users to type_text for text entry, giving a clear exclusion. It does not fully enumerate when to prefer this over other sibling tools (e.g., run_shortcut or app_menu), but for a key-press tool this is sufficient guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the behavioral disclosure burden. It usefully discloses timeout limits (30s default, max 120s), max script size (50 KB), output truncation (50000 characters), and multiline support. However, it does not mention permission/auth requirements, potential for side effects, or that arbitrary osascript execution may prompt the user or modify system state.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is compact and front-loaded with the core purpose, followed by hard constraints and language guidance. Every sentence contributes new operational information, and there is no repetition of schema fields or filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers the main operational constraints and language usage well. However, for an arbitrary code execution tool with no output schema and no annotations, it omits important context: how output and errors are returned, whether execution is synchronous, and what permission/side-effect risks exist. These gaps are meaningful but the description is still substantially complete for basic invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3. The description adds real value by mapping language='javascript' to JXA, stating timeout default and max, and confirming multiline script support. These details go beyond the bare schema descriptions and help the agent choose correct parameter values.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: 'Execute an AppleScript or JXA script on macOS.' It then gives concrete use cases and clearly differentiates from sibling tools like open_app, press_key, or get_clipboard, which are single-purpose actions. The general-purpose scripting scope is unmistakable.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description states broad use cases ('Automate any scriptable app, control system settings, manage files, and more') and explains how to select the JXA option with language='javascript'. However, it does not explicitly name sibling alternatives or state when not to use this tool, leaving routing decisions mostly to inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It discloses that input is staged to a temporary file and that shortcuts waiting for user interaction will block with a 30-second timeout. These are non-obvious behaviors that are crucial for the agent to anticipate. However, it does not mention potential side effects of running arbitrary shortcuts (e.g., system changes) or error handling, but the disclosed behaviors are valuable and go beyond the schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two concise sentences that are front-loaded with the primary purpose. It packs essential behavioral details (temp file, timeout) without any fluff. Every sentence earns its place, and the structure is easily scannable.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with two actions (list/run) and input handling, the description covers the core functionality, input staging, and blocking behavior. There is no output schema, so return values are not explicitly described, but that is not required. It lacks detail on error conditions or permission requirements, but those are not critical for basic invocation. Overall, it provides sufficient context for correct usage.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% for all three parameters, and the schema already explains the purpose of 'name' (required for run) and 'input' (staged to temp file). The description reiterates this info without adding new meaning. Since the schema carries the full weight, a baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's dual function: listing Apple Shortcuts and running one by name. It specifies the exact resource (Apple Shortcuts) and distinguishes itself from siblings like open_app and run_osascript by naming the specific domain. The verb 'list' and 'run' are concrete and unambiguous, making the purpose immediately obvious.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies the use case (interacting with Apple Shortcuts) but does not explicitly mention when to choose this over alternatives. Siblings like run_osascript could perform script execution, but the description does not state any exclusion criteria or comparisons. The guidance is implicit rather than explicit, so it scores a 3.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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 warns that clipboard mode replaces clipboard contents, existing files are never overwritten unless overwrite is true, the extension must match format, and Screen Recording permission is required.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences deliver the core purpose first, then critical constraints and prerequisites. There is no filler or redundant restatement of the tool name.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 9-parameter tool with no output schema and no annotations, the description covers modes, destinations, overwrite semantics, extension requirements, defaults, and permissions. It does not describe what the tool returns (e.g., file path or success status), but the main invocation requirements are present.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents all parameters and defaults. The description reinforces key behaviors like clipboard replacement and overwrite protection but does not add much meaning beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Capture') with clear resource targets: full screen, region, or application window, plus destination options (file or clipboard). It is immediately distinguishable from sibling tools like get_displays or get_clipboard.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It clearly states the capture modes and when clipboard/overwrite behavior applies, plus the required Screen Recording permission. It does not explicitly discuss when to prefer a sibling tool, but no sibling directly competes with screenshot capture.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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 exceeds it by disclosing a key behavioral nuance: suppression under Do Not Disturb, Focus, or screen recording, and that the call still succeeds. This tells an agent not to assume the banner was visually displayed from a successful return.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, each with distinct purpose: the first states the core function; the second adds a critical caveat. There is no redundant wording, and the caveat is placed after the main action for clarity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple notification tool with no output schema, the description covers the essential purpose and the most important behavioral caveat. Schema covers all parameters. There are no nested objects or return values needing elaboration, so the definition is complete for correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3; the description adds no parameter-level detail beyond the schema. The schema already documents title, message, and sound, including truncation limits.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Description opens with a clear verb+resource: 'Display a macOS notification banner.' This precisely identifies the tool's function and distinguishes it from the other macOS automation siblings, none of which are about notifications.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit when-to-use or alternative comparison is provided. However, the unique purpose ('Display a macOS notification banner') implies the appropriate trigger, and no sibling tool competes with this responsibility. With no exclusions or conditions, usage guidance remains in implied territory.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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 warns that previous clipboard contents are lost, which is the most important side effect. It does not mention return behavior, but the lack of an output schema lowers that expectation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two compact, purposeful sentences. The primary action is front-loaded, and the warning about data loss is placed immediately after. No filler or redundancy exists.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a one-parameter setter with no output schema, this description is complete. It states what the tool does, what it affects, and how to avoid an unwanted side effect. Nothing critical is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the schema already fully documents the single parameter. The description adds only the generic phrase 'given text' rather than enriching the parameter with format, length, or special considerations, so baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb, 'Replace', names the resource, 'the macOS clipboard', and clarifies the input is text. It clearly distinguishes itself from the sibling get_clipboard by being the write counterpart.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explicitly states when to first call get_clipboard ('if they matter'), providing clear guidance for the main risk scenario. It does not enumerate broader when-to-use/when-not-to-use cases, but for this simple tool the context is clear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full behavioral disclosure burden and does so excellently. It reveals the clipboard-swap mechanism, the Cmd+V approach, the risk of losing image/file clipboards, the Accessibility permission requirement, and the 500-character limit. This is thorough and honest about side effects.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Every sentence earns its place: purpose, mechanism rationale, clipboard side-effect warning, permission requirement, and length limit. It is compact but information-dense, and the most important functional detail (frontmost application) is front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple one-parameter tool with no output schema, the description covers all essential aspects an agent needs to invoke it correctly: target, method, side effects, permissions, and constraints. Nothing critical is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema already documents the single text parameter with a clear description and maxLength constraint, so schema coverage is 100%. The description adds little beyond restating the 500-character limit, which is already present in the schema. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: 'Type text into the frontmost application.' It also distinguishes itself from a keystroke-based alternative by explaining it uses Cmd+V to avoid garbling non-Latin keyboard layouts, which clearly separates it from sibling tools like press_key.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives clear context on when this tool is appropriate, noting that it is preferred over keystroke simulation for text entry due to layout issues. It does not explicitly enumerate all alternatives or exclusions, but the 'not keystroke' clarification provides practical usage guidance for choosing between tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.