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

With no annotations, the description carries the full burden and does well: it states it is non-destructive, 'never declares artistic PASS automatically', 'does not modify the PSD', and that it registers real evidence (evidence_operation_id and SHA) as a side effect. What is missing is whether materialize_path actually writes a file to disk and any preconditions around the pinned document state.

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 critical output information is buried in the middle rather than front-loaded, and the opening clause is the least informative sentence in the whole definition. There is mild redundancy between 'non-destructive preview' and 'does not modify the PSD', though the length is not excessive for the amount of behavior conveyed.

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 3-parameter analysis tool with no output schema, the description does a good job enumerating returns (full grayscale JPEG, downsampled thumbnail, luminance summaries, evidence_operation_id and SHA) and the safety profile. Only the size/scale parameter and file-writing side effect are left under-specified, which is minor.

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 67%, so the baseline is 3. The description reinforces document_id as the analyzed pinned preview and links materialization to the evidence-registration behavior, but max_dimension_px is never mentioned in the description and the description adds no format/semantics beyond 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 concrete middle of the description ('Returns a full grayscale JPEG, a low-frequency downsampled grayscale thumbnail, and descriptive luminance summaries') makes the resource and output legible, but the opening sentence is opaque jargon ('exact delivered Guard frame', 'materialized grayscale/luminance evidence', 'Director updates') that an agent must decode. It never names a sibling (e.g. photoshop_get_preview or photoshop_guard_review_image) to differentiate itself, leaving overlap with those tools unresolved.

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 hints at the use case ('for Art Director review', 'major-form claims can be checked independently of surface activity') but gives no explicit when-to-use, when-not, or alternatives to the similarly-scoped preview/review siblings. An agent cannot tell from this text when to reach for this tool instead of get_preview.

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?

With no annotations, the description carries the full behavioral burden and does disclose key traits: it is a pure computation that does not touch Photoshop, and it returns per-point normalized error plus mean/RMSE/max. It leaves out edge-case behavior, such as what happens when point names do not match or how normalization is defined, which matters for a comparison 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?

Three sentences, front-loaded with the core action and return values, followed by a useful scope constraint. Every sentence earns its place and there is no repetition or filler.

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

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

For a tool with nested objects, four required parameters, no annotations, and no output schema, the description covers purpose, return shape, and purity of computation. It is not complete enough to reliably guide invocation because matching semantics, normalization basis, and frame-coordinate handling are 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 0%, so the description must compensate. It does map the four parameters conceptually: two named point sets, each with its own semantic frame. But it adds no detail on the frame coordinate meaning, x/y units, or the significance of point names beyond 'named landmark sets', leaving meaningful parameter semantics underspecified.

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 ('Compare') and resource ('two caller-supplied named landmark sets'), and the 'Pure geometry: does not inspect Photoshop or detect landmarks' line separates it from sibling tools that read Photoshop state or detect points. It does not explicitly name the closest alternative, photoshop_transform_landmarks, so it is clear but not fully sibling-differentiated.

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 implies when to use the tool (you have two landmark sets and want an error comparison) and gives a useful when-not signal ('does not inspect Photoshop or detect landmarks'). However, it never names an alternative tool or states an explicit decision rule such as using this instead of photoshop_transform_landmarks.

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?

With no annotations at all, the description carries the full burden and does disclose the two most important traits: the computation is deterministic and it 'creates no Photoshop history', i.e. no document mutation. It also notes that provenance must be supplied exactly by the caller. It omits failure behavior (e.g. near-parallel handling) and result shape, keeping it below 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?

Two tightly written sentences with zero filler; the core identity (pure deterministic geometry, no side effects) is front-loaded before the caller-input detail.

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?

This is an 11-parameter multi-operation tool with no annotations and no output schema, so the description should explain what each operation returns and which inputs it needs. Instead it gives only a general statement, leaving the agent unable to map operations to inputs or interpret results.

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 only 27% across 11 parameters, so the description must compensate and does not. It mentions lines, points, polygons and source-frame provenance in general terms, but says nothing about axis, value, tolerance_px, near_parallel_threshold, or which parameters each of the 10 operations actually consumes.

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: 'pure deterministic source-pixel geometry' that performs computations on caller-supplied line endpoints, points and polygons. It clearly is not a detection or editing tool, which separates it from sibling analysis/mutation tools. It stops short of naming the actual operations (line_equation, corridor_section, etc.) available in the enum.

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 'Scene Geometry Model / Geometry Preflight work' framing gives implied context, and the disclaimer that no semantic detection occurs hints this is for measurement-style work rather than detection. However, it never states when to prefer this over siblings such as photoshop_measure_points, photoshop_transform_landmarks or photoshop_compare_landmarks.

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?

With no annotations, the description carries the full burden, and 'Read' clearly signals a non-mutating operation. It also enumerates the returned setting categories, though it omits prerequisite details such as requiring an active document or brush.

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 a single front-loaded sentence with no filler. Every clause contributes to identifying the tool or the data it returns.

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

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

For a zero-parameter read-only getter with no output schema, the description is nearly complete because it describes the returned setting categories. The main gap is the lack of prerequisite context, such as whether an active Photoshop document or brush is required.

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

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

The tool takes zero parameters, so parameter semantics are not applicable; the baseline score is 4. The description adds no parameter detail, which is appropriate for a no-argument getter.

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

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

The description uses a specific verb ('Read') and a clearly scoped resource ('active Photoshop paint-brush settings'), then names the setting categories returned. It distinguishes itself implicitly from preset-listing tools by specifying 'active' settings, though it does not name a sibling 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?

Usage is implied by 'active' settings and 'used for digital painting', but the description gives no explicit when-to-use guidance or comparisons with siblings such as photoshop_list_brush_presets. The agent can infer this is for inspecting the current brush, but routing is not stated.

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

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

No annotations are provided, so the description carries the full behavioral burden. 'Report' weakly implies a read-only call, but it does not state whether it contacts Photoshop or the UXP bridge, whether the call is safe or cached, or any side effects; it only names the high-level payload.

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

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

A single front-loaded sentence with no filler. It states the payload immediately and does not waste words.

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

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

For a zero-parameter diagnostic tool it conveys the two main return categories, which is enough to know why to call it. However, with no output schema, it leaves the actual return shape and how bridge availability is represented unspecified.

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

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

The tool has zero parameters, so there are no parameter meanings to explain and the empty schema is self-contained. Baseline 4 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 names a specific verb (Report) and a specific resource (version-derived Photoshop feature flags and current UXP bridge availability). It is clear what the tool does, but it does not explicitly distinguish itself from capability-related siblings such as photoshop_guard_capabilities or photoshop_get_painting_method_capabilities.

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

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

