coras_create_diagram

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

No annotations are provided, so the description carries the burden. It discloses real behavior: it writes a file, lays elements out automatically in canonical left-to-right order, sizes them to labels, infers relationship types, and produces output that opens as if hand-drawn. It does not mention that overwrite defaults to true or that a dry_run skips writing, but those are documented in the schema; the description still provides substantial non-obvious behavioral detail.

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 compact and front-loaded, with the primary purpose in the first sentence. The later sentences earn their place by explaining layout order, input modes, and editor compatibility. The phrase 'show you how the editor draws it' is slightly indirect, but there is no wasted or redundant content.

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 tool with 9 parameters and nested spec objects, the description covers the main usage patterns, layout behavior, and output compatibility. It does not explicitly describe the return value or when to use dry_run/overwrite, but those are fully documented in the schema. The description is complete enough for an agent to decide to call the tool and choose an input mode correctly.

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 100%, so the baseline is 3. The description reinforces that 'spec' and 'text' are the two input modes and explains layout/inference behavior, but it does not add materially new per-parameter meaning beyond what the schema already says. This is acceptable given the schema's completeness.

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 a specific verb and resource: 'Build a CORAS diagram file (.dgx)...' and adds the automatic layout behavior. It distinguishes cleanly from siblings like coras_read_diagram, coras_edit_diagram, coras_render_diagram, and coras_validate_file by making 'create' the core action. The input modes ('spec' or 'text') are also clearly stated.

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 gives clear usage context: use this to build a new .dgx file, and provide either a structured spec or CORAS text notation. It does not explicitly name alternatives or say 'use coras_read_diagram for reading', but the create-vs-read/edit/render distinction is strong enough that the intended condition is clear. No exclusions are stated, so it misses a 5.

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