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

Annotations only carry false hints (idempotentHint=false, destructiveHint=false), so the description must clarify behavior. It reveals the job is 'automatically completed' and 'scope-bound,' which is some behavioral insight. Yet it doesn't explain what happens on success/failure, whether it triggers side effects, or what 'for compatibility' implies. This is partial disclosure but not rich.

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

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

Two sentences with no filler, so it is concise. However, the second sentence ('Direct execution normally does not need this tool') is vague and doesn't add concrete value, while the first remains too generic to be useful. Brevity without substance.

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 5 parameters, 0% schema coverage in the description, and no explanation of 'scope-bound' or 'automatically completed,' an agent cannot infer the correct args, payload, or justification. The output schema exists, but parameter semantics are entirely opaque. This is far from complete.

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

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

Schema description coverage is 0%, and the description mentions none of the five parameters (args, engine, payload, command_id, justification). The agent gets zero guidance on what values to provide or how they relate to the job, forcing schema inspection without semantic context.

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 it creates an 'approval job' that is 'automatically completed' and 'scope-bound,' which is a specific verb-resource pairing. However, 'for compatibility' is vague, and it doesn't distinguish itself from sibling tools like photoshop_command_execute or photoshop_job_get. The purpose is understandable but under-specified.

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 statement 'Direct execution normally does not need this tool' gives a when-not condition, which is useful. But it provides no guidance on when this tool SHOULD be used, nor does it mention alternatives among the many siblings (e.g., photoshop_command_execute). There's no explicit routing or exclusion logic beyond the vague 'compatibility' note.

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

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

Annotations already signal read-only and idempotent behavior. The description adds meaningful context beyond those hints by defining 'supported' as 'locally verified' and stating that unverified and unavailable commands are never executed, which is safety-relevant behavior for an agent deciding whether to proceed.

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

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

Two sentences with no filler; the core action is front-loaded and the safety-relevant definition follows immediately. Every clause earns its place.

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

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

With an output schema and read-only annotations, the description does not need to explain return shape or safety. However, it lacks parameter guidance and explicit sibling differentiation, so an agent gets the gist but not enough to confidently use the filters or choose between this and command_search.

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% and the description provides almost no parameter-level detail. The only partial value is clarifying the meaning of the 'supported' status value and the safety of unavailable/unverified ones; query, category, and summary_only remain unexplained by 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?

The description opens with a specific verb and resource: 'List the versioned command catalog,' which clearly identifies a read-only enumeration of available commands. It distinguishes itself from sibling command_search/command_describe by being a list rather than a search or detail view, though it does not explicitly name the alternative 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?

The primary use case is implied: call this to see the command catalog and check supported status. However, the description does not state when to prefer this over command_search or command_describe, nor does it provide explicit when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, covering safety and idempotency. The description adds behavioral value by specifying the output content—schemas, prerequisites, risk, approval, verification, and rollback contract—which is not conveyed by the annotations. It does not contradict any annotation.

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, compact sentence that front-loads the core action and enumerates the key aspects. Every word adds value; there is no redundancy or filler.

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

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

Given the tool has only one parameter and an output schema (which likely details the return structure), the description provides adequate context about what the tool does. However, it does not mention that command_id is required (though that is in the schema) or any prerequisites like needing an active Photoshop pairing. It is reasonably complete but could offer a hint about typical usage scenarios.

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

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

Schema coverage is 0%, meaning the parameter command_id has no description in the schema. The description does not explicitly explain what command_id represents beyond the implied meaning from the tool name and description ('one command'). It lacks details such as how to obtain a valid command_id or example values. The description fails to compensate for the lack of schema documentation.

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

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

The description clearly states the tool's action (describe) and target resource (one command), and enumerates the specific aspects it covers: schemas, prerequisites, risk, approval, verification, and rollback contract. This differentiates it from sibling tools like photoshop_command_search (search) and photoshop_command_execute (execute), making its purpose unambiguous.

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

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

The description implies usage when an agent needs detailed contract information about a command before execution, but it does not explicitly say when to use this versus alternatives like photoshop_command_search or photoshop_command_execute. There is no explicit when-not or alternative routing, leaving some inference to the agent.

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

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

