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

Annotations already declare this is a non-read-only but non-destructive, closed-world mutation. The description adds real context beyond that: cancellation is a *request* (asynchronous/graceful), not an immediate kill, and the caller must poll until a terminal state. It does not say whether a running job's in-flight work is aborted or what happens if cancellation is refused, which keeps it below 5.

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

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

Two short sentences, action leading and workflow guidance second. Every clause carries information; nothing is 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?

An output schema exists, so return-value detail is unnecessary. For a single-parameter async mutation the description covers the action, the applicable state scope, and the required follow-up behavior. It is only slightly short of complete in not clarifying the relationship to job_status and delete_job.

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 one required parameter with 0% schema description coverage, but the tool name and description fully explain what it is: the identifier of the job being cancelled. No format, source, or lookup guidance is provided, so the description neither compensates for the coverage gap nor adds much beyond the obvious.

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 ('Request cancellation of a queued/running job') and scopes it to jobs in non-terminal states, which implicitly separates it from delete_job and job_status. It does not explicitly name the sibling it differs from, so an agent must infer the distinction.

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?

'queued/running job' implies the applicable condition, and the second sentence gives workflow guidance ('Poll until its state is terminal'). However, it never names job_status as the polling tool or explains when to use delete_job instead for removing a job permanently, leaving alternatives 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 already declare destructiveHint=true and readOnlyHint=false, so the description's job is to add context — and it does: it names the collateral damage (logs and artifacts) and the permanence, which annotations cannot express. It also discloses a runtime refusal mode for non-terminal jobs, though it says nothing about behavior for a nonexistent or already-deleted job_id.

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

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

Two short sentences, zero filler, with the destructive effect front-loaded before the precondition. The line break between them is slightly odd for such short text but costs nothing.

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

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

For a one-parameter destructive tool with an output schema (so return values need no explanation), the description covers effect, permanence, and preconditions adequately. The remaining gap is error behavior outside the queued/running case, which an agent will only discover at call time.

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 single job_id parameter has 0% schema description coverage, so the schema contributes nothing and the description must carry the load. It only indirectly constrains the value (must reference a terminal-state job) and gives no format, source, or idempotency guidance — an agent must infer that IDs come from list_jobs or job_status.

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 (delete), resource (job), and effect scope (with its logs and artifacts), then narrows it to terminal jobs (completed/failed/cancelled). That state qualifier alone separates it from cancel_job and list_jobs without requiring the agent to open 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 an explicit when-to-use (jobs in a terminal state) and an explicit when-not (queued/running jobs, which are refused), plus the correct alternative path: cancel them and wait for a terminal state. This is the full when/when-not/alternative triad.

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 it is a non-read-only, non-destructive, closed-world call; the description goes well beyond that by disclosing the asynchronous job model, the side effect of writing contact.jpg, the grid labelling convention ('face N' / 'id N: <appearances>x', '*' for unverified references), and that reference crops are verified to re-detect as one face. That is exactly the extra 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?

Front-loaded with the action and next steps, then mode selection, then the shared artifact output — a logical order. It is dense with parentheticals and backticks but each clause carries information; the trailing 'view it first' instruction is slightly tacked on but still 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?

An output schema exists, yet the description still usefully explains the `faces` vs `identities` return shapes and the crop-reference contract for FaceMapping.target_face. It falls short only on the unexplained `job_id` and `controls` parameters, which matter for a six-parameter job-oriented 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 description coverage is 0%, so the description must compensate — and it does for `frame` (zero-based), `sample_frames` (N evenly spaced) and `frames` (explicit, at most 64). However `job_id` and `controls` are never mentioned anywhere, leaving a third of the parameters with no semantics at all.

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 ('Queue face detection') and immediately distinguishes two operating modes: single-frame detection returning `faces`, versus multi-frame detection (`sample_frames`/`frames`) returning grouped `identities`. An agent can tell exactly what this produces 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?

Prescribes an explicit workflow — queue, then poll `job_status`, then inspect crops via `view_artifact` — naming the sibling tools in order. It also states the selecting condition between modes: use `frame` for a single frame, use `sample_frames`/`frames` 'to find who appears across a video', with the 64-frame cap.

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 readOnly=false, destructive=false, openWorld=false; the description adds real context on top: it writes into a configured downloads directory, returns an absolute local path, and streams large videos to disk rather than buffering. It does not cover overwrite behavior or failure modes.

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

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

Three short sentences, front-loaded with the action and destination, then return behavior and the streaming nuance. No filler sentences.

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?

Return value is covered by an output schema, and the description still helpfully previews the absolute path, but with two undocumented parameters and no guidance on job state requirements or filename control, an agent lacks enough to call it confidently in edge cases.

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

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

