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.

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions that existing positions are kept unless a relayout is requested, and that a .bak copy is made first, which are key behavioral traits. It does not cover permissions, reversibility, or failure modes, but the core mutation behavior and safety net are 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?

The description is concise, with two sentences that front-load the main action and then add key behavioral notes. Every sentence adds information without redundancy, making it efficient for an agent to parse quickly.

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?

The description covers the core functionality and key behaviors (preserving positions, backup), and the schema handles detailed parameters. It does not explicitly mention the preview/return image behavior or the ordered application of operations, but these are available in the schema. For a modification tool with this complexity, the context is adequate but not exhaustive.

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 71%, with descriptions for path, backup, layout, preview, and operations. The description adds little beyond what the schema already says about layout (preserve vs auto) and backup behavior. It does not elaborate on scale, direction, or operation specifics, so it provides marginal added value.

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 clearly states the tool modifies an existing .dgx file in place, listing concrete operations like add/remove elements, rename, recolour, move, add/drop diagrams, and relayout. It distinguishes from siblings (create, read, render) by focusing on editing existing files. The verb 'change' is specific and resource is clear.

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 implies this tool is for editing existing diagrams, as opposed to creating new ones (coras_create_diagram). It states that positions are preserved unless a relayout is requested, giving context on when to use the layout option. However, it does not explicitly name alternatives or exclude cases like reading or rendering, so it lacks explicit when-not guidance.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It adds useful non-obvious behavior: 'The editor keeps running after this returns', which signals the tool is non-blocking and the GUI persists after invocation. It also notes the optional file-open behavior, though it does not discuss side effects such as whether the file is locked or whether the tool requires a graphical environment.

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 two short sentences with no filler. It front-loads the core action ('Launch the Threat Modelling Tool GUI') and then adds the key behavioral detail about persistence, all in minimal words.

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 tool with one optional parameter and no output schema, the description covers the essential invocation context and the non-blocking behavior. It does not mention possible failure modes like missing display or invalid file format, but these are not critical for correct invocation, so the description is reasonably complete.

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 parameter's meaning is already fully documented ('Optional .dgx file to open on start-up'). The description reinforces the .dgx file type but adds little beyond what the schema already provides, so the baseline score of 3 applies.

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 states a specific verb and resource: 'Launch the Threat Modelling Tool GUI'. It also clarifies the optional .dgx file and that the diagram is for manual viewing/editing, which clearly distinguishes this tool from siblings like coras_read_diagram, coras_edit_diagram, and coras_render_diagram that operate programmatically rather than via an interactive GUI.

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 implies the tool should be used when a human needs to interact with a diagram by hand ('so the diagram can be looked at and edited by hand'), but it does not explicitly mention alternative tools or state when not to use it. No exclusions or sibling names are provided, leaving the route to alternatives implicit.

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

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

No annotations are provided, so the description carries the full burden. It discloses that the tool reads a file and returns representations (structured spec and text notation) and optionally renders it. However, it does not explicitly state that it performs no modifications, what happens with missing or invalid files, or how scale affects the render. These gaps limit transparency.

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 two sentences with no wasted words. The primary action and output are front-loaded, and the every clause earns its place (read behavior, output formats, use case, optional render).

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 read tool with no annotations or output schema, the description covers the core functionality but leaves scale completely undocumented (no schema description either). It also does not explain the precise return structure or error handling, which an agent would need for robust use. The tool's complexity is moderate, so this is adequate but not complete.

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 75%, with scale missing a description. The description's phrases 'structured spec and CORAS text notation' map to the format parameter's default 'both', and 'Optionally renders it' maps to preview, adding some semantic value. However, it does not clarify scale or parameter interactions, so it does not fully compensate for the schema 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?

The description clearly states the tool's verb ('Read'), resource ('an existing .dgx file'), and output ('structured spec and as the CORAS text notation'). It also indicates the purpose ('so it can be inspected or rewritten') and an optional rendering behavior. This distinguishes it from siblings like coras_create_diagram (creation) and coras_render_diagram (rendering 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 implies usage for inspecting or rewriting diagrams, but does not explicitly state when to choose this tool over alternatives such as coras_render_diagram or coras_open_editor. There are no when-not-to-use conditions or references to sibling tools, leaving the decision partly to inference.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It explains the tool's scope and the editor's rejection behavior, which is useful context. However, it does not explicitly state whether the call is read-only or what form the returned reference takes, leaving some operational behavior implicit.

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 two tight sentences: the first defines the scope with a compact list, and the second gives a concrete when-to-use trigger. Every clause earns its place and there is no filler or repetition of schema/annotation information.

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 no-parameter reference tool, the description is largely complete: it states what the reference covers, when to use it, and why it matters. A minor gap is that it does not describe the output format or length, but the enumerated content list makes the expected information clear.

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?