There is no guidance on when to call this versus photoshop_get_version, photoshop_guard_capabilities, or painting-method capability tools. The reporting purpose weakly implies a diagnostic use, but no alternatives, preconditions, or exclusions 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?

With no annotations, the description carries the full disclosure burden, yet it only implies read-only via 'Read'. It doesn't say what happens when no document is open, what fields are returned, or that passing document_id fails closed rather than switching tabs (that is only in the 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?

A single front-loaded sentence with no filler. It is efficient, though the terseness leaves substantive gaps that conciseness alone can't excuse.

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 tool with no annotations and no output schema, the description should describe what information is returned and the no-active-document case. Neither is covered, leaving the agent to guess the response shape and error behavior.

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 single optional document_id parameter is documented thoroughly, including fail-closed semantics. The description adds nothing 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 concrete verb ('Read information') and resource ('active Photoshop document'), so the agent knows it's a passive inspection call. It does not differentiate from close siblings like photoshop_get_state, photoshop_list_documents, or photoshop_get_layers, which all read related document data, so an agent cannot fully disambiguate from the sentence alone.

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

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

No guidance on when to choose this over photoshop_get_state or photoshop_list_documents, and no stated preconditions such as requiring an open document. The only conditional behavior (document_id verification) lives in the schema, not the description.

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?

With no annotations provided, the description carries the full disclosure burden, and 'without mutation' usefully declares read-only safety semantics. However it says nothing about permissions, failure modes, or what a history state contains — the fail-closed behavior only appears in the schema, not the description.

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

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

A single short sentence with zero waste, putting the read-only constraint front and center. Nothing is padded or repeated.

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

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

For a simple one-optional-param read tool this is close to adequate, but there is no output schema and the description never indicates what a 'history state' record looks like or in what order states are returned. An agent knows what it will do, but not what it will get back.

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 document_id description already explains the optional id, the fail-closed verification, and the no-auto-switch guarantee in detail. The tool description adds nothing beyond that, so the baseline 3 applies rather than a higher score.

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 ('read') and resource ('active document history states'), plus the key scope constraint that only the active document is involved. It does not distinguish itself from nearby siblings like photoshop_get_state or photoshop_get_document_info, so an agent must infer why it would pick history over state.

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

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

There is no explicit when-to-use guidance, no when-not-to-use, and no named alternative. The 'active document' phrasing hints that non-active documents are out of scope, but the choice between this and photoshop_get_state / photoshop_get_layers is left entirely 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?

No annotations are provided, so the description must carry behavioral disclosure; 'List' implies a read-only operation but that is inference, not statement. It says nothing about cost, result size for documents with many layers, or response shape, though it does at least name the attributes returned.

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 with no filler; the core capability is stated first and the disambiguation second. 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?

For a one-optional-param read tool with full schema documentation and no output schema, listing the returned fields is the right compensating detail. The only meaningful gap is that the description does not confirm the operation is read-only or note how large results are handled.

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 single optional document_id is documented thoroughly, including the fail-closed behavior and the fact that it never switches the active document. The description adds no parameter-level meaning beyond that, which is acceptable given 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 ('List all layers in the active document') and enumerates the returned fields (kind, visibility, opacity), which pins down scope. It does not contrast with nearby read tools like photoshop_get_document_info, but it is unambiguously not the state/summary tool.

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

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

Explicitly routes the agent to photoshop_get_state when a 'lighter session summary' is wanted, giving a concrete alternative and the condition that selects it. It stops short of stating when not to use this tool (e.g., very large documents), so it is not 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?