Schema description coverage is 0% for both parameters, so the description carries the full burden, yet it never mentions job_id or the 'name' parameter (whose default 'result.mp4' strongly implies a filename choice). An agent must guess whether 'name' sets the output filename or the artifact identifier.

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 ('Download a completed artifact') and names the destination ('configured local downloads directory'), which separates it from view_artifact by implying a persisted local file rather than an in-place preview. It stops short of explicitly contrasting with view_artifact.

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 qualifier 'completed' implies a precondition (the job must be finished), which is useful, but there is no explicit when-to-use versus view_artifact or upload_media, and no statement about what happens if the job is still running.

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, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered by structured data. The description adds only the list of what is returned, which the existing output schema already carries, and says nothing about auth requirements, caching, or whether the set is static or environment-dependent.

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

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

A single front-loaded sentence with the resource scope stated immediately and zero filler. Every clause (names, defaults, choices, limits) contributes distinct information about the return payload.

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

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

For a zero-parameter, read-only introspection tool with a full output schema and clear annotations, the description covers what is needed to select and invoke it correctly. The only missing piece is any hint about how the returned parameter metadata relates to the other Fusion tools that consume it, which would help an agent decide when to reach for it.

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

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

The tool takes zero parameters, so there is no parameter meaning to add and the baseline of 4 applies. Nothing in the description misleads about inputs, and it correctly implies the call needs no arguments.

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

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

The description names a specific verb ("Return") and enumerates the exact resource content: Fusion parameter names, defaults, choices and numeric limits. That makes the tool's output scope unambiguous and distinguishes it from the job/media/storage siblings, none of which touch parameter metadata. It stops short of 5 only because "Fusion parameter" is not defined or tied to any consumer tool in the set.

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

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

There is no explicit when-to-use statement and no named alternatives or exclusions. The intent is strongly implied — call this to discover valid parameter names, defaults and limits before invoking other Fusion tools — but the agent must infer that discovery purpose from the content list rather than read it directly.

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 annotations already establish that this is a read-only, non-destructive, closed-world operation. The description adds useful behavioral context by listing the checked subsystems and explaining that code_matches may be null when unknown.

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 short, front-loaded, and free of redundant wording. Every sentence provides relevant diagnostic or output-semantics 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 no-parameter diagnostic tool with an output schema, the description is complete enough: it states what is checked and clarifies the nullable code_matches field. The output schema can carry the remaining return-value 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?

The tool takes no parameters, so parameter semantics are not applicable; the baseline for zero parameters is 4. There is no additional parameter meaning needed.

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

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

The description gives a specific diagnostic verb and enumerates the resources checked: installed revision, deployed release, GPU, memory use, and media/state paths. It is clearly a health/diagnostic tool, but it does not explicitly contrast itself with siblings such as get_settings or job_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?

The diagnostic purpose implies when to use it, but there is no explicit guidance on when to choose health_check versus get_settings or other sibling tools. No exclusions or preconditions are stated.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered by structured data and the description need not repeat it. The description adds the concrete metadata fields extracted, which is useful behavioral context, but says nothing about handling of unsupported or corrupt files, and the presence of an output schema means return shape needs no explanation here.

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

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

A single front-loaded sentence with the verb and extracted fields up front and no filler words. It is efficient, though the metadata field list is packed into one clause without further structure.

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 single-parameter inspection tool with an output schema and full annotation coverage, the description supplies enough to call it correctly. The remaining gap, support for various container or codec formats and the local-file constraint, is minor at this complexity level.

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

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

Schema description coverage is 0% for the single required parameter media_path, so the description must compensate and only partially does: "workstation file" implies a local filesystem path rather than a URL, job ID or artifact reference. It adds no information about path format, accepted extensions or codec support.

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 pairs a specific verb ("Read") with a precise resource and enumerates the exact fields returned: codec, frame rate, dimensions and duration. That clearly separates it from siblings such as normalize_media, upload_media or detect_faces, though it never names those siblings explicitly.

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

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

The phrase "from a workstation file" implicitly scopes usage to local files on the machine, which hints at when the tool applies versus remote or artifact-oriented siblings. However, there is no explicit statement of when to prefer this over normalize_media, detect_faces or view_artifact, and no prerequisites or exclusions 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 only declare read-only, non-destructive, closed-world safety; the description adds genuinely non-obvious behavior: blocking semantics of wait_seconds, the three conditions that end the wait, the subtlety that advancing frame counts do not end the wait, and that a log tail is returned on failure. That is exactly the extra context annotations cannot provide.

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, then the wait contract, then the log behavior, with no redundant restatement of the name or schema. Every sentence carries distinct 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?

