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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the safety profile is covered. The description usefully adds that the file is created if missing, but omits encoding, newline handling, and permission/error behavior for a mutating 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 purpose is front-loaded in one clean sentence, and the Args block is terse with no wasted words. The docstring-style Args formatting is functional though slightly redundant with the 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?

For a simple two-parameter tool with no output schema, the description covers purpose, both arguments, and the file-creation behavior. Only minor gaps remain around encoding, newline handling, and success/failure reporting.

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

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

Schema description coverage is 0%, so the description carries the burden and does document both params: path as a full file path and text as the line to append. It does not clarify newline or encoding expectations for text, so it falls short of fully compensating.

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?

States a specific verb (add/append) and resource (a line to the end of a text file), plus the file-creation side effect. An agent can distinguish it immediately from file-reading siblings like read_file and open_file.

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 when-to-use or when-not-to-use guidance, and no alternatives named. The agent must infer that this is the write counterpart to read_file with no explicit routing information.

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?

Annotations already state readOnlyHint=false and destructiveHint=false, so the safety profile is covered. The description adds that clicks are coordinate-based on the latest screenshot and mentions the double-click mode, but says nothing about out-of-bounds coordinates, failure behavior, or whether the click is delivered to the frontmost app.

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?

Front-loaded one-sentence purpose followed by a compact Args block; no filler. The docstring-style Args formatting is slightly redundant with the schema but low-cost.

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 three-parameter, no-output-schema action tool this covers the essentials: what it does, the coordinate source, and the double-click variant. Residual gaps (error/edge-case behavior) are minor for a tool of this 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 description coverage is 0%, so the description carries the burden and does document all three parameters: x and y as horizontal/vertical positions within the screenshot (critical, since it establishes the coordinate frame) and double as a double-click toggle. It is brief but the key ambiguity about the coordinate reference frame is resolved.

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?

States a specific verb (click) and resource (screen position) and ties the coordinates to 'the most recent screenshot', which tells the agent this is pixel-space clicking rather than DOM/selector clicking. It does not explicitly distinguish itself from the sibling click_page_link, which is the main missing differentiation.

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 phrase 'using coordinates from the most recent screenshot' implies a prerequisite workflow (take a screenshot first), which is real guidance. However, it never says when to prefer this over click_page_link or what to do if no screenshot exists, so usage is only implied.

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?

Annotations already declare readOnlyHint=false and destructiveHint=false, so the agent knows this mutates state without being destructive. The description adds that clicking targets visible text inside web apps, but says nothing about failure modes (missing text, multiple matches), waiting for page load, or navigation 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?

The description is front-loaded with the core action and the target environment, followed by a compact Args block. Every line contributes, though the Args block partially duplicates what a schema-aware agent could infer.

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 two-required-parameter tool with no output schema, the description covers both inputs thoroughly and states the operating context. The remaining gap is behavioral (what happens on ambiguous or failed matches), which is a minor omission for a click action.

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

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

Schema coverage is 0%, so the description carries the full burden and does it well: 'tab' is documented as accepting a tab number, window.tab, or text from a title/URL, and 'text' is defined as visible link/button text with a concrete example. This is meaningfully more than the bare string-typed schema provides.

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?

States a specific verb (click) and resource (link or button on a page) plus the selection mechanism (by its visible text), which implicitly separates it from the coordinate-based 'click' sibling. It never names a sibling explicitly, so an agent must infer the boundary itself.

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 phrase 'works inside web apps like LEARN and Gmail' gives useful context about where this applies, implying page-level web automation. However, there is no when-not guidance and no pointer to the obvious alternative, list_page_links, for discovering the text to click.

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?

The description adds real behavior beyond the annotations by disclosing reversibility: closed tabs are recoverable with Cmd+Shift+T, which contextualizes the destructiveHint=false claim. It also warns that tabs should be enumerated first. It does not mention permissions, limits, or what happens to tabs in other windows, so it is strong but not exhaustive.

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 short sentences, front-loaded with the action, then the workflow, then the recovery behavior, plus a compact Args block. No sentence is redundant or padded.

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 single-parameter mutation tool with no output schema, the definition covers purpose, required workflow, argument format, and undo semantics. It omits anything about scope (current window vs all windows) or failure behavior when a tab identifier doesn't match, but 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?

Schema description coverage is 0%, so the description carries the full burden and does so well: it explains the tabs array holds either window.tab numbers in "1.4" form or title/URL text, and gives the preference rule (prefer numbers). This is exactly the compensating detail the empty schema lacks.

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?

States a specific verb (close) and resource (Chrome tabs), and the domain is narrow enough to distinguish it from siblings like list_browser_tabs, read_browser_tab, and focus_browser_tab. An agent knows exactly what operation this performs without opening the schema.

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?

"List them first, then pass the ones to close" prescribes a concrete workflow that routes the agent to list_browser_tabs before invoking this tool. It stops short of naming an explicit when-not condition or an alternative close path, so it is clear context without 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?

Annotations declare readOnlyHint=false and destructiveHint=false, so the write-but-safe profile is given. The description adds value by explaining the draft is opened in the browser for a human to review and that no sending occurs, which aligns with the non-destructive annotation.

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

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

The purpose sentence is front-loaded and the Args list is compact. The only minor redundancy is that the Args section repeats information already implied by the parameter names in the 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?

For a simple three-parameter tool with annotations present and no output schema, the description gives enough to invoke it correctly: what it does, that it doesn't send, and the meaning of each argument. Minor gaps remain around what happens to the draft afterward.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It does enumerate all three params (to, subject, body) with brief glosses, but these largely restate the parameter names ('Recipient address,' 'Subject line,' 'Message text') without adding format or constraint detail.

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: 'Open a pre-filled Gmail draft in the browser.' It clearly conveys the action and result (a reviewable draft), though it does not distinguish itself from the many other sibling tools beyond naming send_email.

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 routes the agent to the correct alternative with 'To send, use send_email,' clarifying that this tool composes rather than sends. However, no when-not-to-use conditions beyond the send case are given.

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?

Annotations already establish readOnlyHint=false and destructiveHint=false, so safety is covered. The description adds real behavioral context beyond that: the reminder persists and syncs to the iPhone, and omitting due/list_name yields a timeless reminder in the default list. It omits what the call returns, but no output schema exists and the mutation semantics are otherwise clear.

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?

Front-loads the one-line purpose and sibling contrast, then a compact args block where every line earns its place given zero schema coverage. No filler or restated boilerplate.

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 3-parameter mutation tool with annotations and no output schema, the description covers purpose, differentiation, and every parameter's semantics. The only gap is the absence of any statement about the return value or duplicate-handling, which is minor for a create operation.

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

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

Schema description coverage is 0%, so the description carries the full burden and does so: it explains title, gives the exact due format '2026-09-14 20:00' plus the meaning of omission, and explains that omitted list_name falls back to the default list. This is meaning the schema alone does not convey.

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?

States a specific verb and resource ('Add a reminder in the Reminders app') and immediately distinguishes it from the sibling tool notify by contrasting ephemeral notifications with a persistent, syncing reminder. An agent can tell this apart from list_reminders and notify without opening any schema.

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?

