plonk-mcp

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

With no annotations to rely on, the description fully discloses side effects ('copy it to the clipboard', 'show it to the user'), coordinate origin ('origin TOP-LEFT'), and return behavior ('Returns the marked image'). It also warns about the need to actually view the screenshot, preventing common agent missteps.

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 dense but every sentence contributes valuable guidance, from the workflow note to the coordinate example. The example is somewhat lengthy, but it directly addresses a common source of errors and is worth the space.

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

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

Given the complexity of the tool and no output schema, the description covers all necessary aspects: prerequisite workflow, coordinate system, shape-specific semantics, and return value. It does not mention error handling or edge cases, but those are less critical for this tool.

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

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

The schema only briefly documents 'output' and 'clipboard'; the description adds critical semantics for 'marks', including point order for each shape type and a concrete coordinate example. This transforms an otherwise opaque parameter array into a usable specification.

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

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

The description clearly states 'Draw on a screenshot you already took, then copy it to the clipboard and show it to the user', specifying the exact verb, resource, and side effects. It distinguishes itself from siblings like 'take_screenshot' by operating on an existing screenshot and producing annotated output.

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 instructs 'Call take_screenshot first', establishing a clear prerequisite workflow. It also details coordinate semantics and shape-specific point order, implying when to use this tool. While it doesn't list alternative tools, the context is clear enough to avoid misuse.

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

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

With no annotations, the description carries the full burden. It discloses that windows are unminimized, app matching is fuzzy, and returns per-item success/errors. It also specifies coordinate origin and fraction semantics. However, it doesn't mention side effects on existing layouts or persistence, but the provided details are substantial.

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

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

The description is a single dense paragraph packed with useful information. It lacks visual structure like bullet points, but every sentence contributes value. While it could be better organized, it is not verbose or redundant.

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

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

The description covers the core behavior, return value indication, and multi-screen support. It doesn't mention edge cases or failure handling beyond per-item errors, but given the complexity and lack of output schema, it is quite complete. It also distinguishes from related tools indirectly.

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 description enriches parameter understanding beyond the schema: 'app' is fuzzy matched, 'screen' defaults to current screen and comes from get_state, 'frame' uses fractions with top-left origin and provides concrete examples. This adds significant meaning beyond the schema's simple descriptions.

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

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

The description clearly states the tool's purpose: 'Move and resize windows to build a layout.' This is a specific verb+resource that distinguishes it from siblings like snap_window (single window) and apply_saved_layout (predefined layout). The description also explicitly mentions multi-screen support, further clarifying scope.

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

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

The description explains how to use the tool via the 'items' array and parameter details, but it does not explicitly state when to use this tool versus alternatives. It doesn't contrast with apply_saved_layout or snap_window, leaving usage context 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?

No annotations are provided, so the description fully carries the burden. It discloses the macOS limitation (windows appear then jump), the return of per-app success, and the timeout for large workspaces. This is comprehensive behavioral information beyond the schema.

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

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

The description is longer than necessary but every sentence adds value: purpose, legacy note, behavior, platform quirk, return info, and latency. It is front-loaded with the primary action and remains structured, though slightly verbose.

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

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

For a simple tool with one parameter and no annotations or output schema, the description covers all essential aspects: what it does, how it behaves, what it returns, performance caveats, and sibling differentiation. It is complete for effective selection and 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?

With only one string parameter and zero schema description coverage, the description explains 'by name' to indicate the parameter refers to the saved workspace name. It could add format specifics (e.g., exact matching), but the meaning is clear enough.

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

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

The description clearly states the tool launches a saved workspace by name, and distinguishes it from the successor launch_workspace, which adds a screen option. It uses a specific verb and resource, providing a clear, unambiguous purpose.

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 instructs new integrations to use launch_workspace instead, giving clear guidance on when not to use this tool. It also describes the behavior of opening apps and waiting for windows, informing usage expectations.

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

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

With no annotations, the description carries the full burden and does so thoroughly. It discloses that assigning replaces the monitor's previous assignment, takes effect on the next drag, and that omitting the name restores the default set. It also clarifies the 'edge' special value and where to discover valid set names.

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

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

