create_artwork

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

With no annotations, the description carries the full burden and does well: it discloses that painting mode returns a plan rather than an image, that style defaults to a guess from the prompt, and that count defaults to 4 on local GPU but 1 on paid cloud services that charge per image. It does not say what happens to an existing document or how failures surface, which keeps it from a 5.

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?

Front-loaded with the trigger condition and the generate-vs-paint fork, then parameter guidance, then the follow-on workflow. Dense but nearly every clause carries information; the inline enumeration of 20+ style values is long but genuinely useful given the schema has no enums.

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 an 11-parameter, no-annotation, no-output-schema tool, the description covers the decision logic, the mode-dependent return shape, cost behavior, and the downstream workflow. The unexplained name/seed/model/backend parameters are the main omission, but they are secondary to 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 0%, so the description must compensate, and it does for most parameters: it enumerates approach values with their decision logic, lists style and aspect options with defaults, explains count's cost tradeoff, and notes width/height as an alternative to aspect. It leaves name, seed, model, and backend entirely unexplained, which is a real gap across 11 parameters.

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 and resource ('Creates the document') and immediately splits the two modes: GENERATES with an image model or sets up for PAINT with Krita brushes. The 'START HERE' framing plus the explicit contrast with generate_image and the painting siblings makes it unmistakable which tool to pick.

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?

Gives explicit routing rules: 'auto' decides realism/connected model -> generate, hand-made/graphic or no model -> paint, plus hybrid. It also names the follow-on tools (brush_stroke, draw_shapes, add_svg, canvas_snapshot) and the escape hatch to generate_image with a control layer, so the agent knows both when to use this and what comes next.

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