The annotation marks destructiveHint as true, but the description does not warn about potential side effects or irreversibility. It mentions 'risk' and 'approval' checks, which hint at safety, but it does not explain that execution may modify state or have external consequences. Without describing behavior, the agent cannot foresee the impact. It does not contradict the annotation, but it fails to disclose the destructive nature.

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 sentence, concise and without redundant words. It front-loads the core action ('Execute a catalog command') and then lists checks. It is not overly verbose, but it is so terse that it sacrifices informative content. The structure is acceptable for the length, but the content is minimal.

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 6 parameters and zero schema coverage, the description is incomplete. It does not explain what 'catalog command' means, what the output schema might be, nor how the various optional parameters interact. Given the destructive hint, an agent needs to know about approval and idempotency safeguards. The description provides only a generic preview, leaving the agent with many unknowns.

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%, and the description provides no explanation of any parameter. It does not mention command_id, args, approval_token, idempotency_key, dialog_mode, or verification. The agent is left to infer semantics from names and enums, which is insufficient for correct invocation, especially for optional but important tokens like approval_token.

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 the specific verb 'execute' and targets a 'catalog command', which distinguishes it from siblings like photoshop_command_search and photoshop_command_describe. However, it does not define what a 'catalog command' is, though that may be established by related tools. It is not a tautology and gives a clear enough sense of purpose.

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 use this tool versus alternatives. It does not mention that approval may be required first, nor does it reference the approval flow or other prerequisites. The description only states that checks are performed but does not explain the conditions under which an agent should invoke this instead of other 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?

Annotations already declare this as read-only and idempotent. The description adds useful behavior about locale-independence and supported search text types, which supplements the annotations. However, it does not disclose matching behavior, result limits, or failure modes, so it stays at a moderate transparency level.

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 core purpose and search dimensions. There is no filler, and every phrase adds useful information.

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

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

The tool is simple with only two parameters and an output schema, and the annotations cover safety, so the description does not need to explain return values. However, the relationship between 'query' and 'category' is ambiguous, and there is no guidance on expected search behavior or result scope, leaving meaningful gaps for an agent deciding how to construct a valid call.

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 carries the semantic burden. It explains that query and category relate to English, Korean, or description text, but it does not clearly delineate how 'query' and 'category' interact or which values are expected for category. This is partial compensation for the missing schema descriptions.

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

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

The description names a specific verb ('Search') and a specific resource ('locale-independent Photoshop command IDs'), and further clarifies the search dimensions (English, Korean, category, description text). This clearly distinguishes the tool from siblings like photoshop_command_execute or photoshop_command_describe.

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 no explicit guidance on when to use this tool vs alternatives. It does not mention that it should be used before command_describe or command_execute, nor does it state when not to use it. Usage context is only implicit from the name and siblings.

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

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

The description does not disclose side effects, permissions, or output. Although annotations indicate it is non-idempotent and non-destructive, the description itself adds no behavioral transparency.

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 sentence, which is concise but lacks substance. It is not overly verbose but also not sufficiently informative.

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

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

Given the simple tool, the description omits critical information such as parameter meanings, output, and side effects, making it incomplete for an agent to use effectively.

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?

No parameter descriptions are provided in the schema or description. The meaning of 'name', 'width', 'height', and 'resolution' is left implicit, and the description adds no semantic context.

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 identifies the tool as a convenience wrapper for document.create, making it clear it creates a Photoshop document. It distinguishes from sibling tools like layer_create and image_resize by specifying the document creation action.

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

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

The description provides no guidance on when to use this tool versus alternatives. The mention of 'same catalog policy and verification pipeline' is vague and doesn't clarify usage conditions.

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

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

The description adds one behavioral detail beyond the annotations: it follows the same catalog policy and verification pipeline as the underlying export command. But it doesn't explain what that policy/pipeline means in practice, nor does it describe side effects such as file creation or overwrite behavior. No contradiction with the `destructiveHint: false` annotation.

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 purpose is front-loaded. The second sentence adds context, though 'catalog policy and verification pipeline' is vague enough that it does not fully earn 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 tool with three parameters and no parameter documentation in the description, this is incomplete: the agent is left to infer export behavior, file naming, quality semantics, and what the catalog/verification pipeline means. The presence of an output schema covers return values, but the description still lacks important invocation context.

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

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