The description is concise and front-loaded with the primary purpose. Each of the four sentences contributes essential information: purpose, replacement/effect timing, parameter special cases, and where to find supported values. No redundant text or filler.

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

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

Given the tool's simplicity, two parameters, and no output schema, the description is complete. It covers purpose, side effects, timing, default behavior, special values, and a pointer to get_state for supported names and current assignments. No major behavioral gap remains.

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

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

The input schema already documents both parameters, giving baseline 3. The description adds value by naming the default set ('Halves'), explaining per-monitor assignment semantics, and directing users to get_state for valid names, which goes beyond the schema's basic parameter definitions.

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

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

The description clearly states the verb and resource: assigning a zone set to a monitor. It differentiates the tool by explaining per-monitor assignments, replacement behavior, and special 'edge' and default-set handling, which distinguishes it from sibling tools like apply_layout.

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

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

The description provides clear context on when to use this tool: to assign a zone set to one monitor, with effect on next drag. It also explains optional behavior (omit name, pass 'edge') and points to get_state for available names, though it does not explicitly contrast with alternative sibling tools.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It reveals that the check is a network round trip, returns immediately with the current state, and the final result arrives asynchronously via get_state's 'update' key or an 'update' event. It also documents the 409 failure mode when update checks are disabled, and explains the meaning of the return fields. No annotation contradiction exists.

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 long (around 250 words) but information-dense and front-loaded, starting with purpose, then usage, then behavior, then return format. Every sentence adds context relevant to an agent's decision. While somewhat lengthy, the absence of annotations and output schema justifies the extra detail.

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 fully covers the tool's behavior, return values, asynchronous nature, failure mode, and relationship to sibling tools. Since there is no output schema, it explains the exact return fields and their semantics. It also tells the agent how to read the result later via get_state or an event, making it complete for practical use.

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

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

The tool has zero parameters and the schema is empty, so schema coverage is effectively 100%. The description does not need to explain parameters; the baseline of 4 applies because there is nothing to add. It does, however, describe the return object, which is useful given no output schema.

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

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

The description clearly states the tool's function: 'Ask Plonk whether a newer release exists, and report what is installed.' It uses a specific verb and resource, and distinguishes itself from the sibling tool install_update by noting it is a pre-check and that install_update refuses unless a newer release is already available.

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?

Explicit usage guidance is provided: 'Use this when the user asks what version they run, whether Plonk is up to date, or before calling install_update.' It also gives an exclusion: if update checks are off, it fails with 409 and the agent should report back instead of retrying. This clearly outlines when to use this tool versus alternatives like get_state.

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?

There are no annotations, so the description carries the burden. It explicitly says it deletes saved workspaces, which conveys destructive nature. It also mentions it deletes both layouts and workspaces saved by different tools. However, it doesn't describe error handling or permissions, so a 4 seems 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?

The description is three sentences long, front-loaded with the core action, and every sentence adds value: action, legacy context, and usage guidance. No redundancy or filler.

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

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

Given the tool's simplicity (one required parameter, no output schema, no annotations), the description provides sufficient context: what it does, when to use it, where to find names, and an alternative. It doesn't explain return values or error behavior, but such details are less critical for a straightforward delete 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?

With 0% schema_description_coverage, the description compensates by explaining that the 'name' parameter refers to a saved workspace and that existing names can be found via get_state. This adds semantic meaning beyond the schema's bare 'name' 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?

The description explicitly states 'Delete the saved workspace with that name', which clearly defines the action and object. It also clarifies the scope by mentioning both save_layout and save_workspace, leaving no ambiguity.

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

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

It provides usage guidance: 'Use it to clean up saved workspaces that are no longer wanted' and points to get_state for existing names. It also gives an alternative for new integrations (delete_workspace), which helps decision-making.

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

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

With no annotations, the description must convey behavioral traits. It only states the action without mentioning irreversibility, side effects on associated data, permissions required, or any confirmation steps. The user is left unaware of potential destructive consequences beyond the simple delete.

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

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