With no annotations, the description carries the full burden but does add real traits: the map is derived from tools actually registered in this runtime and unsupported methods are reported explicitly rather than fabricated. That is useful trust context, yet it says nothing about cost, side effects, or the fail-closed document-id verification behavior (which lives only in the 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?

Two tight sentences, front-loaded with the action and resource, with the second sentence carrying the trust guarantee. No filler, though the phrasing is slightly abstract ('capability map derived from tools actually registered').

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, so the description is the only source on return shape, and 'capability map' is left unelaborated — an agent cannot tell whether it gets a list of method names, per-method flags, or metadata. Combined with the missing usage routing, it is adequate but leaves gaps an agent must probe at runtime.

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 optional parameter exists and the schema documents it at 100% coverage, including the fail-closed active-document check. The description contributes nothing about document_id, so the schema 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 and resource: 'Return the executable painting-method capability map'. The 'painting-method' qualifier implicitly separates it from the generic photoshop_get_capabilities and photoshop_guard_capabilities siblings, but the description never names those alternatives, so the distinction is inferred rather than asserted.

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 only implied: an agent can infer it should call this before selecting a painting method, since the map tells it which methods are actually executable. There is no explicit when/when-not statement and no pointer to photoshop_select_painting_method or to the generic capability tools it overlaps with.

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?

No annotations are provided, so the description carries the full behavioral burden. It hints at a filesystem side effect via "materialized filesystem copy" but never states that this is a non-destructive read of the document, whether the preview is returned inline or only written to disk, or how failures behave — the critical fail-closed semantics are absent from the description.

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

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

A single front-loaded sentence with the core action first and the optional variations trailing. No filler, nothing to trim.

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 seven parameters, a nested focus_region object, no annotations, and no output schema, the description should say more about what comes back (inline image block vs. file path, and any metadata) and about the destructive/read-only profile. The schema rescues most parameter detail, but the return contract is left implicit.

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 baseline is 3. The description's mention of a "local focus crop" and "materialized filesystem copy" loosely maps to focus_region and materialize_path but adds no meaning beyond what the schema already documents in detail.

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: "Capture a JPEG preview of the active/pinned document," plus the optional variations (focus crop, materialized copy). No sibling tool captures previews, so it is distinguishable, though the description never names an alternative or scope boundary explicitly.

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

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

"active/pinned document" implies the operational constraint (it works on the currently active document, or one pinned via document_id), but the description gives no explicit when-to-use vs. when-not guidance and does not address the fail-closed behavior when a different tab is active — that detail lives only in the schema.

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?

With no annotations provided, the description carries the behavioral burden and does state that the operation is read-only and returns document pixels. It does not disclose important behavior such as what happens when there is no active selection or the coordinate origin, leaving meaningful gaps for a read helper.

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 a single, front-loaded sentence with no wasted words. It communicates the core action, resource, units, and read-only nature efficiently.

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

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

For a simple read tool this is close to sufficient, but it has no output schema and does not describe the returned bounds shape, such as whether it includes x, y, width, and height. The agent can infer the general result, but return-value semantics are left underspecified.

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 single optional document_id parameter is already well documented in the schema. The description adds no additional parameter meaning beyond what the schema states, which is acceptable at baseline when schema coverage is high.

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

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

The description uses a specific verb, "Read," and a precise resource, "active pixel selection bounds," and clarifies units as document pixels. It is clear what the tool returns, though it does not explicitly differentiate itself from nearby sibling tools such as geometry or measurement utilities.

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

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

The phrase "active pixel selection bounds" implies the tool is used when the current Photoshop document has a live selection. However, it does not state when to use this tool versus alternatives, nor does it give exclusions such as behavior when no selection exists.

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?

No annotations are provided, so the description carries the full burden, and it does declare the key behavioral trait: the call reads state 'without mutation.' The fail-closed behavior on document_id mismatch and the refusal to auto-switch tabs are documented only in the schema parameter description, and the description says nothing about error modes or what the returned state contains beyond the phrase 'document/layer/selection state.'

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 text is dominated by workflow policy that belongs to other tools (drawing via guard_cycle_auto, imagegen prohibition, decision-loop stalls, capability discovery), while this tool's own definition is a single trailing sentence. The structure is also back-loaded: the purpose appears last, after several paragraphs of unrelated directives, so the reader must scan to the end to learn what the tool does.

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

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

For a one-optional-parameter read tool with 100% schema coverage and no output schema, the essentials (purpose, when to start with it, non-mutating nature) are present. But the description spends most of its length on policies that do not govern this call, and it describes the returned state only as a three-word enumeration, leaving the agent to infer what 'state' actually includes.

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

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

Schema description coverage is 100% for the single optional document_id, including the fails-closed semantics and the no-auto-switch guarantee, so the schema already does the work. The description adds no parameter-level detail beyond implying a 'confirmed target' is reused. Baseline 3 is appropriate.

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

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

The closing sentence states a concrete verb and resource set: 'Read current document/layer/selection state without mutation; establish or recover the document target.' That distinguishes it from siblings like photoshop_list_documents and photoshop_guard_resume. However, the actual purpose is buried at the end of a paragraph dominated by orchestration policy, so an agent must read through unrelated instruction text to find it.

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

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

Explicitly says to start here to establish the document, names the alternative for the interrupted-run case (photoshop_guard_resume), and instructs reuse of an already confirmed target. It also names the next step (photoshop_guard_cycle_auto) and the authorization condition for document switching. The only weakness is that this guidance is entangled with policy for many other tools rather than kept to this one's decision point.

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?

No annotations are supplied, so the description carries the burden. It does disclose the return value (a version string) and the word 'detected' hints that the value comes from an active connection, but it says nothing about failure behavior if Photoshop is not running or is ambiguous. Adequate but with a clear gap for a no-annotation 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?

Two short sentences, front-loaded with what is returned and followed by the routing hint. Not a wasted word, and the sibling reference is placed where it is needed.

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

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

For a zero-param, no-output-schema read, the description tells the agent what comes back (a version string) and where to go for anything richer. The only missing piece is what happens when no Photoshop instance is detected, which matters because the tool name implies detection.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate. Baseline 4 applies; the description correctly makes no attempt to invent 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 ('Return the detected Photoshop version string') and immediately names the sibling that covers the adjacent need. An agent can distinguish it from photoshop_get_capabilities or photoshop_get_state 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 feature-support questions to photoshop_get_capabilities, which is the main ambiguity for a version tool. It does not say when version info is irrelevant or what to do if nothing is detected, so it stops short of full when/when-not coverage.

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?

No annotations, so the description carries the full burden. It does disclose a useful boundary ('does not certify painted quality') and that interrupt is a state-regressing operation, but it is silent on what interrupt discards, whether state is preserved, permission/auth requirements, or what the response contains — significant gaps for a 12-param 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?

A single front-loaded sentence mapping each action to its effect with zero filler. The dense phrasing ('review issues tasks') is slightly cryptic but the compactness itself is appropriate; every clause corresponds to a distinct action.

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 tool with deeply nested contracts and no annotations or output schema, one terse sentence is far from sufficient. Required pairings (final_comparison and pre_final_hostile_review are mandated for action=complete) are documented only inside the schema, not in the description, leaving an agent that reads only the description under-informed.

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?

With schema coverage at 58% and 12 parameters, the description only illuminates the 'action' enum values (review/interrupt/complete), which are the required minimum. Ten other properties — directive, anchor_decision, final_comparison, pre_final_hostile_review, incomplete_hypothesis, whole_image_glance — get no mention, and the description does not compensate for the roughly 42% of undocumented schema surface.

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

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

States a concrete verb (manage) and resource (Director plans) and enumerates what each of the three actions does: review surfaces tasks, interrupt returns to planning, complete closes a satisfied directive. The scope boundary ('does not certify painted quality') further disambiguates it from evaluation siblings, though no sibling is named explicitly.

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

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

The action semantics imply when each mode applies (review = inspect open tasks, interrupt = abort back to planning, complete = close out a satisfied directive), but there is no explicit guidance on when to prefer this over photoshop_guard_review_image, photoshop_guard_status, or photoshop_guard_set_art_run, and no prerequisites or exclusions are stated.

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

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

With no annotations, the description does useful work by disclosing the effect target (brush inventory, not canvas pixels) and the return value (brush_pack_id). However, for a mutation it omits whether an import merges with or replaces existing brushes, whether it is reversible, and any permission or failure-mode expectations.

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

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

A single tight sentence with the effect scope front-loaded after the action, and every clause (import, return id, non-pixel effect) carries information. 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?

It is a low-complexity tool (2 optional params, no nesting) and the description covers the action, the returned id, and the effect scope, which is much of what matters. Without annotations or an output schema, though, it should say more about overwrite/merge behavior on an existing brush inventory.

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 both source_path and source_files are already documented in the schema, including the mutual-exclusion hint. The description adds no further meaning about formats, path semantics, or precedence, 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 pairs a specific verb (import) with a specific resource (.abr assets) and names the concrete artifact produced (brush_pack_id with verified presets). It also explicitly scopes the effect away from canvas pixels, which sharpens it against pixel-editing siblings, but it doesn't name a direct alternative such as list_brush_presets or brush_pack_profile.

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

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

The phrase 'import supplied .abr assets' implies the precondition of having .abr files, and the 'not canvas pixels' clause implies this is for inventory setup rather than drawing. There is no explicit when-to-use/when-not guidance or any routing to sibling tools like brush_pack_profile that might be the correct next step.

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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It does contribute one real behavioral fact — probe_media draws a disposable sheet — which is genuine side-effect information. But it never says whether plan/build_preflight are read-only, whether record_media/record_stamp persist anything or where, or what the agent gets back, which is critical for a five-mode 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?

It is short, which is appropriate, but the content is packed into one semicolon-and-slash-choked sentence that is hard to parse. Splitting the five modes into a list would cost no extra length and be far more usable. No wasted words, but poor front-loading of the required 'action' discriminator.

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

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

For a 9-parameter tool with deeply nested objects, no annotations, and no output schema, this single sentence is far too thin. The mode enumeration is the minimum an agent needs to pick an action, but mode-specific parameter requirements, side effects, and expected results are all 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 0% across 9 parameters, including a large nested 'profile' object with dozens of enumerated fields (mirror_x, edge_behavior, buildup_behavior, canonical_footprint_bounds, etc.). The description explains none of them. Only the action enum gets indirect coverage via the mode enumeration; preset_states, required_roles, candidate_limit, inventory_total and occurrence_index are entirely unaddressed.

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 sentence enumerates modes that map onto the action enum (plan, probe_media, record_media/record_stamp, build_preflight), so an agent can roughly connect the description to the required discriminator. But the phrasing is compressed slash-jargon ('Plan/probe a brush pack') and never states what a 'profile' or a 'preflight role map' actually is. It also fails to distinguish this from the sibling photoshop_guard_brush_pack_ingest.

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?

No indication of when to choose 'plan' versus 'probe_media' versus 'build_preflight', or what preconditions each requires. The sibling brush_pack_ingest is an obvious candidate for confusion and is never mentioned. The only usage-ish signal is the clause about probe_media drawing a disposable sheet.

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?

With no annotations, the description carries the full behavioral burden. 'Read' signals a non-mutating operation and the reference to a 'recovery contract' hints at a contract-shaped response, but there is no disclosure of idempotency, whether repeated calls are cheap, what an empty-parameter call returns, or how the batch and revision echoes behave. It is enough to avoid misuse but not enough to build a mental model of the 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?

A single front-loaded sentence with two clauses and no filler. It is slightly over-compressed — the semicolon joins two ideas (contract reading and per-command schema resolution) that could be separated for clarity.

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

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

The tool is a discovery endpoint with four optional parameters and no output schema, so the description must explain what comes back. It names the payload only vaguely ('capabilities and recovery contract') and says nothing about the response shape, revision token surfaced for later if_revision use, or batch result structure — gaps the schema cannot fill.

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 explains tool_name, tool_names, if_revision, and deployment_health in detail — the baseline for this dimension. The description adds only one extra nugget, that tool_name yields an exact executable argument schema 'without source inspection,' which is genuine but marginal added meaning.

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

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

States a specific verb and resource (read Guard capabilities and recovery contract) and adds a distinct capability: tool_name returns an exact executable argument schema. However, it never differentiates itself from the sibling photoshop_get_capabilities, which an agent could easily mistake for the same thing, and the phrase 'tool_name returns...' is ambiguous about whether the parameter triggers that behavior.

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 offers no when-to-use guidance: nothing says when to pick this over photoshop_get_capabilities, photoshop_guard_status, or photoshop_guard_reconcile. The only usage cues (when to pass if_revision or deployment_health) live in the parameter descriptions, not the tool description, so the top-level text leaves the routing decision unresolved.

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?

With no annotations, the description still discloses real behavioral traits: it is a stateful review loop requiring previous_operation_id + previous_observation at the critic checkpoint, returns a job_id that must be polled, mutates through bounded passes with document_id pinning that must never be removed, and that a decision-loop stall is advisory rather than a mutation blocker. It does not describe the returned payload shape, failure/rollback semantics, or what 'report the exact blocker' yields.

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 long run-on block of imperative fragments and policy that is not front-loaded with what the tool does; the tool's own name appears mid-paragraph after session routing rules. Much of the content (focus permission etiquette, imagegen prohibition) is session policy that does not belong in a single tool's description and dilutes the callable contract.

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 a very complex, stateful tool with no annotations and no output schema, the description does cover the review-closure protocol and the polling handoff, which is the hardest part. But it leaves the return value, error surface, and the choice between the two large input modes unexplained, and spends its budget on cross-tool policy instead.

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 67% across 6 heavily nested top-level parameters, so the schema does substantial work. The description adds the crucial sequencing semantics (previous_operation_id + previous_observation with optional next_pass; critic_review at its checkpoint) and document_id pinning, but never explains the painting_intent vs next_pass split or when each of the two mutually-shaped entry modes is required.

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 operative sentence, 'Draw through photoshop_guard_cycle_auto,' does identify this as the execution/dispatch tool for a bounded painting pass, and 'one bounded semantic pass, not an entire artistic stage' hints at scope. But the opening frames it as session-wide routing policy ('When the user requests PaintPilot Photoshop/MCP drawing...') rather than stating 'submits one Guard painting pass and returns a job to review', so an agent must infer the core verb+resource from a parenthetical.

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

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

It explicitly sequences siblings: start with photoshop_get_state, use photoshop_guard_resume for interrupted runs, discover photoshop_set_active_document via photoshop_guard_capabilities, fetch images via photoshop_guard_review_image and poll job_id via photoshop_guard_job_poll. It also states prohibitions (no external imagegen, no silent focus switching). It lacks explicit routing versus other dispatch-adjacent siblings like photoshop_guard_lint_next_pass.

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?

No annotations are provided, so the description carries the full behavioral burden. It adds a safety caveat about not replacing running/uncertain work, but it does not disclose whether polling is read-only, what statuses it returns, whether it blocks, or how errors are handled. For a polling tool with zero annotation coverage, this is a significant gap.

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

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

The description is very short and front-loaded with the primary action. It uses semicolons to pack multiple instructions into one sentence without wasted words, though the density makes some directives feel cryptic rather than fully explained.

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 annotations and no output schema, the description should explain return values, status meanings, and error behavior for a polling tool. It only mentions the next step after completion and a mutation caution, leaving an agent without enough context to interpret poll results or handle non-completed states.

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

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

There is one required parameter, job_id, but schema description coverage is 0%. The description only says 'Poll job_id' and does not explain the expected format, where to obtain the job_id, or how it relates to job states. It adds little beyond the schema's type declaration.

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 and resource: 'Poll job_id'. It also points to photoshop_guard_review_image for completed visual reviews, which somewhat distinguishes it from that sibling. The purpose is clear, though the terse phrasing leaves some ambiguity about what polling entails.

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

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

The description gives a next step ('fetch completed visual review via photoshop_guard_review_image') and a caution ('never replace running/uncertain work with another mutation'). However, it does not explicitly state when to call this tool versus alternatives like photoshop_guard_status or photoshop_guard_reconcile, nor does it define what 'running/uncertain' means in practice.

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?

With no annotations, the description carries the full behavioral burden. It helpfully states that pixels and layer structure are not altered, and that composition-scaffold units cannot be promoted or relabelled, but it omits idempotency, request_key behavior, ownership-state side effects, 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?

The description is two tightly written sentences with the core action and constraint front-loaded. Every sentence adds relevant meaning without repetition.

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

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

This is a complex tool with six parameters including a nested scene ownership plan, no annotations, and no output schema. The description covers the core commit semantics but leaves major gaps around conditional requirements, identifier contracts, and expected state changes.

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

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

Schema description coverage is only 33%, so the description should compensate, but it only explains hypothesis_id and layer_id as journal-bound identifiers. It does not clarify request_key, document_id, rationale, or when the complex scene_ownership_plan object is required.

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

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

The description gives a specific verb and object: commit a visually accepted temporary component on a predeclared independent unit using journal-bound IDs. It also states the main exclusion for composition-scaffold units, though it does not explicitly differentiate itself from any sibling guard tool.

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

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

The phrase 'visually accepted temporary component' and 'predeclared independent unit' imply this is used only after visual acceptance and prior declaration. However, there is no explicit when-to-use guidance against alternatives such as reconcile or cycle-auto, and no clear prerequisite checklist.

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?

No annotations are provided, so the description carries the full burden. It does disclose the two traits that matter most: the call is read-only and optional, and validation yields corrections (per the schema, 'without mutation'). It omits failure behavior, whether results are persisted, and what the response contains, which is thin for a tool with this much nested input.

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, no filler, with the 'Optional read-only' qualifier front-loaded so an agent's first takeaway is safety and low obligation. The second clause bundles two distinct prohibitions into one sentence, but nothing is wasteful.

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 a large nested schema, no output schema, and no annotations, the description should explain the call/return cycle and the preconditions for a valid payload. Instead it only says 'optional' and 'cycle_auto already validates', leaving an agent unable to predict what a lint run returns or what happens to a rejected continuation.

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 60% and there are 5 parameters with deep nesting, so the description needs to compensate and does not. The only parameter-related content is the passing mention of 'previous observation'; document_id's fail-closed behavior, review_operation_id, and previous_operation_id semantics are left entirely to the schema.

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

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

States a specific action ('read-only validation of a complete continuation') on a specific artifact and names the sibling that already performs validation (cycle_auto). The term 'complete continuation' is project jargon, so the resource being validated is only inferable from the next_pass schema rather than from the sentence itself.

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 negative rule ('do not lint each normal component or separately close a reviewed previous pass') and says cycle_auto already validates, which implies this is a fallback. It never states the positive trigger — when an agent should actually choose this over just running cycle_auto, or pre-flight vs. post-hoc 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?

With no annotations, the description carries the burden and does disclose meaningful behavior: it will not replay the operation and Guard collects fresh document-list evidence internally rather than trusting caller-supplied evidence. However, it never states what happens on success/failure, whether the barrier/state is cleared, or what permissions or preconditions apply, leaving significant behavioral gaps.

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 compact sentences, front-loaded with the action and immediately followed by the exact invocation recipe and a prohibition. Dense but no filler; the only cost is the heavy internal shorthand.

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 annotations and no output schema, and only 38% of 8 parameters are schema-documented, so the description needed to do more. It covers the primary recovery path adequately but omits what the tool returns, how the alternate evidence-supply path (documents_id/capture_evidence) relates to the closed-document path, and what state_id/preview_id are for.

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 only 38% across 8 params, so the description must compensate. It explains id, outcome=abandoned, document_closed_confirmed, reason, and implicitly documents_id ('do not manufacture evidence ids'), but leaves state_id, preview_id, and capture_evidence entirely unaddressed even though those are the parameters most likely to confuse a caller.

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 ('Reconcile uncertain execution') plus a key constraint ('without replay'), which distinguishes it from replay-style siblings like photoshop_guard_resume. The wording is domain-jargon heavy ('uncertain execution', 'Guard'), but the core action is identifiable.

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

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

Gives an explicit trigger condition ('For a user-confirmed closed document') and the exact call shape to use in that case (id + outcome=abandoned + document_closed_confirmed=true + reason). It also states a prohibition ('Do not read source or manufacture evidence ids'), though it does not contrast against sibling recovery tools such as guard_recover_lock or guard_resume.

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?

With no annotations, the description carries the full safety burden and does disclose important behavioral constraints: locks are released only for dead owners, live-PID stalls require restart, and mutation replay is forbidden. It does not detail permissions, reversibility, or side effects, but the key recovery-safety guidance is present.

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 definition is a single dense sentence with the core action front-loaded and no wasted words. The semicolon cleanly separates the lock-release rule from the live-PID recovery warning.

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?

It covers the critical guard-recovery conditions, but it remains cryptic about what embedded_guard_job_stalled and MCP-child restart mean operationally, and it gives no sense of what the tool returns or how success is confirmed. For a guard-recovery tool with no annotations or output schema, this is minimally adequate but not 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?

The tool has zero parameters and 100% schema description coverage, so there are no parameter semantics to explain. The baseline for a parameterless tool is 4, and the description appropriately does not invent parameter details.

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

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

The description states a specific action and resource: release locks, scoped only to dead owners. It clearly identifies the recovery scenario involving embedded_guard_job_stalled and a live PID, though it does not explicitly name sibling alternatives such as resume or reconcile.

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 a clear usage condition ('only for dead owners') and a critical exclusion: live-PID stalled jobs require MCP-child restart before recovery, and mutation replay must never be used. It lacks explicit alternative-tool guidance, 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?

With no annotations, the description carries the full burden and does a solid job: it discloses the effect (blocks subsequent mutations, including queued work), two important limits (does not replace the host Stop button, cannot undo an already dispatched command). It omits idempotency, permission requirements, and what happens if the operation has already completed.

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, zero filler, and the primary capability is front-loaded ahead of the caveats. Every clause carries information an agent needs.

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

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

For a no-annotation, no-output-schema, two-parameter stop tool, the description covers effects and hard limits well. Gaps remain around the return signal (how does the agent confirm the stop succeeded?), how to source operation_id, and behavior when the execution is already finished or when the call is repeated.

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 only 50%: document_id is well documented in the schema, but operation_id has no schema description and the tool description only says it must be 'one known Guard execution operation_id' without format or provenance. The description partially compensates by scoping the parameter to a single execution, but the agent still cannot tell how to obtain a valid value.

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 (Stop) on a specific resource (one known Guard execution operation_id) with an explicit scope qualifier ('blocks subsequent Photoshop mutations in that execution, including queued work'). It also pre-emptively distinguishes itself from the MCP host chat Stop button, so an agent can tell it apart from both the host control and sibling guard tools.

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?

Establishes the precondition clearly — you must have a known operation_id for a Guard execution — and rules out the most likely misuse (using it as a substitute for the host chat Stop button). It does not point to where an operation_id comes from (e.g., photoshop_guard_status or photoshop_guard_job_poll) nor contrast it with photoshop_guard_resume, so routing guidance is clear but incomplete.

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?

With no annotations, the description carries real behavioral weight: it says uncertain mutations are not replayed, that a pixel/owner comparison happens internally on same_document_confirmed=true, and that mismatch leaves work quarantined. That is meaningful disclosure of a safety-critical behavior; it falls short of 5 only because permissions, side effects, and failure surfacing are unstated.

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

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

Three sentences with no filler, and the core behavior (recover without replaying mutations) is front-loaded. The density of internal jargon ("preserved frame", "fresh pixels/owners") makes it slightly harder to parse than it needs to be.

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 5-parameter, zero-required, no-output-schema, no-annotation tool, the description covers the recovery path and the confirmation flag but is silent on the ownership projection mode and director_fields usage beyond a terse "use a separate call for identity recovery." Adequate but with clear gaps for an agent choosing among parameter combinations.

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 80%, so the baseline is 3; the description earns above baseline by explaining what same_document_confirmed actually does (requires user confirmation and triggers an internal pixel/owner comparison) rather than merely restating the flag. It still says nothing about projection=ownership, owner_id, or director_fields semantics that the schema does not already carry.

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?

Uses a specific verb (recover) on a specific resource (the local Photoshop workflow) and states the defining constraint: uncertain mutations are not replayed. It is distinguishable from siblings like photoshop_guard_reconcile or photoshop_guard_recover_lock, though it never names an alternative explicitly.

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

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

"Keep it unless the user explicitly changes execution mode" gives persistence guidance rather than selection guidance, and the UXP-session-change sentence implies the triggering context. There is no explicit statement of when to prefer this over siblings (e.g. reconcile vs recover_lock), so the routing must be 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?

With no annotations present, the description carries the full burden; it does contribute two real traits — the call does not paint/modify the canvas, and the images are 'exact' (deterministic, reproducible). It says nothing about side effects on guard state, caching, permissions, or the fail-closed document behavior that only appears in the 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?

A single compact sentence that leads with the action and follows with the usage constraint — no filler. It is dense with undefined jargon ('previous_observation'), but nothing is 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?

For a 6-parameter, annotation-free tool with no output schema, the description leaves critical gaps: what the delivered images are (format, count, which roles), what happens to review state, and what 'previous_observation' refers to. The agent cannot confidently predict the return value or side effects from this text.

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?

Six parameters with 67% schema coverage, and the description only echoes operation_id without clarifying its provenance or lifecycle. It adds no meaning to roles, document_id, review_scope, or force_redelivery 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 verb 'Deliver' plus resource 'exact review images for operation_id' identifies the action, and 'without painting' rules out one category of sibling behavior. However, the resource is left abstract (what images, in what form) and the description never distinguishes itself from the obvious alternative photoshop_get_preview, which an agent could easily pick by mistake.

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?

'inspect them before submitting previous_observation' gives one implied ordering constraint, but 'previous_observation' is never defined and no alternative tool is named. There is no statement of when NOT to call it or how it relates to photoshop_get_preview or the guard cycle tools.

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?

No annotations are provided, so the description must carry behavioral disclosure. It usefully states process_dir is immutable, that existing runs keep their profile/transition rules, and that brush preflight gates dependent operations—genuine behavioral context. It stops short of disclosing what binding does/writes, idempotency, or error/rejection behavior, leaving notable gaps.

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

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

Three focused sentences, front-loaded with the core bind action, then profile guidance, then a preflight caveat. It is dense with jargon but each sentence carries distinct information with 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?

This is a complex 10-param tool with nested objects and no output schema, and the description only covers profile selection and brush preflight. The rich schema (80% coverage) compensates for the rest, but the narrative is thin for a run-initialization mutation, leaving the agent to piece together overall intent from structured fields.

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 80%, so the schema already documents most parameters thoroughly and baseline 3 applies. The description adds value specifically around painting_profile's auto/omitted semantics and the preflight prerequisite, but says nothing about commentary_mode, brush_pack_policy, or the invalidation parameter beyond what the schema states.

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

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

The description opens with a specific verb 'Bind' and names two resources (document and immutable process_dir), which conveys a setup/initialization action. However, it never plainly states what an 'art run' is or that this tool initializes one, leaning on 'photoshop_guard'-style jargon, so distinguishing it from siblings like photoshop_guard_set_priorities or photoshop_guard_resume requires 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?

It signals scope with 'for NEW art runs' and states that 'Brush preflight is required before dependent brush operations,' which implies when the tool is appropriate. But it does not explicitly contrast with alternatives such as guard_reconcile or guard_resume, and 'NEW' vs existing runs is only lightly defined.

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?

No annotations exist, so the description carries the full burden. It discloses the blocking/gating behavior (open must-fix problems at coarse scale block finer work), which is genuine behavioral context beyond the schema, but says nothing about persistence, overwrite semantics on re-record, or failure modes.

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

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

One short, front-loaded sentence with the core action first and the gating rationale second. Nothing is wasted, though the terseness edges into under-specification.

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 tool taking a nested array of problem objects with enums and a conditional evidence requirement, plus no annotations and no output schema, the description is far too thin. An agent cannot infer the evidence_operation_id requirement or the scale/severity vocabulary from it.

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

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

Schema description coverage is only 25% across 4 parameters including a nested problems array with seven fields. The description mentions no parameters at all — not document_id, current_stage, evidence_operation_id (whose schema note about preventing arbitrary blocker dismissal is important), or the scale/severity enums. It fails to compensate for the coverage gap.

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

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

The verb 'Record' plus the resource 'whole-frame problem priorities' gives a rough idea, but 'set_priorities' semantics (are these absolute priorities, ranking, gating?) remain vague. It is not distinguished from guard siblings like photoshop_guard_lint_next_pass or photoshop_guard_status, which also deal with problems.

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?

'open larger must-fix problems block finer work' hints at the gating condition under which priorities matter, but it never says when to call this versus other guard tools, nor when not to. Usage is implied rather than stated.

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

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

With no annotations, the description carries the burden and does disclose useful traits: it does not paint, it validates geometry-not-image-proof, and diagnostic_timing_marker is benchmark-only. However it omits what is returned, whether 'solve' mutates anything, and error/blocker behavior, so the disclosure is partial.

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 is front-loaded in the first sentence and no sentence is pure filler, but the dense jargon and four-way bundling make it hard to parse quickly. It is compact where it should be clear.

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?

Against a very large nested construction_model schema, five parameters, no output schema and no annotations, the description is thin. It flags a few behaviors but does not equip an agent to choose the mode, understand returns, or interpret validation failures.

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?

At 40% schema coverage the description must add meaning. It sketches the role of four parameters (next_pass is linted, construction is a geometric target, marker is benchmark-only), but leaves document_id unexplained and does not distinguish construction_ref from construction_model beyond naming both.

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?

It names four distinct operations (read state/readiness, lint next_pass, solve construction_model/construction_ref) but bundles them without saying how they relate, and 'read state/readiness' overlaps heavily with sibling photoshop_get_state and photoshop_guard_lint_next_pass. The verb+resource pairing exists, but the agent cannot cleanly tell this tool apart from its siblings from the description alone.

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

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

The guidance is cautionary ('keep the established local workflow unless its route is unavailable; never replay uncertain mutations') rather than selective. It never states which parameter selects which mode, nor when to prefer this over photoshop_guard_lint_next_pass or photoshop_get_state.

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

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

No annotations are provided, so the description carries the full burden. 'List installed' implies a safe read, and it discloses that filtering is case-insensitive substring and that results are capped. It does not state ordering, pagination beyond the limit, or whether the result is names only, which leaves behavioral gaps for a no-annotation 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?

Two short sentences with zero filler, and the core purpose is front-loaded before the optional behavior. Every clause maps to either the tool's purpose or a parameter.

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

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

For a simple two-optional-parameter read tool with full schema coverage and no output schema, the definition covers what is needed to invoke it correctly. The only shortfall is not indicating the shape of the returned list (names vs. objects), which would help without an output schema.

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

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

Schema coverage is 100%, so both parameters are already documented, including defaults, min/max for limit, and the substring semantics of query. The description only restates those semantics without adding format examples or edge-case behavior, 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?

States a concrete verb and resource ('List installed Photoshop brush presets'), which is unambiguous against siblings like photoshop_list_fonts or photoshop_list_documents. It does not explicitly name an alternative tool or exclusion, but the resource is distinct enough that confusion is unlikely.

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

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

Usage is implied by the verb 'List' and the mention of optional filters, so an agent can infer this is a read/enumeration call. There is no explicit when-to-use vs. when-not guidance, no mention of prerequisites, and no pointer to a sibling for related tasks.

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?

No annotations are provided, so the description carries the full burden. It does disclose the important side-effect guarantee that no tab is activated, plus that the active document is included in the result, but says nothing about ordering, permissions, or cost of the 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?

A single front-loaded sentence with no filler. Every clause (scope, returned fields, non-mutation guarantee) 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 a zero-parameter schema, no annotations, and no output schema, the description supplies the essential facts: what is enumerated, what fields come back, and which document is active. It could be more complete only by comparing itself to photoshop_get_document_info or describing result ordering.

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

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

The tool takes no parameters, so the baseline is 4. The description correctly describes a call with no inputs rather than inventing filtering options that do not exist 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?

The description gives a specific verb and resource ('List all open Photoshop documents') and names the payload returned (ids, dimensions, active document). It is clearly distinct from the singular sibling photoshop_get_document_info, though it never names that alternative explicitly.

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

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

Usage is only implied: 'without changing tabs' signals a safe, side-effect-free enumeration suitable for discovery before other operations. There is no explicit when-to-use, when-not-to-use, or pointer to photoshop_get_document_info for single-document detail.

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?

With no annotations, the description carries the full burden and does well: 'without changing Photoshop' declares the read-only safety profile, and it discloses the return payload (font records, total count, truncation state). It stops short of stating that 'truncation state' pairs with the limit cap or how to retrieve more, which would have made it 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?

Two sentences, zero filler, with the core action and filter scope front-loaded before the return-value note. 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?

A simple two-optional-parameter read tool with no output schema, and the description covers purpose, filtering, read-only behavior, and the shape of the response. Adequate for correct invocation; only the limit/truncation interaction is left implicit.

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 in structured form. The description echoes the filter semantics (name/family/PostScript) but adds no new syntax or format detail, and says nothing about the limit/max behavior beyond what the schema gives.

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 (List) and resource (Photoshop fonts) with scope (optional filtering by name/family/PostScript name). The resource itself cleanly separates it from siblings like photoshop_list_brush_presets and photoshop_list_documents, so an agent can pick it without opening the schema.

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

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

The phrase 'optionally filtered' communicates when to supply a filter versus listing everything, which is useful implied guidance. However, there is no explicit when-not guidance and no named alternative tools, so routing still requires the agent's own judgment.

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?

With no annotations, the description carries the burden; it conveys that this is a read of the active document's guides, which implies non-mutating behavior. It does not explicitly state read-only safety, behavior when no document is open, or the empty-list case, leaving meaningful gaps for a no-annotation 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?

A single sentence that front-loads the verb and resource and packs the returned fields without filler. 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?

Since there is no output schema, the description's enumeration of returned fields (index, orientation, pixel/normalized position) is genuinely useful and covers the return shape. It is nearly complete for a one-optional-param read tool, only missing error/empty-state behavior.

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 document_id already documents the verify-active/fail-closed semantics in detail. The description adds nothing beyond the schema for this parameter, 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 (List) and resource (Photoshop guides) and enumerates the returned fields (index, orientation, pixel and normalized position), scoped to the active document. No sibling tool lists guides, so an agent can identify it unambiguously from the tool list.

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

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

The phrase 'for the active document' implies the usage context, but the description never states when to use this versus photoshop_get_state or photoshop_list_documents, nor any preconditions. Usage is inferable rather than explicit.

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?

With no annotations provided, the description carries the full burden. It usefully discloses the return values (pixel and normalized coordinates, vector distances, optional ratios) which substitutes for the missing output schema, but never states whether the tool mutates the document, nor mentions the fail-closed document_id behavior (that only lives in the 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?

Three short sentences, zero filler. The core action is front-loaded, the outputs follow, and the scope caveat closes it out.

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

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

Return values are described in prose, which compensates for the absent output schema, and the exclusion note prevents misuse. Still missing any statement about side effects or safety profile on the active document, which matters for a no-annotation 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 all four parameters are already documented in the schema, including the document_id fail-closed semantics and the maxItems limits. The description adds little beyond confirming that points are user-supplied and ratios are optional, 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 combination ('Measure user-supplied named points in the active Photoshop document') and enumerates the outputs, then explicitly delimits itself from adjacent landmark tools by saying it does not detect facial/anatomical landmarks automatically. An agent can distinguish this from photoshop_compare_landmarks and photoshop_transform_landmarks 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?

The phrase 'user-supplied named points' plus the explicit negative case ('does not detect ... landmarks automatically') tells the agent the precondition: coordinates must come from elsewhere. However, it never names the alternative tool to use when automatic detection is needed, so routing guidance is implied rather than stated.

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

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

With no annotations supplied, the description carries the full burden. It does disclose the payload contents (transport, version, bridge revision, active document, document count) — valuable since no output schema exists — but says nothing about failure behavior, such as what happens if Photoshop or the UXP bridge is unreachable.

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

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

Two sentences, front-loaded with the diagnostic content and followed by the usage constraint. No filler, nothing repeated from structured fields.

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

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

For a zero-param, non-destructive probe with no annotations or output schema, the definition covers what it checks, what it returns, and when to reach for it. The only gap is error/timeout semantics when the bridge is down — commonly the most important thing to know about a ping.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. The schema is empty and 100% self-describing.

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: 'Verify Photoshop/UXP readiness and report transport, version, bridge revision, active document and document count.' It distinguishes itself from single-value siblings like photoshop_get_version or photoshop_get_document_info by framing itself as a combined readiness probe, though it doesn't name those siblings explicitly.

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

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

'Use for route/bootstrap checks, not every call' gives both a positive trigger and an explicit exclusion, which is more than most definitions offer. It stops short of naming the concrete alternative tools to call instead for routine state reads.

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?

With no annotations, the description carries the burden and does well: it discloses the non-destructive read ('without changing the source document'), the averaging behavior for radius>0, and clipping to document bounds. It omits the fail-closed document_id verification behavior, which is left to the 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?

Three front-loaded sentences with the core operation first and use cases last; no filler. Slightly list-like in the use-case sentence but each clause is relevant.

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 4-parameter read tool with no output schema, the description covers operation, radius semantics, and non-destructiveness. The return value's format (e.g. RGB vs hex, precision) is not stated, which is a minor but real gap.

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; the description adds meaning by explaining that radius>0 yields a Photoshop Average-equivalent color and that the neighborhood is clipped to document bounds. The document_id safety behavior lives only in the schema, not the 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 and resource: sampling visible composite color at a document-space pixel, with radius semantics spelled out. It does not mention the near-identical sibling photoshop_sample_colors, so an agent cannot cleanly separate the two from the description alone.

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

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

Names concrete use cases (painting from references, skin/hair/lip palette pickup, local color checks) and explains radius=0 vs radius>0. It never says when to prefer this over photoshop_sample_colors or photoshop_measure_points, so selection among siblings is left 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?

With no annotations, the description carries the full burden and does disclose key traits: automatic batching of large requests, a hard cap of 1024 returned samples, and that the source document is not modified (read-only implication). It does not say how out-of-range points, partial failures, or large-batch latency are handled.

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

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

Two sentences, front-loaded with the action and batching behavior, then the usage rationale. No filler and nothing buried.

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

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

No output schema and no annotations, so the description must stand alone; it covers batching, cap, and non-mutation adequately for a 2-parameter read tool. The main residual gap is the shape of the returned results (order, per-point failure representation), which the agent must infer.

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 50%, and the schema itself already explains x/y document-space pixels, the optional id label, and the document_id fail-closed / never-switch-tab semantics in detail. The description only reinforces the 1024 sample cap and single-document scoping, adding little syntax or format meaning beyond 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 (sample many visible-composite point colors), a specific resource (points in one pinned Photoshop document), and the scope of the operation (single batch call). This clearly separates it from the singular sibling photoshop_sample_color 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?

Names concrete use cases (reference-driven value maps, palette studies, dense visual checkpoints) and explicitly routes to the alternative condition: use this when repeated photoshop_sample_color calls would be inefficient. The agent has a clear selection rule.

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?

With no annotations, the description carries the full burden, and it does at least assert read-only/non-mutating. It says nothing about what the selection returns, how ties or unsatisfiable constraints (e.g., empty candidate set) are handled, or whether preferred_method_id is guaranteed versus advisory.

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, front-loaded sentences with no filler; the read-only constraint is stated immediately. It is efficient but arguably too terse for the decision complexity involved.

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?

Incorrect placeholder - see corrected reasoning below.

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 only 38% across 8 parameters, and the description adds no parameter meaning at all. The required impact_class enum (construct/subtract/tone/...) and the interplay of impact_class, visual_intent, construction_role and preferred_method_id are undocumented in prose.

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: selecting an executable painting method from a runtime capability map. It is reasonably distinguishable from photoshop_get_painting_method_capabilities (retrieval vs. selection), but it never names that sibling, so the distinction is left implicit.

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?

No when-to-use / when-not-to-use guidance is given beyond 'planning/read-only'. It does not say to call photoshop_get_painting_method_capabilities first, nor how avoid_method_ids or preferred_method_id should influence selection versus simply calling a painting tool directly.

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

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

With zero annotations the description carries the full burden, and it does disclose the most important trait: this is a pure, side-effect-free computation that never touches the Photoshop document. However, it says nothing about what comes back, error behavior on invalid/degenerate frames, or ordering guarantees for the transformed point set.

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, zero filler, with the operation stated first and the crucial non-interaction caveat second. Every clause earns its place and nothing essential is buried.

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

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

Input semantics for a nested 3-parameter geometry tool are reasonably covered, but there is no output schema, so the description should have stated the return shape (transformed named points, in what frame). Combined with the absent annotations, an agent still has to guess the response contract.

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 67% (frame params documented, `points` undocumented), so the description meaningfully compensates by defining `points` as a caller-supplied named landmark set and by stating the core mapping rule ('preserving local u/v coordinates') that explains what source_frame/target_frame actually do. It stops short of clarifying what 'axis-aligned' implies for the frames' numeric 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?

Specific verb (transform) plus resource (caller-supplied named landmark set) and explicit scope (axis-aligned semantic frame to frame, preserving local u/v). The second sentence ('Pure geometry: does not inspect Photoshop or detect landmarks') actively separates it from siblings like photoshop_compare_landmarks and photoshop_measure_points.

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 implies the caller must already have landmarks and frames ('caller-supplied', 'does not detect landmarks'), which hints that measure/compare tools are the way to obtain points first. But it never states when to choose this over photoshop_compare_landmarks or photoshop_geometry_calculate, nor any prerequisites (e.g., non-degenerate frames).

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