mac-pilot-mcp

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 notes that only text is supported, images/files appear as names, and there is no clipboard history. It also mentions the underlying pbpaste/pbcopy mechanism, adding useful context beyond the basic operation.

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

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

The description is concise and well-structured with clear sections for examples and limitations. Every sentence adds value, and the formatting makes it easy to scan. No unnecessary words 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 simple two-parameter tool with no output schema, the description is complete. It covers all actions, example usage, and key limitations. It does not explicitly describe return values or error cases, but those are simple enough not to require explanation. A slight gap is the absence of permission requirements, but this is not critical.

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

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

The input schema already fully describes both parameters (action with enum, text with conditional requirement). The description adds examples showing correct usage but does not provide additional semantic meaning beyond what the schema already states, 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.

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 specific actions (read/write/clear) on the macOS clipboard, and the text-only constraint distinguishes it from any potential clipboard-related tools. Sibling tools like mac_run and mac_screenshot are unrelated, so there is no ambiguity.

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

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

The description provides clear context on when to use the tool via examples and limitations (text-only, no history). It implicitly communicates when not to use it (e.g., for images or clipboard history), though it does not explicitly name alternative tools or provide exclusionary 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, the description carries the full burden. It discloses required permissions ('Requires Accessibility permission for the client app'), the behavior for Electron apps ('expose a thin AX tree'), and the prerequisite for CDP fallback ('needs the user to relaunch the app with --remote-debugging-port=<PORT>'). These are valuable behavioral traits beyond the schema. It does not detail return structure or error handling, which is a minor gap.

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 well-structured: a one-sentence summary, five illustrative examples, and three bullet-point limitations. Every sentence contributes information about usage or constraints. There is no fluff or repetition, and the front-loaded summary quickly establishes the tool's purpose.

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

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

For a tool with 7 parameters and no output schema, the description covers purpose, usage examples, and key limitations. It implies the return contains role, title, position, and size but does not explicitly state the return format (array, JSON). Error behavior for missing permissions or app not running is also absent. Given the complexity, this is a solid but not perfect level of completeness.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value through examples that illustrate parameter combinations (e.g., { app: 'Cursor', useElectronFallback: 'auto' }) and clarifies when to use 'auto' vs boolean for useElectronFallback. This goes beyond the schema's descriptions by showing practical usage patterns.

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 clear verb and resource: 'Find UI elements (role, title, position, size) in an app via Accessibility.' This distinguishes it from sibling tools like mac_run (execute commands) and mac_state (inspect state). It also mentions the optional Electron CDP fallback, further specifying scope.

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 concrete examples for different use cases (all buttons, exact title, fuzzy search, Electron fallback) and notes a key limitation: 'use useElectronFallback when AX returns empty.' It gives clear context on when to use the tool, though it does not explicitly name alternatives or exclusions. The examples and limitations serve as implicit 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?

No annotations are provided, so the description carries the full burden. It transparently discloses that macOS does not expose TCC state to ordinary processes, that the tool probes via a known-safe operation, and that Screen Recording cannot be detected reliably without invoking a screenshot, reporting 'unknown' instead of guessing. This is excellent behavioral disclosure beyond basic purpose.

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 well-structured with an opening purpose line, a concise examples block, and a clearly separated limitations section. Every sentence serves a purpose: purpose, usage example, and critical behavioral caveats. It is appropriately sized and front-loaded.

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

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

Given that there is no output schema and no annotations, the description does a good job of explaining the tool's behavior, including return state summaries, limitations, and probing method. It slightly lacks detail on the exact structure of the returned state (e.g., granted/denied values) and the specifics of the deep-link action, but overall it is sufficiently complete for an agent to use the tool 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 coverage is 100% with an enum and description, so the baseline is 3. The description adds value by providing concrete examples of the parameter values and their effects on the return state (e.g., 'check: all' returns all 3 permissions, 'check: accessibility' only returns that one). This clarifies the semantic output of each enum value 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 opens with a specific verb and resource: 'Check macOS Privacy permissions (Automation/Accessibility/Screen Recording) + deep-link to grant.' It also mentions a deep-link capability, which further distinguishes this tool from the sibling tools (mac_run, mac_screenshot, etc.) that do not handle permission checks.

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 on what the tool does and includes concrete examples for the check parameter. The 'Limitations' section adds important guidance about when results may be unreliable (especially Screen Recording), but it does not explicitly mention alternative tools or exclusive 'when to use' conditions. Overall, usage context is clear but exclusions are not fully 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?

With no annotations provided, the description carries the full transparency burden. It discloses the output format, versioning rationale, default behavior (built-ins excluded), and path/extension constraints. It does not address overwrite behavior or error handling, but it offers meaningful behavioral context beyond a bare operation description.

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

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

The description is concise and well-structured: a one-sentence summary followed by three illustrative examples, then format and limitations. Every sentence serves a purpose, and the content is front-loaded with the core purpose. No redundancy 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?

