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

Beyond the annotations, the description discloses meaningful behavioral traits: idempotent behavior with existing derived revisions, preset-to-recipe hash equivalence, ICC color profile dropping for certain encode formats, and warning-as-not-error semantics. It also clarifies that a new revision is issued. This goes well beyond what readOnlyHint, destructiveHint, and idempotentHint already communicate.

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 packed with essential information but remains well-structured and front-loaded with the core purpose. Each sentence contributes unique value: input constraints, sibling tool pointers, idempotence, and an edge-case warning. No filler is present.

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

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

For a complex transform tool, the description covers input selection, mutual exclusivity, batch behavior, idempotence, encoding caveats, and where to find operation catalog details. An output schema exists, so return-value details need not be duplicated. The description is complete enough for an agent to call the tool correctly in both single and batch scenarios.

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

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

Even though schema description coverage is 100%, the description adds critical parameter semantics not encoded in the schema: recipe structure with operations applied in order, at most one encode operation and it must be last, the exact one-of relationship, batch size limit of 64, and per-item failure isolation. The note about ICC profile behavior further clarifies the recipe parameter's practical effects.

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 begins with a specific verb and resource: 'Apply a transform recipe at full resolution and issue a new revision.' It clearly distinguishes this from siblings like render_preview and export_asset by emphasizing full-resolution processing and revision creation. The operation's core input alternatives are also stated, leaving no ambiguity about what the tool does.

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 usage context: exactly one of recipe/preset and exactly one of revision_id/revision_ids, plus batch limits and failure semantics. It also points to sibling tools list_operations and explain_operation for prerequisite knowledge. However, it does not explicitly state when not to use this tool versus siblings like render_preview, so it stops short of a full 5.

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

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

Despite annotations covering safety, the description adds substantial behavioral detail the annotations cannot: the 640px scaling, 8px gap, A/B placement order, JPEG inline return, diff's dimension precondition, and how to interpret perceptual_hash_distance thresholds. This is rich context beyond structured fields.

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 behavior, then layers diff and metric semantics. Dense and mostly earning its length, though the metric-threshold sentences could be trimmed without losing the essential call 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 three-parameter compose tool with an output schema, the description covers layout semantics, output format, preconditions, and metric interpretation. Nothing an agent needs to invoke or interpret 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 meaning: it explains which layout is default, the placement convention (A left/top, B right/bottom), and the semantic thresholds for the computed distance metrics, going beyond the schema's field docs.

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 specific actions (scale to 640px, compose on one canvas, return JPEG) with a precise resource (two revisions), and it explicitly distinguishes its three layouts including what diff does differently. An agent can tell exactly what this produces.

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 the trigger context ('useful for before/after or A/B visual checks') and the precondition that diff requires identical dimensions. It does not name or contrast sibling tools, but the when-to-use conditions are 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, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds valuable behavior beyond that: coordinate ordering (tl, tr, br, bl), post-EXIF-orientation coordinates, output_size_hint semantics, min_area_ratio constraints, and the exact warning reasons when quad is null. This is rich, non-redundant behavioral detail.

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

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

The description is three sentences, each earning its place: purpose and analogy, coordinate/output semantics, and parameter/warning behavior. It front-loads the core action and keeps supporting details compact, with no filler or repetition.

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

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

Given the annotations, full schema coverage, and presence of an output schema, the description covers everything an agent needs: operation type, coordinate system, ordering, output sizing, parameter defaults, and failure/warning semantics. No important calling decision is left unexplained.

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?

Input schema coverage is 100%, so the baseline is 3. The description still adds meaning to min_area_ratio as 'the smallest fraction of the frame a candidate may cover', and clarifies that output_size_hint matches what perspective will produce. It does not add much to revision_id, but that is already well covered by the schema.

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

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

The description opens with a specific verb and resource: 'Detect the dominant quadrilateral ... in a revision with a contour-based search', and clarifies the return as a 'ready-to-paste perspective operation'. It also distinguishes itself from sibling detect_tilt by drawing the perspective/rotate analogy, so an agent can tell what this tool uniquely does.

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 strong context: it is read-only, never modifies the image, and a null quad means 'do not correct'. It also relates the tool to perspective via detect_tilt, which implies when to use it. It does not spell out explicit exclusion cases or name more alternatives, so it stops short of the strongest possible 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?

Annotations already declare readOnly/idempotent/non-destructive, and the description reinforces this plus adds behavior annotations do not cover: output ordering (reading order, post-EXIF pixel coordinates), the ~16px legibility threshold, the three splitting strategies, and the important guarantee that 'no block found' is not an error. Missing only things like performance or image-size limits.

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 the read-only guarantee are front-loaded, and each dense sentence carries information. There is mild redundancy: the read-only statement repeats the annotation, and the enumeration of returned fields partially duplicates the available output 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?

