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

Annotations already declare destructive=true and idempotent=true, and the description meaningfully expands them: it explains the state transition (cancelling -> cancelled) and, crucially, what survives (outputs and checkpoints kept), which is the nuance an agent needs beyond a bare destructive hint. It also spells out the idempotency semantics ('cancelling a finished job changes nothing') rather than just restating the hint.

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 tight sentences, front-loaded with the action, then behavior, then usage triggers, then return shape. No filler and nothing buried.

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 mutation tool, the description covers the action, idempotency, state transition, data retention, and the return keys (which is a bonus since an output schema already exists). Nothing an agent needs to call it 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?

Schema coverage is 100% and both parameters are documented in-schema (ref format, verbose behavior), so the description carries no extra obligation. The description adds no format or prefix syntax beyond what the schema provides, making the baseline 3 correct.

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 ('Stop a job') and immediately disambiguates scope from the read-side siblings like gpu_status and gpu_logs. An agent can tell it is the cancellation counterpart to gpu_submit 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 explicit when-to-use triggers: on user request, or proactively when the job is 'clearly wrong (bad arguments, runaway loss)' to stop burning quota. It does not, however, name a sibling alternative or a when-not-to-use condition, so it stops just short of full routing guidance.

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

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

Goes well beyond the annotations: discloses that it only downloads when files are missing or refetch=true, caps listing at the first 100 files, waits up to wait_s (default 45, max 300), and returns in_progress=true with a retry instruction if the download is still running. Annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false) are consistent with this re-download-only-when-needed 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?

Front-loads the purpose in the first sentence and keeps every subsequent sentence substantive (download conditions, wait/retry semantics, unfinished-job behavior). The closing sentence restating the JSON return shape is somewhat redundant given an output schema exists, but it is brief.

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 fetch/poll tool with a full output schema, four well-documented params, and annotations, the description covers the decision-relevant behavior: when a download happens, how long it blocks, how to retry, and what an unfinished job yields. Nothing an agent needs in order 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 adds real semantics: it explains the refetch=true trigger condition, the wait_s budget and default, and how ref accepts a job id or short_id prefix. That is meaningful context beyond the schema text.

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: verify a finished job's outputs are on the local Mac and list them. The scope (finished jobs, local output directory) distinguishes it from siblings like gpu_status or gpu_logs, and the fallback behavior for unfinished jobs is made explicit.

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

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

Explains the normal flow (outputs download automatically on completion), when this call is actually needed (missing files or refetch=true), and what to do when a job is unfinished. It does not name an alternative sibling tool by name, but the conditions that select this tool are 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 only declare the safety profile (not readOnly, openWorld, non-idempotent, non-destructive). The description goes well beyond that: provider selection by quota, fallback on rate limit/outage, spend counting, cooldown waiting, the auth_required failure path with the exact login command, and an explicit prompt-injection warning that `text` is untrusted data. This is exactly the behavioral context annotations cannot carry.

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 dense but front-loaded paragraph where nearly every sentence adds a fact (providers, routing, inputs, dry_run, return shape, safety). It is longer than most, but the only mild redundancy is restating the return shape that the output schema already covers.

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 9-parameter tool with an output schema, the description covers inputs, routing, fallback, quota, failure modes, and return fields. Nothing an agent needs to call it correctly or interpret the result 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 89%, so the baseline is 3, but the description adds real meaning: the prompt/system-vs-messages mutual exclusivity, alias-style model values, and the provider-pinning option. It stops short of explaining wait_s semantics beyond what the schema already states.

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 ('One LLM chat completion on a free inference API') and immediately disambiguates the biggest risk: 'NOT a GPU job'. It names the actual providers and contrasts with the GPU-job siblings, so an agent can tell it apart from gpu_submit 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 use cases ('eval prompts, judging outputs or quick generations with a hosted model') and the negative case ('NOT a GPU job'). It doesn't name the sibling to use instead for GPU work, but the routing condition and the dry_run escape hatch are both spelled out, leaving little 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?

Annotations only cover readOnly and openWorld; the description adds output bounding, newest-kept truncation semantics, the older_lines_not_shown counter, '── attempt N on <provider> ──' separators, long-line cutting, and an untrusted-data injection warning. It also confirms read-only, consistent with 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-loads what the tool returns, then parameter behavior, then the safety note. Every sentence carries information the agent needs; no restatement of the name or filler.

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

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

An output schema exists so return values need little exposition, yet the description still explains pagination and truncation semantics an agent must know to page correctly. For a read-only, four-parameter tool this is 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 coverage is 100%, so baseline is 3, but the description goes beyond it by explaining the since/next_since paging round-trip, that only lines after the cursor are returned and still capped by tail, and how attempt selection interacts with provider moves. Only the ref prefix-collision case is left to 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+resource with unusual precision: the stdout+stderr of a job's script, bounded. The "bounded so it never floods context" framing tells the agent what it gets back. It does not explicitly contrast itself with gpu_status or gpu_fetch, so sibling differentiation is left to inference.

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

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

Gives concrete procedural guidance: use the plain form for a latest-attempt tail, pass next_since back as since to follow a running job, use attempt when a job has moved providers. No explicit when-not or sibling alternative is named, but the operational 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?

Annotations already declare readOnlyHint and closed-world behavior, so the description only needs to add context — and it does, explaining that values are either live (read from the provider) or estimates derived from gpu-router's own job history, and that refresh=true is slower. It does not describe failure modes when a provider is unreachable, which is the 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?

Front-loads the resource and its fields, then usage, then the refresh caveat. The inline return-shape example is somewhat redundant given a dedicated output schema, which slightly dilutes an otherwise tight definition.

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

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