Gives clear selection context by contrasting with notifications ('Unlike a notification, this persists and syncs to the iPhone'), which tells the agent when to prefer this tool over notify. It does not, however, reference list_reminders or state any prerequisites, so it stops short of explicit when-not 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?

Annotations already establish the write-but-not-destructive profile (readOnlyHint=false, destructiveHint=false), lowering the burden. The description adds the useful auth constraint that gated pages will fail, but it stays silent on overwrite behavior if a file already exists and on any permission needs, leaving real gaps.

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 core behavior is front-loaded in the first sentence, and the Args block is compact and readable. The per-parameter lines are somewhat redundant with the schema, but that redundancy is justified given 0% schema description coverage.

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 purpose, constraints, and params adequately, but with no output schema it never states what the call returns (e.g., the saved path). For a download tool that produces a file on disk, that return-value ambiguity is a notable omission.

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

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

Schema coverage is 0%, so the description carries the load, and it does document all three params: url as a direct http(s) link, folder as the save location with its ~/Downloads default, and filename as an optional override. It adds the required meaning the bare schema lacks.

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?

"Download a file straight to disk" gives a specific verb and resource, and "straight to disk" signals it is a save operation rather than a view/open. It distinguishes reasonably from open_url and save_browser_tab but never names a sibling, so it stops short of full differentiation.

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?

"Works for public URLs; pages behind a login don't" is a clear when-it-works constraint that tells the agent the applicability boundary. It does not name an alternative tool for the login-required case, so it lacks the explicit routing that a 5 requires.

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?

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds the return payload (phone number and email) and, via "all or part of the name," hints at substring matching. It does not say what happens on no match or with multiple matches, so it adds modest context beyond the annotation.

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

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

Two short sentences front-load the purpose and the usage trigger, and the Args block is minimal and non-redundant. Every line contributes to invoking the tool correctly.

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 single-parameter read-only lookup with no output schema, the description covers purpose, trigger, returned fields, and matching semantics. The only real gap is behavior on no match or multiple matches, which is minor but worth noting.

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

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

Schema description coverage is 0%, so the description carries the burden for the single parameter — and it does: it explains that the value may be a full or partial name and gives concrete examples ("Kuljot", "didi", "mom") that convey case-insensitive partial matching. No format or edge-case guidance (e.g. ambiguity resolution) is given.

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 (look up) and resource (Contacts) and names the returned fields (phone number, email), so the agent knows exactly what this tool produces. It does not explicitly distinguish itself from the sibling list_contacts, which an agent could plausibly confuse it with, so it stops short of a 5.

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?

"Use this before messaging or emailing a person" gives a clear situational trigger tied to sibling tools like send_message and compose_email. It provides no exclusions or explicit pointer to list_contacts for enumerating all contacts, so the routing guidance is helpful but incomplete.

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?

The readOnlyHint annotation already establishes this is a safe, non-destructive read, so the bar is lower. The description adds useful context (Spotlight-backed, filename matching), but omits result ordering, whether the default scope is the whole Mac, and any Spotlight-indexing/permission caveats.

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 one-line purpose is front-loaded and the argument list is compact. The Args block slightly duplicates the schema titles, but the added examples earn their 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?

There is no output schema, so the description should say what comes back (full paths? names? ordering?), and it does not. Combined with no annotation beyond readOnlyHint, the definition is adequate but leaves a gap an agent would want filled.

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

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

Schema description coverage is 0%, so the description carries the full burden — and it does document all three parameters with concrete examples ('ECE 150', '~/Documents') and the default of 10. It does not explain limit bounds or the accepted folder path format beyond one example.

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?

States a specific verb and resource ('Search the Mac for files and folders by name') and even names the underlying mechanism (Spotlight). This clearly separates it from content-reading siblings like read_file, though it never explicitly names an alternative 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 phrase 'by name' implies this is for filename lookup rather than content search, but there is no explicit when-to-use, when-not-to-use, or pointer to any sibling (e.g. read_file, list_embedded_files). The agent must infer the routing.

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?

Annotations already declare readOnlyHint=false and destructiveHint=false, which matches 'bring to the front' (changes active-tab state, non-destructive). The description adds no auth needs, rate limits, or failure behavior, but with annotations covering the safety profile this is a modest gap rather than a serious one.

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?

Short and front-loaded, with the core action in the first sentence and the parameter guidance after. The Args block uses a slightly raw docstring style but wastes no words.

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

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

For a single-parameter, non-destructive tool with no output schema and annotations covering safety, the definition supplies the essential action and parameter formats. Missing failure behavior (e.g., no-match tab) is minor.

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

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

Schema description coverage is 0%, so the description must carry the burden, and it does: it specifies the accepted formats for 'tab' (tab number, window.tab, or text from title/URL). This adds real selection meaning beyond the bare string-typed schema property.

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?

States a specific verb and resource ('Bring a Chrome tab to the front') that is unambiguous and clearly distinct from siblings like list_browser_tabs, read_browser_tab, or close_browser_tabs. An agent can identify the tool's job without opening the schema.

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 purpose implies when to use it (to switch active tab), but there is no explicit when-to-use, when-not-to-use, or alternative routing. No prerequisites, error conditions, or sibling comparisons are given.

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?

readOnlyHint=true already establishes the safe-read profile, so the bar is lower. The description goes beyond that by disclosing what the call returns (percentage, charging state, time remaining), which is valuable given there is no output 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?

A single front-loaded sentence with no filler. Every clause earns its place by naming a distinct returned value.

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

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

With no parameters and no output schema, the description carries the return-value burden and does so adequately for this simple status query. Minor gaps (e.g. behavior on machines without a battery) are not material.

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 takes zero parameters, so the baseline is 4. There is no parameter semantics to add meaning to, and the description correctly omits any parameter discussion.

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?