The description is two sentences long, direct, and without unnecessary details. It effectively conveys the essential 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 simple delete operation, the description covers the primary purpose and appropriate usage. It lacks explicit mention of irreversibility or what happens to the workspace's contents, but given the absence of an output schema and the tool's simplicity, it is reasonably complete.

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

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

The schema shows a single 'name' string parameter. The description adds that deletion is 'by name', but does not clarify whether this is the display name, a unique identifier, or if there are any validation rules. It offers minimal additional meaning beyond the schema.

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

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

The description clearly states the action ('Delete a saved workspace by name') and distinguishes it from other delete tools by specifying 'workspace'. It is specific and unambiguous.

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

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

It provides a clear usage context: 'Use this to clean up workspaces you created that are no longer wanted.' This implies when to use it, though it does not explicitly mention alternatives or when not to use 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?

With no annotations provided, the description carries the full transparency burden. It discloses that deletion is immediate and irreversible, that monitors fall back to the default set (Halves), and that built-ins are refused. These are crucial behavioral traits for a destructive operation.

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

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

The description is three concise sentences, each serving a distinct purpose: action+fallback, scope, and irreversibility+alternative. There is no fluff, and the most important information is front-loaded.

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

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

For a simple one-parameter delete tool with no output schema, the description covers all necessary aspects: what it does, side effects, constraints, and when to use an alternative. It is complete enough for an agent to invoke correctly without ambiguity.

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

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

The schema already covers the parameter (100% coverage) with 'Saved zone set name, as shown in get_state'. The description adds the critical constraint that only sets made with save_zone_set are valid, and that built-ins are excluded, going beyond the schema. It provides meaningful semantic enrichment.

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

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

The description clearly states the tool deletes a saved zone set by name, specifies it only applies to user-saved sets (not built-ins), and distinguishes it from assign_zone_set. The verb 'delete' and resource 'zone set' are explicit, and the scope is well-defined.

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 clear guidance on when to use the tool (to delete a set) and when not to use it: 'use assign_zone_set instead when a monitor should merely stop using a set that others still need.' This explicit alternative makes the usage context highly actionable.

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

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

With no annotations provided, the description carries the full burden and does so thoroughly. It discloses local-only processing ('nothing is uploaded'), interactive mode behavior with a five-minute wait, clipboard copying, the returned text and lines structure with confidence and boxes, coordinate-space compatibility with annotate_screenshot, and the ok-with-empty-text behavior for areas with no readable text.

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 dense but well-organized, front-loading the core purpose and usage guidance before diving into mode specifics and return values. Every sentence adds useful information, and nothing is 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?

Despite having no output schema and no annotations, the description sufficiently explains return values ('text' and 'lines' with confidence and boxes), coordinate conventions, clipboard side effects, interaction timing, and empty-result behavior. For a tool of this complexity, this is complete enough for an agent to invoke it correctly and interpret results.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful behavioral context beyond the schema: mode screen needs no user interaction, region/window open a native picker and wait up to five minutes, path can be supplied by take_screenshot, and clipboard defaults to true. It does not add material language-parameter semantics, but the schema already covers those fully.

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

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

The description opens with a specific verb and resource: 'Read the words off the screen, or off a saved image, and return them as text.' It explicitly distinguishes this tool from take_screenshot, making its unique role clear even alongside 22 sibling tools.

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

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

The description gives explicit when-to-use guidance: 'Prefer this over take_screenshot whenever the answer is words rather than a picture' and lists concrete cases like error dialogs, logs, terminals, and PDFs. It also names the exact alternative for visual questions: 'Use take_screenshot instead when layout, colour or what does this look like is the question.'

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

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

No annotations are provided, so description carries full burden. It discloses coordinate origin and y-axis direction, fraction semantics (0..1 of visible area), and the behavioral consequence of disabled_features (tools fail with an error until re-enabled). This is far beyond minimal and anticipates agent confusion.

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 long but every clause adds needed information given the complexity of the return state. It is front-loaded with the main purpose and uses parenthetical explanations effectively. Slightly dense but not 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?

There is no output schema, so the description must fully explain return values. It covers screens/monitors, windows, layout names, keep-awake, and disabled_features, and even clarifies coordinate system and fraction semantics. Given complexity, this is complete and self-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?