For a read-only analysis tool with full annotations and an output schema, the description supplies the missing pieces an agent needs: orientation/coordinate conventions, legibility semantics, and how to chain the recommended_bands into render_preview. Spending text on individual return fields is somewhat redundant given the output schema, but nothing essential is absent.

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 optional params are already documented in the schema, so the baseline is 3; the description earns an extra point by stating the intent behind them ('bound how many and how small the blocks may be') rather than only restating ranges.

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 ('Find the text-like blocks ... of a revision') and even names the algorithm (binarize + run-length smearing + connected components), which cleanly separates it from sibling detectors like detect_document and detect_tilt. An agent can identify the tool's job from the first clause alone.

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

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

The description gives concrete workflow context: use it to check whether text survives a preview downscale, then paste an entry from legibility.recommended_bands into a recipe before render_preview with long_edge: 1568. It does not, however, state when NOT to use it versus detect_document/detect_tilt, so it stops short of explicit 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?

Beyond the readOnlyHint/idempotentHint annotations, the description explicitly says it never modifies the image, describes processing stages (Canny/Hough then projection-profile refinement), discloses response-size behavior (score curve omitted by default), and defines the null recommended-angle sentinel. This gives an agent strong expectations for side effects and outputs.

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 with purpose and method, and each clause adds useful context. It is slightly dense and contains a minor punctuation issue ('roll,' followed by 'Set'), but no sentence 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?

With an output schema present and annotations covering safety/idempotency, the description supplies the remaining operational context: algorithm, default response size, read-only behavior, and the meaning of null. An agent has enough to call the tool correctly.

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

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

Schema coverage is 100%, and the schema already explains revision_id, max_abs_angle, and include_score_curve. The description reinforces include_score_curve's behavior and adds 'to keep the answer small', but it contributes little beyond the schema and does not deepen revision_id or max_abs_angle semantics.

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 states a specific verb and resource: 'Detect the tilt (roll) of a revision' rather than a generic or tautological phrase. It also details what the tool returns (horizontal-only and vertical-only estimates, optional score curve), so an agent can distinguish it from siblings like detect_document.

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?

Clear context is given: the tool is for measuring roll/tilt of a revision, and the description explains how to interpret disagreement between estimates and when to set include_score_curve=true. However, it does not explicitly name alternatives or state when not to use this tool versus siblings such as apply_transform or detect_document.

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, but the description goes further: it states 'Read-only' explicitly, describes support for preset names, and explains the structured error response for unknown names listing all valid operations. This adds behavioral context beyond the annotations, covering error handling and preset behavior.

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

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

The description is approximately 80 words, composed of three sentences. It front-loads the main purpose ('Full reference for one recipe operation'), then details content, presets, and errors. Reasonably concise and logically structured, though it could be slightly tighter.

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

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

For a read-only reference tool with one parameter and an output schema, the description covers return content (parameters, examples, gotchas), preset handling, and error behavior (unknown names return a structured error with valid operations). All essential information for correct invocation is present.

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 only parameter, 'operation', has a schema description explaining it as the op name to write in the format {"op": "..."}. Schema description coverage is 100%, so the description adds no additional meaning about the parameter itself; it focuses on the return value. Baseline of 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Full reference for one recipe operation' with detailed content (parameters, examples, gotchas). It also covers preset handling and error behavior, distinguishing it from sibling tools like list_operations. The verb 'explain' and resource 'operation' are specific and unambiguous.

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

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

The description implies usage for when detailed information about a specific operation is needed, contrasting with listing all operations. It does not explicitly name an alternative, but the context 'one recipe operation' and the error fallback listing all valid operations provide clear guidance. No explicit exclusions, but sufficient context.

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

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

Annotations already flag destructiveHint=true and readOnlyHint=false, but the description adds behavioral detail beyond them: overwrite is refused by default, collision in a batch writes nothing at all, execution never targets the workspace store or a symlink, and partial batch failure is tolerated. These are non-obvious operational traits worth stating.

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

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

Front-loaded with the purpose, then constraints ordered by invocation path. Every clause carries a real constraint, though the dense parenthetical chains make it heavier to parse than a few shorter sentences would be. 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?

With an output schema present, return values need not be explained, and the annotations carry the safety profile. Given the 6 parameters and the two-form invocation model, the description covers the exclusivity rule, defaults, failure behavior and write restrictions - nothing an agent needs is missing.

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

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