The tool has zero parameters and an empty input schema, so there is no parameter ambiguity to resolve. The description correctly avoids inventing parameters and instead focuses on the tool's content and purpose, which is the appropriate baseline for a parameterless reference.

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 clearly identifies the tool as a reference for the CORAS language as implemented by this 2007 tool, and enumerates its contents: element types, relationships, treatments, and text notation. It also distinguishes the tool from siblings by positioning it as the first thing to read when checking whether an arrow is legal. It lacks an explicit action verb like 'returns' or 'provides,' but the 'reference' role is unmistakable.

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 an explicit use condition: 'Read this first when you are unsure whether an arrow is allowed.' It also supplies a concrete reason (the editor refuses to open files with illegal relationships), which helps an agent decide when to consult it. It does not compare against named alternatives, but the sibling set makes the reference role distinct.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It explicitly states that the tool returns the picture inline and writes it to disk, which are key side effects, and it adds the pixel-identical guarantee. However, it does not mention error conditions, file overwrite policy, or whether the source file is modified, though the render verb implies non-destructiveness.

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 two sentences, front-loaded with the core action ('Render a .dgx file to PNG or SVG') and immediately followed by the key distinguishing detail (pixel-identical) and output behavior. Every word contributes value; there is no redundancy or filler.

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 moderately complex tool with six parameters and no output schema, the description covers the core purpose, the main side effects, and the output format. It does not elaborate on return value structure or edge cases like multiple diagrams or temporary folder behavior, but the schema's high coverage compensates for parameter details. Overall, an agent likely has enough to invoke it correctly, though some behavioral nuances remain only in the schema.

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 83%, which is high, so the baseline is 3. The description does not explain individual parameters beyond what the schema already states; it only rephrases the purpose. It does add that output is written to disk and returned inline, which relates to 'out' and 'inline', but this adds limited meaning beyond the schema's descriptions.

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 states a specific verb ('Render'), a resource ('.dgx file'), and output formats (PNG or SVG). It also distinguishes the tool from siblings by emphasizing the editor's own renderer and pixel-identical output, making it clear this is the dedicated rendering tool among read, edit, create, validate, and open actions.

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 implies when to use the tool (when a rendered image of a .dgx file is needed), but it does not explicitly mention alternatives or when not to use it. It does not reference sibling tools like coras_read_diagram or coras_edit_diagram, so the agent must infer the use case from the purpose alone.

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

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

The description discloses that the tool reports what it found in each diagram, which is a useful behavioral detail. However, with no annotations provided, the description carries the full burden of behavioral disclosure. It does not mention whether the tool modifies the file, what happens on failure, or whether it requires specific permissions. The 'check' verb implies a read-only operation, but this is not explicitly stated.

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 a single, concise sentence that front-loads the primary action ('Check that a .dgx file is well formed') and adds a secondary detail about reporting. Every word earns its place, and there is no redundancy or filler.

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 validation tool with one parameter and no output schema, the description is mostly complete. It explains what the tool does and what it reports. However, it lacks details about the return format or how the results are presented, which could be important for an agent deciding whether to call this tool. The absence of annotations increases the burden, but the simplicity of the tool keeps the gap moderate.

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?

The schema has only one parameter, 'path', with no description. The description mentions '.dgx file' but does not explicitly state that 'path' should point to a .dgx file. Since schema description coverage is 0%, the description must compensate, and it partially does by implying the file type, but it could be more explicit about the parameter's meaning and format.

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 clearly states the tool's purpose: validating a .dgx file for well-formedness and loadability by the Threat Modelling Tool, and reporting findings per diagram. It uses a specific verb ('Check') and resource ('.dgx file'), and it distinguishes itself from sibling tools like coras_read_diagram or coras_edit_diagram by focusing on validation rather than reading or editing.

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 implies when to use this tool: when you need to validate a .dgx file before loading or editing it. However, it does not explicitly state when not to use it or mention alternatives like coras_read_diagram for inspecting content. The context is clear but lacks explicit routing guidance.

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