For a tool with 3 params, no output schema, and no annotations, the description covers the essential context: what it exports, how to invoke it, the output format, and constraints. It hints at inline return via examples but does not explicitly define the return structure, which is a minor gap.

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 has 100% coverage with highly descriptive comments for each parameter (e.g., 'omit = export all user recipes', 'Omit to return inline'). The description adds examples and format context but does not introduce new parameter semantics beyond the schema. Baseline 3 applies.

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

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

The description opens with a specific verb and resource: 'Export user-saved recipes as a portable .mac-recipe.json bundle'. It clearly differentiates from siblings like import, search, and run by focusing on export and the bundle format. The default exclusion of built-ins is also stated, making the tool's scope 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 three concrete usage examples covering inline export, full export to file, and including built-ins. It also states limitations (path constraints). However, it does not explicitly name alternatives like mac_recipe_import for import use cases, so some 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.

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 thoroughly explains the conflict policy (skip, rename, replace) including the fact that 'replace' deletes the existing recipe first, and discloses limitations such as requiring exactly one of `bundle` or `inputPath` and enforced major version validation. This goes beyond basic description.

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 well-organized into sections (Examples, Conflict policy, Limitations), with each sentence providing useful information. It avoids fluff and is appropriately sized for the tool's complexity, making it easy to parse.

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 all key aspects: what it does, how to invoke it, conflict policies, and limitations. However, since there is no output schema, the description does not mention what the tool returns, which would be helpful for a complete picture. Overall, it is comprehensive but slightly lacking in return-value clarity.

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

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

Although the schema covers 100% of parameters, the description enriches them with concrete examples and detailed explanations. For instance, it illustrates how to use `onConflict` with the 'rename' policy and clarifies that `bundle` must be the inline object while `inputPath` must be a file path, adding 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 explicitly states 'Import a .mac-recipe.json bundle (inline or file path)', which is a specific verb+resource. It clearly distinguishes this tool from siblings like export, save, run, and search by focusing on the import action.

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

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

The description provides clear usage examples (from file, from file with replace, inline bundle) and explains the conflict policy options. While it doesn't explicitly state when to use this tool versus alternatives, the examples implicitly define its purpose, making the usage clear enough.

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 present, so the description carries the transparency burden. It explicitly notes that execution stops on the first failed step (no partial rollback) and that steps inherit the recipe's app context. These are useful behavioral disclosures beyond the raw 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?

The description is front-loaded with the core purpose, then gives three concise examples, then lists two limitations. It is compact and well-structured without unnecessary fluff.

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?

While it covers purpose, usage, and limitations, there is no mention of what the tool returns or what happens after execution. Since there is no output schema, the agent is left guessing about the result format.

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 all parameters (100% coverage), so the baseline is 3. The description adds value with concrete examples showing how to pass params as an object and how dryRun previews steps, which helps clarify parameter intent.

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 'Run a saved recipe by name with parameter values,' a specific verb-and-resource statement. It clearly differentiates from sibling tools like mac_recipe_save and mac_recipe_search by focusing on execution.

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 concrete examples (toggle-dark-mode, open-url-with-params, dryRun) but does not explicitly discuss when to prefer this tool over siblings like mac_run. The usage context is implied rather than stated as a rule.

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. It does disclose useful behaviors: JSON-safe placeholder substitution, unique-name failure on re-save, and runtime security sandboxing. However, it omits any success-return behavior or post-save side effects, so coverage is partial.

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

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

The description is front-loaded with a clear purpose statement and uses a compact bulleted 'Limitations' section. The long JSON example is justified because it demonstrates the complex nested object structure and parameter binding. It could be tighter but the length is earned.

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 is fairly complete for a save tool: it covers the purpose, provides a full example of a valid recipe, and notes key constraints. No output schema exists, so a brief statement about return values or success confirmation would improve completeness, but the current description covers most operational needs.

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 provides 100% description coverage, so the baseline is 3. The description adds value beyond the schema by showing a concrete example of how the 'parameters' array connects to '{{param}}' placeholders in steps, and explains JSON-safe substitution, making parameter usage clearer.

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 opening sentence 'Save a multi-step automation as a named recipe' uses a specific verb and object, clearly distinguishing this from sibling recipe tools (run, export, import, search). The example further reinforces the purpose by showing a complete recipe structure.

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

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

The description implies usage for creating/saving named recipes and gives an illustrative example, but does not explicitly state when to use this tool versus alternatives, nor does it provide exclusion guidance. It mentions limitations (unique names, sandboxing) but no when-not-to-use criteria.

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. It discloses the FTS5 English-biased tokenizer limitation, shows example match behavior for queries, and mentions includeHistory semantics. It does not describe return format or pagination, but for a search tool the examples and limitations provide meaningful behavioral context.

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

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