Tool has zero parameters, and schema is empty, so the description needs no parameter details. Baseline for 0 params is 4; the description properly focuses on the rich return state instead.

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?

Clear verb+object: 'Get the current desktop state' with explicit enumeration of contents (screens, windows, layouts, keep-awake, disabled_features). Distinct from siblings like apply_layout or save_workspace, which are actions; this is a read-only state retrieval.

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 states 'ALWAYS call this first before applying a layout' and explains why: to see which apps are running and how many monitors there are. Also warns that disabled features cause tool failures, so calling this first reveals that context. Provides actionable when-to-use guidance.

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

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

With no annotations, the description fully shoulders the burden. It discloses side effects (quits app, stops window arrangement, API unreachable), failure conditions (no release, 409, signature mismatch, write permissions), and the signature check preserving Accessibility/Screen Recording grants. No annotation contradiction present.

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 long but every sentence adds necessary context: action, rationale, side effects, failure modes, return value. It is front-loaded with the main action and remains organized despite its density.

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

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

Given no annotations and no output schema, the description covers prerequisites, side effects, failure conditions, and return shape. It is fully self-contained for an agent to safely invoke the tool.

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

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

The tool has zero parameters, so the baseline is 4. The description adds no parameter details because none exist, and the schema coverage is trivially complete. There is nothing missing that the description should compensate for.

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

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

The description states a specific action ('Install the release that check_for_update found') with a clear resource and distinguishing detail. It differentiates from siblings like check_for_update by describing the full installation sequence.

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 provides when-to-use guidance: 'Prefer this over telling the user to download a build by hand' and instructs to 'Ask the user before calling it.' It also names prerequisites (call check_for_update first) and alternatives, making usage context clear.

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

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

With no annotations, the description fully discloses side effects (opening apps), the macOS quirk (windows jump into place), the per-app success reporting, and the up-to-a-minute wait time for large workspaces.

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 detailed yet efficient, with each sentence contributing unique information (launching, positioning, macOS limitation, return values, timing). No redundant or verbose content.

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

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

The description covers the entire behavior: what it does, how it handles limitations, what it returns (per-app success and failure reports), and the expected duration. This gives the agent full context to decide on invocation and interpret results.

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

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

The schema provides type and description for 'screen', but 'name' lacked a description. The tool description's reference to 'saved workspace' gives enough context to infer that 'name' identifies the workspace to launch, adding semantic value beyond the raw schema.

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

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

The description clearly states the tool's purpose: launching a saved workspace by opening non-running apps, waiting for windows, and positioning them. It distinguishes from similar tools like apply_saved_layout by explicitly mentioning app launching.

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 strong usage context, including macOS limitations and timing expectations. It implies when to use this tool (to restore a workspace with apps), though it does not explicitly compare with alternative tools.

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

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

No annotations are provided, so the description carries full burden. It discloses that the tool takes a still at call start (so animating screens are measured as of that moment), requires macOS Screen Recording permission and fails without it, returns two independent runs not an outline, and explains edge detection behavior (tolerance, large flat backgrounds). It also notes the interactive mode waits up to five minutes. This is comprehensive behavioral disclosure.

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 long but every sentence adds value. It is front-loaded with the core purpose, then usage guidance, then behavioral details, then parameter semantics. While it could be slightly more concise, the density of useful information justifies the length. No filler or repetition.

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

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

Given the tool's complexity (6 parameters, 3 modes, nested objects, no output schema), the description is remarkably complete. It explains the return structure (points, pixels, fraction, scale, text, distance), the difference between points and pixels on Retina, the coordinate system, edge detection behavior, permission requirements, and timing semantics. It also covers all three usage modes and their appropriate contexts. The absence of an output schema makes this description essential, and it delivers.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds significant value beyond the schema: it explains the coordinate system (fractions 0..1, origin top-left, same as apply_layout), the meaning of 'point' vs 'from'/'to' vs 'interactive', and the tolerance parameter's effect (lower stops at fainter borders, raise for photos/videos). It also clarifies the 'screen' parameter's default and relationship to get_state. This exceeds the baseline.

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

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

