create_grease_pencil

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

No annotations exist, so the description carries the full burden. It does disclose the creation side effects (object, first layer, and frame are created), which is useful beyond the name. It does not mention where the object is linked, whether defaults are applied, or any undo/duplication behavior — acceptable for a straightforward creation tool but not rich.

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 purpose sentence, then workflow guidance, then a compact Args/Returns block. Every line is short and scannable; the only mild redundancy is the Returns section, which duplicates the output schema.

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 three-parameter creation tool with an output schema present, the description covers purpose, sibling workflow, all parameters, and what it creates. The only gap is that the location semantics (world vs local space) and default behavior are left implicit.

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's Args block is the only prose documentation for name, location, and layer_name. However, the explanations are near restatements of the parameter titles ('Object name', 'Position [x, y, z]'), adding little beyond confirming format and role. All three parameters are at least addressed, so it partially compensates for the coverage gap.

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 ('Create a Grease Pencil object to draw 2D strokes in 3D space'), which unambiguously separates it from create_annotation, create_curve, and create_object siblings. The purpose is clear without opening the schema.

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?

Explicitly routes the agent: use add_gp_stroke to draw into it, create_gp_material to colour, and the annotation tools for viewport notes. This is a clear when-to-use / when-to-use-something-else statement, though it doesn't cover prerequisites or what to do if a Grease Pencil object already exists.

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