Raster Calculator

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

No annotations are provided, so the description must fully disclose behavioral traits. It mentions writing a GeoTIFF to output_path and using reference_layer for grid/extent, but it does not clarify whether the output is loaded as a new layer in QGIS, what happens if the file already exists, or error handling. This leaves significant gaps for a computational tool.

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 three sentences, each adding value: defining the tool, providing usage syntax, and specifying output behavior. It is front-loaded and contains no redundant information.

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?

The tool has no output schema, so the description should explain return values. It does not mention whether the result is returned or only written to disk. It also lacks details on expression validation or side effects. While it covers key inputs and output format, gaps remain regarding the full behavior from an AI agent's perspective.

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 description coverage is 0%, so the description compensates fully by explaining the expression format with an example, the output_path as a GeoTIFF file, and the optional reference_layer parameter including default behavior. All three parameters are given meaningful context beyond the schema.

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 clearly states it performs band math via the QGIS raster calculator, which is a specific verb+resource combination. It provides an expression syntax example and distinguishes itself from sibling tools like field_calculator by focusing on raster band operations.

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 explains how to reference layers and the output format, but it does not explicitly state when to use this tool versus alternatives like execute_processing or field_calculator. Implicit guidance is provided through the expression syntax, but clear when/when-not is missing.

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