Schema description coverage is 0% and the description provides no details about `format`, `quality`, or `file_name`; it merely binds the parameters to a known export command. The enum and min/max in the schema help, but the description does not compensate for the missing parameter documentation.

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 the exact operation (`document.export`) and frames the tool as a typed convenience wrapper, so the agent understands it exports a Photoshop document. It is not a pure tautology, but it doesn't spell out the file-export behavior or explicitly contrast it with the generic `photoshop_command_execute` sibling.

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 'typed convenience tool for document.export' implies the agent should prefer this tool for exporting rather than raw command execution, and 'same catalog policy' ties it to the command pipeline. However, there is no explicit when-to-use/when-not-to-use guidance or naming of alternatives.

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

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

Annotations indicate non-idempotent and non-destructive behavior, but the description adds little beyond that. 'Uses the same catalog policy and verification pipeline' hints at safety checks but does not disclose what the undo action actually does, whether it is reversible, or what state changes occur.

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 brief and front-loaded with the core fact that this is a convenience tool. The second sentence adds context but is vague. It is concise without unnecessary words, though the content could be more informative.

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 zero parameters and an output schema present, the main gap is the operational context. The description does not clarify what 'history.undo' does, what conditions are needed (e.g., an active document), or how it relates to the broader command execution flow. The tool is underspecified for an agent to use correctly.

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

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

The input schema has zero parameters, so there is nothing to document. The description correctly focuses on the tool's purpose rather than parameters. Baseline of 4 applies for no-parameter tools.

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 identifies the tool as a convenience wrapper for 'history.undo', implying an undo operation, but it does not explicitly state the effect (e.g., 'reverts the last change'). It lacks a clear verb+resource statement and does not differentiate from siblings like photoshop_command_execute.

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

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

The description provides no guidance on when to use this tool over alternatives. It mentions 'same catalog policy and verification pipeline' but does not explain when this convenience tool is preferred, nor does it state exclusions or conditions.

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

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

The description explicitly states 'Side effects: none,' which aligns with the readOnlyHint and idempotentHint annotations. It also adds useful behavioral context by emphasizing 'live' UXP bridge state and 'exact' runtime versions, indicating this is a real-time introspection rather than a cached report.

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 entire description is one tight, front-loaded sentence with no filler. It states the action, the target resource, the specific details returned, and explicitly confirms the side-effect profile.

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 zero parameters, read-only/idempotent annotations, and the presence of an output schema, the description covers everything an agent needs to decide whether and how to invoke the tool. No return-value explanation is needed because an output schema exists.

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 is no parameter-semantic burden on the description. The empty schema already fully covers the input contract, and the description appropriately focuses on the resource being described rather than fabricated 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 uses a specific verb ('Describe') with a clearly bounded resource: the installed Photoshop host, UXP bridge, runtime API versions, and pairing state. This scope distinguishes it from siblings like photoshop_pairing_begin or photoshop_capability_list, even without naming them.

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 wording implies clear context: use this when you need host-level runtime information, API versions, or pairing status. It does not explicitly name alternatives or when-not-to-use conditions, but the scope is clear enough for an agent to route to it correctly.

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

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

Annotations are sparse: openWorldHint=false, idempotentHint=false, destructiveHint=false. The description adds that it is a 'typed convenience tool' and uses 'the same catalog policy and verification pipeline', which implies it will behave consistently with other tools in the catalog, but does not elaborate on specific side effects. Since destructiveHint=false and idempotentHint=false, the description does not contradict annotations, but it also does not disclose much beyond the annotations. The 'verification pipeline' mention implies some validation process, which is useful but vague.

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 brief, only two sentences, and uses a clear structure: it states what it is, then references shared behavior. It earns a high score for conciseness, but it is perhaps too terse, lacking helpful details. It is front-loaded with the purpose, which is good.

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 that there is an output schema (not shown) and the tool is a convenience wrapper, the description may not need to explain return values. However, for a tool that resizes images, an agent would benefit from knowing how the result is returned (e.g., modified document, new file, etc.) and any side effects. The mention of 'same catalog policy and verification pipeline' suggests consistency with other tools but does not spell out behavior. With 2 parameters, both optional per anyOf, an agent needs to know that at least one must be provided, which is implied by the schema but not in the description. Overall, there are gaps in usage context.

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

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

The schema has 0% description coverage, meaning the parameter names 'width' and 'height' are self-explanatory but their semantics (e.g., pixel dimensions, constraints on aspect ratio) are not documented. The description does not add any meaning beyond the schema; it merely says it's a convenience tool for 'image.resize'. The anyOf constraint (either width or height required) is in the schema but not explained in the description. Since the schema is minimal and the description doesn't compensate, this is a gap.

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

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