The description clearly states the tool measures screen dimensions in points and pixels without taking a picture, and explicitly distinguishes it from take_screenshot and extract_text. It specifies the verb (measure), resource (screen), and scope (runs from a point in four directions), making it distinct from 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?

The description provides explicit when-to-use guidance: 'Prefer this over take_screenshot whenever the answer is a number' and names alternatives: 'Use extract_text when the answer is words, and take_screenshot when it is what does this look like'. It also explains the three modes (point, from/to, interactive) and when to use each, including the interactive mode for user judgment.

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

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

With no annotations, the description discloses key behaviors: overwriting existing workspaces ('Saving over an existing name replaces it') and that saved workspaces appear in get_state. It hints at legacy status but does not discuss potential side effects like requiring certain permissions or error handling. This is sufficient for a save operation 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?

All four sentences are packed with unique, actionable content. Opens with purpose, then usage, then behavior, then post-save information. No redundancy or filler.

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

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

For a tool with just two parameters and no output schema, the description covers purpose, alternatives, parameter semantics, overwrite behavior, and downstream discovery via get_state. It is self-contained and requires no further clarification.

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?

Adds critical meaning beyond schema: explains that omitting 'items' snapshots current screen state, while passing 'items' explicitly describes the arrangement. Also clarifies that overwriting happens, which is not in schema. The schema only names parameters; the description enriches the 'items' semantics significantly.

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?

Clear verb+resource: 'save the named window arrangement as a workspace'. Explicitly distinguishes itself from save_workspace by labeling itself as legacy and pointing to the alternative, which removes ambiguity.

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

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

Directly states when to use save_workspace instead ('new integrations should call save_workspace') and explains the difference ('can also record whether running apps get moved into place'). Also gives a clear use-case distinction for omitting vs passing 'items' to control snapshot vs explicit arrangement.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It transparently states that saving over an existing name replaces it, and that omitting 'items' snapshots the current windows. It also links to get_state for listing saved workspaces. Although it doesn't mention permissions or irreversible side effects beyond replacement, it covers the essential mutating behavior adequately.

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

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

The description is concise and front-loaded with the purpose, followed by usage modes and key behaviors. It consists of four focused sentences without any fluff or redundancy. Every sentence adds value: definition, usage modes, overwriting behavior, and discoverability via get_state. This is an exemplary level of conciseness.

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

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

Given the complexity of the items structure and the lack of an output schema, the description covers the essential concepts: what a workspace is, how to specify it or snapshot it, replacement behavior, and where it appears in get_state. It does not detail error conditions or all sub-properties, but the schema handles those. The description is complete enough for an agent to confidently invoke this tool.

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 description adds meaning to the 'items' parameter by clarifying its purpose ('Pass items to describe the arrangement') and the alternative of omitting it, which is not fully evident from the schema alone. It does not explicitly discuss 'move_existing', but the schema provides a clear description for that parameter. With schema coverage at 67%, the description compensates for the missing top-level items description, making parameter semantics effective.

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

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

The description clearly states the tool's purpose: 'Save a workspace' with a detailed definition of what a workspace includes (apps, window placement, and content to open). It effectively distinguishes this from sibling save tools like save_layout and save_zone_set by specifying the resource and scope. The verb 'save' combined with the resource 'workspace' is specific and unambiguous.

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

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

The description explains when to use the tool and provides two usage modes: passing 'items' to describe the arrangement or omitting them to snapshot the current screen. It also mentions overwriting behavior. While it doesn't explicitly list alternatives or when-not-to-use, the context is clear enough given the sibling set, so it earns a solid score.

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 thoroughly discloses behavior: creation vs replacement, zone constraints (inside screen, overlap allowed), active assignment via screen, gap semantics (own vs default), and existence of built-in sets. No annotations were provided, so the description bears full responsibility, and it meets that responsibility well.

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

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

The description is concise, well-organized, and free of fluff. It progresses logically from purpose to zone definition to parameter special cases, covering all essential points without wordiness.

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

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

The description is complete for its complexity: it covers purpose, parameters, behaviors, and edge cases. No output schema is present, so no return documentation is needed. It provides sufficient context for an agent to use the tool correctly.

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

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

