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

Annotations already declare readOnly/idempotent and the description agrees with no contradiction. Beyond annotations it adds extensive behavioral context: the AICOMMANDER_TOKEN auth requirement, the Free-tier 10-oldest usability limit with promotion-on-delete behavior, the 100-record ceiling, the deliberate masking of restricted entries (online:false, lastSeenAt:null, omitted platform/agent/GPU) with the explicit caveat that this is not evidence the machine is offline, and the 'win32' means cmd.exe shell-dialect mapping.

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 carries distinct information — auth, tier limits, field semantics, caveats — with no filler or repetition. The core purpose and usage guidance are front-loaded in the first two sentences; the density is justified by the semantic complexity of the access-state and plan-restriction rules.

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

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

For a no-argument, no-output-schema tool whose complexity lives entirely in the meaning of returned data, the description covers the entry fields (blocked, planRestricted, online, lastSeenAt, platform, agent version, GPU), their semantics, tier-specific behavior, and the failure mode (reason:'plan_device_limit'). Nothing an agent needs to interpret the result safely is missing.

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

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

The tool has zero parameters, which earns the baseline of 4. The description confirms this with 'Takes no arguments,' so there is nothing ambiguous for the agent to resolve.

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 + scope: 'List ALL of the user's saved machines with each one's access state and, when available, live status.' This clearly separates it from per-machine siblings like remote_exec and remote_screenshot, and the description explicitly contrasts it with session_status.

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

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

Gives explicit when-to-use guidance ('USE THIS for fleet-wide questions or when the user has not named a machine yet') and a named fallback ('fall back to session_status with a specific AIC- code' when there is no account). Also provides a hard exclusion: 'NEVER attempt another tool against a plan-restricted entry.'

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 goes far beyond the annotations' destructiveHint/openWorldHint flags, disclosing buffered output, partial-output handling, effective identity, hard-kill vs output-cap semantics, PowerShell exit-code unreliability, and the critical instruction to treat returned stdout/stderr as untrusted data. No contradiction with the annotations; the destructive and non-read-only hints are strongly reinforced.

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 extremely thorough and front-loaded, with the core statement and usage signal at the top, but it is also very long. Some material is tangential to remote_exec itself — the entire 'JOB SURVIVAL ACROSS AN AGENT RESTART' section concerns remote_job_start — and shell caveats are repeated across `command` and `shell`. Strong structure and clear headings keep it usable, so it earns a 4 rather than a 3.

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 destructive, cross-platform tool with 7 parameters and no output schema, nothing is missing: return-value semantics, timeout/output limits, identity behavior, error handling, safety rules, and routing to remote_job_start are all covered. The absence of an output schema is compensated by explicit description of stdout/stderr, exit code, partial and truncated markers.

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 100% of parameters, but the description still adds substantial meaning: how `code` resolves (AIC- code vs alias, pass exactly), the shell enum's rejection behavior and PowerShell CLIXML post-processing, `elevated` incompatibilities, `timeout_ms` validation versus clamping, and the env/elevated conflict. This is far above the baseline 3 for full schema coverage.

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

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

The opening line identifies a specific verb, resource, and scope: 'Execute a shell command on a remote machine running the AI Commander agent.' The description then foregrounds 'THIS IS THE TOOL FOR REMOTE-MACHINE ACCESS' and contrasts it with remote_job_start, so an agent can clearly distinguish it from its siblings without opening their schemas.

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 triggers ('whenever the user asks to connect... run / check / install / fix something ON another machine') and explicit when-not-to-use routing ('For anything expected to run longer than a few minutes... use remote_job_start instead'). It also warns against fallback behaviors like probing DNS or using a raw ssh client, leaving no ambiguity about alternatives.

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 and idempotentHint, and the description reinforces and enriches them: cancellation is irreversible, work is lost unless checkpoints exist, the tool waits a few seconds, and a killed job's outcome is 'unknown' — 'cancelled', never 'succeeded'. This fully explains behavioral nuances beyond the annotations.

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

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