The description states the tool is a 'convenience tool for image.resize' with 'the same catalog policy and verification pipeline'. This clearly indicates the action (resize an image) and the resource (image dimensions). It distinguishes itself from siblings by referencing the generic image.resize operation, which is not named in the sibling list. However, it does not explicitly say what 'image.resize' does (resizing an image by specifying width/height), but the schema and tool name make it fairly evident.

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 explicit guidance on when to use this tool versus alternatives. It mentions 'same catalog policy and verification pipeline' which hints at a shared context with other Photoshop tools, but does not specify when to prefer this over other tools like 'photoshop_command_execute' or 'photoshop_document_export'. No exclusions or alternatives are named.

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

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

Annotations already provide safety context: idempotentHint=true, destructiveHint=false, and openWorldHint=false. The description adds useful context by listing the job states that are valid targets for cancellation, but it does not disclose what happens to the job or related resources upon cancellation.

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, focused sentence with no filler. It front-loads the action and immediately communicates the tool's scope, making it easy for an agent to parse.

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

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

For a one-parameter cancel tool with an output schema and helpful annotations, the description is nearly complete. It covers the target states and purpose, though it does not mention edge cases like idempotent cancellation of already-canceled jobs—though that is partly covered by idempotentHint.

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 does not explain job_id at all. However, the sole parameter is self-describing and the description's reference to 'job' makes the purpose of job_id reasonably inferable. Still, the description leaves all parameter semantics to the schema.

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

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

The description uses a specific verb ('Cancel') with a clear resource ('Photoshop job') and further narrows scope to 'queued, running, or awaiting-user' jobs. This clearly distinguishes it from sibling tools like photoshop_job_resume or photoshop_job_get.

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

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

The description implies the appropriate usage context by listing the job states that can be canceled, but it does not explicitly state when not to use the tool or mention alternatives such as photoshop_job_resume. The usage guidance is adequate but only implicit.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the bar is lower. The description adds genuinely useful behavior beyond annotations: the job may be asynchronous or user-assisted, and completed approval jobs expose a one-time token. No contradiction with the annotations.

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

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

Two short sentences, front-loaded with the core operation and immediately followed by the most important behavioral nuance. Every word 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-parameter tool with an output schema and strong annotations, the description is sufficient: it identifies what the tool retrieves, the async/user-assisted nature, and the one-time token behavior. An agent has enough context to invoke it correctly.

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

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

The single parameter job_id is unambiguous from its name and the tool's purpose, so the lack of an explicit parameter description is not severely harmful. However, schema_description_coverage is 0%, and the description does not directly confirm or elaborate on job_id, so it adds no semantic value 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 description names a specific operation—retrieving an asynchronous or user-assisted job—and adds a key differentiator: completed approval jobs return a one-time approval token. This distinguishes it clearly from siblings like photoshop_job_cancel and photoshop_job_resume.

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

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

The description implies the tool is used to fetch job status/results, especially for asynchronous or user-assisted workflows, and hints at post-completion token retrieval. However, it gives no explicit when-to-use guidance or alternatives, leaving the agent to infer when to call it versus related job 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?

The annotations are sparse (all false hints) and do not contradict the description. The description adds behavioral context: it is for user-assisted jobs, implying that the job is paused waiting on a UI step. This is useful beyond annotations, as it tells the agent the job is in a specific state. However, it doesn't detail what happens if the job cannot resume or any error conditions.

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 sentence, straightforward, and front-loads the action. It conveys the purpose without fluff.

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

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

The tool has a single parameter and an output schema (though not shown), so complexity is low. The description gives the key context about when to use it (after native UI step). However, it could specify what 'resume' entails, such as whether it returns updated job status or requires polling. Given the existence of an output schema and the tool's simplicity, this is adequate but not complete.

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

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

The schema has just one parameter (job_id) with no description, and schema description coverage is 0%. The description does not explain job_id beyond its name. However, with only one obvious parameter, the meaning is likely clear from the name and context. The baseline for high coverage would be 3, but here coverage is 0%, so the description should compensate; it doesn't add any detail about job_id format or origin.

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 ('Resume a user-assisted Photoshop job') and a clear condition ('after the user completes the native UI step'). It is clear what the tool does, and the context distinguishes it from siblings like photoshop_job_cancel or photoshop_job_get. It doesn't describe the outcome beyond resuming, but the verb and resource are specific enough.

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 states that the tool should be used 'after the user completes the native UI step', providing clear context for when to invoke. It does not explicitly mention when not to use it or alternatives like photoshop_job_get to check status, but the when-to-use guidance is direct and useful.

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

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