States a specific verb ('Get') and resource ('MacBook's battery') and enumerates the exact data returned: percentage, charging state, time remaining. No sibling tool covers battery status, so an agent can select it unambiguously.

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?

There is no explicit when-to-use or when-not-to-use guidance, but for a zero-parameter, read-only status query the usage is self-evident from the purpose statement. Adequate but with a clear gap.

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?

readOnlyHint=true already declares this is a safe, non-mutating read, so the bar is lower. The description adds the return semantics ('as a percentage') and scopes the target to the built-in display, which is real value beyond the annotation since no output schema exists to convey the format.

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

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

A single front-loaded sentence with zero filler; every clause (verb, target, unit) 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 with no output schema, the description covers what is returned and in what unit, which is the key missing piece. It stops short of noting edge cases such as a machine with no built-in display, but nothing essential to invoking it correctly is absent.

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 takes zero parameters, so per the rubric the baseline is 4. There is nothing to disambiguate and the description correctly introduces no parameter discussion.

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?

States a specific verb (Get) and resource (built-in display's brightness) plus the return unit (percentage), so the agent knows exactly what it retrieves. It doesn't explicitly name the sibling set_brightness as its counterpart, but the get/set split against that sibling is 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?

Usage is only implied: an agent can infer this is a read used to inspect the current brightness, likely before calling set_brightness. There is no explicit when-to-use statement, no prerequisite, and no alternative named, so it stays at minimum viable.

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?

readOnlyHint=true already declares this is a safe, non-mutating read, so the description carries a lower burden. It adds only that the value returned is the current clipboard contents; it does not describe what format (text, image, multiple items) comes back, which matters since there is no output 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?

A single front-loaded sentence with no filler or redundancy. Every word earns its place and the key constraint ('currently') is prominent.

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 clipboard accessor this is nearly sufficient. The only real gap is the undisclosed return format, which matters slightly because no output schema exists to cover it.

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 takes zero parameters, so there is nothing for the description to disambiguate; the baseline for a parameterless tool 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?

States a specific verb (read) and resource (clipboard), and the read/set pairing with the sibling set_clipboard makes the distinction obvious. It stops short of naming the alternative explicitly, so it is clear but not sibling-differentiating to the level of a 5.

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 intent is implied by 'currently on the clipboard', which tells the agent this reads the present clipboard state rather than a historical one. There is no explicit when-to-use/when-not guidance or mention of set_clipboard as the counterpart, so it is adequate but thin.

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?

readOnlyHint=true already tells the agent this is a safe read with no side effects, so the description doesn't need to restate that. It does add useful scope (the two media sources it reads from), but says nothing about behavior when nothing is playing or when multiple players are active. Adequate but thin against an already-covered safety profile.

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

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

A single front-loaded sentence with no filler. Every clause (verb, returned data, supported sources) carries information.

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

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

For a zero-parameter read tool with no output schema, the description covers what the agent needs: the action, the returned fields, and the sources. Only the empty/no-playback case is unaddressed, 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 tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. The description correctly implies no input is required.

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?

States a specific verb ('Get') and resource ('the track and artist currently playing'), so the agent knows exactly what comes back. It also names the two supported sources (Spotify or Music). It stops short of distinguishing itself from the sibling 'media_control', which also touches playback.

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

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

The phrase 'currently playing' implies the tool's context (querying active playback state) but there is no explicit when-to-use or when-not-to-use guidance, and no pointer to how this differs from 'media_control'. Usage is inferable rather than stated.

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?

readOnlyHint=true already tells the agent this is a safe read, so the bar is lower, and the description adds the return contract that the annotations do not: the 0-100 scale and the boolean mute state. With no output schema, disclosing the shape of the answer is exactly the added value needed. It does not mention permissions or any failure mode, keeping it short of a 5.

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

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

A single sentence that front-loads the core capability, then appends the return scale, mute state, and a natural-language query hook without a wasted word.

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-argument, read-only getter with no output schema, an agent needs to know the resource, the read-only nature, and the returned fields. The description covers all three explicitly, including the numeric range.

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 takes zero parameters, so per the rubric the baseline is 4. There is nothing parameter-wise for the description to clarify, and it correctly does not invent any.

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?

States a specific verb and resource ('Get the Mac's output volume') and goes further by defining the returned scale (0-100) and the mute flag. The verb 'Get' also implicitly separates it from the sibling setters set_volume and set_mute, though it never names them.

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 clause 'also answers "is it loud"' implicitly maps a user intent to this tool, which is useful routing context. However, there is no explicit when-to-use statement, no exclusion, and no reference to the alternative setters, so the guidance stays implied.

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?

readOnlyHint=true already tells the agent this is a safe, non-mutating read, so the description does not need to restate that. It adds no further behavioral context such as the macOS location-permission requirement for reading the SSID, or what happens when Wi-Fi is off. Adequate but thin given the annotation already covers the safety profile.

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

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

A single front-loaded sentence with no filler; both pieces of returned information are named up front and nothing is wasted.

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?

With no output schema, the description carries the burden of describing the return value, and it does name the two things returned (on/off state, joined network). Minor gaps remain (permission requirements, behavior when Wi-Fi is disabled), but for a trivial read tool it is nearly 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 tool takes no parameters, so there is no parameter semantics to explain and the baseline of 4 applies. Nothing in the description misleads about inputs.

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?

States a specific verb ('Check') and resource ('Wi-Fi') plus the exact information returned: power state and joined network. This cleanly distinguishes it from the sibling set_wifi, so an agent can route between the getter and setter without opening either schema.

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 its use case (inspecting current Wi-Fi state) but never states when to call it versus alternatives such as set_wifi, nor any prerequisite. For a zero-argument getter the implied usage is reasonably clear, which lands it at the minimum-viable 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?

The readOnlyHint=true annotation already establishes the safety profile, so the description's main added value is disclosing what information is returned (front app, non-quittable apps). It does not mention ordering, count limits, or whether results are a snapshot, which would be useful behavioral context beyond the annotations.

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

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

A single front-loaded sentence that names the resource first and then adds the specific returned details. No filler, no repetition of the tool name, nothing that does not earn 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?

With no output schema, the description usefully compensates by describing what the listing contains. Combined with readOnlyHint, an agent has enough to call it correctly; only minor details (format/ordering of the list) are absent.

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 takes zero parameters, so per the rubric the baseline is 4. There is no parameter syntax to explain, and the description correctly avoids inventing any.

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?

States a specific verb ("List") and resource ("apps currently open"), and even clarifies the scope parenthetically ("the ones shown in the Dock"). It also enumerates the precise facts returned (front-most app, non-quittable apps), which clearly separates it from siblings like open_app, quit_app, and list_shortcuts.

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?

Usage is implied rather than stated: an agent can infer this is the tool for inspecting currently running apps, but there is no explicit when-to-use, when-not-to-use, or pointer to alternatives such as open_app/quit_app. Adequate for a trivial no-arg query, but no real guidance is given.

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?

readOnlyHint=true already tells the agent this is a safe read, so the description's added value is disclosing the return shape (window.tab number, title, URL). It adds nothing about ordering, tab scope, or whether it covers all windows, so it beats the annotation floor only modestly.

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

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

A single front-loaded sentence with no filler; the resource and the returned fields are stated immediately, and nothing is repeated from the schema or annotations.

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?

With no parameters and no output schema, the description is the only place the return shape can be conveyed, and it does so correctly. Minor gaps remain: nothing about ordering, limits, or whether multiple windows are included.

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 takes zero parameters, so per the baseline this dimension scores 4. There is no argument syntax the description could usefully clarify.

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?

States a specific verb ('List') and resource ('every open Chrome tab') and even enumerates the returned fields (window.tab number, title, URL). This distinguishes it implicitly from siblings like list_page_links and read_browser_tab, though it never names those alternatives explicitly.

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 no when-to-use, when-not-to-use, or alternative guidance. An agent must infer from the scope statement alone that this is the right tool for enumerating open tabs rather than reading one tab's content or listing in-page links.

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?

Annotations already declare readOnlyHint=true, so the safety profile is covered by structured data. The description adds useful but limited context by naming the returned fields (numbers and emails) in the absence of an output schema, but says nothing about volume, ordering, or permission prompts for contacts access.

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

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

One short sentence, front-loaded with the action and scoped to the app and return fields. No 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 zero-parameter, read-only listing tool this is nearly complete: it says what is listed and what comes back. The only meaningful omission is routing versus find_contact, plus any note on result size.

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 takes zero parameters, so there is nothing for the description to disambiguate. Baseline 4 applies per the rubric for parameter-free tools.

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

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

States a specific verb ('List') and resource ('everyone in the Contacts app') plus the fields returned (numbers and emails). It is clearly distinguishable from most siblings, though it never names the obvious alternative find_contact that also touches contacts.

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

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

No when-to-use guidance is given. With siblings find_contact and send_message in the same domain, the description should say to use this for a full enumeration and find_contact when searching for a specific person; instead the agent must infer that.

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?

readOnlyHint=true already covers the safety profile, and the description adds real value beyond it: it explains the viewer/wrapper pitfall and the intended two-step save workflow. It does not mention ordering, error cases, or empty results, which keeps it from a 5.

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?

Front-loaded with the core definition, then the practical caveat, then the arg note. Minor redundancy in the closing sentence ('Open the URL this returns, then save that tab instead'), but every sentence carries information.

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

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

No output schema, so the description correctly specifies what is returned (URLs of the underlying files) and what to do with them. For a single-param read-only tool this is complete, with only error/empty-result behavior left unspecified.

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

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

Schema description coverage is 0%, so the description must carry the parameter explanation, and it does: 'Tab number, window.tab, or text from its title or URL.' That is meaningful disambiguation of accepted input forms beyond the bare string 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?

States a specific resource and output: URLs of files embedded in a page, qualified as PDF viewers/iframes and 'the real file behind a viewer.' An agent can distinguish this from list_page_links by the embedded-file framing, though the sibling is never named explicitly.

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?

Gives concrete context and a follow-up workflow: LEARN wraps PDFs in a viewer, so saving the tab saves the wrapper; instead open the returned URL and save that tab. It states when and what to do next, but does not contrast against alternatives like list_page_links or read_pdf.

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?

The readOnlyHint=true annotation already establishes this is a safe read, and the description adds the output format. However, it says nothing about scope (whole page vs. visible region), frames/iframes handling, or result size, so behavioral disclosure beyond the annotation is thin.

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?

Front-loaded purpose sentence followed by a compact Args block; nothing is redundant. Minor formatting overhead from the Args section, but it earns its space given the zero schema coverage.

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?

No output schema exists, and the description compensates by describing the return as "text -> url" pairs. Both parameters are documented, so an agent has enough to call the tool correctly, though scope and pagination limits remain unstated.

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

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

With 0% schema description coverage, the description carries the load and does so well: tab is explained as accepting a tab number, window.tab, or text from a title/URL, and contains is described as an optional filter with concrete examples ("L3", "download").

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?

States a specific verb (List) and resource (a page's links and buttons) and even specifies the return shape ("text -> url"). It is clearly distinguishable from the sibling click_page_link, since this tool reads the links rather than activating them.

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?

"Use this instead of guessing where to click" gives clear workflow context: discover links before clicking. It does not explicitly name click_page_link as the follow-up alternative or state exclusions, so it falls just 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.

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description does add one behavioral fact beyond the annotations — that only unfinished reminders are returned — but says nothing about ordering, pagination, or whether completed reminders are ever included.

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 purpose sentence is short and front-loaded, but the 'Args:' block merely duplicates the schema's limit property and default value, so not every line 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 one-parameter read-only tool this is close to sufficient, but with no output schema the description should say something about the shape or ordering of returned reminders. As written, an agent knows what it lists but not what it gets back.

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

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

Schema description coverage is 0%, so the description carries the burden, and it does explain the single parameter ('How many to return') along with the default of 10. However, this is essentially restating the schema's title and default rather than adding format or range details.

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?

States a specific verb ('List') and resource ('reminders') and adds a meaningful scope qualifier ('unfinished'), which distinguishes it from the sibling create_reminder. It does not explicitly name any alternative tool, so it falls short of a 5.

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?

There is no guidance on when to use this versus alternatives such as create_reminder, nor any prerequisites or exclusions. Usage is only implied by the verb 'List'.

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?

readOnlyHint=true already tells the agent this is a safe, non-mutating call, so the description need only add context beyond that. It adds that Shortcuts are host-level macOS capabilities usable as a fallback, but says nothing about whether the list can be empty, how shortcuts are identified, or any permissions needed to enumerate them.

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 short sentences, the object of the listing stated first and the usage rationale second. Every clause earns its place with no filler or repetition of the 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 zero-parameter, read-only discovery tool with no output schema, the description covers what it returns and why one would call it. The main omission is that it does not connect the result to run_shortcut, leaving the agent to infer the follow-up step itself.

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 takes zero parameters, and the schema is trivially 100% covered, so there is nothing for the description to compensate for. Baseline 4 applies; no parameter syntax or filtering behavior is claimed or needed.

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 gives a specific verb and resource ('List the macOS Shortcuts available to run'), so the agent knows exactly what is enumerated. It also frames the tool as a capability-discovery mechanism, which separates it from the concrete action siblings, though it never names run_shortcut, the obvious follow-up 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?

'Use this to find capabilities Sommus has no tool for' is a clear and actionable when-to-use condition, effectively telling the agent to reach for this tool when no first-class tool covers a task. It stops short of stating the next step (invoke run_shortcut with a discovered name) or any exclusion/dependency 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?

Annotations only declare non-read-only and non-destructive; the description adds real behavioral context beyond them by stating that running apps are unaffected and that reversal requires a password or Touch ID. It doesn't mention auth prompts or whether other tools' state changes, but for this trivial operation the added detail is solid.

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 short sentences, the action front-loaded, and the second sentence carrying only non-obvious behavioral facts. No 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 no-parameter, no-output, single-purpose action, the description covers the action, side effects, and how to reverse it. Only the relationship to sibling power/display tools is left to inference.

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 takes no parameters at all, so there is nothing for the description to disambiguate; the baseline for a zero-parameter tool is 4.

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

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

States a specific verb and resource ('Lock the screen') with an immediacy qualifier. The clause 'Apps keep running' implicitly distinguishes it from the nearby sleep_display/sleep_computer siblings, but neither is named, so the differentiation is suggestive rather than 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?

Usage is only implied: you lock the screen when you want to secure it. There is no explicit when-to-use versus the very similar siblings sleep_display and sleep_computer, and no when-not guidance, though 'Apps keep running' gestures at the distinction.

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?

Annotations declare readOnlyHint=false and destructiveHint=false, so the safety profile is already covered and the description is not contradicted. The description adds the useful scope fact that it acts on 'whatever is playing' across multiple apps, but says nothing about what happens when no media is active or whether the action reports success.

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?

Front-loaded one-line summary followed by a compact action breakdown; every sentence earns its place with no filler. The parenthetical app list is slightly verbose but useful for identifying scope.

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 single-parameter, non-destructive tool with no output schema, the description covers purpose, action semantics, and intent mapping adequately. The only meaningful gap is failure/no-media behavior, which is minor 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?

Schema description coverage is 0%, so the description carries the burden, and it delivers: it maps all five enum values to meaning, including the non-obvious mapping of user requests for 'stop' and 'resume' onto pause/play. This is meaning the enum alone cannot convey, though it adds no format or default details.

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?

States a concrete verb set (play, pause, skip) plus the resource it controls, and disambiguates the target with examples like Spotify, Music, and YouTube in a browser. It is clear what the tool does, though it never names the read-side sibling get_now_playing, so sibling differentiation is implicit rather than stated.

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?

Gives an explicit intent mapping — use pause/play 'when asked to pause, stop, play or resume' — which is exactly the routing information an agent needs. It does not, however, state any when-not conditions or point at alternatives such as get_now_playing for status checks.

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?

Annotations already declare readOnlyHint=false and destructiveHint=false, so the safety profile is covered. The description adds the immediacy/timing behavior ('right now'), but says nothing about notification permissions, whether the banner persists, or what happens on failure — meaningful context for a display-side-effect tool that is left unstated.

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 short sentences plus a compact Args block; the purpose and the alternative are front-loaded before the parameter detail. Nothing is padded.

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 two-parameter, no-output-schema tool, the description covers purpose, the alternative sibling, and both parameters adequately. The only gap is post-call behavior (permissions, success/failure signalling), which is minor here.

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

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

Schema description coverage is 0%, so the description must carry the load, and it does: 'title' is defined as a short bold heading and 'message' as body text, covering both required parameters with role and formatting expectations. It could go slightly further on length limits or formatting constraints, but it compensates well.

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?

States a specific verb and resource ('Show a macOS notification banner') plus a temporal constraint ('right now'), which immediately separates it from the sibling create_reminder. An agent can identify the tool without inspecting the schema.

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?

Explicitly names an alternative ('For a reminder at a later time, use create_reminder') and gives the condition that selects it, so the when-to-use boundary is unambiguous. This is exactly the routing guidance a sibling-rich toolkit needs.

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?

Annotations give readOnlyHint=false and destructiveHint=false, so safety is partly covered; the description adds genuinely useful behavior beyond that by disclosing the idempotent 'bring to front if already running' semantics rather than assuming a fresh launch. It does not mention what happens if the app name is not found or any permission prompts, which keeps it short of a 5.

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

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

One front-loaded sentence states the core behavior and the edge-case behavior, followed by a compact arg line with examples. Every element earns its place and nothing is padded.

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 single-parameter tool with annotations covering the safety profile and no output schema, the description supplies name format, examples, and the already-running case. The only real gap is failure behavior for an unknown app name, which is minor.

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

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

Schema coverage is 0%, so the description carries the burden, and it does so by specifying the expected string form ('as it appears in /Applications') plus three concrete examples. That is meaningful format guidance beyond the bare string type, though it omits any note on case sensitivity or whether extensions are required.

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?

States a specific verb (open) plus resource (app), and adds the precise scope distinction that the app is brought to the front if already running. This clearly separates it from siblings like open_file, open_url, and list_apps without needing to name them.

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?

Usage is implied by the verb and the /Applications naming convention, but there is no explicit guidance on when to pick this over open_file, open_url, or list_apps (to discover valid names), nor any stated prerequisite such as automation permission. Implied-but-not-stated places it at the minimum viable level.

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?

Annotations declare readOnlyHint=false and destructiveHint=false, so the mutation/safety profile is partly covered. The description adds genuine value beyond that by explaining the side effect of launching the OS default handler for the file type. It omits focus-stealing behavior, blocking vs non-blocking execution, and failure modes for nonexistent paths.

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 core behavior is front-loaded in the first sentence and the rest is a short Args block. The Args block partially repeats the schema, but for a single-parameter tool this is minor waste rather than bloat.

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 launcher with no output schema, the description covers what the tool does and what the argument should be. Remaining gaps (return value, error handling, whether it waits for the app) are modest 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?

Schema description coverage is 0%, so the description must carry the parameter, and it does: "path: Full path to the file or folder" conveys that an absolute path (not a name or relative reference) is expected. It adds the one distinction the bare schema lacks, though no format examples or quoting guidance.

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

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

States a specific verb and resource ("Open a file or folder") and clarifies the mechanism ("in its default app"), including concrete examples of app routing (Finder for folders, Preview for PDFs). It does not, however, distinguish itself from close siblings like read_file or open_app, leaving the boundary to inference.

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 never says when to use this instead of read_file, open_app, or open_url, all of which are plausible alternatives in the sibling list. Usage is only weakly implied by "in its default app"; there are no exclusions or prerequisites.

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?

Annotations declare readOnlyHint=false and destructiveHint=false, so the safety profile is already covered. The description adds the meaningful detail that the page opens in the default browser, but says nothing about return value, whether tabs are reused, or what happens if no browser is available. With annotations carrying the safety burden, a 3 is appropriate.

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

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

One front-loaded sentence states purpose, and the Args block is short. The Args repetition of the single param name is mildly redundant but conventional and not wasteful.

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 action with annotations and no output schema, the definition covers what the agent needs: the action, the target, and the required URL format. It omits side-effect/return behavior, which 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?

Schema coverage is 0% and the schema only declares a bare string, so the description carries the parameter burden. It compensates by specifying "A full http:// or https:// URL," which adds a real format/scheme constraint not present in the schema. Full compensation for a single simple param, short of a 5.

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?

States a specific verb and resource ("Open a web page") and narrows scope with "in the default browser," which separates it from siblings like open_file, open_app, and download_url. It does not name a sibling it is distinct from, so it falls short of a 5.

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 when-to-use guidance, no exclusions, and no routing to alternatives such as download_url (save the resource) or read_browser_tab (fetch content) despite many plausibly related siblings. The agent must infer when opening a URL is the right call.

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?

Annotations already declare the safety profile (readOnlyHint=false, destructiveHint=false), so the description only needs to add beyond that. It does add that the app is 'brought to the front first,' but omits what happens when 'app' is empty and says nothing about required OS accessibility permissions for synthetic key events, which are material for a keyboard-injection 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 purpose is front-loaded in the first line, followed by a compact Args block. Every element earns its place; the docstring-style formatting is slightly heavier than prose but not wasteful.

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 action tool with no output schema, the description covers purpose, both parameters, and focus behavior. The remaining gaps (permission prerequisites, behavior when 'app' is omitted) are minor but real.

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

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

Schema description coverage is 0%, so the description must carry the burden, and it largely does: 'combo' is documented with syntax ('keys joined by "+"') plus concrete examples ('cmd+s', 'escape', 'left'), and 'app' is explained with an example and a 'Recommended' marker. Only the omitted-app behavior is left unstated.

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?

States a specific verb and resource ('Send a keyboard shortcut to an app') and adds a routing clause, 'for actions with no dedicated tool,' that implicitly distinguishes it from siblings like close_browser_tabs or media_control. It stops short of naming the specific alternative tools an agent should prefer.

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?

'For actions with no dedicated tool' gives a clear condition for reaching for this tool over the specialized siblings. No explicit exclusions or named alternatives are provided, but the when-to-use context is present.

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?

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is covered. The description adds meaningful behavior beyond that: the app "may still ask to save unsaved work," warning the agent that the call may be blocked by a dialog. It stops short of describing non-existent apps or failure modes.

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 short sentences plus a minimal Args block; the core action and its caveat are front-loaded with no filler. The "Args:" formatting is slightly formulaic but adds no bloat.

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 single-parameter action tool with annotations covering the destructive profile and no output schema, the description supplies the parameter meaning, the prerequisite lookup tool, and the save-dialog caveat. Enough for correct invocation; only edge-case failure behavior is omitted.

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

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

Schema description coverage is 0%, so the description must carry the parameter. It names the argument, explains it is the app's name, gives a concrete example ("Spotify"), and points to list_apps for exact-name resolution. That compensates well for the empty 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?

States a specific verb and resource ("Quit a running app") that an agent can immediately distinguish from siblings like open_app and list_apps without opening any schema. No ambiguity about what action is performed.

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?

Provides explicit prerequisite guidance: "Use list_apps first if unsure of the exact name." This is a clear when-to-use directive, though it does not discuss when not to use the tool or compare against alternatives such as run_shell.

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?

readOnlyHint=true already tells the agent this is a safe read, so the bar is lower. The description does add one genuine behavioral constraint — it reads only the *visible* text, not full DOM/hidden content — which is useful scoping, but it says nothing about truncation, error behavior for a missing/ambiguous tab, or whether it waits for load.

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?

Front-loaded one-line purpose followed by a tight Args block; nothing is padded. Minor structural noise from the trailing quote/newline in the description string, but the substance is efficient.

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

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

For a single-parameter read tool with no output schema, the core is covered: what it returns (visible text) and how to identify the tab. What's missing is failure handling — an ambiguous title like "MATH 115" matching multiple tabs, a closed tab, or non-Chrome frontmost app — which an agent would need to call this reliably.

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

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

Schema description coverage is 0% and the schema only names the field 'tab' as a plain string, so the description carries the full burden — and it delivers, spelling out three accepted identifier forms (number "3", window.tab "1.3", or title/URL text "MATH 115"). That is meaningfully more than the schema provides.

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?

States a specific verb (Read) and resource (visible text of a Chrome tab), and the clarifying phrase 'the way to see what's on a page' pins down what it returns. It does not, however, contrast itself with the obvious siblings that also expose page content, such as screenshot or read_pdf.

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?

There is no statement of when to prefer this over list_browser_tabs, screenshot, or read_pdf, and no prerequisites (e.g., tab must be open, Chrome must be running). The only hint is the implied 'to see what's on a page', which is essentially a restatement of purpose rather than routing 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?

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds genuinely useful context beyond the annotations – "Long files are truncated" – but says nothing about encoding, binary handling, or the shape of a folder listing.

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?

Front-loaded with the core action and the truncation caveat in two short sentences, then a compact Args block. No filler, though the parameter detail could have been folded into the prose more tightly.

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 single-parameter read tool with readOnlyHint and no output schema, the essentials are present: what it does, the dual file/folder mode, truncation, and path semantics. The only real gap is what a folder listing returns, which is a minor omission given no output schema exists.

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

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

Schema description coverage is 0%, so the description carries the burden and does so reasonably: it names the parameter, calls it a "Full path," and gives a concrete example ("~/Documents/notes.md") that also reveals tilde expansion works. It stops short of stating whether relative paths are accepted.

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?

States a specific verb ("Read") and resource ("text file") and discloses a secondary mode (listing a folder's contents). It is clearly distinguishable from siblings like read_pdf, read_browser_tab, and append_to_file, though it does not name those alternatives explicitly.

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

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

No guidance on when to use this versus read_pdf, read_browser_tab, or find_files, and no prerequisites or exclusions are given. The dual file/folder behavior implies usage but leaves the agent to infer which siblings to pick.

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?

Annotations only declare readOnlyHint=true; the description goes beyond that by disclosing OCR behavior and a concrete cost/latency figure (~3s per page) that affects invocation strategy. It does not cover failure modes (missing file, corrupt PDF) or page-numbering conventions.

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

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

One front-loaded sentence captures purpose and differentiator, followed by a compact Args block with no filler. Each line of the parameter list earns its place by adding format or cost information.

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

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

With no output schema, the description does state the return type ('as text') and all three parameters are documented, so an agent can call it correctly. Minor gaps remain: how multi-page text is delimited, and the fact that ocr defaults to true is left to the schema's default field.

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

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

Schema description coverage is 0%, so the description carries the full burden and does: path with a concrete example, pages with three accepted format examples ('1-5', '3', '2,4,7') plus the omit-for-all behavior, and ocr explained as conditional OCR with a speed trade-off. Every parameter gains meaning beyond its bare type.

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?

States a specific verb+resource ('Read a PDF as text') and immediately adds scope ('scanned ones included'), which distinguishes it from both read_file and screenshot. The comparison to screenshotting tells an agent exactly what niche this tool fills among its siblings.

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?

Gives clear selection context: use this rather than screenshotting page by page because it is cheaper, and use the ocr flag for scanned pages lacking a text layer. It never states an exclusion or names a sibling tool for non-PDF files (e.g. read_file), so it stops short of full when/when-not 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?

Annotations already declare readOnlyHint=false and destructiveHint=true, so the safety profile is covered. The description adds meaningful context the annotations cannot: commands execute as the user 'Jashan' from his home folder, and sudo is unavailable. It does not explain output formatting or error behavior, so it is good but not exhaustive.

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?

Front-loaded with purpose and routing in the first two sentences, then environment caveats, then a clean args block. Every sentence earns its place with no 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 an arbitrary shell-execution tool with no output schema and 0% param coverage, the description supplies the identity/environment context, the sudo limitation, timeout default, and invocation examples. The main remaining gap is describing how output and errors are returned, which is minor since the description says to read the output directly.

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

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

Schema coverage is 0%, so the description carries the parameter burden and does so well: it gives three concrete command examples ('ls ~/Downloads', 'git -C ~/x status', 'brew list | head') and explains timeout as 'Seconds to allow before giving up (default 60)'. This compensates for the bare schema, though it could note the working-directory assumption more explicitly.

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?

States a specific verb and resource ('Run a shell command and read its output') and then positions it against the entire sibling set with 'The way to do anything with no dedicated tool.' An agent can immediately tell this is the catch-all escape hatch rather than any of the specialized 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 line 'the way to do anything with no dedicated tool' is an effective when-to-use rule, implying dedicated siblings should be preferred. It also warns that sudo won't work, which is a real usage constraint. It stops short of naming alternatives explicitly, so it is clear context rather than a full when/when-not/alternatives breakdown.

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?

Annotations declare readOnlyHint=false and destructiveHint=false, so the agent knows this is a mutating but non-destructive operation. The description adds a useful behavioral hint that the effects are open-ended ('covers things with no dedicated tool'), but says nothing about what the shortcut returns, whether it blocks, or how failures surface. Adds some value over annotations, not a lot.

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 tight sentences with the action front-loaded, followed by a compact Args note. No filler, though the Args block adds little beyond restating the single schema property.

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, the description covers purpose, scope, and discovery of valid inputs. The remaining gap — what running a shortcut returns or how errors are reported — is modest 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?

Schema coverage is 0% (the schema only has a bare 'Name' title), so the description carries the burden and does so: it explains that the value is the shortcut's name and routes the agent to list_shortcuts to discover valid values. No format or naming-convention detail beyond that.

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?

States a specific verb+resource ('Run one of the user's macOS Shortcuts') and adds scope that distinguishes it from the many dedicated siblings: it is the catch-all for actions with no dedicated tool. It does not name a specific sibling alternative, but the 'no dedicated tool' framing does meaningful routing work.

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?

Gives a clear use condition (things without a dedicated tool, e.g. Focus modes) and an explicit prerequisite workflow ('call list_shortcuts first if unsure'). No explicit when-not-to-use, but the fallback framing implies it.

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?

Annotations only tell the agent it is a non-read, non-destructive operation. The description adds genuinely useful behavior: the save is driven via a Cmd+S keyboard shortcut (implying the browser/tab must be focused), and it discloses the save target default (~/Downloads). It does not cover overwrite behavior or focus prerequisites, hence not a 5.

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 tightly written sentences front-load the purpose and workflow, followed by a compact args list that adds semantics rather than restating types. No filler, though the args block could be trimmed slightly.

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 2-param, no-output-schema tool, the description covers purpose, mechanism, both parameters, and the next step (read_pdf). It is nearly self-sufficient; only minor gaps like overwrite behavior and focus requirements remain.

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

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

Schema coverage is 0%, so the description carries the full burden and does so: 'tab' accepts a tab number, window.tab, or text from its title/URL, and 'folder' has a documented default of ~/Downloads. This adds meaning well beyond the bare schema types.

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?

States a specific verb+resource ('Save a browser tab's file to disk') and immediately grounds it with the mechanism 'Cmd+S' and the goal 'get a PDF that sits behind a login'. This clearly distinguishes it from siblings like read_browser_tab or download_url. The only slight ambiguity is what 'the tab's file' refers to, but the login-gated-PDF clarification resolves it.

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?

Gives clear context for when to reach for this tool (extracting a PDF that requires authentication) and prescribes the follow-up workflow with read_pdf. It does not explicitly state when-not or contrast against download_url, but the usage context is concrete rather than implied.

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?

readOnlyHint=true is consistent with a capture-only tool, so no contradiction. Beyond the annotation, the description adds genuinely useful behavioral context: the returned image defines the coordinate frame for subsequent click coordinates, which the agent could not derive from structured fields.

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 short, front-loaded sentences with no filler. The action comes first and the critical coordinate-frame caveat follows immediately.

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-param read-only tool with an annotation covering safety, the description supplies purpose and the coordinate relationship. It omits capture scope (full screen vs. active window/tab), which would further sharpen correct invocation, but overall it is sufficient.

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 takes zero parameters and the schema is an empty object, which is the baseline-4 case. There is nothing for the description to clarify about arguments.

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?

"Take a screenshot and look at it" gives a specific verb and resource, and the follow-on sentence clarifies the intent (inspect app state). It does not, however, explicitly differentiate itself from siblings like click or list_browser_tabs, so the agent must infer the boundary.

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?

"Use this to see an app's state, then click what you see" implies the usage context (inspect before clicking), which is helpful sequencing. There is no explicit when-not guidance or named alternative, so the routing is only implied rather than stated.

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?

Annotations already declare readOnlyHint=false and destructiveHint=true; the description adds the reason that matters to an agent — the message reaches a real person and cannot be unsent. That is genuine context beyond the annotation flags, though nothing is said about delivery failure or confirmation behavior.

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 short lines, front-loaded with the action and the risk, then a compact Args block. Every sentence earns its place and nothing is padded.

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 two-parameter mutation tool with no output schema there is little to explain, and the description covers purpose, risk, and both parameters. It could note the expectation after sending (e.g., that delivery is asynchronous or unconfirmed), but 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?

Schema description coverage is 0%, so the description carries the full burden and largely does: it explains that "to" accepts a phone number or Apple ID and how to obtain it, and that "text" is the message body. Naming the accepted identifier formats is the key detail the bare schema lacks.

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?

States a specific verb and resource ("Send an iMessage"), which is precise enough to separate it from compose_email or notify without opening the schema. It does not name a sibling explicitly, so it stops short of the top mark.

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?

Gives actionable routing guidance for the ambiguous case: resolve a name to a handle via find_contact before calling. The irreversibility warning also sets the bar for when to be cautious. It never states when to prefer compose_email or notify instead, so it is clear context without 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?

Annotations already declare this is a write operation that is not destructive (readOnlyHint=false, destructiveHint=false), so the safety profile is covered. The description adds real behavioral context by restricting the hardware scope to the built-in display, but says nothing about persistence, reversibility, or permission requirements.

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

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

One scope sentence followed by a single argument line; everything is front-loaded and nothing is padded. The Args block is slightly redundant with the schema but stays within one line.

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 single-parameter setter with no output schema and annotations covering the safety profile, the description supplies the two things an agent needs most: hardware scope and the valid value range. Only persistence/reversibility behavior is unaddressed.

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

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

Schema description coverage is 0%, so the description must carry the parameter, and it does: 'level' is documented as an integer from 0 (darkest) to 100 (brightest), giving both range and direction. Only the unit (percent) is left implicit, which is a minor gap.

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?

Specific verb (Set) plus specific resource (the built-in display's brightness), with an explicit scope boundary that rules out external monitors. An agent can immediately distinguish it from the sibling get_brightness, which reads rather than writes.

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

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

The description provides one exclusion — external monitors aren't supported — which is genuine when-not guidance, but it never states when to prefer this tool or what an agent should do instead for external displays. Usage is implied rather than fully specified.

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?

Annotations declare readOnlyHint=false and destructiveHint=false, so the agent knows this is a non-destructive write. The description adds little beyond that: it does not say whether existing clipboard contents are overwritten, nor whether the action is silent or confirmed.

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?

Front-loaded one-sentence purpose followed by a compact Args block. The 'ready to paste' clause and the Args repetition are mild padding but nothing is wasted at length.

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, no-output-schema tool this is close to adequate, but it omits the one behavior that matters here: replacing whatever was previously on the clipboard. That gap leaves the agent without key state-change context.

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

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

With one parameter and 0% schema description coverage, the schema carries no meaning beyond the type. The description's 'The text to copy' only loosely restates the parameter name rather than adding format, length, or encoding details.

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?

States a specific verb ('Put') and resource ('text on the clipboard'), which naturally distinguishes it from the sibling get_clipboard. It is clear what the tool does, though it does not explicitly name the read-side 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?

There is no when-to-use guidance, no prerequisites, and no mention of alternatives such as type_text for direct input. Usage is only implied by the phrase 'ready to paste'.

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?

Annotations declare readOnlyHint=false and destructiveHint=false, so the agent knows this is a non-destructive state mutation. The description usefully adds that volume level is preserved, which is a real behavioral trait beyond the annotations, but says nothing about persistence, required permissions, or return behavior.

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 purpose statement is front-loaded and zero-waste. The Args block is functional but reads as restated schema rather than added insight, slightly diluting an otherwise tight definition.

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-boolean, non-destructive toggle with no output schema, the description supplies everything needed to invoke it correctly. Only richer behavioral context (persistence, permissions) is absent, which is minor here.

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

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

Schema description coverage is 0%, so the description must carry the parameter's meaning — and it does, defining both boolean values ('True to mute, False to unmute'). It fully covers the single parameter, though it adds no format or default nuance beyond that.

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?

States a specific verb (mute/unmute) and resource (sound output), and the clause 'without changing the volume level' implicitly distinguishes it from the sibling set_volume. An agent can select this over set_volume without opening a schema.

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?

Usage is only implied: the 'without changing the volume level' clause suggests set_volume is the alternative for volume changes, but neither set_volume nor any when/when-not condition is named. No prerequisites or context are given.

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?

Annotations declare a non-destructive write, and the description adds a genuine behavioral detail beyond them: setting the volume also unmutes, which the agent could not have inferred. It still omits whether the change persists and whether any permission is needed.

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

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

Two short sentences, action and side effect front-loaded, then the parameter meaning. Nothing is wasted and the structure is easy to scan.

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, non-destructive setter with no output schema, the description supplies the action, the side effect, and the value range, which is enough to call it correctly. Only persistence/permission behavior is left unstated.

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

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

Schema description coverage is 0% with no min/max or enum on 'level', so the description carries the burden and does so well by defining the scale as 0 (silent) to 100 (maximum). A single integer parameter is fully explained.

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?

States a specific verb and resource ('Set the output volume') plus a second effect ('unmute'), which distinguishes it from the sibling get_volume. It does not explicitly name the sibling alternatives, but the action is 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?

No guidance on when to use this versus set_mute or get_volume, and no preconditions or exclusions are stated. The agent must infer that this is the mutating counterpart to get_volume.

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?

Annotations already flag destructiveHint=true and readOnlyHint=false, but the description adds concrete, non-obvious impact: turning Wi-Fi off cuts the internet including the agent's own connection. That self-impact warning is genuinely useful context beyond the annotation, though it says nothing about recovery time or failure modes when re-enabling.

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?

Front-loaded with the action and immediately follows with the riskiest consequence. The Args block is slightly redundant in form but necessary given the schema has no parameter descriptions of its own.

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 single-parameter toggle with no output schema, the essential information — what it does, what the param means, and the harmful side effect — is present. It could go further by noting that the caller should verify state with get_wifi or that re-enabling restores connectivity.

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

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

Schema description coverage is 0%, so the description carries the full burden, and it fully compensates: 'True to turn Wi-Fi on, False to turn it off' maps both boolean values to their meaning unambiguously.

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?

States a specific verb and resource ('Turn Wi-Fi on or off') and implicitly covers the full scope of the operation. It does not explicitly distinguish itself from the sibling get_wifi, though the naming makes the read/write split 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?

Usage is implied by describing the two states, and the consequence sentence hints that turning it off is a weighty action. However, there is no explicit guidance on when to prefer this over alternatives such as checking state first with get_wifi before toggling.

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?

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is partly covered. The description adds genuinely useful behavior beyond that: the calling agent stops responding until the lid is opened or a key is pressed, which tells the agent this call effectively ends its ability to act programmatically.

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 short sentences, both load-bearing: the action first, then the consequence and recovery condition. Zero filler 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 parameterless, no-output-schema tool whose destructive nature is already flagged by annotations, the description covers the action and its consequence adequately. It could note that no in-band recovery (e.g., a wake call) exists, but nothing essential is missing 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 tool takes zero parameters, so there is no parameter semantics to document; the baseline for a no-parameter tool is 4. Nothing in the description misleads about inputs.

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 ('Put the whole MacBook to sleep'), and the word 'whole' implicitly contrasts with the sibling sleep_display, which only sleeps the display. It never names that sibling explicitly, so the differentiation is inferable rather than stated.

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?

Usage is only implied: an agent can infer this is the full-machine sleep versus sleep_display from the word 'whole', but there is no explicit when-to-use, when-not, or named alternative. No prerequisites or cautions about invoking it are given.

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?

Annotations already establish this is a non-read-only, non-destructive action, and the description usefully adds that running apps and downloads are unaffected. It does not say how the display is restored or whether any permission is needed, but for a zero-parameter action the added behavioral context is solid.

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 short sentences, front-loaded with the action and followed by the one behavioral fact that matters. Every word earns its place 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?

For a no-argument toggle with no output schema, the description covers the action and its side-effect profile well. A note on how the display is woken (or that it is out of scope) would make it fully self-contained.

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 takes no parameters, so there is no parameter semantics to explain; the baseline of 4 applies. Nothing in the description misleads about inputs.

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?

"Turn the display off" gives a specific verb plus resource, and the second sentence clarifies the scope of the action. It does not explicitly name siblings like sleep_computer or lock_screen, so the agent must infer the distinction, but the action itself is 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?

"Apps and downloads keep running" implies the intended use case (blank the screen without interrupting work), which quietly separates it from sleep_computer. However, no alternative tool is named and no explicit when/when-not condition is stated, leaving the agent to infer the routing.

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?

Annotations declare this is a non-read-only, non-destructive write action, and the description adds the crucial behavioral trait that keystrokes go to whatever is in front, plus that press_return submits the line. It doesn't say whether the tool returns any confirmation or what happens if the target app has no focused input, but the core interaction model is disclosed.

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?

Front-loaded with purpose, then usage guidance, then a compact args list — every element earns its place. Minor redundancy between 'pass app (or focus it first)' in the body and the app arg entry keeps it from being perfectly tight.

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 3-parameter, no-output-schema input tool, the description covers purpose, routing to a sibling, focus behavior, and all parameters. It stops short of describing failure modes or whether any confirmation is returned, which is the only notable 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?

Schema description coverage is 0%, so the description carries the full documentation load, and it does explain all three parameters meaningfully: text as literal text, press_return as post-typing Return/submit, and app as the app to bring forward ('Strongly recommended'). A bit more on app formatting (exact names) would earn a 5, but the semantics are clear.

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?

States a specific verb and resource ('Type text into an app') and immediately scopes the purpose with concrete use cases (document, form, chat box). It also explicitly distinguishes itself from the run_shell sibling, so an agent can route correctly without opening either schema.

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?

Gives explicit when-to-use context (writing into a document, form, or chat box) and an explicit when-not: 'Don't use this to run shell commands; use run_shell, which returns output.' It also states the focus prerequisite for targeting a particular app.

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?

readOnlyHint=true already tells the agent this is a safe non-mutating wait. The description adds one real behavioral detail beyond the annotation: the maximum duration is capped at 10 seconds. It says nothing about whether the wait blocks execution or what it returns, so the added value is modest.

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?

Very short and front-loaded: the purpose clause comes first, then the single parameter with its ceiling. The 'Args:' indented block is slightly awkward for a description but wastes no words.

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

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

For a one-parameter, non-mutating pause tool with readOnlyHint and no output schema, the description covers purpose, the parameter's meaning, and its cap. Nothing an agent needs to invoke this 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?

Schema description coverage is 0%, so the description must carry the parameter meaning — and it does, explaining the parameter is the wait duration and importantly disclosing the upper bound of 10. Unit (seconds) is conveyed by the parameter name, and the cap is the one non-obvious semantic an agent needs.

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?

States a clear verb (pause/wait) and scopes the use case to pages, apps, or downloads that need time to settle. An agent can distinguish this from action siblings like click or open_url, though no sibling is named as an alternative. Purpose is immediately graspable.

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 phrase 'for pages, apps or downloads that need a moment' implies when to reach for this tool, giving useful context. However, there is no explicit when-not guidance and no named alternative, so the routing logic must be inferred.

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