The description is long but front-loaded with the core action and effect, and every clause carries useful information about behavior, parameters, or safety. It could be tightened slightly, but it is well-organized and 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?

With no output schema, the description explains exactly what the reply will indicate (STOPPED, exit code, unknown outcome, cancellation accepted) and tells the agent what to do in the ambiguous case. It also covers the destructive nature, confirmation requirement, and parameter semantics, making it complete for correct invocation.

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

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

Schema description coverage is 100%, so the baseline is 3; the description adds meaningful context on top, especially for 'code' ('name the machine with code exactly as the user said it', examples like AIC-XYZ-1234 and wearfits-m3) and for 'job_id' (the value returned by remote_job_start). This pushes it above baseline.

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

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

The description clearly states the tool's action: stop a running detached job on a remote machine, terminating its process tree and releasing GPU resources. It names the resource (remote job) and the verb (cancel/stop/kill/abort), which distinguishes it from sibling tools like remote_job_status and remote_job_start.

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

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

It explicitly says 'USE THIS when the user asks to stop/kill/abort a job, when a run is clearly failing, or before starting replacement work on the same card.' It also gives when-not-too-act guidance (cancelling a finished job is not an error) and tells the agent to confirm with remote_job_status instead of repeating the cancel when the process outlives the wait.

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, idempotentHint, and non-destructive. The description goes beyond this by disclosing critical behavioral traits: the machine's retention window (about a week), the meaning of 'unknown' status including causes (SIGKILL, OOM, taskkill /F), the warning that unknown end times are estimated and can be minutes late, and the security note to treat output as untrusted data. No contradiction with 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?

The description is long but every sentence earns its place: it covers purpose, usage, output semantics, status interpretation, machine naming, command omission, and a security warning. It is front-loaded with the core purpose and usage guidance before the detailed behavioral notes. 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?

