Adds a rectangle or ellipse at specified pixel coordinates with an optional hex fill; target the current document or pass a session UUID for another.
Add a rectangle or ellipse at pixel coordinates (x, y, width, height) with an optional #RRGGBB or #RRGGBBAA fill. Defaults to the current document; pass session_uuid to target another.
| Name | Required | Description | Default |
|---|---|---|---|
| x | Yes | ||
| y | Yes | ||
| fill | No | ||
| kind | Yes | ||
| width | Yes | ||
| height | Yes | ||
| session_uuid | No |
Changes observed during successful MCP inspections.
v0.1.0Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare this is a non-read-only, non-idempotent, non-destructive mutation, so the safety profile is covered. The description adds the coordinate system (pixels) and default-document behavior, but says nothing about whether the new shape becomes selected, z-order placement, required permissions, or what happens if no document is open.
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?
Two tight sentences with no filler; the core action and geometry come first, then the fill format, then the document-targeting note. Every clause carries information an agent needs.
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 simple create-primitive tool with no output schema, the description covers the action, geometry, styling, and document targeting adequately. The remaining gaps are outcome-related (selection/z-order, error when no document exists), which are helpful but not blocking 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 description coverage is 0%, so the description must carry the load, and it does explain the geometric parameters (x, y, width, height in pixels), the two shape kinds, the #RRGGBB/#RRGGBBAA fill format, and the purpose of session_uuid. It omits that fill is optional and what it defaults to, and does not note the positivity constraint on width/height, leaving minor gaps.
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 ('Add') and resource ('a rectangle or ellipse') plus the coordinate model, so an agent can distinguish it immediately from affinity_add_text (text) and affinity_place_image (image). The scope of the operation is unambiguous.
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 clarifies targeting behavior ('Defaults to the current document; pass session_uuid to target another'), which is useful context. But it gives no when-to-use vs sibling guidance (e.g. add_shape vs add_text vs execute_script for programmatic creation), nor prerequisites such as needing an open document.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.