The description is concise, well-structured, and front-loaded with the core purpose. Examples are useful and the limitation is stated in one line. Every sentence earns its place without redundant fluff.

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 moderately simple search tool with no output schema, the description provides enough to get started: purpose, examples, and a key limitation. It does not disclose what the result payload looks like or how matches are ranked, but the examples and explicit 'before writing AppleScript' context make this acceptable for the tool's complexity.

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

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

Schema coverage is 100%, but the description enriches parameter understanding with concrete examples: query is natural-language text, app is a filter that also helps with CJK tokenization, and includeHistory expands search to raw action history. This adds value beyond the terse schema descriptions, though the schema already documents the basics.

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 searches 118 built-in and saved recipes using natural language, which is a specific verb+resource pairing. It also differentiates from siblings by emphasizing this is a search step before writing new AppleScript, distinguishing it from mac_recipe_save, mac_recipe_run, and import/export 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 gives a direct usage directive: 'Call this BEFORE writing new AppleScript,' which establishes when to use it. Examples show useful variations with app filtering and includeHistory, and the limitation note advises using the app filter for Korean/CJK. It does not explicitly name alternative sibling tools for when not to use it, but the context is fairly 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 burden of disclosing behavioral traits. It clearly mentions permission requirements, security exclusions, and the self-learning behavior of appContext. It lacks details on return values or error handling, which could be useful, but the description is notably transparent for a command execution 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 well-organized and appropriately sized for a tool with 10 parameters and 7 action types. It starts with a clear summary, lists supported actions, provides 5 diverse examples, and ends with a concise bullet list of limitations. Every sentence serves a purpose, and the structure aids scannability.

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 tool's capabilities, limitations, and usage patterns comprehensively. It does not describe the output/return format, but since there is no output schema, this is a minor gap. Overall, it provides enough context for an agent to select and invoke the tool correctly for most cases.

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 provides 100% description coverage for all 10 parameters. The description adds value via concrete examples that map actionType to required params, and it explains the appContext param's role in self-learning, which goes beyond the schema description. This enriches the semantics of the parameters.

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

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

The description clearly states the tool's purpose: 'Run an AppleScript/JXA/shell command or send click/type/keypress to macOS.' It enumerates all supported action types, distinguishing this as a general execution tool. The examples and limitations further clarify its scope, making it distinct from sibling tools like mac_state or mac_find_ui.

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 on when to use the tool by listing action types and showing examples. It also highlights important prerequisites (Accessibility/Automation permissions) and limitations (cannot bypass lock screen, dangerous shell patterns blocked). However, it does not explicitly compare against alternative sibling tools or state when not to use this tool in favor of another.

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 discloses key behaviors: output format (base64 PNG), permission requirements (Screen Recording), default scale (0.5) for token efficiency, and cursor exclusion. It also warns about token cost for high-fidelity captures, providing valuable operational context.

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

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

The description is front-loaded with a clear one-sentence summary, followed by well-organized examples and limitations. Every sentence provides useful information with no redundancy, balancing detail with brevity.

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

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

Given 4 parameters, one nested object, and no output schema, the description covers all necessary aspects: capture modes, parameter behavior, permissions, output format, and caveats. It is sufficiently complete for an agent to correctly select and invoke this tool without ambiguity.

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?

Although the schema already describes parameters, the description adds meaningful semantics: coordinate origin for region capture, the meaning of windowName (app name), and scale's impact on token cost. The examples directly illustrate parameter combinations, adding value 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?

Opening sentence 'Capture screen, window, or region as base64 PNG' uses a specific verb and resource, clearly defining the tool's function. It also distinguishes itself from sibling tools like mac_run and mac_state, which focus on execution and system state rather than screen capture.

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 concrete use cases with examples for each target type (screen, window, region), giving clear context for when to use each mode. It does not explicitly name alternative tools or state when not to use the tool, but the examples and limitations effectively guide 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, the description responsibly discloses key behaviors: empty input returns all state, window listing depends on Accessibility, and clipboard functionality is supported but deprecated in favor of a sibling tool. It does not describe the output format or potential side effects, but for a read-only state tool that 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?

The description is compact, well-organized into overview, examples, and limitations. Each sentence serves a distinct purpose: defining scope, demonstrating usage, and flagging caveats. There is 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?

The tool is simple (one optional parameter) and the description covers all enum values, usage, and limitations. However, with no output schema, it would be stronger to hint at the structure of the returned state. Still, for its complexity, it is sufficiently complete.

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

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

The schema already documents the 'include' parameter with enum values and a default, giving baseline coverage. The description adds value by showing exactly how to pass values in examples and clarifying that omitting include returns everything, which enriches the schema's meaning.

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: 'Read current macOS state,' and enumerates the exact aspects (frontmost app, windows, Finder selection, running apps). It distinguishes itself from siblings by explicitly noting that the clipboard is better served by mac_clipboard, making the tool's scope clear.

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 concrete usage examples for all state, window-only, and frontmost-app queries. It also gives clear exclusions: the clipboard works but mac_clipboard is preferred, and window listing requires Accessibility permissions. This gives an agent explicit guidance on when and how to invoke the tool.

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