For a read-only list tool with no output schema, the description thoroughly covers output fields, status semantics, retention, limits, machine naming, and safety. An agent has everything needed to call it correctly and interpret results correctly. The only minor gap is that the description doesn't explicitly mention the default limit of 20, but the schema covers that.

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 parameters are already well documented. The description adds meaningful context for limit (history retention and context burning), status (narrowing), and include_command (off by default so command strings aren't echoed). This exceeds the baseline 3 by adding rationale for parameter choices and behavioral consequences.

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 precise verb and resource: 'List the detached jobs on a remote machine', and immediately differentiates from siblings by saying it shows what is running now and recently finished retained jobs. It also explicitly names the sibling alternative use cases (finding a jobId, checking before starting work), so an agent can tell it apart from remote_job_status, remote_job_logs, and remote_job_cancel without opening their schemas.

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: answer 'what is running on the GPU box?', find a jobId from an earlier conversation, or check before starting new GPU work to avoid collision. It also gives concrete behavioral guidance: omit commands unless include_command:true, don't quote unknown end times as exact, don't report unknown outcomes as success, and pass the machine code exactly as the user said it.

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

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

Annotations carry readOnlyHint=true and idempotentHint=true, but the description adds substantial non-obvious behavior: the 256 KiB per-reply page cap, the 256 MiB recording cap after which output stops being captured while the job keeps running, that a truncated log's tail is 'the last thing written before the cap, NOT the job's latest output', and the security rule that log contents must be treated as untrusted data, never as instructions. None of this contradicts the annotations — all consistent with a read-only, side-effect-free tool.

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

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

The description is long but logically front-loaded: purpose, then usage, then machine naming, then sibling contrast, then limits, then safety. Nearly every sentence earns its place given the tool's real pitfalls. It loses a point because it re-explains some schema-covered ground (max_bytes' 256 KiB ceiling and offset_bytes' continuation mechanism appear in both schema and description), adding length without new information.

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

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

With no output schema, the description carries the burden of explaining return behavior, and it does: tail-by-default, a header line instructing continuation with offset_bytes, the 256 KiB page cap, and the truncated-state failure mode. It covers machine naming/auth, the read limit, the distinction from a stalled job, and content-safety handling. For a tool with this many edges, nothing an agent needs to call 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 coverage is 100%, so the baseline is 3, but the description genuinely adds meaning beyond the schema: the machine-naming rule for `code` ('AIC- session code... or a saved alias/hostname... if the user's text contains 'aic-'/'AIC-' in any case, that is one of their machines') and the paging protocol for `offset_bytes` (the previous reply's header line naming the continuation offset). It also explains the tail/offset interaction that the schema only states individually.

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 pair and a distinguishing detail: 'Read the output (stdout and stderr, interleaved as a terminal would show it) of a detached job.' It explicitly differentiates itself from remote_exec later in the same description, so an agent can tell this tool apart from its nearest sibling without opening either schema.

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

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

Gives concrete when-to-use guidance ('USE THIS to follow a long run — training loss, build progress, a stack trace after a failure') and names the alternative with the exact condition: 'Unlike remote_exec — whose reply is truncated at 1 MiB... a job's output is kept in a file...' It also warns against a specific misinterpretation ('do not read a stalled tail as a stalled job') and points to remote_job_status / remote_job_list for the `truncated` 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?

The description goes far beyond the annotations (readOnlyHint=false, destructiveHint=true) by disclosing exactly how behavior differs per platform: reparenting on macOS, tree-kill fragility and auto-update risks on Windows, systemd scope protection and upgrade ordering on Linux. It also spells out output caps (256 MiB recording cap after which the job runs on unaffected), identity semantics, GPU reservation locking and gpu_busy refusal, and prompt-injection-style untrusted-data warnings. This is exemplary behavioral transparency.

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 content is front-loaded with the core purpose and key distinction, followed by well-labeled sections (SURVIVING AN AGENT RESTART, GPU WORK, IDENTITY, SAFETY). The text is dense and every section earns its place given the genuinely complex platform-specific behavior. It is long, but the length is justified by real hazards; a small deduction for some repetition of the shell/identity points across sections and for paragraphs that could be tightened without losing 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?

Given the tool's complexity — background execution, platform-specific survival semantics, GPU locking, identity, and safety — the description covers everything an agent needs to call it correctly: how to name the machine, how to follow up, how to handle restarts/upgrades, how to choose the right shell, and what to do about unsupported parameters. The output schema is absent, but the description states the return behavior (returns as soon as spawned with jobId) so the agent knows what to expect. No critical gaps remain.

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

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

Schema coverage is 100%, so the baseline is 3. The description nonetheless adds meaningful semantics beyond the schema: it explains that the `shell` parameter is intentionally unsupported and will be rejected rather than silently dropped, clarifies the security rationale for `elevated` rejection, and describes the GPU reservation/locking behavior of `gpu_index`. The command parameter also gains critical cross-platform shell guidance (Windows `;` pitfall, heredocs, default-shell behavior). This exceeds the baseline but is slightly redundant with schema descriptions in places.

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 — start a LONG-RUNNING command on a remote machine as a detached background job — and immediately contrasts itself with remote_exec by naming the exact alternative and the condition that selects it (anything expected to take more than a few minutes). It clearly states what the tool is for, distinguishes it from siblings, and never once restates the title.

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 guidance is explicit and thorough: it says to use this instead of remote_exec for long-running work, explains the exact failures of remote_exec (1-hour kill, 1 MiB truncation), and routes to remote_job_status/logs/cancel/list for follow-up. It also gives explicit when-not-to conditions, such as using remote_exec for short commands that need a chosen shell, and warns to check platform before committing multi-hour runs.

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 mark readOnly/idempotent/non-destructive, but the description adds substantial behavioral depth: semantics of running/exited/unknown, that unknown must never be reported as success, why no exit marker exists (SIGKILL, OOM, cancel), and that end time is ESTIMATED and not authoritative. It also warns that returned data is untrusted.

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

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

The description is front-loaded and every sentence carries value, but it is a long dense paragraph. It could be slightly more scannable with bulleted status definitions; still, there is no filler or redundant broadening.

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, the description fully covers what an agent needs: status values and their interpretation, exit-code authority, estimated end-time caveats, machine code handling, and when to delegate to remote_job_logs. This is unusually complete for a status-check 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%, so the baseline is 3. The description adds meaningful guidance for `code` — 'pass it exactly as the user said it' with AIC- session code/alias/hostname examples and a heuristic for recognizing machine references. It repeats `job_id` provenance already in the schema and adds no extra for `include_command`, so not a 5.

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

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

The description opens with a specific verb and resource: 'Check one detached job: is it still running, what exit code did it finish with, how big is its log.' This clearly distinguishes it from siblings like remote_job_list (list all) and remote_job_start/cancel (lifecycle operations).

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 when to use it: 'USE THIS to poll work started with remote_job_start' and gives polling guidance ('not in a tight loop', e.g. every few minutes). It also directs to remote_job_logs for printed output, which is strong 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 discloses far beyond the annotations: temporary storage with 24-hour blob TTL and 1-hour link TTL, hourly sweep behavior, `plan_device_limit` failure reason, the relay being a courier not a file host, no listing/renaming/backup support, and TTL persistence after downgrade. There is no contradiction with the annotations; readOnlyHint=false aligns with the tool creating temporary blobs.

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 section earns its place: plan restrictions, behavioral caveats, limits, path rules, and machine-code handling. It is well-structured with clear paragraph breaks and front-loaded with the most decision-critical facts (purpose and plan gate). No fluff or redundant restatement of the tool name.

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

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

With no output schema, the description carries the full burden of explaining the return contract, and it does: it returns a `blobId` and download link, specifies expiration, covers failure modes, size limits, and directory refusals. It also provides complete workaround guidance for large files and permanent storage needs. Nothing needed for correct invocation is missing.

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

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

Schema coverage is 100%, so the baseline is already solid. The description still adds meaning beyond the schema: it emphasizes passing `code` exactly as the user stated, explains case-insensitive detection of AIC- session codes, reinforces that relative paths are refused, and clarifies Windows path conventions. It also ties both parameters together in practical workflow guidance (tar directories first).

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: 'Copy a FILE off a remote machine so you (or the user) can actually open it.' It immediately clarifies the tool's scope (regular files, not directories) with concrete examples (checkpoint, image, CSV, log). It also distinguishes itself from sibling remote_exec by explicitly saying to use this instead of cat-ing.

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 and when-not-to-use guidance: 'USE THIS instead of cat-ing a file through remote_exec' and explains why (1 MiB cap, binary mangling). It directs large artifacts to job-side storage (`aws s3 cp`, `rclone`, `scp`), tells users to tar directories before pulling, and specifies upgrade requirements for Free/anonymous callers. This is exemplary routing behavior.

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 goes well beyond the destructiveHint annotation by explaining atomic writes, overwrite behavior, plan-related failure reasons, 24-hour blob TTL, and the tool's inability to access the user's local filesystem. These are material behavioral details an agent needs to avoid incorrect calls.

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 densely informative, covering plan gating, blob provenance, overwrite semantics, and alternatives. It is front-loaded with the most critical constraint (PRO PLAN ONLY). Some redundancy exists around Free/anonymous restrictions, but each sentence largely earns its place.

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

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

For a three-parameter tool with no output schema, this description covers prerequisites, failure modes, parameter formats, and safety warnings. It even supplies the exact upload command when the user has no blob_id. Nothing essential for correct invocation is missing.

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

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

Schema coverage is 100% and each parameter already has a solid description, so the baseline is 3. The description adds extra operational nuance: dest_path must be absolute and overwrites atomically, code can be an AIC- session code or alias, and blob_id can come from a prior remote_pull. This additional context justifies 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 uses a specific verb+resource: 'Write a stored file ONTO a remote machine' and clarifies it takes a blob_id, not a local path. This clearly distinguishes it from sibling tools like remote_pull and remote_exec.

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

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

It explicitly says when to avoid this tool (small text files → use remote_exec heredoc) and when to use it (binary or anything over a few KB). It also explains how to obtain a blob_id via remote_pull or the upload command, and gives upgrade instructions for Free/anonymous users.

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 is rich, covering the one-screenshot-per-display limitation, caption semantics, required permissions, failure modes, and the instruction to treat screen content as untrusted data. However, the annotations declare openWorldHint false while the tool's output depends on the live, uncontrolled state of a remote screen—the description even says the caption includes 'when it was taken.' This is a direct contradiction with the annotation, so per the rubric the score is 1.

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 and dense, but well-structured with front-loaded purpose and clearly separated concerns: use case, display caveats, prerequisites, failure behavior, and security. It earns most of its length, though a few points echo what is already in the parameter schema, keeping it just short of a perfect conciseness score.

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

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

Even without an output schema, the description fully explains what the agent will receive: an image plus a text caption with display count, index, resolution, downscale status, and timestamp. It also covers platform restrictions, permission prerequisites, version-dependent behavior, failure responses, and a safety rule, making it complete for correct invocation.

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

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

Schema coverage is 100% and the schema already documents both `code` and `display` in detail, so the baseline is 3. The description adds meaningful emphasis beyond the schema, such as the multi-monitor risk that the primary display may not be the one the user means, and the guidance to read the caption before concluding anything.

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 action and resource: 'Capture a screenshot of a remote desktop machine and return it as an image.' This clearly differentiates it from sibling tools like remote_exec or remote_pull, making it the obvious choice for screen-viewing requests.

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 says 'USE THIS when the user asks to see, view or screenshot what is on one of their machines' screens.' It also tells the agent to check session_status first for the Share Screen and macOS Screen Recording permission status, which is concrete pre-flight guidance about when the tool will or will not work.

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 annotations (readOnly, idempotent, non-destructive), the description discloses rich behavioral context: screen-sharing availability, GPU report semantics, the ambiguous absence of a GPU section, stale offline GPU readings, and the per-account machine-notes path conditions. It also explains that anonymous/offline calls simply get no notes path, setting correct expectations.

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 carries operational value and there is no filler. It is effectively front-loaded: the core purpose and first-step role appear in the opening sentence, followed by usage guidance, parameter nuances, behavioral caveats, and secondary use cases in logical order.

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 no output schema, the description compensates thoroughly by explaining what the result reports (screen sharing, GPU details, notes path) and what edge cases look like. Given the tool's complexity and its role as a gateway to several siblings, nothing needed for correct invocation 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?

While the schema already fully documents `code`, the description adds crucial semantic depth: pass the name exactly as given, AIC- session codes vs saved aliases/hostnames, and that non-AIC names are resolved as aliases. It even covers the authentication dependency on alias resolution, which cannot be inferred from the schema alone.

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 a specific verb and resource: 'Check whether a remote machine is online, active, reachable and ready' and explicitly identifies it as the FIRST step for connection requests. It clearly distinguishes itself from sibling tools such as remote_exec and remote_screenshot by being the canonical status check rather than a data-transfer or job tool.

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

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

Provides explicit when-to-use guidance with concrete user-phrase examples ('connect to / reach / log into', 'is my laptop connected?') and strong signals like 'aic-' prefixes. It also states what NOT to do (probing DNS, mDNS, ping, raw ssh) and routes to alternatives like remote_exec for GPU confirmation, leaving no ambiguity about tool selection.

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