Schema description coverage is 100%, so the schema already carries the baseline. The description goes further by pairing each form's parameters (revision_id + dest_path vs revision_ids + dest_dir), spelling out template placeholders ({revision_id}, {index} 1-based zero-padded, {ext} from MIME, {stem}) and the default template - meaning genuinely beyond what the structured fields convey.

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 ('Copy revisions' bytes out of the workspace') and names the exact scope: workspace bytes to an external path. It is naturally distinguishable from the inverse sibling import_asset and from list/inspect tools 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?

It explicitly declares the two mutually exclusive invocation forms ('exactly one of the two forms'), gives the batch cap (up to 64), notes that one failure does not abort the batch, and instructs the agent to ask the user before overwriting. This is full when/when-not guidance rather than implied context.

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 beyond annotations by detailing the deterministic and idempotent behavior (same params produce byte-identical PNG and return existing revision). It also clarifies what the mask represents (white = full application, black = none) and that gradients use dimensions while ranges use pixels. The idempotentHint annotation is confirmed and expanded with specifics.

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 moderately long but every sentence serves a purpose: it defines the function, parameter kinds, output semantics, usage example, and idempotency. The front-loaded summary of kinds is efficient, and the JSON usage example is compact yet informative. No fluff or repetition.

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

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

Given the tool's complexity (13 parameters, 4 kinds) and presence of output schema, the description covers key aspects: output semantics, idempotency, and usage integration. It omits explicit return value format (though output schema exists) and some edge cases, but the examples and schema descriptions cover most. The description is sufficient for an agent to call it correctly.

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

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

Schema coverage is 100% with detailed descriptions for each parameter including default values and units. The description adds clarity by grouping parameters by kind and explaining the common semantics (like feather behavior) but does not add substantial new information beyond the schema. The description's parameter list matches the schema and provides complementary context (e.g., which parameters apply to which kind), but this is largely redundant.

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

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

The description clearly states the tool's function: generating a deterministic grayscale mask as a new PNG revision with exact dimensions from a reference. It enumerates four distinct mask kinds with their parametersholistic details, and explains the white/black semantics. This distinguishes it from siblings like render_preview or apply_transform by focusing on mask generation.

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 explicitly explains how to use the result: referencing the returned revision_id in tone/filter operations with a concrete JSON example, and how to visualize it with render_preview overlay. It does not explicitly mention when not to use it, but the detailed operation contracts and idempotency note provide clear context for typical use cases. The alternatives are implied by sibling tools, and the usage examples are sufficient.

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

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

Beyond the annotations (readOnly=false, idempotent=true, destructive=false), the description discloses idempotency behavior ('same bytes returns the existing revision'), partial-batch failure behavior ('one bad file does not abort the batch, it lands in `failed`'), and a derived-output warning with `already_derived_from`. This is substantial behavioral context that the annotations alone do not convey.

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

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

Four sentences, each carrying distinct information (purpose, selection rule, idempotency, derived-output warning), with the core purpose front-loaded. No filler or repetition of the schema.

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

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

For an import tool with an output schema present, the description need not explain return values, yet it still flags the meaningful outcome fields (`failed`, `already_derived_from`). Combined with the safety annotations, an agent has everything needed to invoke it correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the schema: it resolves the ambiguity left by zero required parameters by asserting 'exactly one of the two' is required, and restates the 64-file batch cap and per-file failure model. That is genuine value over structured fields.

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 ('Import a local image file into the workspace') plus the notable side effect ('issue an immutable revision'). This is clearly distinct from siblings like export_asset and list_assets. An agent can identify the operation without opening the schema.

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

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

It states the operational context clearly: use `path` for one file or `paths` for a batch, exactly one of the two, and describes the batch-failure semantics. It does not name a sibling alternative or state when-not to use (e.g., directory vs file, remote URLs), 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 already declare readOnly/idempotent/non-destructive, so the description's added value is the interpretation detail: sharpness is a relative Laplacian variance (below ~30 usually means motion blur or defocus), perceptual_hash is a dHash for identity checks, and include_exif is off by default because full EXIF can carry GPS coordinates and names. That privacy and interpretation context goes 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?

Two dense sentences that front-load the enumeration and end with the opt-in flag's rationale. Every clause carries information, though the output enumeration is long enough that it slightly blurs the primary purpose.

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 adds interpretive value the schema cannot (sharpness scale, dHash semantics) and explains the include_exif default. For a read-only, non-destructive, idempotent inspection tool, an agent has everything needed to invoke and interpret 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?

Schema description coverage is 100%, so the schema already documents revision_id and include_exif including the privacy rationale. The description restates the include_exif default and its reason without adding syntax or format detail beyond the structured field, so the baseline 3 is appropriate.

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

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

Names a concrete verb (Inspect) and resource (revision/image) and enumerates the exact attributes produced: dimensions, MIME type, byte size, alpha/ICC, EXIF orientation, GPS presence, luma stats, sharpness, perceptual_hash. This clearly separates it from siblings like compare_revisions, detect_text_blocks, and render_preview.

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

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

Usage is implied by the listed outputs (image QA, blur detection, duplicate detection via perceptual_hash), and the sharpness note says to compare against a known-good capture. However, there is no explicit when-to-use/when-not guidance nor any reference to sibling tools such as compare_revisions for revision diffing.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is clear. The description adds that it lists revisions and includes specific data fields, which is useful context but does not disclose behavioral traits like pagination or ordering. With annotations covering safety, a 3 is appropriate; no contradiction exists.

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

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

One concise sentence that front-loads the action and includes only essential information. No filler or redundancy; every word contributes to clarity.

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

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

For a simple read-only tool with one well-documented parameter, an output schema, and safety annotations, the description is sufficient for correct invocation. It does not explain domain-specific terms like 'workspace ledger', but that is likely implicit in the system context.

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% for the single parameter asset_id, which includes a clear description (filter by asset_id, omit for all). The tool description adds no additional meaning beyond what the schema already provides, so the baseline 3 is 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?

The description states a specific action (List) and resource (revisions in the workspace ledger), and enumerates returned fields (lineage, recipe hash, dimensions, sizes). It distinguishes from siblings like list_operations by focusing on revisions. However, the tool name 'list_assets' suggests assets rather than revisions, creating slight ambiguity about what is being listed.

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

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

The description provides no guidance on when to use this tool versus alternatives, nor any exclusions or conditions. An agent must infer usage from the name and description alone; there is no explicit 'use when...' or 'instead of...' context.

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 destructiveHint, so the safety profile is covered. The description adds behavioral context by specifying what the catalog contains and that category narrows the output. It also repeats the read-only property, which is consistent 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 compact and front-loaded: it states what the tool returns, then covers the optional filter, the sibling tool to use for more detail, and the read-only nature. Every sentence earns its place with no redundancy or filler.

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

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

Given the simple single-optional-parameter interface, an output schema, and annotations that already convey safety, the description provides everything needed to invoke the tool correctly. It includes the category values, the filtering behavior, and the fallback tool for deeper detail. Nothing essential is missing.

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

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

Schema description coverage is 100%, so the schema already fully documents the category parameter, including its allowed values and default behavior. The description adds 'narrows the list' but does not materially go beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states a specific purpose: listing every operation in the recipe vocabulary with one-line descriptions, parameter hints, and preset names. It differentiates itself from explain_operation by explicitly directing users there for full schema details. This is far beyond a vague or tautological description.

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

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

It states the optional category filter and its allowed values, and explicitly names explain_operation as the alternative when full schema details are needed. This gives an agent clear guidance on when to use this tool versus its sibling. The read-only note reinforces safe usage.

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 safety hints (readOnly=false, idempotent, non-destructive); the description adds genuinely non-derivable behavior: overlay lines appear only on the preview and never on apply_transform output, mask overlay tints pixels red above 0.5 weight, and ICC profiles are silently dropped for png/webp/avif with a warning. It stops short of saying the preview file is written to disk (implied by readOnlyHint=false) or describing rate/size limits.

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

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

Front-loads the core purpose and output in the first sentence, then layers parameter guidance. Every sentence carries actionable information, though the dense multi-topic prose (overlay modes, ICC caveat, size rationale) makes it longer than the minimum.

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-format detail is not required, and the description still names the inline image plus path. Combined with the parameter guidance and the ICC warning, 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 100% (descriptions in Japanese), so the baseline is 3. The description nevertheless adds decision-relevant meaning beyond the schema: raise long_edge to 1568 specifically to read text because 768 is too small, and mask_revision_id is required for overlay="mask" and rejected otherwise. It does not restate enums redundantly, which is a plus.

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 (render) and resource (a recipe as a small JPEG preview), names the exact output (inline image plus file path), and explicitly frames its role relative to the sibling apply_transform. An agent can distinguish it from apply_transform 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?

Explicitly says when to use it (to check composition before committing to apply_transform), how it relates to alternatives (takes recipe or preset exactly like apply_transform), and even covers the 'neither' case with a concrete use case (overlay="grid" to read crop coordinates). No inference required.

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