color_calibrate

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

The description discloses external prerequisites (plate solution + internet), sensor-specific default tuning (Sony OSC with UV/IR cut), the fallback chain between methods, and the linear-data-only restriction. This goes well beyond annotations (destructiveHint true) by explaining what the tool actually does and what it needs before running. No contradiction with annotations.

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 at about 36 words and front-loads the method flow, then optional behavior, input constraint, and safety. The arrow notation is dense but every clause earns its place, balancing information density with brevity.

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 tool with 9 parameters and no output schema, the description covers the critical decision path: method selection, prerequisites, linear data, and checkpointing. It is enough to invoke minimally with just an id. It leaves advanced parameter semantics ambiguous, but those are optional and the core operation is sufficiently specified.

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?

Only 2 of 9 schema properties have descriptions (22% coverage), so the description must compensate. It does clarify the method parameter (default SPCC, fallback chain) and the neutralization behavior, but leaves narrowband, limit_magnitude, white_reference, and background_reference_id unexplained in both schema and description. This is partial, not full, compensation.

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 identifies the tool's purpose through named PixInsight color-calibration processes (SPCC, PCC, ColorCalibration) and mentions optional background neutralization. It distinguishes itself from siblings like background_neutralize by placing color calibration at the core. However, it never explicitly states a verb phrase like 'calibrate colors', relying on the tool name and process names to convey purpose.

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 provides explicit fallback routing: SPCC by default (requiring plate solution + internet), PCC as fallback, and ColorCalibration when no astrometry is available. It also restricts input to linear data and instructs checkpointing first, establishing clear usage windows. It does not explicitly contrast the whole tool against sibling tools such as background_neutralize or plate_solve, leaving some selection inference to the agent.

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