Editmamei Connect

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

Annotations (readOnly=false, destructive=false, idempotent=false) already signal a non-idempotent mutation; the description goes well beyond them by disclosing non-destructiveness, that nothing is baked until export_photo, the merge-on-re-edit behavior, the immutability of mask at creation, that only Editmamei-created filters can be re-edited, and the post-masked-adjustment lockout on transforms. It is consistent with destructiveHint=false. It does not, however, cover rate limits or permission requirements.

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

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

It is front-loaded sensibly (purpose, then type list, then targeting, then pitfalls, then re-edit, mask, ordering), which suits a 40-parameter tool. However, several sentences restate details already present in the schema (curves endpoints, one-range-per-filter, to_kelvin direction), so not every sentence earns its place independently of structured data.

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 high-complexity mutation tool with 40 parameters and an output schema (so return values need no explanation), it covers layer scoping, type/field coupling, mask constraints, re-edit merge semantics, cross-type rejections, and ordering preconditions. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds cross-parameter semantics the schema only hints at: the vibrance-vs-saturation distinction, one filter per channel/range rules, the counter-intuitive to_kelvin direction, and the layer-targeting rule (layer_id beats layer). Some of this duplicates the per-field schema text, limiting the added value 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?

States a precise verb and resource: 'Add a non-destructive adjustment to a layer, or re-edit one in place with filter_id.' It distinguishes the add-mode from the re-edit-mode and clearly separates itself from siblings like manage_filters (delete/list), apply_look and add_effect. An agent knows exactly what this tool does without opening a schema.

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

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

Explicit when/when-not routing: it tells the agent to use manage_filters op=delete to remove it, op=list to inspect the stack, and export_photo to bake. It gives ordering prerequisites (straighten/flip/resize, then crop, THEN masked adjustments) and specifies the alternative for a problematic hue shift (color_balance or a small hue move). Alternatives and exclusions are named, not inferred.

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 a generic write profile (readOnly=false, idempotent=false, destructive=false, openWorld=true). The description adds substantial behavior the annotations cannot: re-edit is a MERGE that preserves omitted fields, masks are frozen at creation, external filters are refused and must be deleted and recreated, transform tools refuse once a masked filter exists, and specific effects stay locked or auto-update their center/angle/offset under rotation.

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

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

The core create-vs-re-edit distinction and the sibling alternative are front-loaded in the first sentence, which is the right priority. The body is long and partially duplicates schema text (mask, filter_id, ordering), but for a 29-parameter tool with heavy cross-effect interactions most sentences carry distinct constraints rather than 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 no explanation. Given the tool's complexity, the description still covers everything an agent needs before calling: mode selection, effect semantics, spatial vs relative units, ordering hazards, refusal conditions, masking limits, and the verification step with manage_filters.

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 per-field baseline is 3, but the description adds cross-parameter semantics the schema does not carry: 'type picks the effect; a field that belongs to another effect is refused', the layer-vs-flattened targeting rule, and the mapping of each effect to its controlling fields. It does not need to restate ranges, which are already exhaustively in the schema.

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

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

First sentence states a specific verb and resource ('Add a non-destructive effect to a layer'), plus the alternate mode ('re-edit one in place with filter_id') and enumerates the exact effect types. It explicitly positions itself against siblings ('the same live, editable, maskable mechanism as add_adjustment', 'For a plain blur use add_adjustment type=gaussian_blur'), so an agent can separate it from add_adjustment, manage_filters and photo_effect 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 names concrete alternatives with the condition that selects them (plain blur -> add_adjustment type=gaussian_blur; stack management -> manage_filters op=list/set_visibility/delete). It also spells out when-not and sequencing constraints: order of straighten/flip/resize then crop then masked effects, the refusal conditions, and the delete-and-recreate path for non-Editmamei effects.

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 cover safety (non-read-only, idempotent, non-destructive), and the description adds substantial behavior beyond them: looks are live/editable filters, re-application replaces rather than stacks, strength 0 removes the effect, determinism of same-look-same-strength, and that no file is produced except under jpeg_crush. This is unusually rich disclosure for a mutation 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 purpose, replacement semantics, then the look catalog, then the export caveat — a sensible order. It is long and the look glosses are dense, but nearly every clause is load-bearing given how sparse the schema's enum description is; only minor trimming is possible.

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

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

No output schema exists, and the description compensates by explaining what the call yields (editable filters, no file) and that jpeg_crush returns a download link, plus pointing to export_photo for retrieval. 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% but the schema itself is thin (look is merely "Which look."), so the description carries real semantic load: it enumerates and explains all nine looks, defines strength as intensity with 0 meaning removal, and reiterates the layer requirement. That is meaning well beyond the 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?

States a specific verb+resource ("Give a photo a named look") with a concrete outcome (named presets, adjustable strength) that clearly separates it from generic siblings like add_adjustment, add_effect, and manage_filters. An agent can identify the tool's job 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 routing guidance ("Offer these to people who describe an outcome instead of naming adjustments"), the layer precondition for multi-layer images, the repeat-call semantics ("replaces the earlier one, it never stacks; strength 0 removes it"), and the required follow-up with export_photo for a download. When-to-use and downstream dependency are both spelled out.

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 destructive/idempotent, but the description adds substantial beyond-the-annotation context: irreversibility with no session undo, that text layers are not rasterized, that group layers are skipped and reported under skipped_groups_with_filters, and that targeting a group is refused. These are exactly the behavioral traits an agent needs before a destructive call.

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 effect and survival guarantee, then layers in defaults, batch behavior, and the undo warning. It is long, but nearly every clause carries distinct operational information; a slight trim of the repeated group-skip note (stated in both description and schema) would tighten it.

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 description still proactively names skipped_groups_with_filters. Combined with the destructive/irreversibility disclosure, an agent has everything needed to call this correctly on a 4-param tool.

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

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

