affinity_place_image

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

Annotations only cover the write/safety profile (readOnly=false, idempotent=false, destructive=false); the description adds genuinely non-obvious behavior: Affinity's filesystem setting restricts readable folders and Desktop is allowed by default. It does not disclose whether repeated calls create duplicate layers (relevant given idempotentHint=false) or failure behavior for disallowed paths.

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?

Three compact sentences, front-loaded with the action, then the placement mode, then the environment constraint. No filler; the filesystem caveat 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?

Six parameters with zero schema descriptions and no output schema mean the description must carry more weight. The unexplained session_uuid and absent return-value behavior (e.g., whether a layer reference is returned) leave real gaps for a mutating placement tool.

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 description coverage, the description does meaningful work explaining that x/y/width/height define a fit rectangle and their omission yields natural size. However image_path's accepted format (relative vs. absolute, allowed roots) and session_uuid's purpose are left entirely undefined.

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 and resource: 'Place an image file into the document.' The image-file target implicitly separates it from affinity_add_shape and affinity_add_text, though no sibling is named explicitly.

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?

Useful conditional guidance on the two placement modes (rectangle-fit vs. natural size) and the default target document ('Defaults to the current document'). It does not say when to choose this over affinity_add_shape or how session targeting relates to siblings.

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