Add cards to an existing canvas

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

With no annotations, the description carries the full burden, and it delivers meaningful detail: preserving all existing items and positions, placing new cards to the right, and defining how connections can reference new or existing cards. It does not cover error behavior or permissions, but the core side effects are well disclosed.

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, front-loaded with the action and the most important guarantee (preservation), followed by placement and connection rules. Every sentence earns its place with no redundancy.

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 mutation tool with three parameters and nested card/connection objects, the description plus the rich input schema covers the essential invocation context. It could explicitly say to use create_canvas when the target does not exist, but 'existing' and the sibling context make this a minor gap.

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 67% and the description adds value beyond it, especially for connections: new cards can be referenced by index/title, existing cards by title. It also clarifies the append behavior and placement, which helps the agent understand the effects of the cards parameter.

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 uses a specific verb ('Append') and resource ('existing v4 .klypix'), and clearly states the preservation behavior. This distinguishes it from sibling tools like create_canvas or read_canvas without relying on the title alone.

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 clearly frames this as the tool for modifying an existing canvas while preserving its content, which orients the agent toward 'add to existing' rather than 'create new'. It does not explicitly name alternatives like create_canvas or state exclusions, but the context is strong enough.

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