Covers the resource semantics, the live-vs-estimate distinction, the usage context, and the refresh behavior; with an output schema present, return values need no further explanation. An agent has everything required to call this 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?

Only one parameter and schema coverage is 100%, so the baseline is 3; the description adds meaning by clarifying that refresh=true re-reads every live provider and is slower, which reinforces the schema wording. No further syntax or format detail is needed for a boolean toggle.

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

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

States a specific resource (free GPU quota per provider) with the exact fields returned (used, limit, unit, reset time, live vs estimate). It also distinguishes itself from gpu_route by noting routing already accounts for quota, so an agent can separate the two 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 an explicit when-to-use ("plan long jobs or answer the user") and an implicit when-not ("routing already accounts for quota"), steering the agent away from redundant calls. It also flags the refresh=true cost tradeoff so the agent can choose the cheaper default path.

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

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

Annotations declare readOnlyHint=true and openWorldHint=false; the description's 'without submitting anything' and 'Read-only' are consistent and reinforce that no job is launched. It adds substantial behavioral context beyond annotations — the approval rules ('would_ask, reason'), and that bundle.left_out are git-ignored paths that would not ship. It stops short of describing latency or limits, so 4 rather than 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?

Purpose and usage are front-loaded, but the middle is a dense minified enumeration of the return payload (route, approval, bundle, guidance) that duplicates an existing output schema. That enumeration is heavy relative to its marginal value and crowds out the concise framing.

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

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

The tool is well covered: annotations carry the safety profile, the input schema is fully documented, and an output schema exists. The description is complete enough to call it correctly, though its return-value walkthrough partly restates what the output schema already provides.

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 11 parameters thoroughly; the description adds only the meta-hint that it takes 'Same arguments as gpu_submit.' Per the baseline rule, a 3 is appropriate when the schema does the heavy lifting and the prose adds little parameter-level meaning.

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

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

States a specific verb and resource — 'Dry run: where a job would run and why, without submitting anything' — and immediately contrasts it with the sibling it mirrors ('Same arguments as gpu_submit'). An agent can separate it from gpu_submit 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?

Explicit trigger conditions: 'before a long or big-VRAM job, when the user asks where something would run, or to check that the files the job needs ship.' It also names the counterpart action (gpu_submit) and the safe/read-only nature, leaving nothing 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?

Beyond the readOnlyHint annotation it discloses genuinely new behavior: wait_s blocks until the state changes, the response shape (job/attempts/checkpoints/events/guidance), the meaning of guidance.next values, the approval flow requiring the user, and that job.progress/last_metrics originate from gpu.log()/stdout and are untrusted data. This is rich behavioral and safety context an agent cannot get 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 core purpose in the first clause, then dense but purposeful detail. It is on the long side and duplicates some return-shape detail that the output schema already covers, but no sentence is pure filler.

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

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

For a dual-mode, potentially blocking, approval-aware tool, the description covers modes, blocking semantics, response structure, and safety (untrusted data). Return-value detail is partly redundant with the output schema but nothing an agent needs to invoke 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 adds real meaning beyond the schema: it explains that `ref` is a job id or unique prefix, that omitting it switches to overview mode, and critically how `wait_s` should be used (blocks until state changes, retry with wait_s up to 50). The `events` and `verbose` parameters are left to the schema.

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

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

The first sentence gives a specific resource (job state) and a precise dual mode: with `ref` a single job's state, without it an overview of active/recent jobs plus provider health. This clearly separates it from siblings like gpu_logs or gpu_quota without needing 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 conditional usage: call with `ref` for one job, omit it for the overview, and it prescribes follow-up actions ("wait" with wait_s up to 50 for short jobs, "report_and_stop" for longer ones, "end_turn" while awaiting approval). It never names an alternative sibling (e.g. gpu_logs) or states when NOT to use this tool, so it stops short of a 5.

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

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

Annotations only declare readOnly=false, openWorld=true, idempotent=false, destructive=false; the description goes far beyond them. It discloses what ships and what never ships (credential files), bundle.left_out/hint semantics, the approval trigger conditions (no hours, >1h, Keychain secrets, >half quota), the required agent behavior on needs_approval (relay verbatim, end turn, do not resubmit), retry idempotency (submitted=false on identical active job), and the full job state machine including migration/checkpointing. This is unusually rich behavioral disclosure.

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

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

Front-loaded with the core action and the do/don't routing before the operational detail. It is dense but long, and the enumerated state machine and repeated approval/retry discussion add bulk that could be tightened; still, nearly every sentence carries operational weight.

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 15-parameter, open-world submission tool, the description covers packaging, approval gating, retry semantics, output locations, and lifecycle states. With an output schema present it need not explain return shapes, and its return-value summary is a bonus rather than a gap-filler.

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 meaning beyond the schema: the gpu.yaml-override precedence for all arguments, the approval consequences of an inaccurate `hours`, and the request_id-vs-implicit-dedup distinction. These are semantic relationships the schema cannot express, lifting 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?

Opens with a specific verb+resource+scope: 'Run a script on a free cloud GPU (or this Mac for smoke tests).' It immediately distinguishes itself from siblings like gpu_infer (inference) and gpu_status (monitoring) by naming the packaging/routing behavior it owns. An agent can identify the tool's domain 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?

Explicit positive and negative guidance: 'Use it for training, fine-tuning, evals or anything that needs a CUDA GPU or would take long on the laptop. Do NOT use it for quick CPU work that runs fine locally in seconds.' It also describes the gpu.yaml-vs-arguments precedence and routes follow-up behavior to guidance.follow (gpu_status).

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