The output schema exists, so return values need not be explained, and the description covers the only risky behavior (blocking up to wait_seconds). For a three-parameter, read-only tool this is sufficient 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 0%, so the description has to carry the burden, and it does explain the two non-trivial parameters' semantics (wait_seconds blocking behavior, include_log triggering the log tail). Only job_id format/expectations are left unexplained, which is a minor residual gap.

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

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

The description uses a specific verb ('Read') with a precise resource enumeration (durable queued/running/completed/failed/cancelled state, progress, results), which is far beyond a tautology. It doesn't explicitly name the sibling it differs from (list_jobs for enumeration, cancel_job for mutation), which keeps it from 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?

Usage is implied through the wait_seconds and include_log conditions, but there is no explicit when-to-use-this-vs-list_jobs guidance or statement of preconditions (e.g., valid job_id ownership). The description doesn't route the agent to cancel_job or list_jobs as 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 cover the safety profile (readOnlyHint, destructiveHint false, closed-world), so the description's added value is the cross-client visibility note and the summary field inventory including elapsed_seconds and progress. It does not state ordering guarantees beyond "most recently updated" or how many jobs exist before truncation.

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

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

Front-loaded with the action and scope, then a compact field list; every sentence is short and purposeful. The field enumeration is somewhat redundant given an output schema exists, but it reads efficiently.

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?

Because an output schema exists, the return-value inventory is largely duplicated effort, while the more consequential gap — how the three optional filters behave and whether they combine — goes unaddressed. The definition is serviceable but incomplete for a filtered listing 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 description coverage is 0%, so the description must carry the load, yet it never explains the kind, status, or limit parameters as filters. The mention of "kind" and "status" describes fields in the returned summary, not the input filters, which risks being misread as if these parameters merely echo results.

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 ("List the most recently updated jobs") plus a scope qualifier ("including jobs submitted by another client") that no sibling covers. It also distinguishes itself from job_status, which handles single-job results and logs.

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 routes the agent to job_status "for results and logs," establishing list_jobs as the discovery/browsing tool. It lacks an explicit statement of when not to use it (e.g., for a known job ID) and does not mention pagination or recency-window limits.

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 the safety profile (not read-only, not destructive, closed-world), while the description supplies substantial behavioral context: CPU-only execution avoiding the GPU lock, exact output codec/rate/color/pixel-format, rotation normalization, metadata stripping, odd-dimension padding, and audio stream handling. The remaining gap is that it never says whether the job is queued asynchronously and how completion is observed (presumably via job_status), which matters for a queueing 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?

Front-loaded with the action in the first sentence, followed by a dense but entirely informative paragraph on output characteristics and the downstream consumer. Every sentence carries call-relevant information; nothing is redundant with the annotations or schema.

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

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

An output schema exists, so return values need not be restated, and the safety annotations cover the mutation profile. The description is complete on output format and downstream use, but the unexplained job_id parameter and unstated async/completion mechanics leave a small gap for a queued job 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 description coverage is only 33%, and the description compensates only partially: it explains fps behavior in depth (source average rate default, snapped to a standard rate within 2%), which adds meaning beyond the schema's format examples. media_path and especially job_id receive no explanation at all, leaving the idempotency/resume semantics of job_id undocumented in both 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?

States a specific verb and resource ('Queue conversion of a video') plus the shape of the result ('render-ready copy'). It also implicitly separates itself from GPU-bound siblings by noting it runs on CPU without the GPU lock, so an agent can distinguish it 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?

Usage is implied through the pipeline note that the result's media_path is 'usable in submit_swap', which tells an agent where this sits relative to a sibling. However, there is no explicit when-to-use/when-not guidance and no mention of inspect_media or upload_media as upstream steps, so the agent must infer the workflow.

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 destructiveHint=true and readOnlyHint=false; the description adds real value on top by stating the default is a non-destructive dry run, precisely what would be removed, and what the response contains (paths, jobs, byte totals). The description is consistent with the annotations: it is a destructive tool that defaults to a safe preview.

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

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

Two sentences, front-loaded with the report-vs-delete distinction and the selection criteria, with no redundant restatement of the name, schema defaults, or annotation flags.

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 destructive with only two optional parameters and an output schema, so the description's job is criteria and safety profile, both of which are covered. An agent can decide whether to call it and predict the effect without further reading.

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

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

