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

The annotations already flag destructiveHint=true, but the description adds crucial behavior beyond them: the cascade deletion of all contained elements, a recovery path via graphite_undo, and the specific LAYER_NOT_FOUND error for invalid ids. These details materially inform the agent about the operation's impact and 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?

Three short sentences, front-loaded with the core action and scope, followed by reversibility and error behavior. Every sentence earns its place with no redundancy.

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?

Given the destructive nature, single required parameter, rich annotations, and the presence of an output schema, the description covers the essential gaps: deletion scope, recovery mechanism, and failure condition. No critical information is missing for correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, and the schema already explains that layer_id comes from graphite_insert_svg or graphite_get_document. The description only adds the error condition that the id must be in the active document, which is useful but minimal beyond the schema 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?

The description states a precise verb-resource pair ('Delete a layer') and extends it with the critical scope 'and everything inside it,' which is not obvious from the name alone. It clearly distinguishes this destructive operation from sibling mutation tools like graphite_transform_layer or graphite_rename_layer.

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 clear contextual guidance: deletion is reversible via graphite_undo, and it fails with LAYER_NOT_FOUND when the id is not in the active document. This tells the agent when the operation succeeds or fails, but does not explicitly state when to choose this tool over alternatives or any exclusions.

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 by enumerating three concrete failure modes (EXPORT_FAILED, BRIDGE_TIMEOUT with the env var and 'just retry' advice, EXPORT_PATH_NOT_ALLOWED) and the path-sandbox constraint. The destructiveHint=true annotation is consistent with a tool that writes/overwrites files.

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 action and return value, then layers guidance and failures compactly. Every sentence carries actionable 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?

An output schema exists, so return details are covered; the description still names the returned path. Combined with error codes, timeout behavior, and path restrictions, 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 coverage is already 100%, but the description still adds practical meaning: svg vs raster trade-offs and the 0.25–0.5 cheap-preview tip for scale. It doesn't restate the path rules beyond what the schema says, so it is additive without redundancy.

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 ('render the active Graphite document to a file and write it to disk') plus the return value (absolute path). The emphasis on writing to disk implicitly distinguishes it from sibling graphite_preview, so an agent can tell what this tool produces.

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 format-selection guidance ('svg for editable/scalable output', 'png for a bitmap') and a cheap verification workflow via png at scale 0.25–0.5. It never explicitly names graphite_preview as the alternative for on-screen inspection, so the when-to-use-this-vs-sibling routing is implied rather than 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 readOnlyHint, idempotentHint, and openWorldHint=false, and the description reinforces this with 'Read-only; never changes the document.' It usefully discloses what the report contains (connection state, commit, available commands), though it adds little beyond what the annotations and output schema already guarantee.

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?

Two sentences, front-loaded with purpose and followed by the recovery instruction. Every clause carries actionable 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?

The output schema covers return values, annotations cover the safety profile, and the description supplies the diagnostic trigger and scope. Nothing needed to invoke this zero-arg 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?

The tool takes zero parameters, so the baseline is 4; there is no argument syntax an agent needs to interpret. The description correctly avoids inventing parameter details for a call that accepts none.

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 names a specific verb and resource set: it reports tab connectivity, the running Graphite commit, and available commands. This diagnostic role is clearly distinguishable from sibling mutation tools like graphite_insert_svg or graphite_transform_layer.

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 an explicit invocation trigger: 'Call this first if another graphite_* tool returned GRAPHITE_NOT_CONNECTED.' This is a precise when-to-use rule tied to a named error condition, 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 already declare readOnlyHint, idempotentHint and openWorldHint=false, so the safety profile is covered. The description still adds real behavioral context beyond that: the NO_ACTIVE_DOCUMENT failure mode and the fact that the response carries only identity/layer metadata, not content. It stops short of noting any rate limits or latency expectations, but for a read-only query 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?

