get_composite_rect

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

No annotations are provided, so the description carries full burden. It discloses that it reads the composited result of all visible layers (not a single cel), and mentions the flattened composite nature. It also details the return format. While it doesn't mention side effects (none expected) or performance implications, it is sufficiently transparent for a read-only operation.

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 well-structured with a summary line, contrast, and then bulleted Args and Returns. It is front-loaded with the main purpose. However, it uses a numpy-style docstring format which is slightly verbose; each sentence contributes, but some parts like 'Args:' could be more concise. Still, it is efficient and clear.

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 description provides enough context for using this tool among over 100 siblings. It names the sibling get_composite_pixel directly, which helps agents disambiguate. It explains the return format (JSON array of objects), which compensates for the lack of an output schema. However, it does not mention related tools like get_pixels_rect or when to prefer this over other reading tools, leaving some gaps in completeness.

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?

The description lists all 6 parameters in Args format, and adds some semantics like 'sprite-global' for x and y. However, the schema itself has titles but no descriptions (0% coverage), so the description adds moderate value. For parameters like width and height, the description 'Region width' and 'Region height' is tautological, adding little beyond the schema. The default for frame_index is mentioned. Overall, it compensates for schema gaps but not exceptionally.

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 reads composite RGBA over a rectangle from all visible layers, and distinguishes itself from get_composite_pixel by specifying it is the rectangular counterpart. The verb 'Read' and resource 'composite rectangle' are explicit, and the differentiation from a sibling tool (get_composite_pixel) is immediate.

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 clear context by comparing to get_composite_pixel, implying that for a rectangular region this tool is appropriate while for a single pixel the other is used. However, it does not explicitly contrast with other similar reading tools (e.g., get_pixels_rect), leaving some ambiguity about when to choose this over alternatives. Still, the comparison is helpful.

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