Schema description coverage is 0%, so the description must carry the parameter meaning, and it does: `older_than_days` is defined as the age since job completion and since upload last-touch, and `dry_run` is characterized as report-only versus actually deleting. It does not restate defaults or unit bounds (0-36500) that the schema already encodes.

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 pair and resource scope: report-or-delete of old terminal jobs, unused uploads, and orphaned transfer files. The age/terminal-state criteria make it clearly a bulk cleanup tool, distinguishable from single-item siblings like delete_job and cancel_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 clear selection conditions for what qualifies (jobs finished more than `older_than_days` ago; uploads untouched that long with no queued/running job referencing them) and states dry run is the default. It does not explicitly say when to prefer this over delete_job or cancel_job for individual items, but the context 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 only declare readOnlyHint=false, destructiveHint=false and openWorldHint=false; the description adds substantial context beyond that: outputs are new job artifacts (non-destructive by construction), H.264 video with AAC first-audio-stream encoding, the Inswapper128 preview default, and a real operational constraint that GPU jobs run one at a time. It does not say whether submission returns immediately with a job handle or blocks, nor what identifiers come back, which is why it stops 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 well front-loaded: purpose first, then mode semantics, then output behavior, then constraints. Every sentence carries information, though the run of constraints at the end is terse to the point of feeling compressed and could be split for readability.

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 no prose, and for an 8-parameter write tool the description covers purpose, mode semantics, output format, concurrency and rejection conditions well. The remaining gap is the trio of undocumented inputs (job_id, controls, media_path) for a schema with zero description coverage.

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

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

Schema description coverage is 0%, so the description must carry the parameter burden and it only partly does. It explains the mode-dependent meaning of `frame`, `start_frame` and `max_frames` (including that None means through the end), but `media_path`, `job_id`, `controls` and the structure of `mappings` receive no explanation in either place.

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 ('Queue an image/frame preview or CFR video render') and immediately splits the two modes, so an agent knows exactly which operation it is committing to. It is clearly distinct from inspection siblings like inspect_media or detect_faces, which analyze rather than queue work.

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

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

Explicitly distinguishes when to use preview ('processes `frame`') versus render ('processes `start_frame` and at most `max_frames`'), names the prerequisite tool ('Consult get_settings before changing parameters'), and routes unsupported inputs elsewhere ('Renders reject VFR, nonzero start times, odd dimensions and rotation; use normalize_media'). Both the when-to-use and when-not-to-use paths are covered with named 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 readOnlyHint=false, destructiveHint=false, and openWorldHint=false, so the write-locality profile is covered. The description adds genuinely non-obvious behavior: a 20 GiB ceiling, a closed set of accepted formats, and content-addressed dedupe where re-uploading identical media returns the existing path (idempotency semantics). It does not say what happens on format/size rejection or whether uploads can be undone, which keeps it from a 5.

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

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

Three short sentences, front-loaded with what the tool does and its return value, then the acceptance constraints, then dedupe semantics. No sentence is redundant and constraints are grouped where an agent would look for them.

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 one parameter, an output schema present, and annotations covering safety, the remaining burden is behavioral, and the description covers formats, size limit, dedupe, and downstream use. The only material omission is the failure path for oversize or unsupported files, which is a minor gap given the output 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?

Schema description coverage is 0% for the single required parameter local_path, so the description must carry the meaning. It partially compensates by implying the file lives on the Mac and constraining the media types that the pointed-to file may be, but never clarifies whether the path must be absolute, supports ~ expansion, or may point to a non-media file.

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?

"Stream a Mac image/video to private workstation storage and return its remote path" gives a concrete verb (stream/upload), a concrete resource (image/video media), a destination (private workstation storage), and a result (remote path). This is easily separable from siblings such as inspect_media, normalize_media, and download_artifact, which operate on already-stored media rather than ingesting it.

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

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

"Use this path in other tools" states the downstream purpose clearly, telling the agent this is the ingestion step that produces a handle for later calls. It stops short of explicit routing guidance — it does not say when NOT to use it (e.g., for already-remote URLs) or name a specific alternative sibling.

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 readOnly/non-destructive/closed-world, so the bar is lower. The description still adds real value: the artifact is rendered inline into the conversation rather than written to a file, it targets Claude/Codex surfaces, and it only applies to completed jobs. It omits failure behavior for missing/incomplete artifacts.

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

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

A single front-loaded sentence with no filler; the key constraint ('completed job') and the output mode ('inline') both appear early.

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

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

For a two-parameter read-only tool with no output schema, the description covers purpose and rendering mode adequately. It leaves the artifact-naming parameter and error cases undocumented, which matters given 0% schema coverage.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It hints that 'crop or preview' variants exist (likely tied to the 'name' parameter, defaulting to preview.jpg) but never explains what 'name' should contain, whether it is a filename or key, or what job_id expects.

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

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

Specific verb ('Show ... inline') plus resource ('a completed job's PNG/JPEG crop or preview'), which distinguishes it from download_artifact (saves to disk) and inspect_media. It doesn't name a sibling explicitly, so it stops short of a 5.

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

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

'a completed job's' implies the precondition that the job must be finished, which is useful gating. However, there is no explicit statement of when to pick this over download_artifact or inspect_media, and no note on what happens if the job is still running.

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