Photoshop Full MCP v2 es un servidor MCP local con control de capacidades para Photoshop. Está dirigido a Photoshop 2026 (27.9) instalado, evitando suposiciones sobre versiones y rutas de instalación.
Requisitos previos: Windows 10/11, Photoshop 24 o posterior, Node.js 20 o posterior y Codex Desktop o la CLI de Codex. Photoshop 2026 (27.9) es el host de referencia.
Descarga photoshop-full-mcp-v2.0.1-windows.zip desde la última versión y extráelo. El manifiesto firmado adyacente y la firma autentican las actualizaciones futuras; el archivo .sha256 es una verificación de integridad opcional.
Abre PowerShell en la carpeta extraída photoshop-full-mcp-2.0.1 y ejecuta:
powershell -NoProfile -ExecutionPolicy Bypass -File .\Install.ps1El instalador verifica el runtime incluido, lo instala en %LOCALAPPDATA%\PS_MCP y registra un servidor photoshop_full_mcp independiente. La carpeta de descarga o extracción ya no es necesaria después.
Haz doble clic en el archivo photoshop-full-mcp-v2.0.1.ccx incluido para instalar el plugin de Photoshop. Si la instalación CCX no está disponible, usa Adobe UXP Developer Tools y selecciona el manifiesto instalado que muestra Doctor.
Reinicia Codex, abre Photoshop y elige Plugins > Photoshop Full MCP Bridge.
En Codex, llama a photoshop_pairing_begin, introduce el valor port-code completo que muestra el cuadro de diálogo de confianza de Windows en el panel de Photoshop y llama a photoshop_host_describe. Una respuesta con bridge.connected: true confirma que el emparejamiento fue exitoso.
Ejecuta Doctor en cualquier momento:
powershell -NoProfile -ExecutionPolicy Bypass -File "$env:LOCALAPPDATA\PS_MCP\app\tools\Doctor.ps1"El modo de aprobación predeterminado es automático. Los comandos de edición normales no requieren aprobaciones una por una. Consulta la guía de instalación para Windows y la guía de solución de problemas ilustradas para actualizar, desinstalar y recuperar.
No se afirma que todas las funciones de la interfaz de Photoshop sean scripteables. El catálogo distingue:
supported: implementado y comprobado con una instancia real de Photoshop en el host de destino
experimental: depende de licencias, modelos, red o créditos
requires_user: crea un trabajo no bloqueante con instrucciones explícitas de menú nativo que el usuario debe completar; no automatiza clics del sistema operativo
unverified: inventariado pero bloqueado hasta que pase una prueba local
unavailable: no existe un contrato UXP de escritorio confiable
Related MCP server: Photoshop MCP Server
Servidor MCP: Node.js/TypeScript sobre stdio
Puente de Photoshop: panel UXP Manifest v5 sobre 127.0.0.1 autenticado
Descubrimiento: puertos 38452 a 38462
Emparejamiento: código port-code de 128 bits de corta duración mostrado solo en un cuadro de diálogo de confianza de Windows abierto por photoshop_pairing_begin
Ejecución: validación de esquema, política de capacidad/riesgo, cola FIFO, executeAsModal, agrupación de historial única y verificación de estado antes/después
Aprobaciones: automáticas por defecto; los tokens de un solo uso con ámbito, la protección contra reproducción, los límites de rutas y las listas de permitidos de descriptores avanzados permanecen aplicados
Puente de archivos predeterminado: la exportación y la reapertura confinada usan la carpeta %LOCALAPPDATA%\PS_MCP\exports propiedad del servidor, sin selector de archivos; una carpeta UXP persistente seleccionada por el usuario sigue siendo opcional
batchPlay avanzado sin procesar: oculto por defecto; establece PS_MCP_ADVANCED=confirm para exponer solo los descriptores deselect e invert sin parámetros. Los demás descriptores sin procesar y todo el JSX sin procesar se rechazan antes de llegar a Photoshop
Telemetría: ninguna
El inventario amplio de funciones está en catalog/features.json. Los contratos ejecutables están en catalog/commands.json.
Estado auditado actual: 101 contratos de comandos (87 supported, 1 experimental, 0 unverified, 11 requires_user, 2 unavailable) y 52 grupos de funciones (21 supported, 1 experimental, 0 unverified, 10 requires_user, 20 unavailable). Un comando o grupo de funciones se promueve a supported solo después de que pase una prueba de integración con una instancia real firmada de Photoshop 27.9. Los descriptores Generative Fill y Neural Filter heredados no válidos están explícitamente no disponibles, y los descriptores sin procesar malformados o no incluidos en la lista de permitidos se rechazan en el servidor para que no puedan abrir el cuadro de diálogo de comando desconocido de Photoshop.
La instalación desde el ZIP de la versión se recomienda. Los colaboradores pueden clonar el repositorio y ejecutar:
npm ci --no-audit --no-fund
powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\Install-Local.ps1El envoltorio de compatibilidad se compila una vez, copia un runtime de producción autocontenido a %LOCALAPPDATA%\PS_MCP y registra esa copia instalada. Mover o eliminar el checkout del código fuente después no rompe el servidor MCP. El instalador registra photoshop_full_mcp junto a un photoshop_mcp existente; no elimina ni modifica el paquete anterior.
Para el plugin de UXP, ejecuta npm run uxp:package e instala el CCX generado, o carga el manifiesto instalado que reporta Doctor en Adobe UXP Developer Tools. Opcionalmente, elige una carpeta de exportación en el panel. Sin una, document.export usa la carpeta de exportación predeterminada propiedad del servidor autenticado.
# Download, verify, and install the newest GitHub release
powershell -NoProfile -ExecutionPolicy Bypass -File "$env:LOCALAPPDATA\PS_MCP\app\tools\Update.ps1"
# Remove the installed runtime and Codex registration; preserve pairing and exports
powershell -NoProfile -ExecutionPolicy Bypass -File "$env:LOCALAPPDATA\PS_MCP\app\tools\Uninstall.ps1"
# Also remove pairing state and exports
powershell -NoProfile -ExecutionPolicy Bypass -File "$env:LOCALAPPDATA\PS_MCP\app\tools\Uninstall.ps1" -RemoveUserDataphotoshop_host_describe
photoshop_capability_list
photoshop_state_get
photoshop_command_search / photoshop_command_describe
photoshop_command_execute
photoshop_preview_get después de cambios visuales
Los comandos destructivos, de validación, que consumen créditos y los permitidos se aprueban automáticamente por el servidor local, por lo que no se necesita ningún clic de aprobación en el panel de Photoshop. photoshop_approval_request permanece como una API de compatibilidad y devuelve inmediatamente un trabajo completado con ámbito. Establece PS_MCP_APPROVAL_MODE=panel solo si quieres intencionalmente el flujo de trabajo anterior de aprobación por clic. El sandboxing de rutas, las compuertas de estado de capacidad, la protección contra reproducción y las listas de permitidos de descriptores sin procesar no se omiten.
Para la validación del host local, inicia un servidor temporal con PS_MCP_VALIDATION=confirm. Esto expone photoshop_validation_request y photoshop_command_validate. Aceptan solo comandos UXP DOM catalogados sin verificar, se aprueban automáticamente por defecto y operan únicamente en documentos llamados PS_MCP_VALIDATION_*. La ejecución de validación nunca promueve una capacidad automáticamente.
npm run check incluye una auditoría automática de cada entrada de comando y función. La auditoría informa sobre la presencia del manejador, la procedencia de la prueba en vivo, la deriva del resumen del contrato del catálogo y la coherencia de estado/ejecución/ruta. Un comando o función supported falla la verificación a menos que exista una prueba transaccional coincidente en evidence/live, por lo que una implementación o cadena de documentación por sí sola no puede promover el soporte.
Genera el informe completo de solo lectura con:
npm run audit:inventory:jsonLa revisión de promoción además requiere un resultado photoshop_host_describe capturado recientemente cuyo puente esté actualmente conectado. La prueba en vivo también debe llevar una firma de evidencia local válida:
npm run audit:promotion -- --promotion-command selection.ellipse --host-report .\host-describe.jsonEl comando falla con LIVE_HOST_DISCONNECTED cuando el puente UXP no está en vivo, incluso si existe una prueba más antigua. La evidencia ya no se acepta de JSON de host, resultado o aserción generado por el llamador. El grabador inicia una sesión MCP de perfil de validación por sí mismo, verifica la identidad de Photoshop conectada, recibe la aprobación automática con ámbito, ejecuta el comando en un documento PS_MCP_VALIDATION_*, verifica los hashes de estado y de vista previa de píxeles, realiza el viaje de ida y vuelta de deshacer cuando es necesario, cierra el documento temporal y firma el recibo de transacción:
Set-Content .\validation-args.json '{"left":0,"top":0,"right":64,"bottom":64}'
npm run evidence:record -- --command selection.ellipse --args .\validation-args.jsonLa clave privada de firma de evidencia se almacena en %LOCALAPPDATA%\PS_MCP con una ACL solo de usuario; solo la clave pública de verificación se almacena en el repositorio. El grabador escribe hashes y metadatos de host/verificación en la lista de permitidos únicamente. No copia píxeles, contenidos ni nombres de documentos, avisos, tokens de puente, argumentos de solicitud ni resultados sin procesar de Photoshop. La grabación de evidencia no edita catalog/commands.json; la promoción de estado sigue siendo un cambio revisado por separado.
npm run check
npm test
npm --prefix apps\uxp-plugin run check
npm run build
npm run test:contractLas pruebas generativas en vivo están excluidas intencionalmente. Deben ser aprobadas explícitamente porque pueden consumir créditos y dependen de la cuenta de Adobe con sesión iniciada.
Si una ejecución de validación se interrumpe, inspecciona el documento activo antes de la limpieza. El comando de mantenimiento es de solo simulación por defecto y se detiene tan pronto como el título activo no sea un título de validación PS_MCP_* propio:
npm run cleanup:owned-documents
npm run cleanup:owned-documents -- --applyCaptura un comando con el Grabador de acciones de desarrollador de Photoshop y luego genera una entrada de catálogo no verificada:
node .\scripts\import-action-recording.mjs --id filters.example --category filter --en "Example Filter" --ko "예제 필터" --file .\recording.jsonEl importador imprime una definición de catálogo y un resumen de evidencia SHA-256. Nunca promueve el comando a supported; la promoción requiere una prueba de integración con documento aislado.
Secreto de emparejamiento y metadatos de endpoint: %LOCALAPPDATA%\PS_MCP
Exportaciones predeterminadas: %LOCALAPPDATA%\PS_MCP\exports
Token UXP: almacenamiento seguro UXP de Photoshop
Los secretos y los datos de imagen de vista previa nunca se escriben en los registros.
Create an automatically completed, scope-bound approval job for compatibility. Direct execution normally does not need this tool.
| Name | Required | Description | Default |
|---|---|---|---|
| args | No | ||
| engine | No | ||
| payload | No | ||
| command_id | Yes | ||
| justification | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
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.
List the versioned command catalog. Supported means locally verified; unverified and unavailable are never executed.
| Name | Required | Description | Default |
|---|---|---|---|
| query | No | ||
| status | No | ||
| category | No | ||
| summary_only | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
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.
Describe one command's schemas, prerequisites, risk, approval, verification, and rollback contract.
| Name | Required | Description | Default |
|---|---|---|---|
| command_id | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
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.
Execute a catalog command after schema, capability, prerequisite, risk, approval, modal, and verification checks.
| Name | Required | Description | Default |
|---|---|---|---|
| args | No | ||
| command_id | Yes | ||
| dialog_mode | No | ||
| verification | No | ||
| approval_token | No | ||
| idempotency_key | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
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.
Search locale-independent Photoshop command IDs using English, Korean, category, or description text.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | ||
| category | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
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.
Typed convenience tool for document.create. Uses the same catalog policy and verification pipeline.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | ||
| width | Yes | ||
| height | Yes | ||
| resolution | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
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.
Typed convenience tool for document.export. Uses the same catalog policy and verification pipeline.
| Name | Required | Description | Default |
|---|---|---|---|
| format | Yes | ||
| quality | No | ||
| file_name | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
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.
Typed convenience tool for history.undo. Uses the same catalog policy and verification pipeline.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
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.
Describe the installed Photoshop host, live UXP bridge, exact runtime API versions, and pairing state. Side effects: none.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
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.
Typed convenience tool for image.resize. Uses the same catalog policy and verification pipeline.
| Name | Required | Description | Default |
|---|---|---|---|
| width | No | ||
| height | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
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.
Cancel a queued, running, or awaiting-user Photoshop job.
| Name | Required | Description | Default |
|---|---|---|---|
| job_id | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
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.
Get an asynchronous or user-assisted job. Completed approval jobs return a one-time approval token.
| Name | Required | Description | Default |
|---|---|---|---|
| job_id | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
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.
Resume a user-assisted Photoshop job after the user completes the native UI step.
| Name | Required | Description | Default |
|---|---|---|---|
| job_id | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
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.
Typed convenience tool for layer.create. Uses the same catalog policy and verification pipeline.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
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.
Typed convenience tool for layer.rename. Uses the same catalog policy and verification pipeline.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
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.
Display the short-lived port-bound bridge pairing code in a trusted local Windows dialog. The value is never returned to the MCP client.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
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.
Return a low-resolution JPEG preview of the active Photoshop document. Side effects: temporary export only.
| Name | Required | Description | Default |
|---|---|---|---|
| max_edge | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
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.
Typed convenience tool for selection.deselect. Uses the same catalog policy and verification pipeline.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
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.
Typed convenience tool for selection.select_all. Uses the same catalog policy and verification pipeline.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
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.
Return live document, active layer, selection, and history state from the UXP plugin. Side effects: none.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
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.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v2.0.1photoshop_approval_requestphotoshop_capability_listphotoshop_command_describephotoshop_command_executephotoshop_command_searchphotoshop_document_createphotoshop_document_exportphotoshop_history_undophotoshop_host_describephotoshop_image_resizephotoshop_job_cancelphotoshop_job_getphotoshop_job_resumephotoshop_layer_createphotoshop_layer_renamephotoshop_pairing_beginphotoshop_preview_getphotoshop_selection_deselectphotoshop_selection_select_allphotoshop_state_getScored across 20 tools
Most tools target distinct operations (e.g., photoshop_command_search vs photoshop_command_describe), but photoshop_state_get and photoshop_preview_get could be confused since both return document-related state. photoshop_host_describe is oddly named and overlaps conceptually with photoshop_capability_list, as both can describe the host environment.
The naming pattern is inconsistent: many tools follow verb_noun (command_search, command_execute), but others invert or mix forms (photoshop_host_describe, photoshop_capability_list, photoshop_selection_select_all). The 'photoshop' prefix is applied to different word orders, and some tools use different verb stems (e.g., 'deselect' vs 'select_all'), creating a chaotic feel.
20 tools is a sizeable but defensible surface for an automation server covering host info, jobs, approval, documents, layers, selections, history, and image operations. The count fits the scope, though it borders on the heavy side.
Document management is shell-shaped (only create/export, no document read/delete), layer management lacks list/delete/get operations, and job control lacks a job list or a full workflow. There is no redo counterpart, no history list, and image operations are only resize/export.
Edit images over MCP with object removal, background removal, and guided generative edits.
The Canva MCP server connects AI assistants (like Claude, ChatGPT, and Cursor) to Canva's API, enabling them to create and manage designs directly within chat conversations. Key capabilities include generating new designs from prompts, autofilling templates, searching and resizing existing designs, importing files from URLs, exporting designs as PDFs or images, and managing folders and comments without switching between tools.
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
Use AI models for chat, image, and video generation from Claude Code and other MCP hosts.