Annotations include idempotentHint=false, destructiveHint=false, openWorldHint=false, but the description mentions a 'verification pipeline' without detailing behavior like requiring pairing or approval. It does not contradict annotations, but it falls short of what is expected for a tool with no annotation on read-only or side effects. The description does not address the side effects of creating a layer (e.g., document mutation) or the need for an open document.

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, only two sentences, which is concise, but it is not well-structured. It front-loads 'Typed convenience tool' which is vague, and does not provide useful information in the first sentence. The structure is adequate but could be improved by leading with a clear action statement.

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

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

The tool has a single optional parameter and an output schema, but the description leaves the agent guessing about prerequisites (e.g., open document, pairing state) and what the tool actually returns. Given the output schema exists, it doesn't need to explain return values, but it should explain the creation side effects and any required context, which is missing.

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

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

Schema description coverage is 0%, so the description must compensate, but it gives no explanation of the 'name' parameter beyond the schema's type and maxLength. There is no guidance on what the name should be, whether it is optional (since required is 0), or how it is used. The description adds zero value for parameter understanding.

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 says it is a 'Typed convenience tool for layer.create', which indicates creating a layer, but it doesn't explicitly state the action or the resource (layer) directly, and it doesn't distinguish from sibling tools like photoshop_layer_rename. The purpose is somewhat clear from the 'layer.create' reference, but an agent might not know what this tool does without prior knowledge of the underlying API.

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 mentions 'Uses the same catalog policy and verification pipeline', which hints at usage context, but it does not explain when to prefer this over direct execution or sibling tools. There is no explicit condition for when to use this tool instead of others, such as when you need to create a layer with minimal typing.

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

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

Annotations are minimal, and the description only adds a vague reference to 'the same catalog policy and verification pipeline.' It does not explain what verification checks are performed, whether the operation affects the selection, or what side effects renaming may have.

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 one compact sentence with no padding. It is front-loaded with the core purpose, and the catalog-policy note is kept separate, but the phrase 'the same' is ambiguous without additional context.

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?

Despite having only one parameter, the tool is under-specified: it omits the target layer context and clarifies neither the role of 'name' nor the practical meaning of the catalog/verification policy. The presence of an output schema does not compensate for these input-side gaps.

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

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

The schema description coverage is 0% and the description adds no detail about the single required 'name' parameter. It is not clear whether 'name' is the new layer name, the current layer name, or an identifier, nor what layer the renaming applies to.

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 identifies the operation as 'layer.rename' and clearly points to renaming a layer. It establishes this as a typed convenience wrapper rather than a generic command execution, which helps distinguish it from command-level tools, though it stops short of a plain-language statement like 'Renames the selected layer.'

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 or when-not-to-use guidance is given. The phrase 'Typed convenience tool' hints that this is a specialized wrapper, but it does not tell the agent when it should be preferred over photoshop_command_execute, photoshop_layer_create, or other layer-related 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?

Annotations provide no hints (all false), so the description carries the burden. It adds key behavioral context: the code is never returned to the client, and it is displayed in a trusted local dialog. However, it does not disclose other potential traits like whether it blocks, whether user interaction is needed beyond viewing, or failure conditions (e.g., if already paired). It is useful but not comprehensive.

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, focused sentence with no filler. It front-loads the primary action and immediately follows with the critical behavioral note about the return value. Every word 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 tool with no parameters and an existing output schema, the description is largely complete. It explains the effect and the key limitation (no return value). It does not mention prerequisites like Photoshop being running or whether this is a required first step, but for such a narrow tool, the description is adequate. A minor gap exists for conditions like 'must be called before other commands', but that is not essential for calling it correctly.

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

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

There are zero parameters, so the schema trivially covers everything. The description does not need to add parameter semantics, and it does not. Per the baseline for 0-parameter tools, a 4 is appropriate because no additional explanation 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 states a specific verb ('Display'), a clear resource ('short-lived port-bound bridge pairing code'), and a specific context ('trusted local Windows dialog'). It clearly distinguishes from sibling tools, none of which appear to handle pairing. It is unambiguous about what the tool does.

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

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

