ps_actionManager

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

Adds real value beyond annotations: it discloses that results come back as result descriptors and that dialogs:true surfaces the plugin dialog, plus the stringID vs '$' charID convention. However, for a tool that can execute literally any Photoshop menu command it says nothing about mutation scope, irreversibility/undo, or whether the command batch is atomic — a notable gap given that destructiveHint=false understates the reach of 'every menu item'.

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

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

Front-loaded with the capability claim, then the payload format and the two rules (charID prefix, dialogs). Dense but every element earns its place; the inline JSON example is longer than prose would be but is the most information-dense way to convey the schema.

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

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

Return value is covered ('result descriptors') so no output schema is needed, and the payload format is demonstrated. Missing for a mutation-class escape hatch: failure modes when a command ID is invalid, whether commands run sequentially, and what state is left behind on partial failure.

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

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

With 0% schema coverage the description carries the entire burden, and it does so well: it shows two concrete command objects, explains the _obj/_target/_unit/_value shape, and documents the '$' charID prefix and dialogs:true behavior. It still leaves some ambiguity, e.g. whether dialogs applies globally or per command, and the required key ordering is only inferable from the example.

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

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

States a specific verb+resource (run any Photoshop command) and explicitly scopes it as the general escape hatch: full feature access including every filter, neural/AI command, third-party plugin filter and menu item. That framing separates it from narrow siblings like ps_applyFilter, ps_runMenuCommand and ps_runAction, which cover only a subset.

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 'ANY ... full feature access' phrasing strongly implies 'use this when no dedicated tool covers your case', but that routing rule is never made explicit and no siblings are named. There is no guidance on when to prefer ps_applyFilter / ps_runAction / ps_runMenuCommand instead, nor on prerequisites such as an open document.

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