Two sentences, both front-loaded: the return payload first, then the decision-relevant usage. No filler, and the error code is placed at the end where it belongs.

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?

Complete for a zero-parameter read tool. An output schema exists, yet the description still names the key fields an agent needs for its stated verification workflow (layer_id in layer_ids), and the documented NO_ACTIVE_DOCUMENT branch covers the main failure path.

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?

Zero parameters, so the baseline is 4. There is nothing to mis-specify, and the description correctly implies no arguments are needed by framing the tool entirely around ambient state ('the active document').

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 ('Return the active document's id and name, all its layers... and the list of open documents') and enumerates the shape of what comes back. Distinguishable from siblings like graphite_select_document or graphite_get_capabilities.

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 two explicit when-to-use scenarios tied to sibling tools: verifying whether a graphite_insert_svg that returned BRIDGE_TIMEOUT actually landed (by checking layer_id in layer_ids), and confirming a document is not empty before exporting. The condition that selects this verification path is spelled out rather than inferred.

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 only supply the safety flags; the description adds substantial non-obvious behavior: one undo step, ~40 ms per element build cost, automatic <text> outlining (and the outline_text=false escape hatch), and three named failure modes with remediation. The duplicate-layer warning on retry is a real behavioral hazard disclosed only here.

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 usage, then errors; nearly every sentence carries new information. It is on the long side and a few clauses (e.g. re-explaining that <text> becomes paths) overlap with the schema, costing a point but not readability.

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 mutation tool with an output schema, the description covers what the schema cannot: cost model, undo semantics, error taxonomy and retry safety. Nothing an agent needs to call this 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 coverage is already 100%, but the description still adds decision-relevant meaning: which of svg/svg_path to prefer and why (file read by connector, markup not re-sent), and why outline_text defaults to true (Graphite cannot render text). These are trade-offs, not restatements.

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 precise verb+resource+outcome: inserting SVG markup as an editable group layer where each SVG element becomes its own vector layer. It also positions itself among siblings by calling itself 'the main way to create artwork', so an agent can distinguish it from graphite_export or graphite_new_document.

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 selection guidance between the two input modes ('svg_path ... preferred for anything large'), tells the agent to generate the SVG itself first, and names the prerequisite (graphite_new_document) when NO_ACTIVE_DOCUMENT fires. The BRIDGE_TIMEOUT recovery path — check graphite_get_document before retrying to avoid duplicates — is exactly the kind of when-to-do-what guidance that prevents agent errors.

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 non-readOnly, non-destructive, non-idempotent, and closed-world, so the mutation safety profile is covered. The description adds genuinely useful context beyond that: the document becomes the active tab, it returns a document_id, it has no artboard, and inserted artwork uses document coordinates with y growing downward. It stops short of describing failure/permission behavior, so not a 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Four short sentences, front-loaded with the action and return value, followed by behavioral detail and the routing rule. Every sentence carries distinct information with no redundancy.

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 one-optional-param creation tool with full annotations and an output schema (so return values need no explanation), the description covers action, side effects, coordinate behavior, and sibling routing. Nothing an agent needs to call 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 coverage is 100% and the sole 'name' parameter is fully documented in the schema, including default and length bounds. The description adds no parameter-level 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?

States a specific verb and resource ('Create a new, empty Graphite document') plus a side effect ('make it the active tab'). It also distinguishes itself from the edit-what-is-open case, so an agent can tell it apart from graphite_get_document/select_document without opening 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?

Explicitly names when to use it ('before graphite_insert_svg when the user asks for a fresh document') and when not to ('do not call it if they want to edit what is already open'). Both the trigger and the exclusion are stated, 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 (readOnly, idempotent, closed-world), and the description adds substantial context beyond them: no disk writes, the default scale rationale, and concrete failure modes with recovery guidance (EXPORT_FAILED for layerless documents, BRIDGE_TIMEOUT with retry). This is exactly the behavioral detail annotations cannot express.

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?

One tight paragraph, front-loaded with the core action, then usage, then constraints, then error handling. Every clause carries information; nothing is 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 an output schema covering return values and annotations covering safety, the remaining gaps an agent needs — when to call it, cost implications, and failure/retry behavior — are all present. Complete for this tool's complexity.

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 reinforces the single parameter's tradeoff ('default scale 0.5 keeps the image small') in plain language that complements the schema's 'larger previews cost more context' note. It adds modest framing rather than new syntax.

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?

Starts with a specific verb+resource: 'Render the active document to a PNG and return it as an image.' It also distinguishes itself from the sibling graphite_export by stating 'Nothing is written to disk,' so an agent can tell the preview apart from the export tool 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 clear context: 'Use it after inserting artwork to check composition, alignment and missing elements before iterating.' That is explicit when-to-use guidance. It stops short of naming graphite_export or graphite_get_document as the alternative for the non-visual case, so it is not a full 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=false, idempotentHint=false and destructiveHint=false, covering the safety profile. The description adds useful scoping ('in the active document', 'most recently undone') but does not disclose what happens if there is no undo history or how the mutation affects the document state.

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?

A single front-loaded sentence with no redundancy or filler; the operation is stated immediately and nothing is wasted.

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?

An output schema exists, so return values need not be explained, and annotations cover the safety profile. For a zero-param tool this is nearly complete; only the no-history edge case is unaddressed.

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 with 100% schema coverage, so there are no parameter semantics to clarify. Baseline of 4 applies since the schema fully documents the (empty) input.

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 (redo) and resource (the most recently undone change in the active document), which is unambiguous and clearly distinct from the graphite_undo sibling. It stops short of explicitly naming the undo counterpart, but an agent can select it correctly without confusion.

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 phrase 'most recently undone change' implies the tool is used after an undo, giving contextual usage guidance. However, it never states when to use it versus graphite_undo or any precondition (e.g. that an undo history must exist).

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=false, idempotentHint=true, and destructiveHint=false. The description adds that the change affects the display name in the Layers panel, which hints this is a UI-facing label rather than an SVG id, but it says nothing about permissions, reversibility via undo, or side effects.

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?

One short, front-loaded sentence with no padding or repetition of the title. It is efficient, though it could carry one more clause of guidance at no structural cost.

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 tool is simple and an output schema exists, so return values need not be explained. However, for a mutation tool with no usage guidance and only partial parameter documentation, the description leaves the agent short on when to invoke it and whether an undo step is expected.

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 50%: layer_id is documented in the schema while name relies on minLength/maxLength. The phrase 'the name shown for a layer' adds semantic context that 'name' is a display label, which is genuinely useful, but the description does not restate the length constraints or format expectations.

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 (Set) and resource (the name shown for a layer), which is clear enough to distinguish from delete_layer, transform_layer, and set_style. It does not, however, explicitly name or contrast with any sibling tool.

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 no when-to-use guidance, no prerequisites (e.g., an existing layer_id must come from insert_svg or get_document), and no mention of alternatives such as undo for reverting. Usage is only implied by the tool name.

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 idempotent, non-destructive, non-open-world write semantics, so the bar is lower. The description adds real value beyond them by disclosing the global side effect: every other tool operates on whatever document is active, so this call changes the target of subsequent calls.

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, zero filler, front-loaded with the action and followed by the supporting lookup tool and the context for why it matters.

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?

An output schema exists so return values need not be explained, and the description covers the action, the sibling to find IDs, and the cross-tool effect. What is missing is any hint about failure modes (e.g., passing a document that is not open) or the ID format.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so the description must carry the burden for document_id. It implies the ID comes from graphite_get_document, which is useful, but it never states the numeric-string format (^\d+$) or that exactly one ID is required, so compensation is partial.

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 first sentence gives a specific verb and resource: 'Make another open document the active tab.' It is unambiguous and clearly distinct from graphite_get_document, which is named as the listing tool rather than the switching tool.

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 names the sibling that lists candidates (graphite_get_document) and states the consequence that selects this tool: all other tools act on the active document, so this is how you redirect them. There is no explicit when-not-to-use, but the context is clear enough to choose correctly.

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 (idempotent, non-destructive, not read-only), so the bar is lower, and the description still adds real behavioral detail: partial application ('Only the fields given are changed'), null-as-removal semantics, the one-undo-step per change guarantee, and the specific error code on a missing layer. Only return-shape detail is absent, which the output schema covers.

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 with no filler, and the primary effect is front-loaded before the partial-update, undo and error clauses. Every sentence carries distinct 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 mutation tool with full schema coverage, an output schema, and annotations declaring its safety profile, the description supplies the remaining operational facts an agent needs: scope of allowed targets, partial-update semantics, undo cost, and error behaviour.

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 five parameters (including colour format, opacity range and stroke width) are already documented in the schema. The description only restates the null-removal behaviour and adds no format or default detail beyond what the schema provides.

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?

Names a specific verb and resource ('Change the solid fill colour, stroke colour and width, and/or opacity of an existing layer'), which cleanly separates it from siblings like graphite_transform_layer, graphite_rename_layer and graphite_delete_layer. The agent knows exactly which properties this tool mutates.

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?

Establishes that the target must be an existing layer in the active document and reports the LAYER_NOT_FOUND failure mode, giving clear context for when the call is appropriate. It does not, however, explicitly contrast itself with transform_layer/rename_layer or state prerequisites such as a selected document.

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 it is a non-read-only, non-idempotent mutation with no destructive hint. The description adds genuinely useful behavior beyond that: transform is combined by default, replace=true overwrites, and it consumes exactly one undo step. The undo-step disclosure is particularly valuable for an agent planning sequences.

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 tightly packed sentences; the coordinate-space scoping is front-loaded and each clause carries distinct information (coordinate space, composition order, matrix alternative, replace semantics, undo cost). 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 an output schema present and annotations covering the safety profile, the description supplies everything else an agent needs: coordinate space, argument composition rules, override precedence, and reversibility cost.

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 baseline is 3, but the description adds semantics the schema does not: the fixed application order (scale, then rotate about origin, then translate) and that matrix overrides the component parameters. That ordering is essential for predicting the result.

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 (apply transform) and resource (existing layer) and immediately scopes the coordinate space (parent's coordinate space, document pixels for top-level layers). An agent can distinguish this from graphite_set_style and graphite_insert_svg at a glance.

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?

Clear context: applies to an *existing* layer, and the compositional rules (translate/scale/rotate vs raw matrix) tell the agent which input mode to pick. It stops short of naming an alternative sibling or stating when NOT to use it, but the use case is unambiguous.

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 the safety profile (non-read-only, destructive, not idempotent, not open-world), and the description usefully adds behavioral detail those annotations cannot convey: the undo granularity ('inserts, style, transform, rename and delete are each one step'). It still omits failure behavior (e.g. no-op or error when history is empty) and undo-depth limits, keeping it out of 5 territory.

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?

A single front-loaded sentence with no filler; the parenthetical earns its place by defining what constitutes one undo step 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?

For a zero-parameter tool with full schema coverage and an output schema that carries return values, the description covers the essential behavior. The one real gap is the absence of any linkage to the graphite_redo counterpart, which matters in a sibling set that includes redo.

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, which is the baseline-4 case; there is no argument surface for the description to disambiguate. Scoring higher is unnecessary since the description correctly implies the tool acts on the active document implicitly.

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 ('Undo') and a precise scope ('the most recent change in the active document'), which is far more informative than restating the name. It does not name or differentiate itself from the obvious sibling graphite_redo, so it stops short of a 5.

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 only implied: an agent can infer this is the recovery action after the listed mutations, but the description never says when to prefer undo over redo or any other sibling, nor what happens when there is nothing to undo. Adequate-but-underspecified.

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