Schema coverage is 100%, so the schema already documents all four parameters; baseline is 3. The description nonetheless adds real meaning over the schema: it explains the group-skip/reporting semantics of `all`, and the refusal when targeting a group via layer/layer_id, which the schema does not state as a hard rule.

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 ('bake') and resource ('a layer's live filters into its own pixels'), and immediately disambiguates from merging siblings by clarifying the layer survives as itself. It even distinguishes the outcome for text layers, so an agent can tell it apart from add_effect/apply_look/manage_filters without opening a schema.

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

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

Gives explicit when-to-use context (make a masked adjustment safe to resize/rotate/flip), the default target (selected layer, else topmost), the batch mode (all: true), and the recommended precaution (run `checkpoint` first). It also names the prior refusal from canvas_size/resize/transform_image, routing the agent correctly.

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

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

Goes well beyond annotations: sequential one-image-at-a-time processing, per-photo failure isolation, JPEG export for looks, time-budget truncation returning `remaining`, and credit charging. Annotations only supply the generic safety/idempotency flags; the description supplies the operational reality.

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 that puts purpose first and then handles sources, args, edge cases, and cost. Every sentence carries information, though the single-block format makes some details (failure handling, remaining) slightly harder to scan than bullet-style would.

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

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

No output schema exists, yet the description explains what comes back (collected download links, `remaining`) and how errors surface. For a non-idempotent, open-world mutation tool, everything an agent needs to invoke and re-invoke it correctly 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?

Schema coverage is 100% so the baseline is 3, but the description adds genuine meaning: that `sources` accepts 'upload:<id>' handles or https URLs and that one link can carry several photos, and that `args` is the preset's arguments minus `image`, with a concrete example ({marketplace: "etsy_square"}).

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 ONE preset over several photos in one call,' then enumerates the exact preset names it can batch. An agent can distinguish this from the single-photo sibling presets (apply_look, product_shot, etc.) purely from the 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?

States when to use it (several photos, same arguments), the constraint that opens the door ('Only presets you can call yourself can be batched'), and the continuation path when the time budget is exhausted ('call again with those'). Also implies the single-call alternative by tying costs back to 'the single calls'.

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 destructive=true and idempotent=false, but the description goes well beyond them: no undo in this session, refusal on masked/foreign filters, workspace pixel limits at higher bit depths, and the filter-mask-doesn't-travel caveat. 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 purpose and constraint-first ordering, and most sentences carry non-obvious refusal/caveat information. It is dense and slightly repetitive of the schema's fill wording, but little is genuinely wasted.

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, the description needn't explain returns, and it covers everything else an agent needs: refusal triggers, irreversibility, anchor/offset exclusivity, fill layering, and ordering relative to filters.

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 field descriptions are themselves detailed (fill semantics, mutual exclusivity, offset bounds). The description restates rather than extends: 'give one or the other, not both' and the anchor grid are already in the schema, and the long fill parenthetical duplicates the field description.

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 ('Extend the canvas: grow it and reposition the existing content') and immediately disambiguates from the sibling `crop` since it 'never shrinks'. An agent can tell exactly what this does without reading 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?

Explicitly routes shrinking to `crop`, tells the agent to run `checkpoint` first when in doubt, and gives the ordering rule (extend the canvas before adding masked filters, not after). Refusal conditions (no growth, masked filters with content movement) are spelled out as when-not-to-constraints.

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 adds substantial behavior beyond that: it renders a composite, enumerates exactly what is measured (pixel size, aspect ratio, border whiteness, product fill ~85%, edge touching), and describes the return structure. This is rich, non-redundant 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 purpose, then behavior, then return shape, then the marketplace table. Dense and mostly earning its place, though the marketplace enumeration is lengthy and could be slightly compressed.

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

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

No output schema exists, but the description explains the return fields (rule, pass, measured, required, fix) and the marketplace-specific targets, so an agent has everything needed to interpret results and act on them.

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 a marketplace enum, so baseline is 3, but the description adds real meaning: the required pixel dimensions per marketplace (amazon 2000x2000, etsy_landscape 2700x2025, etc.), which is not in the schema. The image param is not elaborated, keeping it from a 5.

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

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

States a specific verb and resource ('check whether a photo is ready to list on a marketplace') and immediately scopes it as non-mutating ('without changing it'). This clearly distinguishes it from siblings like product_shot or export_photo that act on the image.

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?

Frames the tool as a pre-listing validation step and explicitly routes to the fix path ('usually product_shot with that marketplace'). No explicit when-not or exclusion, but the usage context and alternative 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 only signal destructive/non-idempotent/non-readonly. The description goes far beyond: 24-hour retention surviving crashes/restarts/reconnects, per-photo cap of 5 (6th refused, not evicted), 20 total cap, per-session and cross-session 1024 MiB disk caps, replace-not-copy restore semantics with close_failed handling, unknown-id refusal that names known ids, and open/pending list states. This is exemplary disclosure of edge cases and 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?

Front-loaded with the undo-substitute framing and organized by op, with each sentence carrying operational weight for a genuinely complex tool. It is dense and run as one long block, which slightly hurts scanability, but there is little filler.

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

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

With an output schema present, the description needn't detail return values, yet it explains retention windows, quota limits, restore replace semantics, and failure cases thoroughly. Nothing an agent needs to invoke checkpoint operations 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 schema already documents all three parameters (baseline 3). The description adds value on top: it clarifies restore's close-on-success/close_failed behavior, list's reported fields and open/pending flags, and that unknown ids are refused with known ids listed, going beyond the enum 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 for each operation (create saves current state, restore reopens as NEW image, list reports, delete removes) and frames the tool's role as standing in for undo. An agent can distinguish it from siblings like bake or export_photo 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?

Clearly explains when each op applies (create to snapshot, restore to roll back, list to enumerate, delete to free slots) and the 'undo substitute' framing gives clear context. However it does not explicitly contrast this tool with alternative rollback/serialization siblings such as bake or export_photo, so no explicit exclusions or alternatives are named.

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 carry destructiveHint=true and readOnlyHint=false, so the safety profile is known; the description goes further by spelling out the specific loss ('WITHOUT saving it') and prescribing a data-preserving workaround. It stops short of stating irreversibility/undo availability, so it is strong rather than complete.

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, front-loaded with the destructive consequence before the recommended alternative. Every clause earns its place, including the parenthetical about psd preserving layers.

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 destructive nature, the alternative route, and the format nuance; return values are handled by the existing output schema. What remains unstated is failure behavior (e.g., invalid or already-closed image id), a minor gap for a single-param 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?

Only one parameter and schema coverage is 100%, with the schema itself explaining 'Image id, as returned by open_photo'. The description adds no additional meaning about the identifier, which is the expected baseline when the schema does the work.

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 ('close a photo') and immediately qualifies the scope with 'WITHOUT saving it', which is the key differentiator. It also names the sibling that handles the opposite need (export_photo), so an agent can route 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 reach for another tool: 'If the work should be kept, export it first with export_photo'. That is a concrete alternative plus the condition that selects it, and it even names the format (psd) that preserves layers.

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, idempotentHint, openWorldHint), so the bar is lower. The description adds real behavioral context beyond them: the before/after proxy semantics, that 'regions' returns per-rectangle stats without a delta, and that preview output is gated by privacy.send_previews_to_llm. It still says nothing about cost or size of the proxy computation.

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 with the core purpose front-loaded before the mode breakdown, and no filler. The second sentence is dense with parenthetical asides, but each clause carries information the schema alone doesn't convey, so nothing is wasted.

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 8-parameter tool with an output schema (so return values need not be explained here), the description covers both modes, their applicable parameters, and the preview privacy dependency. The only minor gap is timing/cost expectations for proxy rendering, which is not critical for correct invocation.

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

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

Schema description coverage is 100%, so the schema already documents mode semantics, mode-scoping of region/region_a/region_b/include_previews, and defaults. The description restates mode semantics in prose and clarifies the before/after meaning, but adds little syntax or constraint detail beyond what the schema fields already say. 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?

States a specific verb and resource ('Compare before and after, or two regions') and then defines the two modes precisely, including what 'before' and 'after' mean (photo without filters vs with them). It does not, however, distinguish itself from nearby read tools such as get_histogram, inspect, or preview, so an agent gets the tool's own scope but no sibling differentiation.

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

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

