NoMac

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

Annotations only flag destructiveHint=true and idempotentHint=false; the description goes well beyond them by disclosing the exact escalation (SIGTERM, a one-second grace, then SIGKILL), the resulting state (exited/cancelled), that partial output remains readable, and the no-op case for an already-finished command.

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 zero filler, and the most decision-relevant fact (what gets killed and how) 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?

With no output schema, the description compensates by describing the return state ('comes back exited with reason cancelled', 'cancelled: false'), and it covers the destruction semantics an agent needs before firing a destructive call.

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 job_id and session_id are already fully documented in the schema; the description adds no further parameter meaning (e.g., session scoping rules). Baseline 3 applies when the schema carries the load.

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 ('Stops a running command and everything it started') and scopes the blast radius to the process tree, which clearly separates it from exec_mac and get_mac_job among the 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 concrete when-to-use conditions: 'For a hung build, an endless test run or a server no longer needed.' It does not name an alternative tool or state when not to cancel, but the trigger scenarios are clear enough to route the agent.

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, openWorldHint and non-idempotency. The description adds genuinely useful behavior beyond them: the 2 GiB cap and, importantly, that a url is a public page anyone with the link can use with no account, plus that download links survive the Mac stopping. It omits permission requirements and link revocation 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 core purpose is front-loaded, but the body is a dense semicolon-chained run-on that interleaves return values (url, upload_command, download_url) with parameter behavior, making it harder to parse than it needs to be.

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 compensates by explaining the return fields for both directions (url/upload_command, url/download_url) and the key caveats (size cap, public access, persistence). This is nearly complete, missing only permission and revocation details.

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 every parameter is already documented in the schema. The description restates direction and extract effects but adds little beyond that; baseline 3 is appropriate when the schema carries the load.

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 ("Makes a link for one file") and adds a concrete scope limit (up to 2 GiB). It cleanly explains the two directions, though it never names a sibling such as get_mac_file_link to distinguish creating a link from retrieving one.

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 upload/download explanations imply which mode fits a given need, and the persistence note ("working after the Mac stops") hints at long-running retrieval. However, there is no explicit when-to-use vs when-not, and no pointer to alternatives like get_mac_file_link or write_mac_file.

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?

Beyond the annotations (destructiveHint, openWorldHint, idempotentHint=false), the description discloses output truncation (first 64 KiB each of stdout/stderr), the 64 KiB command cap, job continuation semantics, and that the same request_key+arguments return the same job rather than a second run. This is rich behavioral context an agent needs to invoke it safely.

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 action is front-loaded and each sentence carries distinct information (timeout behavior, job fallback, shell syntax, size limits, idempotency, process lifetime). It is dense but none of the content is redundant, though the final sentence takes a second read to parse.

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

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

For a complex 6-parameter tool with no output schema, the description covers what returns on success (exit_code, stdout, stderr), what happens when it doesn't finish (a job retrieved via get_mac_job), the size limits, and idempotency. Nothing essential to calling it correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents all six parameters with defaults, ranges and formats. The description reinforces wait_seconds behavior and request_key idempotency but adds little per-parameter detail beyond what the schema already states, making the baseline 3 appropriate.

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

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

The first sentence states a specific verb and resource: 'Runs an argv command on the Mac as the agent user.' It also distinguishes the tool from siblings by naming get_mac_job for commands that outlive the wait window, so an agent can tell exec_mac apart from job-retrieval tools 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?

