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

The description adds behavior beyond the annotations: it discloses the in-place project-file write ('Writes the project file in place') and the non-rendering side-effect profile, corroborating readOnlyHint=false and non-idempotent behavior. It also documents the return shape, which is useful given no output schema. Minor gaps remain (no mention of permission/auth requirements), but the side-effect disclosure is meaningful.

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?

Three tight sentences, front-loaded with purpose, then the behavioral note, then the return contract. Nothing is wasted and the most decision-relevant information (what it does and that it doesn't affect rendering) comes first.

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 8-parameter write tool with no output schema, the description covers the essentials: purpose, non-rendering semantics, in-place write, and the returned index needed to chain into annotation_remove. Annotations handle the safety profile, so the definition is nearly complete, though it doesn't tie the returned index back to more of the surrounding workflow.

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 all 8 parameters (including the kind enum, position, size defaults, graph scoping, and around_nodes) are already documented in the schema. The description only loosely reinforces the group/note distinction and adds no syntax or format detail beyond it, so the baseline 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 ('Adds a comment to the node graph') and immediately disambiguates the two modes it supports ('a framed group around nodes, or a free text note'). An agent can distinguish it from annotation_remove and the node_* siblings 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?

It gives a clear usage frame by clarifying annotations 'only document the graph; they do not change the rendered result', which tells the agent when this tool is and isn't appropriate versus rendering tools like project_render. It also points at annotation_remove for the removal flow. However, no explicit when-not or alternative-tool routing is stated for the add case itself.

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?

Annotations already flag destructive/non-idempotent/write, and the description adds real context beyond that: index-shift semantics for later annotations of the same kind, the failure mode on a nonexistent index, in-place project-file write, and the return shape. This is exactly the extra behavioral detail a mutation tool needs.

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?

Four tightly packed sentences, each carrying distinct information (action, index-shift caveat, failure condition, write/return). Front-loaded with the core action, zero 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?

With no output schema, the description supplies return values ('{"ok": true}'), failure behavior, side effects (in-place file write), and the stateful index consequence. Nothing an agent needs to call it correctly and safely is missing.

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 100%, so the baseline is 3, but the description earns extra by explaining the consequence of 'index' (later same-kind annotations shift down by one) which enriches how the agent should treat that parameter across repeated calls.

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 (deletes) and a precisely scoped resource (one group or note annotation from the node graph). An agent can distinguish it immediately from the annotation_add sibling and the node/link removal tools.

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?

Provides actionable sequencing guidance: 're-read project_summary before removing another' after an index shift, and states the failure condition (index does not exist). It lacks an explicit when-not/alternative statement, but the workflow context is clear.

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?

Annotations already declare destructiveHint=true and idempotentHint=true, but the description adds real value beyond them: it spells out that previous keys are discarded and that the project file is written in place. That in-place write disclosure is exactly the kind of context annotations cannot convey.

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?

Three tight lines: the destructive replacement is front-loaded, followed by the file-write consequence and a clearly labeled Returns line. No sentence is redundant.

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?

With no output schema present, the description correctly supplies the return shape (curve name and key count), plus the destruction and in-place write behavior. It stops short of stating whether the target curve must pre-exist or how errors on invalid positions are reported, which would matter for a destructive write.

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%, including enum values, defaults, and the points format, so the schema does the heavy lifting and a baseline of 3 applies. The description adds only the loose framing of 'keys' and the return field names; it contributes no semantics beyond the schema for path, graph, node_id, points, or interpolation.

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: replacing all keys of a node's curve, with concrete examples (remap curves, custom oscillator waveforms). It is clearly distinguishable from generic node_set, though it never explicitly names the analogous siblings gradient_set/spline_set, so the agent must infer the routing.

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?

Usage is implied by the examples of curve types it targets, and 'replaces all the keys' hints that this is the wholesale-set operation rather than an incremental edit. However, there is no explicit when-to-use vs. gradient_set/spline_set/node_set guidance, and no prerequisite (e.g. curve must already exist) is stated.

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?

Annotations already declare read-only/idempotent/non-destructive, and the description reinforces with 'Offline and read-only', then goes further by disclosing return shape, the pin-kind taxonomy (Grayscale, Color, Signal, Inherit), and error behavior ('unknown type fails with close-match suggestions'). That failure-mode and return-content detail is genuine added value beyond the annotations.

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?

Purpose and when-to-use are front-loaded in the first two sentences, with return details grouped after. It is on the longer side and the pin-kind enumeration is dense, but every sentence carries usable context and nothing is redundant with the 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?

With no output schema, the description steps in to describe the return payload in detail (params structure, curves, inputs/outputs/optional_inputs, parameter_pins mapping) as well as the error path, so an agent has everything needed to call and parse the result.

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 100% and the single node_type parameter already documents case/spaces/prefix optionality and gives an example, so the schema carries the parameter semantics. The description adds no further parameter detail, making the baseline 3 correct.

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 ('Describes one node type: its parameters, curves and typed input/output pins'), clearly distinct from the sibling list_node_types which enumerates rather than inspects a single type. An agent can tell them apart without opening either 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 instructs when to call it: before node_add/node_set to obtain valid parameter names, kinds, defaults and ranges, and before link_add to get pin names and data kinds. Alternative timing conditions are spelled out rather than left 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?

Goes well beyond the annotations: it discloses exactly what is destroyed ('previous stops are discarded'), the failure condition, that it persists via an in-place project file write, and the return payload. destructiveHint=true and idempotentHint=true are already declared, so this is genuine added context, and it is consistent with them.

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?

Four short sentences, front-loaded with the core action, then destruction, failure, persistence, and return. Every sentence carries distinct information with no 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 destructive 6-parameter mutation with no output schema, the description covers the essential unknowns: what gets overwritten, the failure mode, that the file is written, and the return values. Nothing an agent needs to invoke it safely is missing.

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 every parameter (path, graph, index, stops, node_id, color_space) is already documented in the schema. The description only gestures at 'stops' and 'color_space' via the return summary and adds no syntax or format detail beyond what the schema provides, so the baseline 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?

States a specific verb+resource ('Replaces a node's color gradient') and immediately scopes the applicable node types (Color Ramp, Color Interpolate, Geometry Combine Color). An agent can tell this apart from the analogous curve_set/spline_set siblings because the resource is unambiguous.

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 the applicability context (which node types have gradients) and a hard precondition ('Fails if the node has no gradient'), which tells the agent when this tool is valid. It does not explicitly name alternatives or when-not-to-use cases, so it stops short of 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?

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, but the description adds value beyond them: it explicitly states it does not start IlluGen and changes nothing, and it enumerates the returned diagnostics including running_instances (GUI processes included) and the exe path sourced from ILLUGEN_EXE.

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 core purpose, then usage conditions, then a compact labelled return list. Every sentence earns its place with no 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?

With no output schema, the description carries the return contract and does so thoroughly: exe, installed, running_instances, catalog_illugen_version, node_types and presets_dir. It also supplies the diagnostic entry-point rationale, making it fully self-sufficient for a no-arg status tool.

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 takes zero parameters, so there is no parameter semantics to document; the baseline for a no-arg tool is 4. The description correctly reinforces this with 'Takes no arguments.'

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: 'Reports whether IlluGen is installed and which node catalog this server uses.' This clearly separates it from sibling tools like list_node_types or list_presets, which enumerate catalog contents rather than reporting installation/server state.

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 says when to call it: first, when an engine tool (project_render, project_validate with engine=true, project_screenshot, project_normalize) fails, or to locate the presets folder. It names the exact alternative conditions and the triggering siblings, leaving nothing 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?

Goes well past annotations: discloses that an existing input connection is replaced, that pin data kinds are validated with an explanatory failure, and that the project file is written in place. The write-in-place note is the meaningful complement to readOnlyHint=false. There is mild tension with destructiveHint=false given the silent replacement of an existing connection, but replacing a link is recoverable and not a hard contradiction.

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-loads the core operation in one sentence, then layers edge-case semantics. Dense but every sentence carries information (validation, replacement, parameter/subgraph pins, side effect, return value). Slightly long across four paragraphs but no 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?

With 7 parameters, no output schema, and a mutation that alters an existing graph, this description covers the essentials: replacement semantics, validation failure mode, pin-kind categories, side effect on disk, and the return shape (link object plus warnings). Nothing critical for a correct call is missing.

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 100%, so the baseline is 3, but the description adds real meaning: parameter pins let a Signal node drive a parameter, optional inputs are exposed automatically, and subgraph pins map to inner Node_Input/Node_Output labels. It does not elaborate on modulation_range syntax beyond what the schema already states.

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?

Opens with a precise verb+resource: 'Connects an output pin of one node to an input pin of another.' This cleanly separates it from sibling link_remove and from node-level tools like node_set. No ambiguity about what operation is performed.

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?

Usage context is implied but never stated as when-to-use. It never names link_remove or explains when to re-link vs. modify an existing node, and gives no prerequisites (e.g. node must already exist). The description does explain the input-replacement semantics, which is the closest thing to 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 annotations already marking the operation destructive and non-idempotent, the description goes further: it writes the project file in place, restores a driven parameter to a fixed/default value, treats a no-op as non-error, and discloses the return value (count of removed links). This is the side-effect information an agent genuinely needs.

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 core action, then side effects, then error semantics, then return value. Every sentence carries distinct information with no 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?

No output schema exists, but the description supplies the return value explicitly, along with mutation side effects and no-op behavior. Nothing needed to invoke it correctly is missing.

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 schema already documents path, graph, to_pin, to_node and from_node. The description reinforces the to_pin/to_node relationship but adds no syntax or format detail beyond the schema, so the baseline 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?

States a specific verb (disconnects/removes) and resource (incoming link(s) on a named pin of a named node), and contrasts naturally with sibling link_add. An agent can tell exactly what this does 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?

Gives clear context: it is the unlink counterpart to link_add, points to node_get for discovering a node's incoming links, and notes that removing nothing is not an error. It does not spell out explicit when-not-use conditions, but the operative context is clear.

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?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is largely covered. The description adds genuinely non-annotated context: it works offline without a running IlluGen instance, and it discloses the return shape along with the empty-object edge case. Not a full 5 only because filter/failure behavior beyond the empty case is left 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?

Three short paragraphs, each earning its place: purpose, routing/offline context, and return format with an example. The routing advice is front-loaded immediately after the purpose sentence, with no 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?

Despite having no output schema, the description supplies the return structure ({category: [type names]}) with a concrete example and the empty-result meaning, which is exactly what an agent needs for a no-required-parameter listing tool. Combined with full schema coverage and annotations, nothing material is missing.

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% and both parameters carry detailed descriptions (including the full category list), so the schema does the heavy lifting. The description only alludes to 'filters' generically without adding matching semantics or syntax beyond the schema. Baseline 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?

States a specific verb and resource ('Lists the IlluGen node types this server can create') plus the grouping ('by category') and scope ('this server can create'). This is clearly distinguishable from siblings like describe_node_type (details for one type) and node_add (which consumes a type name).

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 names the downstream tools and the order of use: find a type name here for node_add, then call describe_node_type for parameters and pins. It also states the operational precondition ('Offline (IlluGen not needed) and read-only'), so an agent knows no live connection is required.

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?

Annotations already cover the safety profile (readOnly, idempotent, non-destructive). The description adds real behavioral context beyond them: the data source (presets folder of the installed IlluGen), the guarantee that presets are never modified, and the two conditions that produce an empty result.

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 core purpose, then follow-up usage, then return/empty-case behavior. Nearly every sentence earns its place, though the trailing parenthetical about illugen_status could be tightened.

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?

Covers purpose, next-step workflow, return shape, sorting, and the empty-result condition, which is everything an agent needs for a one-parameter read tool. An output schema exists, so the brief return description is a bonus rather than a requirement.

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 100% and the single 'search' parameter is fully documented in the schema (case-insensitive substring match, empty = all). The description adds no parameter-level detail beyond that, so the baseline 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?

States a specific verb and resource ('Lists the example projects shipped with IlluGen') plus their purpose ('usable as starting points'). An agent can immediately distinguish this read-only catalog from mutation siblings like project_new.

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: pass a returned name to project_new(from_preset=...) to get an editable copy, and check illugen_status when the list comes back empty. Both the follow-up action and the empty-result fallback are named, leaving nothing 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?

Annotations cover the safety profile (not read-only, not destructive, not idempotent), and the description goes well beyond them: it discloses the in-place file write, the exact validation failure mode ('an unknown name or invalid enum value fails with suggestions and nothing is saved'), and that out-of-range values are kept with warnings. This is unusually rich 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?

Front-loaded with purpose, then mutation/validation behavior, then the sibling hand-off, then return values. Four tight sentences with no 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 six-parameter mutation tool with no output schema, the description covers the write semantics, validation outcomes, follow-up step, and return shape (id, type, warnings). Nothing material is missing.

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 schema already documents all six parameters including graph nesting syntax and param encoding. The description adds only the 'omitted parameters keep defaults' framing, which the schema also states, so baseline 3 is appropriate.

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 ('Adds a node to the graph') plus the scope of default behavior and optional parameter setting. It also distinguishes itself from siblings by naming link_add as the follow-up step and implying node_set operates on existing nodes.

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 clear context: writes the project file in place, parameters are validated, and connection requires calling link_add afterwards. It does not state explicit when-not conditions or prerequisites such as needing a node_type from list_node_types (though the schema parameter description does).

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?

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world); the description still adds the 'Offline' trait and a detailed return contract, including the '<driven by link>' sentinel for Signal-driven params, which annotations cannot express. It stops short of noting pagination or size limits, but for a single-node read that is minor.

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?

Purpose and usage routing come first, followed by the return enumeration; every clause carries information. The Returns block is long but justified because no output schema exists, so the size is earned rather than padding.

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?

With no output schema, the description takes on the full burden of describing the response and does so field by field, including nested params, curves, gradients, pins and links. Combined with the pre-setter usage rule, an agent has everything needed to call and interpret this tool.

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 path, graph and node_id are already fully documented, and the description adds nothing about their syntax. It reinforces the node_id source (project_summary/node_add) that the schema also states, which is baseline-appropriate but not additive.

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 (get) and resource (one node) plus the exact payload scope (parameters, curves, gradients, spline points, pins, links). It also names the setters it complements and the sibling (project_summary) that covers the rest of the graph, so an agent can place it instantly.

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 says to call it before node_set, curve_set, gradient_set, spline_set and node_set_data to learn current values and exact names, and points to project_summary for whole-graph inspection. Both the when and the alternative are spelled out.

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?

Annotations already flag destructiveHint=true, but the description goes further: it discloses that the project file is written in place, that the operation cannot be undone, that incoming links are cascade-deleted, and what the return value contains. This is exactly the extra context an agent needs before an irreversible mutation.

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?

Three short paragraphs, each with a distinct job: what it does and cascades, the irreversibility warning and alternative, then the return value. Front-loaded with the core action, zero 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?

With no output schema, the description carries the return-value burden itself ('removed_links, the number of links from other nodes that pointed to the deleted node') and covers the destructive nature. Nothing an agent needs to invoke this safely is missing.

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 path, graph, and node_id are already fully documented in the schema. The description refers to the node generically but adds no syntax, format, or edge-case meaning beyond what the schema provides, so the baseline 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?

States a specific verb (Deletes) plus the exact resource (a node from the graph) and the full blast radius (its outgoing links and every incoming link). This scope statement distinguishes it from siblings like link_remove and node_set without needing to open any 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 to an alternative ('To bypass a node without losing it, use node_set(disabled=true) instead') and gives a concrete prerequisite (copy the file first if you may need the node back). Both when-to-use and when-not-to-use are covered.

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 annotations declaring non-read-only, idempotent, non-destructive, the description still adds substantial context: it writes the project file in place, validation mirrors node_add, and it documents the return payload plus two warning conditions (out-of-UI-range values, values currently driven by a link that only take effect once unlinked). This goes well beyond the annotation hints and is consistent with idempotentHint=true.

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?

Three short sentences, front-loaded with the purpose, then the partial-update rule, then sibling routing and return/warning behavior. The Returns paragraph is justified because there is no output schema, and no sentence is redundant.

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 7-parameter mutation tool with no output schema, the definition covers the missing pieces: in-place file write, partial-update semantics, validation behavior, sibling alternatives, and the return/warning shape. An agent has everything needed to invoke it 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 every parameter is already documented, including 'omit to keep it' semantics for label/disabled/position. The description adds only the general 'only what you pass changes' framing and the node_add-compatible params format, so the baseline 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?

States a specific verb (changes) and resource (an existing node) and enumerates the mutable fields: parameter values, label, position, disabled flag. It then explicitly routes editing of curves, gradients and spline points to curve_set, gradient_set and spline_set, so an agent can separate it from those siblings without opening their schemas.

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 clear context ('Only what you pass changes') and names the three alternative tools for other resource kinds. It lacks explicit prerequisite/exclusion guidance (e.g. when to prefer node_set_data or subgraph_expose_param over this tool), so it is strong but not complete.

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?

Annotations already declare destructiveHint=true and idempotentHint=true, and the description reinforces this with concrete consequences: the value is written without type checking, the project file is written in place, and validation should be run afterwards. It also discloses the return shape, which no output schema provides.

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?

Three short sentences that are tightly front-loaded: purpose first, then the when-not-to-use constraint, then the risk/validation notice and return value. No sentence is 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?

With no output schema, the description supplies the return value, the side effect (in-place project file write), the validation requirement, and the sibling alternatives. Nothing needed to invoke it safely is missing.

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 key, path, graph, value and node_id are all documented in the schema, including the tagged-JSON value format and the unknown-key failure mode. The description adds no meaning beyond that, so the baseline 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 precise verb and resource ('overwrites one raw field of a node's internal data block') and frames it as a low-level escape hatch, which immediately distinguishes it from the higher-level setters. An agent can tell what this does 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?

It explicitly limits use to fields not covered by node_set, curve_set, gradient_set and spline_set, naming the alternatives and the condition that selects this tool over them. It also prescribes a follow-up step (project_validate) after use.

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?

Goes beyond the annotations by disclosing the write scope ('Writes only the file at `path`; the copied preset or project is left untouched, and a copied preset is made editable') and by describing the return payload. Annotations cover the readOnly/destructive profile, so this added mutation-scope detail is genuine value rather than repetition.

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?

Three sentences, each earning its place: the action leads, the workflow hint follows, then the side effects and return shape. No filler or restatement of the title.

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?

Though there is no output schema, the description names the return value and cross-references project_summary for its shape, so an agent knows what to expect. Side effects, overwrite behavior, and the required path are all covered across description and 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 100%, so the baseline is 3, but the description adds real meaning for `from_preset` by clarifying that a copied preset becomes editable and that the source is left untouched. `overwrite`'s destructive potential and `path` semantics are left to the schema, which already covers them.

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 a new .illugen project file') plus the two creation modes (blank or copied from preset/project), which separates it cleanly from siblings like project_normalize or project_summary that operate on existing files. An agent can identify it 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?

'Start every new graph here, then add nodes with node_add' gives an explicit ordering and points at the next tool in the workflow. It doesn't state when NOT to use it (e.g. use project_normalize for existing files), but the creation framing makes the boundary largely self-evident.

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?

Goes well past the annotations by disclosing the file is overwritten in place, that a copy is preserved as <name>.illugen.bak (replacing any previous backup), and that IlluGen must be installed. This matches and enriches the idempotentHint/destructiveHint=false profile rather than contradicting it.

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?

Three tight sentences: what it does, when to use it, and side effects/return values. The destructive-adjacent facts (overwrite, backup) are front-loaded rather than buried at the end.

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?

With no output schema, the description compensates by enumerating the returns (path, backup, log_issues, node_count). It also covers the hard prerequisite (IlluGen installed) and the overwrite/backup behavior, leaving nothing an agent needs to invoke it safely.

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% for the single 'path' parameter ('Absolute path of the .illugen project file'), so the schema already carries the semantics. The description adds no format or path conventions beyond that, which is the baseline case for full coverage.

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?

Precise verb+resource: 'Loads the project in a private, invisible IlluGen and saves it back in place, the way IlluGen writes it', then enumerates the actual transformations (fills defaults, applies IlluGen's own fixes, refreshes embedded thumbnail). This differentiates it cleanly from siblings like project_validate, project_new and project_thumbnail, which do not rewrite the file on disk.

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 trigger conditions: 'Use it before sharing a project built with this server, or to update a project made with an older IlluGen.' Clear when-to-use context, though it names no alternative (e.g. project_validate for checking without rewriting) and states no when-not-to-use exclusion.

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?

Goes well beyond the annotations: discloses that IlluGen runs as a private invisible instance, that the project file is not modified, that image files are written and existing files with the same name are overwritten, and that failures yield screenshots of error dialogs. This is exactly the mutation/overwrite context the annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=true) cannot convey on their own.

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 core action, then structured into behavior, requirements, and return shape. Dense but every sentence carries information; only mild redundancy with the schema on output_dir.

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?

No output schema exists, and the description fully covers the return contract: success shape ({ok, items_written, seconds, files, exports, log_issues} plus preview) and failure shape ({ok: false, error, log_issues, hint} plus screenshots). Nothing an agent needs to invoke or interpret results is missing.

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 schema already documents path, preview, timeout_s, and output_dir. The description restates output_dir behavior ('written to output_dir or the export nodes' folders') but adds no syntax or format detail beyond what the schema provides; baseline 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?

States a specific verb (renders/runs export) and resource (the project's enabled Node_Export_* nodes) and implicitly distinguishes itself from project_validate, project_screenshot, and project_thumbnail. An agent can tell exactly what operation this performs 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?

Gives clear prerequisites (IlluGen installed, at least one enabled export node) and an explicit sequencing rule: 'Run project_validate first when the graph is new.' It does not, however, state when to prefer project_render over project_thumbnail/project_screenshot, so it stops short of naming alternatives.

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?

Annotations already declare a safe read-only, idempotent, non-destructive profile, but the description adds substantial context beyond them: the tool opens a private/invisible instance, operates on a temporary copy so the project file is not modified, requires IlluGen installed, and takes a few seconds. It also discloses the return shape ({path} and PNG).

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-loads the purpose and keeps use cases, alternative, side-effect guarantee, requirement, and return value in tight sentences. Slightly dense with parenthetical detail, but every sentence earns its place.

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?

Although there is no output schema, the description states the return value ({path} plus a PNG image). Combined with the requirement (IlluGen installed) and the non-destructive guarantee, an agent has everything needed to call this 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 path, width, and height are fully documented in the schema itself. The description adds no syntax or format detail about the parameters beyond that, so the baseline 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?

States a specific verb and resource ('returns a screenshot of its window') and immediately scopes the output ('viewport and the node graph with each node's live preview'). It is clearly distinguishable from siblings project_render and project_thumbnail by naming what is captured and why.

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 gives when-to-use ('check visually what a graph does, or to see why a render fails') and names the alternative for a different goal ('Use project_render to produce the actual image files'). Nothing is left to inference about choosing between them.

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 annotations already declaring non-read-only, non-destructive and idempotent, the description adds the meaningful extras: it writes the project file in place, applies to the whole project including subgraphs, and performs a partial merge of supplied values only. That is real behavioral context beyond the hints, though it omits any mention of permissions or failure modes.

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?

Four short sentences, zero filler. Purpose and merge semantics come first, scope second, the sibling disambiguation and return-value note last — the ordering matches how an agent reads the tool.

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?

Even without an output schema, the description closes the loop by stating the return is the resulting settings in the same shape as project_summary.settings. Scope, partial-update behavior and the write-in-place effect are all covered for a 5-parameter mutation tool.

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 parameter formats (seconds, fps, power-of-two enum strings) are already fully documented in the schema. The description only restates the field groups at a high level, adding scope rather than meaning, which is the expected baseline when the schema carries the load.

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 (changes) and resource (project-wide settings) and enumerates the three affected settings groups. It also explicitly distinguishes itself from node_set, which handles per-export resolution, so an agent can separate the two without opening either 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?

Gives the key selection condition ('only the values you pass change; omitted ones are kept') and routes a related but distinct need (per-export resolution) to node_set. It stops short of naming when to prefer project_new or project_normalize, so it is clear context without full exclusion rules.

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?

Annotations already declare readOnly, idempotent, closed-world, and non-destructive, so the safety profile is covered. The description adds valuable context beyond that by spelling out the return payload (path, graph scope, app_version, settings, annotations ordering, node_count, node fields, subgraph nodes) and the fact that it works offline; the only mild redundancy is restating 'read-only'.

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 front-loaded with purpose, then usage routing, then return structure, so an agent can act on it quickly. The return list is long but earns its space because there is no output schema; the only small waste is repeating 'read-only' already covered by annotations.

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?

With no output schema, the description fully enumerates the returned fields an agent needs, including nested node details and subgraph nodes. Annotations cover the safety profile and the schema covers parameters, so nothing material is missing for a read-oriented summary tool.

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 both path and graph are already documented in the input schema. The description only alludes to the graph parameter via 'scope shown' without adding syntax or edge-case meaning beyond the schema, so baseline 3 is appropriate.

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: 'Gives an overview of a project' and enumerates what that overview includes (nodes, links, export settings, annotations, main settings). It clearly distinguishes itself from the sibling node_get by routing single-node reads elsewhere.

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?

It gives explicit when-to-use guidance: get node ids before node_get/node_set/link_add, and check the graph after edits. It also names the alternative (node_get) and the condition that selects it, leaving nothing 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?

Goes well beyond the annotations (readOnly/idempotent/destructive are already declared) by disclosing performance profile ('Instant and offline, IlluGen not needed'), a real accuracy caveat (can be outdated or missing for server-edited projects), and the failure shape ('{thumbnail: null, hint}'). This is exactly the supplemental context annotations cannot carry.

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 core behavior, then tradeoffs, then return shape – efficient overall. The standalone 'Read-only.' line repeats what readOnlyHint=true already conveys, a small redundancy that keeps it from a 5.

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?

With no output schema, the description correctly documents both success and empty-case returns (JPEG vs {thumbnail: null, hint}), covers why the result may be stale, and gives the remediation path. Nothing needed to call this single-parameter tool correctly is missing.

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?

Single parameter with 100% schema description coverage, where the schema already defines 'path' as the absolute path of the .illugen project file. The description adds no format, resolution, size, or edge-case semantics for the parameter, so the baseline 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?

States a specific verb and resource: 'Returns the preview image IlluGen embedded in the project file at its last save.' It immediately distinguishes itself from the visually similar siblings by naming project_screenshot and project_render as the current-state alternatives.

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?

Explicit when-to-use context with named alternatives: it says the thumbnail can be outdated for projects edited through this server, and points to project_normalize to refresh it or project_screenshot/project_render for current state. The condition that selects each alternative is stated, not implied.

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 annotations already declare readOnlyHint/idempotentHint/destructiveHint=false, and the description reinforces this with an explicit 'The project file is never modified' plus the detail that the engine path works on a temporary copy in an invisible IlluGen instance. It also discloses the real cost and prerequisite of engine=true (slower, needs IlluGen installed) and enumerates what each mode surfaces, which goes well beyond the annotations.

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 one-sentence purpose, then cleanly sections offline checks, engine checks, the non-mutation guarantee, and the return shape. Dense but every clause carries information an agent needs; nothing is 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?

There is no output schema, but the description compensates by spelling out the complete report structure ({ok, offline_issues, legacy_params} plus engine fields and screenshots). For a two-parameter tool with strong annotations, this is fully self-contained.

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 100%, so the baseline is 3, but the description earns extra credit by explaining what engine=true actually does internally (load, re-save copy, trial export, log issues, load dialog screenshot) and clarifying that legacy_params is informational. It adds real semantic depth beyond the one-line schema 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?

States a specific verb+resource ('Checks a project for problems') and adds the crucial framing 'before rendering it', which distinguishes it from siblings like project_normalize, project_render, and project_summary. An agent can tell exactly what this tool is for 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?

Gives clear context ('before rendering it') and, more usefully, explains the two operating modes and when to choose each: offline-only by default, or engine=true for the slower real-IlluGen check that requires IlluGen installed. It does not explicitly name sibling alternatives (e.g. project_normalize) as the tool to use instead, so it stops short of full routing 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?

Goes beyond the annotations by disclosing that previous points are discarded, that the operation fails on nodes without spline/lattice points, that it writes the project file in place, and what it returns (point and segment counts). The discard behavior corroborates destructiveHint=true and the return info substitutes for a missing output schema.

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?

Four short sentences, each carrying a distinct fact: what is replaced, default versus explicit chaining, failure and side-effect behavior, and return values. The most important clause (replacement) is front-loaded with no 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 destructive mutation tool with full schema coverage and no output schema, the description supplies the write-in-place side effect, failure mode, and return shape. It stops short of stating permission/auth requirements or interaction with the `graph` scoping, which would round it out.

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 100%, so all six parameters are already documented, including point formats per node type and the edges override. The description's chaining statement largely restates the schema's 'Overrides the default chaining' note, so it adds little beyond the baseline.

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+resource ('Replaces the control points of a spline, sweep, point-shape or lattice node') and enumerates the node types it applies to. It does not differentiate itself from the neighboring curve_set or node_set, so an agent must infer when spline_set is the right choice.

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 a usage condition for `edges` ('chained in order unless edges is given') and a precondition ('Fails if the node has no spline or lattice points'). However it never contrasts this tool with curve_set, gradient_set, or node_set, so selection among siblings is left to the agent's 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?

Annotations cover the safety profile (non-destructive, idempotent, writes), and the description usefully adds 'Writes the project file in place,' which tells the agent a side effect on disk occurs. It also states the return payload, which the absence of an output schema makes valuable.

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 purpose is front-loaded in the first sentence, followed by a compact workflow note and a returns line. The subgraph-construction aside is slightly tangential but short and contextually useful, with no 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?

With six parameters, a mutation side effect, and no output schema, the description covers the missing pieces: it states the file write and enumerates the returned fields. Only the relationship to invoking alternatives is 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 coverage is 100% and every parameter already carries a clear description, so the schema does the heavy lifting. The description adds no syntax or format detail beyond what the schema provides, so the baseline 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 gives a specific verb+resource ('Shows a parameter of a node inside a subgraph on the subgraph node itself') and states the resulting behavior (expose for tweaking outside). It is clearly distinguishable from generic mutators like node_set, though it never names a sibling to contrast with.

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?

It supplies a prerequisite workflow (how to build a subgraph with node_add/link_add and Node_Input/Node_Output), which implies the context in which this tool is valid, but it never says when to prefer this over alternatives or when not to use it.

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