photoshop_get_preview

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

No annotations are provided, so the description carries the full burden. It discloses side effects ('creates and deletes a temp file; does not modify the document'), preconditions ('active document required'), and return format ('MCP image content block (JPEG) plus metadata text'). This is strong behavioral disclosure for a read-only preview tool, though it could mention failure behavior if no document is active.

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 compact and well-structured: a one-sentence purpose, a clear 'Use when'/'Do NOT use when' pair, and a concise 'Returns/Preconditions/Side effects' block. Every sentence earns its place, and the most important routing information is front-loaded.

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 preview tool with 3 optional parameters, 100% schema coverage, and no output schema, the description covers purpose, usage, preconditions, side effects, and return format. It is complete enough for an agent to call correctly. The only minor gap is not describing what happens when no document is active (error vs. no-op), but the precondition statement implies the requirement.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters (quality, document_id, max_dimension_px). The description adds context for document_id ('activates that document before running so a UI tab switch cannot retarget the edit'), which is valuable. However, quality and max_dimension_px are fully covered by the schema, so the description doesn't need to add more. Baseline 3 is appropriate.

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

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

The description states a specific verb and resource: 'Export the active document as a base64 JPEG preview for visual verification.' This clearly distinguishes it from sibling tools like photoshop_get_state (numeric state) and photoshop_export_as (full export). The purpose is immediately understandable and differentiated.

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

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

The description explicitly provides when-to-use ('after visual edits to confirm result before reporting success') and when-not-to-use ('Do NOT use when: you only need numeric state — use photoshop_get_state (much cheaper)'). It names the alternative tool directly, giving the agent a clear decision rule.

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