The description says what the tool does but does not state when to use it relative to other tools, such as prerequisites (e.g., 'use before other Photoshop commands') or when not to use it. No alternatives or exclusions are mentioned, leaving the invocation context to inference.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=truesing. The description adds that the export is temporary and low-resolution, which is additional context about side effects and output character. That goes beyond the structured hints, so a 4 is appropriate.

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, no fluff. Front-loaded with the core purpose. Exceptionally concise.

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 description covers purpose and side effects, but lacks any guidance on parameter usage or prerequisites. Since it's a simple tool with one param, and output is presumably described by the output schema, it's adequate but not complete. A 3 reflects the missing parameter explanation.

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%. The parameter max_edge has no description in the schemaestr. The tool description does not explain what max_edge controls (likely the maximum edge dimension of the preview). The agent must infer from the name. This is a significant gap, so score 2.

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 ('Return') plus a precise object ('low-resolution JPEG preview of the active Photoshop document'), which immediately tells an agent what the tool does and what resource it operates on. It also implies a distinction from the sibling export tool by calling it a 'preview'.

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

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

The phrase 'Side effects: temporary export only' signals that this is for quick previews and not persistent exports, but it does not explicitly name the alternative (e.g., photoshop_document_export) or state when to choose one over the other. The guidance is indirect and could be clearer.

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

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

The description adds little beyond the annotations: it mentions that the same catalog policy and verification pipeline is used, but does not disclose side effects, failure conditions, or what state is modified. It does not contradict the annotations, so it avoids a 1.

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 waste, and the primary identification of the tool comes first. The second sentence adds pipeline context, though 'same' is vague without a named baseline.

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 tool with an output schema and existing annotations, the description is minimally viable: it identifies the wrapped command and mentions shared verification. It falls short of a 4 because it never states the operation's effect in plain terms, leaving domain familiarity to fill the 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?

The input schema has zero parameters with 100% coverage, so there is nothing for the description to add. The baseline of 4 applies because no parameter documentation is needed.

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

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

The description explicitly maps the tool to the selection.deselect command, conveying the action (deselect) and resource (selection) without ambiguity. It does not, however, provide a plain-language statement of the effect, and it does not contrast the tool with select_all or command_execute.

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 invoke this tool versus alternatives such as photoshop_selection_select_all or the generic command executor. The only usage signal is the command name itself, which leaves the agent to infer the appropriate context.

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

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

The description adds 'same catalog policy and verification pipeline' but never explains what that means or what selecting all actually does (e.g., modifies the current selection, affects the document state). Annotations do not cover read-only behavior, and no such context is provided in the description. No contradiction with annotations exists.

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

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

The description is extremely short with no filler, making it easy to consume. The two sentences are structured with the primary purpose first. However, the usefulness of the 'catalog policy' sentence is questionable since it is not 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?

For a zero-parameter tool with an output schema and a clear sibling (deselect), the description is minimally sufficient. Yet it omits any explicit statement of what 'select all' does or what the output represents, which keeps it from being fully complete as a standalone description.

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 schema coverage is 100%, so the description is not required to explain parameters. Baseline for a zero-parameter tool is 4, and the description does not introduce any confusion.

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 ('selection.select_all') and the tool name emphasizes 'select_all', making it clear this is a select-all operation. It is distinguishable from the sibling 'photoshop_selection_deselect'. However, it relies on the tool name and domain jargon rather than plainly stating what the tool does in user-facing terms.

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 is given about when to use this tool versus alternatives like photoshop_command_execute or photoshop_selection_deselect. The phrase 'convenience tool' hints at usage but does not state the condition or compare with siblings.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the description's 'Side effects: none' is consistent but adds little beyond the annotations. It provides no additional behavioral context such as staleness, performance, or whether the state is a snapshot.

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 that states the return content first and the safety property second. Every word earns its place, with no filler or repetition.

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

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

For a read-only, zero-parameter state getter with an output schema present, the description is complete. It names the exact state components returned and confirms no side effects, so an agent has enough to invoke it correctly.

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

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

The tool has zero parameters and the input schema is empty, so there is no parameter burden for the description to carry. The baseline for 0 params is 4, and the description adequately covers the tool's input 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?

The description uses a specific verb ('Return') and names the exact resource scope: live document, active layer, selection, and history state from the UXP plugin. This clearly distinguishes it from sibling tools like photoshop_preview_get or photoshop_host_describe.

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 no guidance on when to use this tool versus alternatives. While the name and content imply it is for reading current Photoshop state, it does not state when to prefer it over photoshop_host_describe, photoshop_preview_get, or other state-related siblings.

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