d365_plugin_image_update

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

Annotations already declare destructive=true and non-idempotent, and the description adds meaningful confirmation-side detail beyond them: omitted patch values are preserved (partial-semantics), validation runs against fields, parent step and duplicate aliases, and saved fields are read back. It doesn't spell out consequences of a bad update or permission requirements, but the added disclosure is well past the annotation baseline.

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?

Two sentences, front-loaded with the verb and resource, with no redundant restatement of the title. The second sentence compresses four distinct behaviors into one clause chain, which is dense but still parseable.

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 an 11-parameter, nested-object mutation with no output schema, the description covers the preview-to-write flow, partial-patch semantics, the validation gates, the fingerprint requirement and the read-back return. Missing only sibling routing and explicit failure/concurrency edge cases.

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?

Coverage is 73% and the schema already documents dryRun, ifMatch, expectedFingerprint and allowUnprotectedUpdate. The description still adds real semantics the schema lacks: patch is a partial patch whose omitted values are preserved, and a preview fingerprint is mandatory for the write path. It leaves the ifMatch/allowUnprotectedUpdate interplay to the schema, so not a 5.

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 ("Preview/update an unmanaged customizable image") and the tool name plus sibling naming convention (image_register, image_delete, image_update) makes the target obvious. It doesn't explicitly contrast itself with those siblings in the text, so it stops short of a 5, but the operation 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?

The description implies the workflow (preview first, then a fingerprint-gated real write) and names prerequisites for the write path. It never states when to choose this over d365_plugin_image_register or d365_plugin_image_delete, nor any exclusions, so usage is only implied rather than prescribed.

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