photoshop_pairing_begin

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.