It gives concrete when-to-use guidance: wait_seconds default/max, get_mac_job for longer commands, ['/bin/bash', '-lc', '...'] for shell syntax, and the nomac-service pattern for long-running servers. Context is clear, though it doesn't state explicit exclusions (e.g. when to prefer write_mac_file over running a command).

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 non-destructive, non-idempotent write (readOnlyHint=false, destructiveHint=false, idempotentHint=false). The description adds real behavioral value beyond that: it clarifies no credit is added, that the spend cap moves with the time limit, and that the Mac bills $0.80/hour while running. It does not describe failure modes (e.g., extending a Mac that isn't running).

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?

Dense but front-loaded: the core action leads and the cost caveat trails. The colon-separated clause list is slightly run-on, but every clause (default, cap, cost) 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?

With only two fully-documented parameters and no output schema, the definition covers what an agent needs to invoke it, including cost implications. It omits what happens if the Mac is not running or what the response returns, which are minor given the simple surface.

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 both parameters are already fully documented, including defaults, bounds (1-480), and the ses_ pattern. The description restates the default of 60 and the 8-hour ceiling but adds no syntax or semantics 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?

States a precise verb+resource+effect: it raises a running Mac's time limit by minutes and raises the spend cap with it. An agent can distinguish this from siblings like start_mac, stop_mac, or get_mac_session 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 concrete triggering conditions: a stop_notice at the time limit or spend cap, or a build that needs longer. It does not explicitly name an alternative tool or a when-not-to-use case, but the usage context is clear.

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

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

Goes well beyond the annotations by disclosing that the tool never charges anything itself, that credit comes in $10 packs (12.5 hours), never expires, and earns bonus credit at higher tiers, plus that the response 'says what to suggest'. The keyed idempotency statement ('the same request_key returns the same checkout') sits in mild tension with idempotentHint=false, though the description's 'a new key is new work' framing explains 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?

Front-loads the core action and side-effect disclaimer in the first clause, then packs constraints, pricing, and idempotency into a dense but readable single block. Slightly overstuffed — the pricing/tier detail is close to surplus for tool selection — 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?

For a 2-parameter tool with no output schema, it covers the action, the side-effect boundary, the pricing model, idempotency, and hints at the response content ('the answer says what to suggest'). Remaining gaps are minor, e.g. checkout link lifetime or whether human presence is required.

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 both parameters are already documented and the baseline is 3. The description adds only marginal meaning over the schema (hours-per-pack and bonus context for 'packs'), while request_key semantics largely restate 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?

States a concrete verb and resource: it 'Creates a checkout link for prepaid Mac credit', which usefully corrects the misleading 'get_' name and clarifies it 'never charges anything itself.' It does not explicitly name or route against siblings such as get_mac_credits or create_mac_link, 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?

Gives clear context for use: the link is 'for the human to open and pay in their browser', and it explains the purchase shape (1-10 packs per purchase). There are no exclusions or named alternatives, e.g. what to call when the human just wants to see an existing balance.

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 and destructiveHint=false, so the trailing 'Read-only' adds no credit. However, the description goes beyond them by disclosing the conditional low_credit field with purchase guidance when under an hour remains, plus the set of returned fields in the absence of an 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?

Two dense but front-loaded sentences: the primary return payload comes first, the conditional low_credit behavior second, and the trailing 'Read-only' is the only expendable clause. 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?

With no output schema, the description carries the full burden of describing return values and does so thoroughly (spendable dollars, spendable_seconds and its meaning, held amounts, pricing, recent purchases, first_purchase, conditional low_credit). An agent knows exactly what to expect from a call.

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 schema imposes no burden and the baseline is 4. There is nothing further the description could meaningfully add on this dimension.

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 ('Returns the prepaid Mac credit') and enumerates the concrete contents of that resource (spendable dollars, spendable_seconds, held amounts, pricing, purchases). This clearly separates it from siblings like get_mac_checkout, get_mac_job, and get_mac_session.

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 balance-check tool, and the 'under an hour left' clause hints at a pre-flight check before exec_mac or start_mac. But no explicit when-to-use, prerequisites, or named alternatives 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 declare readOnlyHint=false, destructiveHint=true and idempotentHint=false, so the safety profile is partly covered; the description still earns credit by disclosing the concrete side effect (the arrived upload is moved onto the Mac by this call), the blocking wait with a bound, and the full state machine. One caveat: 'Safe to repeat' sits in mild tension with idempotentHint=false, although retry-safety is not strictly the same property as idempotency, so this is not a direct contradiction.

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

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

Three sentences, zero filler, and front-loaded: purpose and state list first, then the side effect and wait behavior, then the retry note. The state enumeration is long but carries real routing information, so it earns its 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?

There is no output schema, and the description compensates by enumerating the possible return states, plus explaining the side effect and the blocking wait. It omits auth requirements and error behavior for failed/expired links, but for a two-parameter polling call it is essentially 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?

Schema description coverage is 100%, so both parameters are already fully documented (link url/download_url; wait_seconds 0-50, default 20). The description's 'by its url' and its restatement of the wait bound/default add no semantics beyond the schema, so the baseline of 3 applies.

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

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

States a specific verb+resource+key ('Returns a file link's state by its url') and then enumerates the exact state values, which is more informative than a restatement of the name. It is clearly distinguishable from siblings such as create_mac_link, read_mac_file or get_mac_job by resource, though it never names an alternative 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?

Usage is implied rather than stated: the agent can infer this is the polling/placement call because it says an arrived upload 'is moved onto the Mac by this call' and blocks for wait_seconds. There is no explicit when-to-use, when-not, or routing to a sibling (e.g. read_mac_file once ready), so it stays 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 already declare readOnlyHint=true and destructiveHint=false. The description adds real behavioral context beyond that: 64 KiB truncation per stream, a cursor returned when more data follows, the 40s wait cap, and the guarantee it will not re-run the command. It omits details like ordering/consistency of stream reads, keeping it short of 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?

Dense but front-loaded: state/exit code/streams come first, then the cursor and wait mechanics, then the read-only guarantee. Every sentence carries distinct information with no padding.

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

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

No output schema exists, so the description correctly explains what is returned (state, exit code, stdout/stderr, cursor). Combined with the annotations covering the safety profile and the 100% schema coverage, an agent has everything needed to call 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 coverage is 100%, so all five parameters are already documented in the schema. The description reinforces cursor/stream/wait_seconds behavior and adds the nuance that streaming works 'also while it runs,' but adds little beyond the schema's own parameter text. Baseline 3 applies.

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

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

States a specific verb and resource: returns a command's state (running, exited, failed), exit code, and stdout/stderr. An agent can immediately distinguish it from exec_mac (which runs commands) because the description explicitly says it never runs the command again.

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?

Explains the two usage modes clearly: stream+cursor to read chunks (even while running) and wait_seconds to avoid a polling loop. It also clarifies the read-only, non-re-executing nature. It stops short of naming alternative sibling tools (e.g. cancel_mac_job) or exclusions, so not 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 cover the safety profile (readOnlyHint=true, destructiveHint=false), so the bar is lower, yet the description still adds value: it enumerates the state machine values, discloses that the call can block for up to 40 seconds, and notes that installed secrets are returned by name only, not values. It omits error/not-found behavior, which is the main remaining gap.

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

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

It is a single dense paragraph that front-loads the return shape before moving to the two behavioral parameters, and nearly every clause carries information. It is longer than a minimal definition and reads as a run-on of semicolon-joined clauses, which costs a point but not much.

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 correctly carries the return-value burden and does so thoroughly, including conditional content ('once ready, also the image...'). It stops short of covering failure modes and whether/when the returned image data is absent, which would round out a read tool with three optional parameters.

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 all three parameters are already documented in the schema, including the include enum rationale and the session_id default of 'the account's running Mac.' The description largely restates that material (wait window, include contents) rather than adding new syntax or constraints, so the baseline 3 applies.

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

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

It states a precise verb and resource ('Returns a Mac session') and then enumerates the returned payload: state with its full enum, cost, deadlines, cleanup_confirmed, and the ready-state image/secrets/drive. That level of detail distinguishes it from siblings like get_mac_checkout or get_mac_job 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?

It gives real usage context: 'wait_seconds (up to 40) waits for a starting or stopping Mac to change state' (i.e. use this instead of polling) and 'include adds the account's recent sessions... to find a Mac after a lost answer.' It does not, however, name an alternative tool or state when a sibling such as get_mac_checkout is the better choice.

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 nonetheless adds useful detail beyond them: it removes deleted secrets, installs on a running Mac immediately, and is a manual trigger after human changes.

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, front-loaded with the action and scope before the nuance. No filler, though the second sentence could be marginally tighter.

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 mutating tool with no output schema, the description covers what it does, when to invoke it, and the destructive/removal side effect. It omits edge cases such as behavior when no Mac is running, but nothing critical 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?

Schema coverage is 100%, so both names and session_id are already documented in the schema. The description echoes the names semantics ('on-request ones named in names') but adds no syntax, format, or behavior beyond what the schema provides, and does not mention session_id at all – baseline 3.

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

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

States a specific verb (installs), concrete resources (secrets and signing identities) and a precise scope (on a running Mac, now). It is clearly separable from sibling request_secret, which requests rather than installs.

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 trigger: 'call this after the human adds or changes one,' and explains the alternative path (a Mac gets every-Mac secrets automatically on ready), which tells the agent when NOT to call. It stops short of naming a competing tool explicitly, so 4 rather than 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 destructive=true, openWorld=true and non-idempotent, so the safety profile is covered. The description adds genuinely non-redundant traits: it operates on the lock screen and in password dialogs, it returns a screenshot unless suppressed, and 'a retry types again' warns that repeating the call duplicates input rather than being idempotent.

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 front-loaded sentences that state capability, then action-to-parameter mapping, with zero filler. The action list is dense but each item earns its place by mapping an enum value to its parameter.

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, and the description compensates by stating that the call answers with a screenshot unless screenshot=false. For a 10-parameter, open-world GUI automation tool the coverage is solid, though coordinate scaling and session defaulting are left to the schema.

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 100% schema description coverage, the baseline is 3, and the description largely restates what the schema already documents (action meanings, screenshot toggling, x/y coordinate reference). It adds no syntax or format detail 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?

It names a specific verb and resource ('Sends real keyboard and mouse input, as a person at the Mac would') and immediately scopes the capability to the lock screen and password dialogs, which separates it from shell-oriented siblings like exec_mac. The action enumeration makes the full surface of the tool visible 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?

It tells the agent the concrete situations this tool is for (lock screen, password dialogs, GUI interaction) and even routes one case away: long text should be pbcopy'd with exec_mac and pasted with cmd+v. It does not state an explicit when-not against exec_mac for general command execution, so it falls short of a full 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?

Adds substantial context beyond annotations: it discloses the two-phase lifecycle (start returns immediately, stop finalizes), the auto-stop behavior after max_seconds, that the download link persists after the Mac stops, a concurrency limit ('one recording at a time'), and a data-loss risk ('stopping the Mac deletes an unsaved one'). None of this is inferable from 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?

Front-loaded with the purpose, then organized by action (start vs stop) followed by constraints. It is information-dense and mostly earns its sentences, though the middle is somewhat run-on with parenthetical asides.

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 no output schema, the description covers the return values of stop (length, size, url for browser, download_url for curl), the persistence of the link, and the full stateful lifecycle. An agent has everything needed to invoke start and stop correctly and to handle the 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 description coverage is 100%, so all five parameters (path, action, target, session_id, max_seconds) are already fully documented in the schema. The description restates target and max_seconds semantics but adds no new syntax or format detail beyond the schema, so the baseline of 3 applies.

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

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

States a specific verb + resource: 'Records the Mac's screen as an MP4,' which is unambiguous and inherently distinguishable from the static-image sibling screenshot_mac. It stops short of naming or contrasting any sibling explicitly, so it falls just below 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?

Clearly explains the two operating modes: action start begins and returns at once, action stop saves and returns metadata. It gives the context for choosing start vs stop and screen vs simulator, but offers no guidance on when to use this tool instead of screenshot_mac or other capture 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?

Beyond the annotations, the description discloses that a human signs in at nomac.app, that the link is browser-based with mouse and keyboard, and that the session disconnects after 15 minutes without input. This adds useful behavioral context on auth flow and timeout. It does not cover all possible operational details, but with annotations already declaring read-only safety, the additional disclosure is substantive.

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

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

The description is compact and front-loaded: it leads with what is returned and why, then adds sign-in, timeout, readiness, and safety details in a tight sequence. There is no wasted text.

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

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

For a single-parameter tool with full schema coverage and no output schema, the description covers what the tool returns, who interacts with it, the timeout behavior, and the readiness prerequisite. An agent has enough to call it appropriately without needing more.

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?

There is only one optional parameter, and the schema already documents session_id with 100% coverage. The description does not add format or semantic detail beyond what the schema provides, so the baseline 3 is appropriate.

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

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

The description gives a specific verb and resource: it returns a browser link to the Mac desktop with mouse and keyboard. It clearly frames the tool as human-interactive rather than agent-executed, which helps distinguish it from siblings like exec_mac and screenshot_mac, though it does not explicitly name an alternative.

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

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

It states the intended use case clearly: seeing or clicking things like Xcode, the Simulator, or a sign-in window. It also notes the prerequisite that the Mac must be ready. It stops short of naming when-not-to-use cases or explicit alternatives, so it is strong but not exhaustive.

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 and destructiveHint=false, so the description's trailing 'Read-only' is confirmatory rather than additive. It does add real behavioral context beyond annotations: format-dependent return shapes (text vs image vs base64), the truncation-to-metadata fallback for oversized binaries, and the default/max byte caps.

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 dense sentence with the return modes front-loaded after the core action. Every clause carries information (size caps, format branches, path resolution, safety), and there is 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?

Since there is no output schema, the description must explain return values and it does thoroughly via the format branches. It omits error behavior (missing file, permission denial) and whether truncation is signalled, which are minor gaps for a read-only 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?

Schema coverage is 100% and every parameter is documented in the schema, including the same default/max byte values and path-resolution note the description repeats. Baseline 3 is appropriate since the description adds essentially nothing new for parameters.

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

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

States a specific verb+resource (reads a file on the Mac) and disambiguates from the sibling write_mac_file by scope and read-only nature. An agent can distinguish it from get_mac_file_link and screenshot_mac from the stated behavior alone.

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 tool name and the described return modes, but there is no explicit when/when-not guidance or pointer to siblings (e.g., use get_mac_file_link for large binaries, or screenshot_mac for screen content). The agent must infer the alternative.

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?

Goes well beyond the annotations: it discloses that repeats are merged, that supplying email requests a direct reply from support, and that omitting the description turns the same tool into a read of support's replies — an important non-obvious dual behaviour for a tool flagged readOnlyHint=false. It does not say whether reports are visible to other users or what happens after submission, so it stops 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?

Three short sentences front-load the action and pack in the dedup rule, email semantics, feedback variant and read mode with no filler. The compressed semicolon style is dense but every clause carries a distinct fact.

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 correctly covers the return behaviour (support's replies when called without a description). The only gap is that with zero required parameters it never states the minimum viable call — e.g. whether at least one of description or an identifier is needed to file versus read.

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 each parameter is already documented in the schema; the description mainly restates the Mac-vs-build split for session_id/job_id versus ref_id. It adds the useful framing that these identify what the issue is about, but no format or mutual-exclusion guidance beyond the schema. Baseline 3 applies.

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

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

States a specific verb and resource (sends NoMac support an error) plus the payload it carries (session_id/job_id for a Mac, ref_id for a build), so the agent knows exactly what the call does. No sibling tool overlaps this purpose, and the feedback variant and read-replies mode are distinguished inline.

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?

"An error the tools could not resolve" gives a clear trigger condition, and "kind feedback sends a note instead" routes the alternative case. What is missing is an explicit when-not (e.g. don't file reports for ordinary user input mistakes) and whether identifiers are truly optional.

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 the generic safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=false). The description goes well beyond them with lifecycle facts an agent could not otherwise infer: the link is single-use, expires in 24 hours, requires no account, and its value never transits the chat.

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 dense sentences, zero filler. The core mechanism (browser link, never through chat) is front-loaded, and the delivery behavior follows in the second sentence where it belongs.

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 multi-step, asynchronous human-in-the-loop tool with no output schema, the description covers the important mechanics: what is produced, its lifetime, who receives it, and the follow-up tool for running Macs. The one gap is not stating what the agent receives back (presumably the link to hand to the human), which is the agent's immediate next step.

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

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

Schema description coverage is 100%, so the schema already documents every parameter, including both enums and the destination field. The description's concrete examples (token, .env value, .p12, config file) loosely illustrate the kind enum but add no syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

The description states a specific action and artifact: it 'Creates a link where the human enters a secret in their browser,' and immediately distinguishes this from the sibling install_secrets, which 'puts it on a running one.' An agent can tell this apart from the exec/write/read siblings without inspecting 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?

It gives clear contextual routing: new Macs automatically receive the secret, while already-running Macs require install_secrets. It does not state explicit exclusions versus siblings like mac_input for one-off prompts, but the use context (out-of-band secret entry, never through chat) is unambiguous.

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 cover the safety profile (readOnlyHint=true, destructiveHint=false), so the bar is lower; the description adds genuine context beyond them by listing what is returned (front_app, screen_locked, open dialog with buttons/next_step, JPEG path) and the 1440x900 resolution and coordinate mapping. It stops short of explaining latency, caching, or freshness 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?

Two front-loaded sentences that lead with the core action, then the return payload and prerequisite. Every clause earns its place, with no redundant restatement of the title.

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 correctly compensates by enumerating the return fields and the JPEG path. Combined with the target modes and the 'ready Mac' prerequisite, an agent has enough to invoke it correctly, though return semantics (e.g., when a dialog is present vs null) remain implicit.

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 real meaning beyond the schema: it specifies that target=screen is the 1440x900 desktop whose pixels map to mac_input's coordinates, and that simulator is the booted iOS Simulator. This coordinate-mapping detail is not present in 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?

States a specific verb and resource ('Returns the Mac's screen as an image') and enumerates both target modes with their scope. It also positions itself against the sibling mac_input by noting the screen pixels are mac_input's coordinates, so an agent can tell what it does and how it relates to neighbors.

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 prerequisite ('Works on a ready Mac') and explains the two target choices, which implies when each is appropriate. However, it never names an alternative tool or an explicit when-not condition (e.g., screenshot vs mac_recording), leaving routing to inference.

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

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

Discloses cost model ($0.80/hour billed by the minute from prepaid credit), expected readiness time, no admin prompts, the password location in $NOMAC_MAC_PASSWORD, drive persistence, and the exact error strings (insufficient_credit, session_limit_reached with the running Mac's id). This is far beyond what the annotations convey.

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?

Dense with semicolons but front-loaded: purpose and cost land first, then readiness, security, persistence, and failure modes. Nearly every clause carries actionable information, though the run-on packing pushes toward the upper limit of readable 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?

With no output schema and a mutation tool, the description carries the burden well by naming success timing, error codes, and credit implications. It lacks details on what the response object looks like (id vs. session), which is the one remaining 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 already 100%, so the baseline is 3, but the description adds real semantics: request_key idempotency ('same request_key returns the same Mac', 'a new key is new work'), parallel starting without the account's drive, and limit tuning guidance ('past 6 hours 15 minutes, raise the spend cap too').

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?

Opens with a specific verb+resource ('Starts a cloud Mac') and immediately specifies the image contents (macOS, Xcode, iOS Simulator), which cleanly separates it from siblings like stop_mac, extend_mac, and get_mac_session. An agent can pick this tool 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?

Gives clear operational context: readiness is checked via get_mac_session with wait_seconds, and the parallel flag is named as the route to a second Mac. It never states explicit when-not-to-use rules or direct alternatives, but the surrounding guidance is strong enough to route correctly.

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 idempotentHint=false, yet the description goes further: it names what survives (~/drive), what is destroyed (all other files), the billing consequence, the observable confirmation path via get_mac_session, and that the action is irreversible. That is substantive context beyond the structured hints.

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 dense sentence chain that front-loads the destructive action and then layers consequences in order of importance. No filler, no restatement of the title 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 output schema, the description supplies the return signal (get_mac_session showing cleanup_confirmed), plus destruction scope, preserved data, billing effect, and irreversibility. An agent has everything needed to invoke this safely without further exploration.

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% and the single optional session_id is fully documented in the schema, so the description adds nothing about parameters. Baseline 3 is appropriate when the schema carries the full parameter burden.

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 pair and resource ('Stops a Mac and deletes it'), immediately distinguishing it from start_mac, exec_mac, and the read-oriented get_mac_* siblings. The scope of destruction is defined inline, so an agent knows exactly what operation this is.

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

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

The description implies the terminal use case (irreversible teardown) but never states when to choose this over alternatives, nor does it name a sibling tool for a softer stop. Context is clear but there are no explicit exclusions or alternative 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?

The description ends with 'Safe to repeat', but annotations declare idempotentHint=false (and destructiveHint=true). Claiming repeat-safety directly conflicts with the structured idempotency signal, so the description misleads on retry behavior even though its other disclosures (folder creation, replacement, 3 MiB cap, executable) are useful.

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 verb and size limit, and every clause (path resolution, folder creation, replacement, executable, repeat-safety) carries information. Slightly dense semicolon stacking keeps it just short of ideal.

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?

Annotations cover readOnly/destructive/openWorld, the schema is fully described, and there is no output schema, so the description need only add behavior — which it does (size cap, path semantics, folder creation, replacement). The one gap is that the retry/idempotency claim is wrong, and no auth/permission context is given.

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 path, content, content_base64, executable, and session_id are already fully documented in the schema, closely mirroring the description's wording. The description adds the 3 MiB content cap and the text-vs-base64 choice, but largely repeats structured data, so the baseline 3 applies.

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

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

States a specific verb and resource ('Writes a file ... on the Mac') plus a concrete constraint (up to 3 MiB). The wording clearly distinguishes it from the sibling read_mac_file and from exec_mac without needing 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?

It routes the agent between the two content modes ('content as text, or content_base64'), which is useful selection guidance, but gives no explicit when-to-use versus siblings (e.g., read_mac_file, exec_mac) and no when-not conditions. Usage is 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.