The description adds substantial meaning beyond the schema. It explains the zone coordinate system and overlap rule, clarifies the special meaning of 'screen' (assign and activate) and 'gap' (set or follow default, and omission behavior). This is far more informative than the schema's brief descriptions.

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

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

The description clearly states the tool's function: 'Create or replace a named zone set used for drag snapping.' It distinguishes from sibling tools by focusing on zone sets and provides details about zone coordinates, which is specific and unambiguous.

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

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

The description explains when to use the tool implicitly by outlining its purpose (create or replace) and describes special parameter behaviors (screen, gap). It does not explicitly contrast with sibling tools like assign_zone_set, but the name and content make the use case clear enough for an agent to decide.

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

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

With no annotations, the description carries the full burden. It discloses key side effects: the active agent shows in menu bar/settings, outgoing requests go there, and with exclusive mode other agents cannot change window/settings but can still read state and take screenshots. This is good transparency, though it doesn't explicitly state the default behavior when exclusive is false, which is slightly implied.

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

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

The description is three sentences, each serving a purpose: the first states the core function, the second explains agent selection and its visual impact, and the third covers the exclusive option and a way to discover agents. It is front-loaded with the main verb and resource, and every sentence adds value with no fluff.

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

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

For a two-parameter tool with no output schema and no annotations, the description is remarkably complete. It covers all parameter behaviors, the user-visible effects, the exclusive mode restrictions, and where to find valid agent names. There are no significant gaps for an agent to misuse this tool.

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

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

Although the schema already describes both parameters, the description enriches them significantly: it explains the three legal values for 'name' (specific agent, omit, empty string) and the nuanced effect of 'exclusive' (rejects changes from others, but allows reads/screenshots). This goes beyond the schema's simple field descriptions.

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

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

The description clearly states the tool's purpose: 'Make an agent the user's active one in Plonk.' It specifies the verb 'make' and the resource 'active agent', and differentiates from siblings like set_active by explaining the unique semantics of selecting, clearing, and exclusive mode.

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 usage patterns: omitting 'name' selects the client itself, passing an empty string clears the choice, and 'exclusive' true adds extra restrictions. It also directs users to get_state to list agents, which is a helpful pointer. This is clear enough for an agent to know when and how to use 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?

With no annotations provided, the description carries the full burden and does so thoroughly. It discloses the mechanism (Shift keypress every two minutes), the impact on idle time and sleep, that it only starts and ends sessions, the schedule override behavior, and that certain conditions (no Accessibility permission, battery restrictions) are not reported as errors but surfaced via 'active' and 'status'. This level of transparency is exceptional.

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?

Although lengthy, every sentence adds value: purpose, distinction, mechanism, duration options, edge cases, and return values are all covered without redundancy. The structure is logical, front-loaded with the core purpose, and efficiently uses paragraphs to group related concepts.

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

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

Given 3 parameters, no output schema, and no annotations, the description is remarkably complete. It explains all parameters, return values ('active' and 'status'), error handling (non-error conditions), interaction with the schedule, and the relationship with set_awake. Nothing essential is omitted for an agent to correctly invoke and interpret the tool.

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 description adds significant meaning beyond the schema. It explains 'until' with examples ('17:00', ISO-8601 timestamp) and clarifies that it ends at the next such moment, defines 'minutes' as a countdown, and explains the 'neither' case (runs until switched off or default timeout). This enriches the schema where the 'on' parameter has no description.

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

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

The description clearly states the tool's purpose: 'Turn stay-active on or off, so chat apps go on showing the user as available instead of Away.' It distinguishes itself from sibling set_awake by explaining the mechanism (posting a Shift keypress every two minutes) and why it's the correct choice for chat app status, making the purpose specific and unambiguous.

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

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

Explicitly tells when to use this tool over set_awake ('Pick this over set_awake by what is being protected') and explains the relationship between them ('stay-active implies keep-awake and there is no need to turn both on'). It also provides clear guidelines on choosing duration parameters ('until' vs 'minutes') and states the default behavior when neither 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?

