Position/size a source

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

Beyond the sparse annotations (readOnlyHint:false, destructiveHint:false), the description discloses that omitted keys remain unchanged, that desktop layouts never map to mobile, and gives exact canvas dimensions and recommended patterns. This is valuable behavioral context that guides invocation.

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 long but well-structured, with the core purpose up front, then coordinates, then directives, then examples. While some layout guidance is verbose, each section adds practical value and no sentence is wasted.

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 7-parameter tool with no output schema and only 14% schema coverage, the description covers the essential parameters and provides concrete usage patterns. It omits only self-explanatory identifiers like source_id and scene_id, making it complete enough for correct invocation.

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 only 14% (format described). The description explains x, y, width, height with examples and clarifies that coordinates are absolute pixels, and discusses format usage. It also notes that omitted keys are unchanged, adding significant meaning 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 opens with 'Set a source's position and/or size on a canvas', using a specific verb and resource. It clearly distinguishes from sibling tools like set_source_crop or set_source_effects by focusing solely on position/size.

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?

Provides clear context for when to use the tool (positioning/resizing) and explicit mandates such as 'ALWAYS set the two canvases SEPARATELY' with layout patterns for different scenarios. It does not explicitly compare against alternatives, but the usage context is well-defined.

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