prepare_reference

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

With annotations declaring readOnlyHint=false/destructiveHint=false, the description goes well beyond them: it discloses that it writes an RGBA PNG, that the background must be plain, that threshold defaults to just above border noise, that holes smaller than fill_holes are closed while larger openings (trigger guard) stay, that flip is applied before rotate, and that many-open-holes/border-touch/large-drop conditions raise a `warning`. This is unusually rich behavioral disclosure.

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?

Front-loaded with the purpose and worked example, and most sentences carry parameter or behavioral payload. It is dense and occasionally sprawling (the return-value sentence bundles warnings, counts, and preview colours), but little is redundant.

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 9-parameter image-processing tool with no output schema, the description covers input semantics, the required 'plain background' precondition, the produced artifact, and the full payload of the answer including warning conditions and preview contents. Nothing needed to call it correctly is missing.

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 0%, so the description carries the full burden and does so: crop as [x0,y0,x1,y1] fractions from top-left, keep=all vs largest, threshold as colour distance with an auto-default, fill_holes as a share of object area with 0/1 boundary semantics, flip axis meaning and rotate direction/order, and pad margin. Only `out` is left implicit via 'use its path'.

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 ('clean a real-world reference ... crop it, remove the background and keep only the biggest object') and immediately grounds it with a concrete example (two donuts + caption -> one donut, transparent background). It also distinguishes itself from the downstream reference tools by framing itself as their preprocessing step.

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?

Gives clear downstream context: the output path is meant to be used as the reference for compare_view, fit_to_reference, visual_hull, and measure_profile, and it names the transformation options used to bring a panel into the expected view. It does not state explicit exclusions or when NOT to use it, but the role among siblings is unambiguous.

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