The mode breakdown effectively tells the agent which variant to pick: 'before_after' for measuring filter effects, 'regions' for two rectangles on the same filtered image with the explicit instruction 'no delta (compare them yourself)'. It gives no exclusions or pointers to alternative tools, but the context for each mode 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 declare destructive/irreversible and idempotent, but the description goes well beyond them: it explains that grayscale permanently discards color, that grayscale-to-rgb does not restore it, that indexed sources are refused, that live filters block conversion, and that the no-op check precedes the refusal. This is unusually rich behavioral disclosure for a destructive mutation tool.

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

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

The core purpose is front-loaded in the first clause, with constraints and alternatives following in a logical order. It is dense and parenthetical-heavy, but nearly every clause carries actionable information, so the length is largely earned.

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 annotations covering the safety profile and an output schema covering the return shape, the description supplies everything an agent needs: refusal conditions, irreversible effects, ordering of the no-op check, and remediation paths. Nothing material 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 both parameters are already documented; the enum on mode and the image id note carry the structured meaning. The description reinforces the indexed-source refusal and conversion direction but adds little syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource (convert the photo's base color mode) with explicit directionality (rgb <-> grayscale) and scoping (indexed refused as source). An agent can distinguish this from siblings like recolor, apply_look, or manage_filters 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 explicit preconditions and routing: bake or manage_filters op=delete the live filter first, or the call REFUSES; a checkpoint is recommended when in doubt. It also clarifies ordering around the no-op case, so the agent knows exactly when a call will succeed, fail, or be a no-op.

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

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

Annotations already flag destructiveHint=true and idempotentHint=false, but the description goes well beyond them: it declares there is no undo in this session, prescribes checkpointing first, and explains that live filters, mask channels and the filter record survive the crop. The note that this is 'the one geometry change that never refuses because of masked filters' is distinctive behavioral context an agent cannot get from 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?

Four tightly packed sentences, each front-loaded with its key fact: what to crop, what it is not, that it is irreversible, and what it preserves. No filler.

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

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

The tool has an output schema, so return values need not be described, and the mutations' side effects are fully covered. Given the destructive annotation, the coverage of irreversibility, preservation semantics and the checkpoint recommendation makes the definition complete for correct invocation.

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

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

Schema description coverage is 100%, so all five parameters are already documented with their units and the width/height minimum of 1. The description only clarifies that the values are in photo pixels (schema says document pixels), which is a marginal addition. Baseline 3 is appropriate when the schema does the heavy lifting.

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 (crop) and resource (canvas) and enumerates the exact geometry parameters, distinguishing it from scaling: 'This is not a scale (use `resize`)'. An agent can tell this apart from `resize` and `crop_for_platform` 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?

Names the alternative explicitly ('use `resize`') and gives a concrete when-to-use rule ('make a `checkpoint` first when in doubt'). Both the excluded case and the recommended preceding action are spelled out, 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?

Annotations declare destructiveHint=true, idempotentHint=false and openWorldHint=true, and the description goes well beyond them: it explains subject-centred cropping with centre fallback, down-only scaling (never upscaling), a pre-emptive checkpoint with rollback on failure, and export of a download link. This is exactly the extra context needed for a destructive, non-idempotent 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 core action and outcome, then behaviour, then formats. The format enumeration is long but each entry carries loader-relevant data (dimensions), so it earns its space; the story_reel note is a minor tack-on.

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

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

With no output schema, the description does most of the work on returns, mentioning the download link and the story_reel key-content hint. A little more on the actual response shape or size of the exported file would make it fully self-contained.

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 3 baseline applies, but the description adds real meaning the schema lacks: concrete output dimensions per enum value and the note that cinema_wide is crop-only. It also explains the `focus` default logic in prose matching 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 (crop), resource (photo), and purpose (for a platform), plus the distinguishing outcome: a finished JPEG in one call. This separates it from the generic `crop` and `export_photo` siblings without requiring the schema to be opened.

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 heavily implied by the platform format list and the 'in one call' framing, which hints at the multi-step crop/resize/export alternative. However, it never names the direct sibling alternatives (`crop`, `resize`, `export_photo`) or states when NOT to use it.

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

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

Goes well beyond the annotations: filters are baked in, ALL metadata (EXIF/XMP/IPTC/GPS/thumbnail) is stripped, PSD layer-merge quirks are disclosed, approximate PSD size per layer and the 100 MiB download cap are stated, the download_url lifetime is 24 hours, and transparency defaults to white unless keep_alpha is set. This is exactly the kind of destructive/behavioral detail an agent needs before invoking.

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 format split, and every clause carries real information. It is dense and runs long in places (the PSD layer-merge sentence), but there is little padding to cut.

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 export tool with an output schema, the description supplies the missing operational context: format-specific flattening, size/download limits, link lifetime, and how to fetch the artifact. Nothing an agent needs to call it correctly 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 description coverage is already 100%, so the baseline is 3. The prose reinforces rather than extends it — keep_alpha's white-flattening and lossless/bit-depth restrictions largely duplicate the schema, though the explicit 'a download here is capped at 100 MiB' constraint adds a useful non-parameter bound.

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

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

States a precise verb+resource (write the finished photo) and immediately qualifies it by format: jpg/png/webp/tiff flattened, psd keeping layers. It distinguishes itself from open_photo and tells the agent exactly which artifact each format 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 clear context ('for finishing elsewhere') and names the sibling relationship (open_photo does not take a PSD), plus how the returned link is consumed. It stops short of stating when to prefer this over other output-path siblings such as bake or share_edit, so it is a strong 4 rather than 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?

Goes well beyond the annotations: states where the new layer is inserted (directly above target, inside its group), that gradients blend in sRGB and are undithered, that the current selection is preserved and does not clip the fill, and how the layer-limit accounting works. Minor gap: it does not say what happens on failure or how the operation is undone, despite destructiveHint=false and non-idempotency.

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

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

Front-loads the core action and placement rule in the first sentence, then layers constraints, exclusions, and returns in a logical order. It is dense and slightly repetitive against the schema (sRGB blending and stop count appear twice), which keeps it just short of a 5.

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 14-parameter mutation tool with nested point/stop objects, an output schema, and full annotation coverage, the description covers insertion position, masking behavior, gradient color space, selection interaction, and layer-size accounting. Nothing an agent needs to call this 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. The description largely restates schema content — '2-8 colour stops', 'mask (a channel name)', 'mode color tints without touching lightness' — all of which already appear in the property descriptions, adding little beyond confirming defaults like start/end positions implicitly.

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 ('Add a NEW layer') plus the resource and the three fill operations, so the agent knows exactly what is produced. It also distinguishes itself from `add_adjustment`/`add_effect` style siblings by naming the fill-type enum inline and explicitly excluding `retouch`.

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?

Contains an explicit when-not with the replacement: 'Do NOT use for painting strokes or touching up pixels; use `retouch` for that.' It also gives a task-level recommendation ('mode color ... the usual choice for recolouring'), routing the agent away from the `recolor` sibling for that intent.

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 (readOnly, idempotent, openWorld, non-destructive), but the description adds real behavioral context beyond them: return format, best-first ordering with scores, and the key trait that it 'never picks' because multiple candidates may mean multiple objects or a wrong match. This ambiguity disclosure is exactly what an agent needs and is not captured by annotations.

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

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

Front-loaded with the purpose, then the return shape, then the workflow caveat — three dense, purposeful sentences with no filler. Slightly compressed but every clause 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?

With no output schema, the description carries the burden of explaining returns and does so (candidate boxes [x1,y1,x2,y2] in document pixels, best first, with scores). The downstream workflow is also covered, leaving only minor gaps like the meaning of the `max` cap.

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 80%, so the schema already documents word, image, layer, and layer_id. The description adds no syntax or format detail for parameters beyond the implied 'by name' mapping to `word`, so the baseline of 3 applies.

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

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

States a specific verb+resource ('find things by name') and immediately distinguishes itself from select_with_ai by noting it 'never picks'. The agent can tell this is a candidate-generation tool, not a selection tool, 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?

Explicitly routes the workflow: check the returned boxes ('preview with a region') before passing one to 'select_with_ai target=object'. It names the downstream alternative and the condition that selects it, so the agent knows both when to call this and what to do next.

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 readOnly/idempotent annotations it discloses timings (0.3 s proxy vs ~4 s on 24 MP), a real risk (timeout restarts the editing session and loses unsaved work), a measurement caveat (small clipped highlights under-counted on the proxy), and the luminance weighting model. That is exactly the 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?

Long but dense and front-loaded with what is returned before the cost/risk discussion. Some redundancy — the timeout warning and exact-mode timing are restated almost verbatim in the schema's `exact` description, so a sentence could be trimmed without loss.

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 this only needs to explain how to read the result, and it does: bin indexing, clipping detection, luminance weighting, and the proxy-vs-full-resolution accuracy tradeoff. An agent has everything needed to call it correctly and interpret the output.

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 would be 3; the description still adds interpretation the schema lacks, notably `bins[v]` = pixel count at value v and the pixel-count-at-0/255 clipping signal, plus a one-line summary that region and mask narrow the measurement. Not a full 5 since the individual parameter behaviors are already well covered by 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?

Names a specific verb (statistics) and enumerates exactly which statistics — mean, median, percentiles, 256-bin histogram — per channel, with the 'ONE render' cost note clarifying it is a single pass. This clearly separates it from siblings like inspect, preview and overview.

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: default fast mode for iterating, `exact: true` as the final clipping check before `export_photo`, and `checkpoint` first if there is unsaved work. It also names the two sibling tools that bookend its use.

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 openWorldHint, so safety is covered. The description adds real behavior beyond that: the `checked: false` lazy state, that size is only read when `open_photo` first opens a photo, and that uploads aggregate across any signed-in connection. This is meaningful extra context, though return-format specifics are largely delegated to the output schema.

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

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

It opens with the front-loaded 'Read-only.' and then walks the modes in order, with each sentence carrying specific information. It is slightly dense and longer than strictly necessary, but nothing 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?

With an output schema present and annotations covering the safety profile, the description only needs to explain mode selection and edge cases, which it does thoroughly (lazy size, cross-connection uploads, server scoping). 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. The description goes further by explaining the semantics of each `what` value in terms of the returned data (image ids vs upload handles/sizes/expires_at vs font names) and confirms `filter` applies only to fonts, adding meaning beyond the raw enum values.

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 ('lists') for each distinct resource selected by the `what` enum: open photos by image id, uploads with handles/sizes/expires_at, and installed fonts. It cleanly enumerates the three modes so an agent knows exactly what it returns, and it references `open_photo` to distinguish the read path from the open path.

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 clear: the `what` value selects the mode and `filter` narrows fonts, with the description explaining each context. It also scopes ownership ('uploads and open photos belong to this server; a photo opened through another connector stays with that connector'), which helps decide relevance. It stops short of explicitly naming when to prefer this over siblings like status/overview or check_listing.

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, but the description goes far beyond that with concrete refusal rules (delete refused on sole layer, merge_down refused on hidden source, flatten refused on any hidden layer including inside hidden groups), reporting behavior (rasterized_text, has_alpha: false, discarded_hidden_layers), and no-undo warning. This is exactly the added 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?

The single dense paragraph is front-loaded with addressing rules and the no-undo warning, which is good, but it is very long and packs per-op rules into semicolon-laden prose that is hard to scan. The schema already documents ops individually, so much of this is duplicated rather than summarized.

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-param, 9-op destructive tool with no undo, the description covers refusal conditions, side effects, reporting, addressing precedence, and the checkpoint escape hatch. With an output schema present, return-value detail is appropriately left out. Nothing an agent needs to call 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: the default target of select, the name-uniqueness suffix rule (' 2', ' 3'), the 'color' mode HSL distinction, and the parent_group/to_top_level interaction. It falls short of 5 only because a few params (opacity, visible, position defaults) 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 description opens with a specific verb-resource statement ('Layer management') and enumerates all nine ops, each with a distinct meaning. It explicitly distinguishes itself from siblings by noting 'there is no separate group tool,' which prevents an agent from searching for one.

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

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

Gives explicit when-to-use and when-not-to-use guidance across ops: 'checkpoint first when in doubt,' 'Every op except select changes pixels... there is no undo,' and names the specific failure conditions for delete, duplicate, reorder, merge_down, and flatten. It routes the agent to bake before duplicate when an Editmamei filter is present.

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 non-idempotent, and the description reinforces this with real consequences: apply 'bakes the mask into the layer's transparency: a cut-out', and create replaces any existing mask. It adds the crucial semantic that the mask travels with the layer, which annotations cannot express. No note on undo/reversibility or scoping of the bake, so not 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?

Front-loads the definition of what a layer mask is, then packs the four operations and a workflow into one dense paragraph with no filler. The semicolon-chained operation list is efficient, though slightly choppy to parse on first read.

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 described, and the description covers the operation set, source options, and a canonical workflow. Remaining details (layer vs layer_id precedence, invert scoping) are handled by the fully-populated schema, so the description is adequate without being exhaustive.

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 naming the concrete source values and explaining where a channel comes from ('a saved selection channel, e.g. from select or select_with_ai'). That provenance is genuinely new information not present in 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 the specific resource (a layer mask, explicitly 'real' and layer-bound) and enumerates the four operations it performs: create, delete, apply, invert. The parenthetical '(it moves with the layer)' distinguishes it from selection-style masking, so an agent can separate it from siblings like modify_selection without opening 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?

Gives concrete when-to-use guidance — create masks from a saved selection channel produced by `select` or `select_with_ai`, or from white/black/alpha/grayscale — plus a worked workflow ('place the photo as a layer, select on that layer, then create its mask from the channel'). It never states when *not* to use this tool or contrasts it explicitly with a masking alternative, so it stops short of 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?

Goes well beyond the annotations (readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false). It discloses non-obvious behaviors: the origin image is left intact, the result returns a new image id, the subject-centered crop logic, no-upscaling constraint, seamless joining mechanism, and a performance warning for 10-slide carousels.

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?

Well-structured and front-loaded with the core action and return value, then parameters, then implementation details. It's dense but every sentence provides actionable information. Slightly long, but the length is justified by the non-trivial behavior being disclosed.

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 complexity of the operation, no output schema, and rich annotations, the description covers everything an agent needs: input requirements, parameter behavior, processing logic, output structure (download links), and a performance caveat. Nothing critical 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?

Adds meaning beyond the 100% schema coverage: explains the '4:5' and '1:1' ratios with pixel dimensions (already in schema but reinforced), and clarifies what the default slide count means (as many as the photo's width allows at full height). The 'format' parameter is left to the schema, which is fine given full coverage.

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

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

States a specific verb (split) and resource (wide photo into seamless slides) with the exact outcome (one download link per slide, in order). This is clearly distinguishable from siblings like make_grid, make_story, and crop_for_platform.

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 photo requirements (wide photo) and use case (Instagram carousel) are clear, and the parameter behavior is well-explained. However, it doesn't explicitly contrast with alternatives like make_grid or crop_for_platform, leaving the agent to infer when this specific approach is preferred over siblings.

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

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

Annotations only declare the generic safety profile (not read-only, open-world, non-idempotent, non-destructive). The description goes well beyond: it discloses that the grid opens as a NEW image with live layers, that a failed source aborts the whole grid with a named error, that the new image is closed on failure so 'nothing is left open', and that explicit widths over server pixel/layer limits are refused. That is exactly the side-effect and failure-mode context an agent needs.

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

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

It is a long single paragraph, but it is front-loaded with the purpose and then walks parameters in backticked order, so it scans well. Nearly every clause adds operational detail; it would be tighter split into a purpose line and a parameters block.

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 8 parameters, no output schema, and a mutation-style side effect (creating an image), the description covers the essentials: what is returned (a download link and the new image's id, which is in the result) and what happens on failure. Only minor gaps remain, such as the exact shape of the result object and any ordering of returned links.

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 adds real meaning: `sources` may be upload: handles (with a cross-reference to request_upload) or URLs fetched first, `layout` sizes require exactly that many photos, `auto` picks the most square grid and leaves background-filled cells, and photos are scaled to COVER and clipped. It also explains the width-vs-server-limit interaction that the schema's 200-10000 range does not.

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 with scope: 'Make a collage or multi-panel meme from 2 to 9 of the user's photos and get one download link.' An agent can see it produces a single new composite image, distinct from single-photo edits. However, it never names or distinguishes itself from close siblings like make_carousel, make_meme, or make_story, 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?

Usage is implied through the constraints (2-9 photos, upload handles vs URLs, layout counts) but there is no explicit when-to-use/when-not statement and no routing to alternatives such as make_carousel or make_meme. The agent must infer when a grid is the right tool from the parameter descriptions alone.

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 (destructiveHint=true, non-idempotent, open-world), and the description adds substantial context beyond them: a checkpoint is taken first and the image is restored on failure, success leaves the meme as live editable text layers, the result returns the plain photo's checkpoint id, oversized inputs are refused, and long text is shrunk then clipped with the result saying so.

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 output are front-loaded, which is good, but the body is a dense wall of text and the font fallback enumerations (Anton, Oswald Bold, Bebas Neue, League Gothic, Inter, Roboto, Open Sans, Playfair Display, Times) are low-value padding that hurts scannability without changing how an agent calls the tool.

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 nine parameters, no output schema, and destructive non-idempotent semantics, the description carries the full burden and does it: it describes the return payload (download link plus checkpoint id), the failure/revert behavior, the size limit, and per-style rendering. An agent has everything needed to call it correctly on the first attempt.

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 meaningfully expands it: it maps top/bottom/caption/title/subtitle to the layouts that consume them and explains typography, alignment, casing and sizing for each style (e.g. classic is white-with-outline, centered, fitted to a 92% x 22% box). It does not restate the format or uppercase enums beyond what the schema already documents.

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 verb (turn into a meme), the resource (the user's photo), the scope (three layouts), and the output (a download link). It is trivially distinguishable from make_sticker, make_grid, make_carousel and make_story, all of which are separate meme-adjacent siblings.

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

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

It supplies real operating context: the input must be a photo id, photos over ~14 MP are refused by the pixel cap and must be resized first, and text should be kept short or it will be shrunk and clipped. It stops short of naming alternative tools or stating when NOT to reach for it, so it lands just below the explicit when/when-not/alternatives bar.

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, it discloses non-obvious behavior: the source photo is left untouched and the call restores it, so the result carries a NEW image id, plus the full processing pipeline (find subject, cut on a copy, add border, add shadow unless shadow is false, crop with room, keep transparency). This is consistent with destructiveHint=false and readOnlyHint=false and adds genuinely useful context.

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 output are front-loaded, and the pipeline/constraint sentences each carry real information. It is slightly long and repeats schema-level default values (border, border_color, shadow), which keeps it from a 5.

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

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

With no output schema, the description still explains the return value (a transparent PNG/WebP download link plus the new image id), the destructive/restore behavior, the layer-count constraint, and the rotated-subject edge case. 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 schema already documents all six parameters with defaults and enums. The description mostly restates these (border default 2.5% of the subject's long side, border_color #ffffff, format keeps transparency) and only marginally extends meaning via the subject_up orientation hint, so the baseline 3 applies.

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

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

The description opens with a precise verb+resource: cut the subject out as a die-cut sticker and return a transparent PNG/WebP download link. The output (bordered, shadowed die-cut sticker) is unmistakably distinct from the sibling generative tools (make_meme, make_grid, make_carousel, make_story), so no confusion is possible even without naming an alternative.

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

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

It gives clear preconditions and context — the image must have a single layer, the selection service is required, and subject_up should be set when the subject is not upright — which tells the agent when the call will work. It never states when to prefer this over a sibling or any exclusion cases, 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 flag destructiveHint=true and readOnlyHint=false, but the description goes well beyond them: it discloses that a checkpoint is taken first and the image is restored on failure, that on success the story persists as live layers, and that the result carries the checkpoint id. It also documents the safe-zone geometry (top 250 px / bottom 340 px unsafe bands) and the single-layer and panorama constraints.

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 opening sentence front-loads output type and dimensions, and every subsequent sentence carries required information (background modes, safe zone, constraints, checkpoint behavior). It is a dense single paragraph rather than organized sections, and the final checkpoint sentence is a run-on, which costs a point on 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?

With no output schema, the description still explains the returns: one download link plus the checkpoint id for the plain photo. Given seven parameters and destructive/open-world behavior, it supplies the constraints, defaults, and side-effect behavior an agent needs to call it correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuine meaning the schema lacks: blur defaults to a blurred scaled-up copy of the photo, gradient runs top-to-bottom with gradient_top defaulting to white and gradient_bottom to a 15% darker shade, and caption styling (white bold with black outline, fitted above the handle). This meaningfully extends the terse schema descriptions.

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

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

States a precise verb+resource ("Make a 9:16 story frame (1080x1920) from a photo") with exact output dimensions and format, which clearly separates it from siblings like make_meme, make_grid and make_carousel. An agent knows 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?

Gives clear operative context and constraints: the image must have a single layer, and a panorama (very wide/tall photo) cannot take the blurred background and must use a color or gradient. It never names a sibling alternative or explicitly says when another tool is preferred, so it stops short of explicit routing.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=false, so safety is partly covered. The description adds valuable specifics beyond that: delete is permanent with 'no undo', set_visibility is non-destructive, and no reorder API exists. Slightly redundant with the destructive hint but adds real operational context.

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 op enumeration, then usage and constraints in logical order; every sentence carries information. Some minor overlap with the schema's op description (layer inclusion, no reorder), which is the only reason it isn't a 5.

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 formats need not be explained, and the description still covers all three ops, their side effects, and the absence of apply/reorder. Complete for a multi-op mutation 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 100%, so the schema already documents op, image, visible, and filter_id plus the editmamei/readback source semantics. The description largely restates op behavior already in the enum description, 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?

Opens with a specific verb+resource plus an enumerated op list ('Manage the filter stack: op list | set_visibility | delete'), and explicitly distinguishes itself from siblings add_adjustment/add_effect for creation/editing. An agent can tell what this tool does 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: 'list' is the way to check what add_adjustment/add_effect produced and to find a filter's id for re-edit; set_visibility vs delete are contrasted by reversibility. It also names the alternatives for the absent operations ('no apply... no reorder: delete and re-create').

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, readOnlyHint=false, idempotentHint=false, and openWorldHint=true, so the safety profile is carried. The description adds a genuine behavioral precondition not in the annotations: refusal when the target channel already confines a filter. It does not explain in-place overwrite semantics or auth/limits, so not a full 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 tightly written sentences, purpose front-loaded, with the refusal constraint second. The op enumeration slightly duplicates the schema enum, which keeps it from a perfect score, but there is no wasted prose.

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, rich annotations, and 100% schema description coverage, the description covers what an agent needs: what it edits, the operations, and the one refusal condition. It omits in-place vs output write behavior, but that is largely covered by the schema's output parameter.

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 enum values, px requirements, caps, and the optional output/channel semantics are fully documented in the schema itself. The description only restates the op list and adds no parameter meaning beyond the schema, which matches the baseline 3 when the schema does the heavy lifting.

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

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

The description uses a specific verb+resource (modify a saved selection channel) and enumerates the seven operations, making the scope clear without opening the schema. It implicitly distinguishes itself from siblings like select_with_ai and selection_preview, which create or preview selections rather than edit a saved one.

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

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

The only usage guidance is the guard 'Refused if the target channel already confines a filter,' which tells the agent a precondition but not when to choose this over alternatives. No explicit when-not or sibling routing (e.g., selection_preview, select_with_ai) is provided.

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

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

Goes well beyond the annotations: it discloses the 20-look / 50-filter caps, that saving under an existing name replaces it, that only recreatable settings are kept while masked/disabled/foreign filters are skipped and reported, that apply takes a checkpoint and rolls back on refusal, and that nothing-to-save is an error. This is the kind of operational detail an agent must have before mutating a user's photo.

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 opening sentence front-loads purpose and the rest is organized op-by-op with consistent op=... labels, so it is navigable despite being a single dense paragraph. A tight per-op bulleted layout would scan faster, but no sentence is filler.

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

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

With no output schema, the description carries the return-shape burden and does so: list returns step counts and save times, unreadable looks are reported rather than used, and skipped filters are listed in the save result. Error, limit, and rollback behavior are all covered, leaving nothing an agent needs before calling.

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 the schema lacks: which params each op requires, that layer is required only for multi-layer images, that layer_id takes priority, and that replace forces an earlier apply to be removed first. That is more than restating 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 resource ("Your saved looks: filter recipes kept on this server, for you only") with a clear scope and ownership qualifier, and the sub-operations are enumerated explicitly. It is clear what the tool manages, but it never differentiates itself from the sibling apply_look, which an agent could reasonably confuse with op=apply here.

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?

Each op is given explicit when/why guidance: save reads live filters from a layer and requires a named layer when multi-layer, apply puts a look back on a layer with replace semantics, list is for enumeration, delete removes the definition but leaves already-added filters on the photo. It also names the prerequisite sibling (manage_filters op=list) and covers the batch-invocation case.

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 tell the agent this is a non-readOnly, non-idempotent, non-destructive, open-world write. The description goes well beyond them by disclosing server-side resource limits, the refusal of 32-bit precision, the reduced size ceiling at 16-bit, and the two-photos-open ceiling — genuine operational constraints an agent must know before calling.

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 dense paragraph, front-loaded with the verb and the sibling disambiguation, followed by parameter notes and limits in a sensible order. Every sentence carries information, though the restatement of schema defaults (rgb, white, Background) is mildly redundant.

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 and the description sensibly just notes the return shape mirrors open_photo rather than re-documenting it. Limits, mode, fill and precision behavior are covered, leaving only the unresolved discrepancy between the prose '32 is refused' and the schema's 32-bit cap as an incompleteness.

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 width/height/mode/fill/name are already fully documented and the description largely restates them. It adds a behavioral note about precision usage, but that note ('32' precision is refused on this server) conflicts with the schema, which documents a 60 MP 32-bit mode — the added meaning is unreliable as a result.

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

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

States a precise verb+resource ('Create a new, empty photo from scratch') and immediately differentiates it from the nearest sibling by naming open_photo as the file-based path. An agent can distinguish this from open_photo, place_image, or make_* 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?

Names the alternative ('not from a file: that is `open_photo`') and lays out the conditions under which this tool will or will not work: the workspace pixel limit, '32' precision refused, '16' only up to a smaller size, and a hard cap of 2 open photos. That is explicit when/when-not/alternative guidance rather than 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 flag this as a non-read-only, non-idempotent, open-world operation, so the bar is lower. The description adds real behavioral context beyond them: the two-photos-open-at-once limit, cross-connector scoping ('a photo opened through another Editmamei connector stays with that connector'), supported format list, and that RAW is restricted to the larger workspace.

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 essential purpose is front-loaded in the first sentence, and the remaining sentences each carry functional detail (formats, limits, scoping). It is dense but not padded, though a couple of clauses are run-on and could be tightened.

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 description covers the full operational surface for a 3-param tool with a nested object: sources, formats, RAW development, precision, concurrency cap, and server scoping. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description still adds meaning: the accepted `source` forms (upload handle, upload name, public https URL, `sample:<name>`), that `raw` errors for non-RAW sources, and that `precision` promotes bit depth before grading. These go 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 ('Open a photo') plus its key output ('get its image id, which every other tool uses'), which immediately distinguishes it from siblings like close_photo, request_upload, and inspect. The role in the workflow is unmistakable.

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 strong context on what qualifies as a `source`, routes the agent to `request_upload` for upload handles and to `inspect what=uploads` for sample photos, and states an exclusion ('It never opens a file path'). It stops short of an explicit 'use this before adjusting/exporting' sequencing statement, but the routing guidance 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 idempotentHint, and the description partially repeats 'read-only', but it adds genuinely new behavioral context: it needs no photo loaded and is static documentation. For a zero-param doc tool this is adequate disclosure beyond the 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-loads the purpose, then enumerates covered topics, then closes with constraints. The topic list is fairly long but each item signals real content, so it mostly earns its place rather than being 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, return values need no explanation, and the description already names the content areas plus the read-only, no-photo nature. Nothing an agent needs to decide whether to call it is missing.

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

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

The schema has zero parameters, so there is nothing for the description to disambiguate; baseline is 4. The description correctly signals the no-input nature by stating it needs no photo.

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 ('a static brief on how this server works') and enumerates exactly what it covers, distinguishing it from the action-oriented siblings like add_adjustment or edit tools. The agent can immediately tell this is orientation content, not an operation.

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

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

Gives a clear when-not condition ('A single simple edit doesn't need it') and notes it needs no photo, which helps an agent decide whether to spend a call on it. It stops short of naming an explicit alternative tool, but no sibling serves the orientation role, so the guidance is effectively complete.

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 read-only, destructive, and idempotent hints, the description adds rich behavioral context: checkpoint/rollback on failure, layer replacement on re-run, strength=0 removal, channel side effects, layer naming collisions, and known gaps. This goes well beyond what annotations provide and gives an agent confidence about mutating 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 front-loaded with the overall purpose but then becomes extremely long, diving into implementation details (YCbCr rules, channel names, exact blur percentages) that an agent may not need for tool selection. It is well-structured by type but likely contains more detail than necessary for efficient invocation.

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 high complexity (three effect types, layer handling, external upload dependency, no output schema), the description is remarkably complete: it covers parameter requirements, side effects, failure recovery, and known limitations. An agent has all information needed 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 description coverage is 100%, so the baseline is 3. The description adds substantial meaning beyond schema text—e.g., how strength maps to blur radius, opacity, and curve intensity per type—plus the requirement conditions for `sky`, `layer`, and `subject_up`. This extra semantic depth warrants a 4, though the schema already covers the basic parameter purpose.

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 verb ('Effects on a photo'), resource ('photo'), and output form ('as named layers, nothing is flattened'), immediately distinguishing it from tools that bake or flatten. It also names a required follow-up sibling (export_photo), so an agent can place it correctly in a workflow.

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 clearly indicates when each effect type is appropriate (portrait mode, skin smoothing, sky replacement) and states that export_photo is needed for a file. However, it does not explicitly compare itself to sibling effect tools like add_effect or apply_look, leaving some alternative selection 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 annotations (which only flag it as a writable, non-idempotent, open-world op), the description discloses multi-page TIFF handling (only ONE picture placed), workspace pixel/layer limits that constrain placement, and the server-scoping of uploads versus other connectors. These are non-obvious behavioral constraints an agent could not infer from 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?

The purpose is front-loaded, then details follow in a logical order (source, geometry, cut-out recipe, multi-page caveat, limits). It is dense and long, but nearly every clause carries information; a small amount could be trimmed without loss.

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, non-idempotent compositing tool with an output schema already present, the description covers the source contract, geometric defaults, edge cases (multi-page files), workflow integration, and resource limits. 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 already 100%, so the baseline is 3, but the description adds meaning by mapping x/y/width/height/name/position to the semantics of 'layer op=create' and restating the 'upload:<id>' source format. This cross-references an existing contract rather than merely echoing 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 states a specific verb and resource ('Place another uploaded photo into an open photo as a NEW LAYER') and even parenthetically frames the operation as compositing, which distinguishes it from adjustment/filter siblings. An agent can tell what this does 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 explains the source format (upload handle from request_upload, or a built-in sample via inspect what=uploads) and gives an explicit workflow recipe for cut-outs using select_with_ai and layer_mask. It references 'layer op=create' as the semantic model but never states when NOT to use this tool versus those siblings, so it stops short of full alternative routing.

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

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

Goes well beyond the readOnly/idempotent annotations: it discloses latency (~1/3 second at 1024px), the byte/context cost ('previews are most of the bytes a session returns'), the proxy-vs-exact tradeoff, and that out-of-bounds regions are refused rather than clamped. These are exactly the traits an agent needs to budget calls.

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

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

Four tight sentences, front-loaded with the core action, then cost, then routing, then the region nuance. No sentence is filler; the latency and byte-cost details are load-bearing for call budgeting.

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 the return type needn't be described further, and the description still covers performance, cost, exactness, and refusal behavior. Nothing an agent needs to call this 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 already 100%, so baseline is 3, but the description adds real meaning: region produces an exact full-resolution crop rather than the approximate whole-image proxy, and the 1024px latency figure gives max_px practical weight. It does not restate the coordinate syntax, which the schema already covers.

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 — render the filtered photo as a JPEG — and explicitly frames it as the visual counterpart to get_histogram. An agent can distinguish it from numeric/sibling inspection 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?

Explicitly routes between alternatives: prefer get_histogram for a numeric check, use this for spatial questions, and use region when an exact full-resolution crop is needed. It names both the alternative and the condition that selects it.

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

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

Beyond the annotations (destructiveHint=true, openWorldHint=true), the description discloses real behavior: it takes a checkpoint first and restores the image on failure or when no product is found, it exports JPEG (PNG only when the background is transparent), and color_strength is auto-eased so strong colors don't clip. The single-layer precondition and amazon-specific overrides further reduce surprise.

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 a one-sentence summary, then dense but information-bearing clauses; almost every phrase carries a default, range, or constraint. It is a long run-on paragraph rather than a structured list, which costs a point but wastes little.

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 10-parameter, no-output-schema tool, the description covers the pipeline, output format, per-marketplace sizing, all option domains, defaults, and failure/rollback behavior. Nothing essential for calling it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds cross-parameter meaning the schema does not: amazon forces a white background and disables shadow, gradient_bottom defaults to 15% darker than gradient_top, 'upload:<id>' supplies another photo as background, and fill is bounded 0.5-0.95. These constraint interactions justify a bump 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 concrete verb+resource+outcome ('Turn a product photo into a marketplace-ready listing image in one call') and then enumerates the full pipeline it performs (find, cut out, frame, background, shadow, color, export). An agent can distinguish this from generic siblings like export_photo or crop_for_platform 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 rich selection context: per-marketplace dimensions and constraints, 'amazon allows only white', shadow auto-off for amazon, and the 'image must have a single layer' precondition. It does not, however, explicitly route the agent away from the visually similar siblings (crop_for_platform, export_photo) or say when this tool is the wrong choice.

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

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

Goes well past the annotations: it details the internal pipeline (tone slide, LCh tint, mask export, layer removal so the document is left as it was), the lightness-point fallback rule, that the active selection is replaced, that links expire, and the partial-results-on-timeout behavior. Annotations are non-destructive and non-read-only, and the description confirms the document is restored.

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

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

Dense but front-loaded, with purpose and output stated first, then mechanism, then caveats (layer requirement, selection replaced, timeout, link expiry). Almost every sentence carries new information, though the mechanism sentence is long and can be skimmed poorly.

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

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

There is no output schema, and the description fully compensates: it describes the per-color link, the measured average color and its distance from the target, the fallback reporting, and failure/timeout semantics. Nothing an agent needs to call it correctly appears to be 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 frames `word`/`box`/`channel` as three alternative ways to identify the object, explains that the server resolves `word`, and that `names` maps positionally to colors. It does not clarify `format` or parameter interaction beyond that.

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 ('Show one object in several colors, and get one download link per color, in one call'), plus the concrete output shape. It is clearly distinguishable from siblings like apply_look or select_with_ai.

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 real prerequisites (needs a single-layer image, or name the layer), points to the producing sibling for `channel` (select_with_ai target=object), and explains the retry path when time runs short. It does not explicitly contrast itself with color-adjacent siblings such as apply_look or product_shot, so it falls short of 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 say readOnly=false, destructiveHint=false, idempotent=false, openWorld=true. The description goes well beyond: it discloses that a NEW layer is created, that deleting that layer undoes the operation (non-destructive in practice, consistent with destructiveHint=false), the 5-15s runtime, and two pre-flight refusal conditions (object larger than the AI's square, or hole exceeding a quarter of the AI's working area).

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?

Information-dense and front-loaded: purpose, target specification, mechanics, undo, verification, limits, and exclusions in that order. It is a long single block, and a couple of clauses (mask-growth arithmetic, preview/compare) could be tightened, but essentially every sentence carries decision-relevant content.

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 7-parameter mutation tool with no output schema, the description covers everything an agent needs: how to target the object, where the result lands, how to undo, how long it takes, failure/refusal conditions, and when not to use it. Nothing material 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 baseline is 3, but the description adds interaction semantics the schema cannot: the three target-specification routes are alternatives, the server resolves `word` itself, and the new layer is placed directly above the cut layer 'the top of the stack when no `layer` is given'. It also clarifies grow_px's default rationale (0.5% of long side, max 50).

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+resource ('removes an object and fills in the background') and immediately names the AI-based mechanism, distinguishing it from siblings like retouch and fill. It also names the alternative (retouch spot_heal) for the small-blemish case, so an agent can route without opening a schema.

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

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

It states explicitly how to specify the target (word/box/channel), when to prefer each, and a clear negative case: 'Do NOT use for small blemishes or dust (retouch spot_heal is faster).' It also tells the agent how to verify the result (preview or compare), which is genuine usage guidance rather than restated mechanics.

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 set readOnlyHint=false and idempotentHint=false; the description goes far beyond them, disclosing one-time link semantics, the 10-photo cap, the 5-minute idle close / 15-minute expiry, 40 MB and RAW 100 MB limits, the curl 403/'host not allowed' path with `if_curl_blocked`, and cross-connection visibility. 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?

It is front-loaded with the core purpose, and almost every sentence carries actionable detail (limits, curl fallback, inspect cross-reference). However, it is dense and long for a zero-parameter tool, and the `inspect`(what='uploads') reference is repeated, which slightly dilutes conciseness.

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 an output schema exists, the description needn't explain returns, yet it still clarifies the key result fields (page_url, curl, if_curl_blocked, upload_id). Combined with the limits and expiry rules, nothing an agent needs to call this 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?

There are zero input parameters, so per the rubric the baseline is 4; there is nothing for the description to disambiguate in the schema. The description's detail about output fields is not input-parameter 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?

States a specific verb and resource: 'Get a one-time way to send photos from the user's device to this server.' It then distinguishes itself from siblings by naming `inspect` (what='uploads') for already-sent photos and `open_photo` for online images, so an agent can route correctly without opening 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?

Explicitly tells when NOT to call it: 'a photo already there needs no new link' (use `inspect`) and 'For an image already online, pass its https:// URL to `open_photo` instead.' It also covers the sandbox-blocked case and cross-connection opening, 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?

Goes well beyond the annotations (destructiveHint, non-idempotent) by disclosing that the operation is irreversible with no undo, that it refuses with masked/foreign filters, that large targets can take tens of seconds, and that a timeout restarts the session and loses unsaved work. It also notes the workspace pixel-limit constraint on the result.

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 and sibling distinction, then layers refusal conditions and timeout risk in a logical order. Efficient per sentence, though the checkpoint advice appears twice ('when in doubt' and 'before an aggressive resize'), a minor redundancy.

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 explained. The description covers everything else an agent needs for a destructive, timeout-prone mutation: reversibility, refusal conditions, ordering constraints, and the workspace pixel limit.

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 width/height/long_edge descriptions already carry the semantics. The description restates the same rules (width+height stretches, one alone keeps aspect, long_edge targets the longer side) without adding new syntax or format detail, so the baseline 3 applies.

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

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

States a specific verb and resource ('Scale the whole photo up or down') and immediately distinguishes itself from the sibling 'crop' by name. An agent can tell resize apart from crop, canvas_size, and transform_image 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?

Names the alternative to avoid ('not a crop, use crop'), spells out the exact parameter combinations for the three scaling modes, and states explicit preconditions and refusals (masked filters, filters made outside Editmamei). It even prescribes the ordering: resize before adding masked filters, not after.

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 say destructive/open-world/non-idempotent; the description adds the real behavioral context: a 'Retouch' copy is created above the layer on first call and reused while it stays adjacent, selection is kept and does not clip, and the tool refuses groups, text layers, locked/hidden layers, indexed photos and out-of-layer points. It also warns about a per-call work limit and how to split calls, which annotations cannot convey.

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

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

Dense but well front-loaded: method semantics first, then target/placement, then refusals, then limits. The object-removal warning is stated twice (mid-paragraph and again as the final sentence), which is redundant for a description this long.

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 12-parameter, nested-object, destructive tool, the description covers placement semantics, failure modes, work limits and recovery advice; the output schema exists and the return-value sentence is just a convenience pointer. Nothing needed 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; the description earns above that by adding cross-parameter meaning, notably the `target` decision rules tied to layer opacity/mode/mask and the fact that all coordinates are photo pixels and the source is chosen before any paint. Minor gap: `hardness`, `brush_size` and `layer_id` precedence 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?

Specific verb-plus-resource with the three methods (heal, clone, spot_heal) defined inline and differentiated from each other. It also explicitly distinguishes itself from the sibling `remove_object`, so an agent can route between them without opening 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?

States when to use each method (blemishes/dust vs exact copy vs auto-sourced spots), when `in_place` is required (below 100% opacity, non-Normal mode, layer mask, semi-transparent pixels), and gives an explicit exclusion: 'Do NOT use for removing whole objects (use `remove_object`)'. Alternatives and boundaries are named, not inferred.

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

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

Beyond the annotations, the description discloses per-step time limits, a sequence-wide time budget checked before each step, the three on_error strategies with rollback checkpoint/restore behavior and new image ID, rollback refusal conditions, and return-mode behavior including preview image handling. This is unusually detailed behavioral context for a destructive, open-world tool.

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

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

The description is front-loaded with purpose and constraints, and nearly every sentence earns its place given the tool's complexity. It is dense and could be more scannable with formatting, but there is little redundancy.

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

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

With no output schema and a complex compositional tool, the description covers return modes, error handling, time limits, image ID changes, and preview behavior. An agent has enough information to invoke run_steps correctly in normal and failure 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 coverage is 100%, so the baseline is 3, but the description adds substantial meaning beyond the enum labels: it explains the effects of stop/continue/rollback, the checkpoint and new image ID behavior, and how summary versus full affects returned results. That is meaningful semantic expansion for the on_error and return parameters.

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

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

The description opens with a specific verb and resource: "Run several edits in one call." It immediately clarifies the mechanism as an ordered list of steps, each naming a tool the agent already has, and distinguishes itself from the many sibling tools that cannot be composed.

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 an explicit rule: use it when you already know the steps and do not need to look in between, and for exploratory work call tools one at a time. It also names the sibling tools that cannot be steps, so the agent knows exactly which alternatives to use directly.

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