With no annotations provided, the description carries the full burden and does so thoroughly: it discloses that user settings may pause or auto-enable keep-awake, that the returned 'status' reflects reality, that the menu bar icon glows, that process-bound sessions are not restored after restart, and that errors occur for invalid pids or past times.

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 substantial but every sentence earns its place: purpose, end-condition modes, external settings, return semantics, restart behavior, and error cases. It is front-loaded with the core purpose and then logically organized.

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

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

Given the tool has moderate complexity, no annotations, and no output schema, the description covers all essential context: what the tool does, how each parameter behaves, what the response fields mean, and what error cases exist. It is sufficient for an agent to select and invoke the tool correctly.

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

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

The description adds meaningful semantics beyond the schema, such as the preference ordering among pid/until/minutes, the 'best by far' guidance for running jobs, and the caveat about process-bound sessions not surviving restart. The schema descriptions are good, but the tool description enriches their practical meaning.

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

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

The description opens with a specific verb+resource: 'Turn keep-awake on or off, so the Mac does not sleep part-way through something.' This clearly distinguishes set_awake from sibling tools like get_state, set_active, or workspace/layout 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?

It gives explicit when-to-use guidance by ranking the three end conditions in order of preference and explaining that 'pid' is 'best by far when something is running.' It also states the behavior when none are given, which covers the full usage space.

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

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

With no annotations, the description must convey safety and side effects. It implicitly indicates a move/drop operation and clarifies zone numbering semantics (e.g., middle of three is 2) and where to find zone assignments (get_state). It does not explicitly state whether the operation is reversible or requires permissions, but for a window manager action, the description is sufficiently transparent about the effect on the window's position. A 4 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?

Two sentences, highly efficient. The first sentence states the core function, the second clarifies numbering and directs to alternatives. No wasted 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?

Given the tool has 4 params (all documented in schema), no output schema, and no annotations, the description covers the essential behavioral context: how zone numbers work, where to get zone sets (get_state), and when to use apply_layout instead. It could mention return behavior, but that's often unnecessary for manipulative tools. The description is complete enough for an agent to select and invoke it correctly.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds meaningful context beyond the schema: it explains how zone numbers are derived (from the drag overlay) and clarifies the relationship between the 'screen' parameter and window location. This enriches parameter understanding, justifying a 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?

The description clearly states the action (drop a window into a zone) and the resource (numbered zone of the snap-zone set on a monitor). It distinguishes itself from sibling tools by explicitly mentioning apply_layout for size-based layouts. This is specific and unambiguous.

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

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

It provides explicit guidance on when to use this tool (when user refers to a zone number) and when not to (use apply_layout for size descriptions). It also references get_state for zone set configuration, giving clear context. This meets the highest bar for usage 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?

The description clearly states that mode 'app' works even when the window is behind others (minimized excepted) without raising it or taking focus, while 'region' and 'window' require user interaction. It also reveals the returned image is scaled down while the file keeps full resolution — useful details not visible from schema or annotations. Missing a small amount of detail about clipboard/editor side effects, but for a screenshot tool this is strong disclosure.

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

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

The description is a paragraph but every sentence earns its place. It front-loads the core action and then advances through modes, preferences, annotation flow, path handling, and resolution behavior without fluff.

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

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

Given the tool is action-oriented with no output schema and a rich set of 7 parameters, the description covers when to use each mode, how to feed the capture into annotate_screenshot, the practical distinction between scaled image and original file, and explicit choice support for real agent scenarios.

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

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

The schema already explains enum values, so the description adds meaning where schema is thin: it clarifies the interaction behavior for each mode, how 'app' and 'title_contains' interplay, and what annotate/path/clipboard do beyond their one-line schema descriptions. With 86% schema coverage, the description goes beyond baseline 3 rather than merely repeating schema.

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

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

The description names the verb ('Capture the screen and return the image') and specifies four distinct modes with concrete behaviors. It clearly distinguishes the tool from siblings like annotate_screenshot and extract_text by explaining when the capture is returned versus handed to the drawing editor.

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

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

The description gives explicit guidance: prefer mode 'app' when the user asks about a particular program, and use annotate=true when the user wants to mark the shot themselves. This creates a clear decision tree rather than just listing features.

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