photoshop_recipe_batch_watermark

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

With no annotations provided, the description carries the full burden of behavioral disclosure and delivers: side effects ('writes one JPEG per source image; source files are never modified'), preconditions (assets_dir exists; text or logo_path given; no active document required), error semantics ('Files that fail are skipped, not fatal'), and the return shape. The schema adds the document_id activation behavior. This is comprehensive for a mutation tool with zero annotation coverage.

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?

Well-structured with labeled sections (Use when, Do NOT use, Returns, Preconditions, Side effects) and front-loaded core purpose. It's longer than minimal, but for a 10-parameter batch tool with no annotations, every sentence carries information. Minor deduction only because a couple of points (e.g., 'text wins' precedence) also appear in the schema — a small redundancy, not waste.

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 complex 10-param tool with no annotations and no output schema, the description covers preconditions, side effects, error handling, return format, and usage boundaries. The only gaps are minor: the exact output filename/naming convention and destination folder are not stated in prose (though output_paths implies them). Otherwise an agent has everything needed to call 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?

Schema coverage is 100%, so baseline is 3. The description adds genuine value beyond the schema: the 'text wins if both are given' precedence rule, the font_size default 0 = auto sizing at 4% of image height, and the logo/text mutual exclusivity. It does not restate every parameter, which is appropriate given the schema's own rich descriptions. Slight deduction for not clarifying output JPEG path/naming in prose, but that's covered by the return's output_paths.

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: 'Apply a text or logo watermark to every image in a folder and export watermarked JPEGs.' The recipe_ prefix already signals it's a high-level workflow distinct from single-document tools, and the description explicitly differentiates from siblings by naming the alternatives it is not. The distinction from photoshop_create_text_layer and photoshop_place_image is 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?

Explicit 'Use when' and 'Do NOT use when' sections with named alternative tools (photoshop_create_text_layer / photoshop_place_image for single docs) and a clear exclusion (removing watermarks is not supported). This is textbook guidance — nothing is left to inference.

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