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

Annotations already declare destructive, non-idempotent, closed-world behavior, and the description adds genuinely new traits: atomicity/all-or-nothing semantics, a single undo entry for the whole batch, and the $step data-passing mechanism. It still omits what is returned and what state is left after a mid-batch failure, but the added context is substantial.

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 dense sentences with no filler; the atomicity/undo-scope claim is front-loaded before the $step mechanics. 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?

For a destructive batch executor with no output schema and no parameter descriptions, the definition covers the core execution model but leaves the return value, failure/rollback details, and the label parameter unexplained. Adequate but with clear gaps.

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

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

Schema description coverage is 0%, so the description must carry the parameter burden. It explains the commands array structure and the {$step: n} cross-step reference convention (a real coding rule not expressible in the schema), but the 'label' parameter is never mentioned at all.

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 ('Several commands as one undo step') plus the underlying command name (command.batch), which tells an agent exactly what the tool does. It is distinguishable from run_command by the 'several/all-or-nothing' framing, though it never names the sibling explicitly.

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 'one undo step, all-or-nothing' phrasing implies when to reach for it (multiple related mutations that must succeed or fail together), but there is no explicit when-not-to-use or pointer to run_command for single commands. Usage must be 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 already declare the mutation profile (readOnlyHint=false, destructiveHint=true, idempotentHint=false), so the safety burden is partly carried. The description adds genuinely new behavioral context by explaining the coordinate space ('page units relative to the parent frame, the page when there is none'), but says nothing about ordering/index effects, what happens on failure, or how props interact with type.

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 the type enumeration, and the coordinate rule is placed second where it belongs. The type list is long but each item is load-bearing; nothing is padded.

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 13-parameter creation tool with no output schema and zero schema documentation, the description leaves too much unknown: how 'type' selects valid props, what 'path' and 'index' do, and what a successful creation returns. It covers only the coordinate convention.

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?

13 parameters at 0% schema description coverage, and the description only clarifies x/y semantics (implicitly the parent frame). Critical parameters such as type, props, path, index, parent, points, and closed are entirely unexplained in both the schema and the description, which is a major compensation gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb ('Create') and enumerates the exact node types it can produce, which is more informative than the title's vague 'layer'. It does not, however, contrast itself with siblings like set_properties or batch, so the agent must infer the boundary.

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?

There is no statement of when to use this tool versus alternatives such as batch, set_properties, or the run_command/command path. The only guidance offered is a coordinate-system note, which is a usage detail rather than a when-to-use rule.

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 and readOnlyHint=false; the description usefully discloses the dual behavior that without `path` bytes are returned as image content and with `path` the file is written. It stops short of warning that a write may overwrite an existing file or describing permission/format constraints, so it adds moderate context but not the full picture.

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, no filler, and the most consequential distinction (path vs. no path) is placed second but stated immediately after the format list without 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 14-parameter tool with no output schema and zero schema descriptions, the description is far too thin: an agent cannot determine what `ids` selects, how `size`/`scale` interact, or how cropping/mark options apply. The core I/O behavior is covered but most invocation surface is not.

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% across 14 parameters, so the description carries the full burden, yet it only clarifies `path` (destination vs. inline bytes) and echoes the list of values for `format`. Parameters such as ids, size, scale, bleed, cmyk, cropMarks and the svg* flags receive no semantics anywhere.

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 ('Export layers') and enumerates the supported output formats, so the agent knows exactly what operation is performed. It does not differentiate itself from sibling image-producing tools such as screenshot/get_screenshot, which is the only thing keeping it from 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?

The description explains the two output modes (bytes returned vs. file written) but never says when to choose this tool over screenshot, get_screenshot, or get_metadata. No prerequisites, no exclusions, no alternative routing.

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 covered. The description adds genuinely useful behavioral detail: that html/react/leptos return a whole layer tree rather than a single node's snippet. It says nothing about default language, unit handling, or error behavior when a node has no code.

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 tight sentence with the resource stated first and the format list in a parenthetical. Nothing is padded, though the parenthetical scoping note about whole layer trees is slightly 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 and 0% parameter coverage, the description carries the full burden for a tool with four inputs. It omits what nodeId identifies, how unit/rootFontSize affect the generated output, and which language is used by default — all things an agent needs before calling 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 0% across four parameters. The description names the six language values, but that merely repeats the language enum and earns no credit. nodeId, unit (px vs rem), and rootFontSize are never explained, so the description does not compensate for the documentation gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific resource — the generated code for a layer — and enumerates the exact output formats (CSS, HTML+CSS, React, Leptos, SwiftUI, Jetpack Compose). That is enough to distinguish it from neighbors like get_design_context or get_code_connect_map, though it never explicitly names a sibling or uses a leading verb.

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?

There is no when-to-use or when-not-to-use guidance and no reference to the sibling tools (get_design_context, get_code_connect_map, inspect_document) that also surface layer information. The only implied guidance is that the caller must pick a language, which is inferred from the format list 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 destructiveHint=false, so the safety profile is fully covered by structured data. The description adds the useful fact that the result spans the whole document rather than one node, but says nothing about empty results, pagination, or whether it covers only the current page/file.

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 sentence, front-loaded with what the tool returns, zero filler. Every clause (scope, fields returned) carries information an agent needs.

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 parameters and no output schema, the description compensates by enumerating the returned fields, and annotations carry the safety profile. Only minor gaps remain (scope of 'document' as file vs current page, behavior when nothing is connected).

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 since no parameter semantics need explaining. The description correctly avoids inventing arguments the schema does not have.

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 resource (the code connect links of the document) plus a precise enumeration of what each entry carries: language, import path, name, and template. The document-wide scope implicitly separates it from node-scoped siblings like get_code, but no sibling is named explicitly.

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 says only what the tool returns; it never states when to reach for it versus alternatives such as get_code or get_metadata. Usage is left entirely to inference from the content description.

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 establish the safe-read profile (readOnlyHint, idempotentHint, destructiveHint=false, openWorldHint=false), so the description's job is to add context beyond that. It does so by disclosing the composition of the returned payload in detail — auto layout, styles, variables, component links, interactions — which is meaningful behavioral context, especially since there is no output schema. It does not explain how depth controls traversal or the cost of a deep fetch.

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 that puts the resource first and the purpose clause last; no filler or restated boilerplate. The long enumeration is dense but each item is a real content type rather than padding. Slightly heavy punctuation (dash-separated list) but well structured overall.

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 five-parameter tool with a six-value language enum, no required parameters, and no output schema, the description covers only the return payload. It omits parameter behavior entirely — what depth defaults to, whether includeProperties/includeCode gate the returned fields, and what nodeId expects — and gives no routing guidance against sibling readers. The annotations cover safety, but the parameter and selection gaps are too large for a tool of this 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 description coverage is 0% across five parameters, including an enum (language: css/html/react/leptos/swiftui/compose) and control flags (includeCode, includeProperties, depth 0-64). The description's mention of 'the facts a code generator needs' only faintly hints at includeCode, and it says nothing about nodeId, depth semantics, or the language enum. With zero schema descriptions, the description should have compensated and largely does not.

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 the resource precisely ('the design context of a layer') and enumerates exactly what that context contains — geometry, auto layout, fills, strokes, effects, typography, styles, variables, component links, interactions. An agent immediately understands what this returns. It loses a point because it never distinguishes itself from close siblings like get_node, get_metadata, inspect_document, or get_code, which an agent must disambiguate on its own.

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 closing clause 'the facts a code generator needs' implies the downstream use case (feeding code generation), which is a genuine usage signal. However, there is no explicit when-to-use, no when-not-to-use, and no named alternative among the many sibling read tools (get_node, get_metadata, get_code, inspect_document). Usage 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=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the return structure and the no-nodeId default scope, which is useful, but it says nothing about depth truncation, size limits, or how deeply children nest.

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 compact sentences, front-loading the return shape before the scoping caveat. No filler, though the phrase 'in the Figma MCP shape' is slightly jargon-heavy.

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 low-complexity, read-only, two-optional-parameter tool with no output schema, the description covers the core return contract and the nodeId default. It leaves the depth parameter and any hierarchy-truncation behavior unexplained, which an agent needs to traverse the result 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 0%, so the description must carry both parameters. It explains nodeId's default behavior (falls back to current page) but never mentions `depth`, its 0-64 range, or what depth controls in the returned hierarchy.

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 concrete verb+resource (retrieves the layer hierarchy) and even specifies the returned shape {id, name, type, children}, so an agent knows exactly what comes back. It does not, however, distinguish this from siblings like get_node, inspect_document, or get_design_context, which also expose document structure.

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 only usage-like statement is a scoping default ('Without nodeId the current page is returned'), which is really parameter behavior. There is no guidance on when to call this instead of get_node or inspect_document, no prerequisites, and no 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?

Annotations already declare readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered. The description adds that the return is JSON with a specific field set, but says nothing about the most consequential behavior: whether the 'depth' parameter expands the returned subtree, and what happens for a missing or invalid id. With annotations carrying safety, this is a middling 3.

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 that leads with the return shape. The long field enumeration is borderline padding, but for a tool with no output schema it doubles as return-value documentation.

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, so the field list is a reasonable partial stand-in for describing the response. However, the depth parameter's traversal behavior, error cases, and payload size implications are unaddressed, leaving the agent under-informed for a tool whose schema is entirely undescribed.

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

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

Schema description coverage is 0% for both parameters, so the description must compensate and does not: it never mentions 'id' or 'depth'. The word 'layer' hints that id is a node identifier, but the semantics of depth (subtree expansion, max 64) are entirely undocumented anywhere an agent can see.

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 resource ('one layer') and enumerates the returned fields, so the agent knows this is a single-node read that yields a rich property bundle. It distinguishes itself implicitly from create_node/set_properties by being a read, but never names a sibling like get_design_context or inspect_document to sharpen the boundary.

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?

There is no statement of when to use this versus get_design_context, get_metadata, inspect_document, or get_code, all of which plausibly overlap with reading design data. The agent must infer the selection rule from the field list alone.

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

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

Annotations already declare read-only, idempotent, non-destructive, closed-world behavior, and the description does not contradict them. It adds that the result is PNG and follows the Figma MCP shape, but it omits return encoding, scaling effects, and size-limit behavior, so the added behavioral context is modest.

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 compact sentence front-loads the output type and scope, then maps two key parameters. There is little waste, and the structure makes the main modes easy to scan.

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 five-parameter tool with no parameter descriptions and no output schema, the definition is under-specified: three parameters and the exact return payload are unexplained. Annotations reduce safety concerns, but the description is not complete enough to guarantee 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 0% across five parameters, and the description explains only nodeId and window. The ids, scale, and maxSize parameters remain undocumented, leaving most invocation semantics to inference.

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 the resource and output clearly: a PNG of a layer or the current page, with nodeId vs window mapping. It is distinguishable from a generic screenshot, but it does not explicitly differentiate itself from sibling tools such as screenshot and export.

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 in-tool selection guidance by mapping nodeId to one layer and window:true to the app window, so the two main capture modes are implied. It says nothing about when to prefer this over sibling screenshot/export tools, nor any prerequisites or 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered. The description adds genuine value beyond that by disclosing the returned content and format ('modes, code names and scopes', 'the Figma MCP shape'), which helps an agent predict output structure. It stops short of explaining pagination or the effect of the includeStyles toggle.

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 that names the primary resource first and the format qualifier last. Every phrase carries information with no filler, though the trailing 'the Figma MCP shape' is somewhat jargon-laden and unexplained.

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 must carry the return-value burden, and it does reasonably well by enumerating modes, code names, and scopes. However, it leaves the single parameter's behavior and the meaning of the 'Figma MCP shape' format unstated, so an agent still has gaps before calling it.

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

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

Schema description coverage is 0% and includeStyles is undocumented in the schema. The description mentions 'paint styles' being returned, which weakly hints at what the toggle controls, but it never explains that includeStyles governs whether styles are included or that it defaults to some value. With one undocumented parameter, the description does not compensate.

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 the resource precisely — document variables and paint styles with their modes, code names and scopes — so an agent knows exactly what data comes back. It is a noun fragment rather than a verb-led statement, but the intent (retrieve variable/style definitions) is unambiguous. It does not differentiate itself from retrieval siblings like inspect_document, get_metadata, or get_design_context.

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?

There is no when-to-use, when-not-to-use, or alternative guidance. The 'Figma compatible' framing implies a context but the description never says when an agent should call this instead of inspect_document or get_design_context. Usage must be inferred entirely.

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=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds a useful preview of the payload (undo history, layer tree, colour profile), but omits the behavioral caveats that matter here — that the full undo history and layer tree can make this a very heavy response, and that output size depends on the depth/allPages controls.

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 that leads with what the tool returns and then enumerates the fields. It is a sentence fragment rather than a full clause, but nothing is padded or 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, the description correctly carries the return-value burden and does so reasonably. However, for a tool whose output is a whole document tree plus undo history, the omission of any guidance on scoping via depth/allPages and on response size leaves the agent unable to control or anticipate the call's 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 description coverage is 0%: neither 'depth' (0-64) nor 'allPages' is documented anywhere. The description never mentions them, so an agent cannot infer the default depth, whether sublayers are expanded, or whether only the current page is returned — the two knobs that determine the shape and size of the result are entirely unexplained.

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 the resource (the document) and enumerates exactly what the JSON contains — name, path, dirty flag, page, selection, layer tree, styles, undo history — so an agent knows precisely what comes back. It does not differentiate from close siblings such as get_metadata, get_node, or get_design_context, which also return document-derived 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?

There is no statement of when to call this versus get_metadata, get_node, get_design_context, or inspect_ui, all of which overlap in scope. No prerequisites, no note on cost or when a narrower tool is preferable.

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=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered by structured data. The description adds useful behavioral content by listing what state surfaces are read (timings, frames drawn, live session, windows), but says nothing about freshness, permissions, or whether calls are expensive. With annotations carrying the safety burden, this is a modest value-add.

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 sentence fragment with no wasted words, front-loaded with the subject 'The app state'. The colon-delimited list is compact, though the missing verb makes it read as a label rather than a description.

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 burden of explaining returns, and it does list the state categories an agent will receive. However, it gives no sense of the shape or structure of that data, no usage context against the many sibling inspection tools, and no note on whether it is a snapshot or live stream. Adequate but with clear gaps for a zero-arg inspection 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 are no parameter semantics to document and the schema is trivially complete at 100% coverage. The baseline for a parameterless tool is 4.

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 enumerates the data surfaces the tool exposes (panels, current tool, view, zoom, timings, windows, live session, home screen), which implies a read of app UI state, but it never states a verb or resource explicitly. It is essentially a restatement of the title 'Inspect the app UI' as a colon-delimited list rather than a purpose statement. An agent can infer what it returns but not what it does.

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?

There is no guidance about when to call this tool versus close siblings like inspect_document, get_metadata, or screenshot. No prerequisites, no condition that selects it, no exclusions. The agent is left to infer usage entirely from the 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 destructiveHint=true and non-idempotent, so the agent knows a keypress can trigger irreversible effects. The description adds nothing behavioral beyond that — no warning that a key can fire destructive actions, no statement about focus/target window, and no note on repeat or timing. With annotations present, a small amount of added context is expected but nearly absent 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?

Two compact sentences with no padding; the key-format examples lead and the macOS note follows. Slightly awkward as an opening fragment, but no sentence 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?

For a five-parameter, zero-schema-coverage, no-output-schema tool, the description covers only the primary parameter and one modifier. Modifier keys and the consequences of a destructive keypress are left unstated, which is thinner than this tool's complexity warrants.

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

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

Schema description coverage is 0% across five parameters, so the description must carry the load. It does explain the `key` value format well (literals like "Enter", "ArrowLeft", "=", plus egui names like "Plus") and clarifies that `cmd` maps to Cmd on macOS, but `alt`, `ctrl`, and `shift` are never addressed and no combination semantics are given.

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 conveys that this simulates a keypress on the canvas and gives concrete key examples ("A", "Enter", "ArrowLeft", "Plus"), so the resource is identifiable. But it is a noun-phrase fragment with no verb and no differentiation from the sibling `type_text`, which is the obvious confusion point for an agent choosing between keyboard 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?

There is no statement of when to use this tool versus `type_text`, `pointer`, or `run_command`, and no prerequisites or exclusions. The examples imply 'single key/shortcut' usage but that inference is left entirely to the agent.

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), so the description only needs to add context. It does: it discloses the total result size (561) and the shape of each entry, implying the call returns the full catalog rather than a page. It does not state whether the list is paginated or ordered, which is a minor remaining gap.

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 front-loaded sentence plus a four-word follow-up. The return fields and the filtering instruction are both given without a wasted clause.

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 one optional parameter and no output schema, the description covers what an agent needs: the resource, its scale, and the fields returned. The only substantive omission is how `filter` matches, which would be required for confident use.

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% for the single `filter` parameter, so the description must carry the semantics and only says to filter with it. It never specifies matching behavior — substring vs. exact vs. regex, case sensitivity, or which fields (id, label, menu) are searched.

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 ('every command the FigCraft app can run') plus the exact fields returned (id, label, menu, shortcut, parameter doc), so an agent immediately knows this is a catalog lookup rather than an executor. It never names its obvious sibling run_command, so differentiation is implied by 'can run' rather than stated.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

'Filter with `filter`' is the only usage hint, which is a functional cue rather than a when-to-use rule. Nothing tells the agent to call this first to discover an id before run_command, nor when filtering is preferable to fetching all 561 entries.

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 declare destructiveHint=true and idempotentHint=false, so opening a file evidently discards or overwrites current state — but the description calls it a benign 'open' and discloses no such consequence (unsaved changes, document replacement). It adds only the return payload (file summary + document outline), leaving the most important behavioral trait unstated.

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 tight sentences, purpose front-loaded and the return payload appended. No padding; the format enumeration is dense but earns its space.

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 and no parameter documentation, and the description omits the destructive side effect that the annotations flag. Stating the return shape is a positive, but an agent still lacks what it needs to call this 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 0% and the description explains neither parameter. The format list loosely hints at what 'path' may point to, but 'variables' (a string-or-object anyOf) is completely unexplained in both schema and description.

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?

Specific verb+resource: 'Open a ... file in the app', with an explicit enumeration of accepted formats (.figcraft, .json, .fig, .svg, image). It is trivially distinguishable from siblings like save_file or create_node, though it never names an alternative explicitly.

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?

No when-to-use guidance, no prerequisites, no statement of what happens to the currently open document. The agent must infer whether this replaces state, requires an existing session, or is safe to call mid-workflow.

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=false, destructive=true and idempotent=false, so the safety profile is covered. The description adds useful context beyond annotations — that gestures act through the current tool and use page coordinates — but it never explains what can be destroyed (clicks firing irreversible UI actions) or that repeated calls are not idempotent, leaving a gap for a destructive tool.

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 tight sentences, with the gesture kinds and the coordinate semantics front-loaded. It avoids padding, though the kind enumeration duplicates the enum and slightly dilutes the front-loaded content.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For an 11-parameter, destructive interaction tool with no output schema, the description is thin: it omits modifier-key semantics, steps/pressure meaning, the tool parameter's effect, and any note on what the call returns or whether coordinates are absolute or viewport-relative beyond 'page coordinates'.

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

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

Schema description coverage is 0% across 11 parameters, so the description must carry the burden. It clarifies x/y as page coordinates and `to` as the drag target, which is genuinely additive, but leaves alt, cmd, shift, steps, pressure, pressureTo and tool entirely unexplained; many of these (application-defined tool) are not self-evident.

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 concrete action (mouse gesture) and enumerates the seven gesture kinds, which lets an agent distinguish this from keyboard siblings like key and type_text. However, the kind list largely restates the schema enum rather than sharpening the purpose, and it never names the sibling that handles pointer interaction alone.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The phrase 'with the current tool' hints that behavior depends on prior tool state, but there is no explicit when-to-use/when-not-to guidance and no alternatives named (e.g., 'use key/type_text for keyboard input'). No prerequisites such as needing a selected tool or active canvas are 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 destructiveHint=true, idempotentHint=false, and readOnlyHint=false, so the safety profile is covered structurally. The description adds no behavioral context beyond that – it doesn't say what scope redo applies to, what it does when there is nothing to redo, or what state gets overwritten.

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 short sentence with the action verb front-loaded and no filler. It is efficient, though extremely terse for a tool whose annotations flag it as destructive.

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 command whose annotations carry the mutability flags, a one-line description is nearly adequate. It still omits the operating scope (which document/editor the redo applies to) and the no-op case, both relevant for a destructive-flagged 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, and the description correctly implies a parameterless command. With no parameters to document, the baseline of 4 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?

"Redo the last undone change" names the operation and its scope, so an agent knows it re-applies the most recently undone edit. However, it largely restates the name/title and does not distinguish itself from the sibling `undo` tool, leaving the caller to infer the pairing.

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?

There is no when-to-use guidance, no prerequisite (an undone change must exist), and no mention of the obvious alternative `undo`. The agent gets no routing help between redo and undo.

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 declare destructiveHint=true, readOnlyHint=false, and idempotentHint=false, yet the description says nothing about commands mutating or destroying document state, nor about behavior on invalid commands. The id-format hint is useful but is discovery context, not behavioral disclosure, so the description adds little 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?

Single front-loaded sentence with a useful example list; nothing is padded. It is efficient, though the trailing ellipsis leaves the enumeration open-ended rather than closing the thought.

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 catch-all dispatcher with no output schema and no parameter documentation, the description is too thin. It omits what params the underlying commands accept, error behavior for unknown ids, and any indication of what a call returns or changes.

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

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

Schema description coverage is 0% for 2 parameters. The description does add real meaning to `command` by tying ids to menus/shortcuts/Actions palette, but the `params` object (arbitrary nested properties) is completely undocumented, leaving a significant gap for a dispatcher that forwards arguments to arbitrary commands.

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 clear verb+resource ('run any command of the app') and clarifies the command namespace by pointing to menu/shortcut/Actions palette ids with concrete examples like align.left and file.export. It is reasonably distinguishable from list_commands, but as a catch-all dispatcher it overlaps with concrete siblings like create_node and batch without explaining the boundary.

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?

No when-to-use/when-not guidance and no mention of alternatives. It never says to use list_commands to discover valid ids or batch for multiple operations, and never clarifies why an agent would pick run_command over the dedicated sibling tools.

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 disclose destructiveHint=true, readOnlyHint=false, and idempotentHint=false, so the safety profile is known. The description adds one genuine behavioral detail beyond them: that the path is only needed on the first programmatic save, implying the tool remembers the target. It does not explain the overwrite/destructive semantics that destructiveHint implies.

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 clause with no wasted words, and the key constraint about `path` follows immediately. It is appropriately terse, though for a destructive mutation the brevity comes at the cost of missing behavioral detail.

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 write with no output schema and 0% schema coverage, the definition should state overwrite behavior, error conditions, and the return/confirmation surface. None of that is present, so an agent lacks what it needs to invoke this mutation 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 0% and the single `path` parameter is only typed as a string with minLength 1. The description compensates partially by stating when path is needed (first programmatic save), but never explains what the path refers to (filesystem path? document identifier?) or the format expected.

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 ('save the document'), which clearly distinguishes it from siblings like open_file, export, and inspect_document. It does not name an alternative tool, but the action is unambiguous enough to identify 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?

There is an implied usage cue (this is the step after programmatic edits produce a document), and the description hints when a path is required on the first save. However, it names no alternatives or when-not-to-use conditions, and does not clarify the relationship to export or open_file.

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 covered. The description adds genuinely useful behavior — the image is scaled to fit `maxSize`, includes the background, and window capture is scoped to the app window — though it omits how the PNG is returned (inline data vs. file path).

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?

It is appropriately short and front-loads the output format and default, but the final clause ('a window id that window') is grammatically broken, which undercuts comprehension rather than serving conciseness. Two sentences, no padding, but one is unusable as written.

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 4 undocumented-in-schema parameters, no output schema, and a near-identical sibling (`get_screenshot`), the description should do more: it never states the return format or how this tool differs from its sibling. The parameter hints it does provide are the only reason this is not a 1.

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

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

Schema description coverage is 0%, so the description must carry the load, and it does explain three of four parameters: `ids` (the given layers), `window` (true = app window, or a window id), and `maxSize` (default 1600). `scale` is only implied via 'scaled to fit', and the window clause is garbled, 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 description conveys the resource (a PNG capture of the page or given layers, or the app window) but writes it as a noun phrase rather than a specific action, and it does not distinguish this tool from the sibling `get_screenshot`, which appears to do something very similar. An agent can guess the purpose but cannot tell which screenshot tool to pick.

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?

There is no when-to-use guidance, no statement of how this differs from `get_screenshot` or `export`, and no conditions under which window capture is preferable to page capture. Usage context is left entirely 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 declare destructiveHint=true and readOnlyHint=false, so the safety profile is already known. The description adds useful behavioral detail beyond annotations: it clarifies that the operation replaces the existing selection and that an empty array deselects.

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 sentence, front-loaded with the main action and including the critical empty-array nuance. 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?

For a single-parameter mutation tool with no output schema and explicit annotations, the description covers the essential behavior. It does not describe return values or selection state afterward, but those are minor gaps here.

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 parameter meaning. It explains that 'ids' are layer ids and that an empty array has the special deselect behavior, which is meaningful beyond the raw array-of-integers schema.

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-resource pair ('Replace the selection') and clarifies the key input behavior ('given layer ids'). It is clear without opening the schema, though it does not explicitly distinguish itself from unrelated siblings like set_properties.

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 replacement and empty-array deselect semantics. There is no explicit guidance on when to use this versus related operations, nor any excluded contexts.

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, readOnlyHint=false, and idempotentHint=false, so the safety profile is covered structurally. The description adds the selection-defaulting behavior, but says nothing about what a destructive change overwrites, how partial/invalid props are handled, or whether properties are merged or replaced — meaningful gaps for an untyped 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?

Two sentences, front-loaded with the action and the property inventory, then the targeting rule. The category list is long but each item earns its place by defining the untyped `props` bag; no filler text.

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, non-idempotent mutation with a free-form props object and no output schema, the description covers the target selection and property scope but omits error/partial-application behavior and any permissions or preconditions. Adequate but with clear gaps given the 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 0% and `props` is a free-form object with no documented keys, so the description must carry the load; it partly does by enumerating property categories (fills, strokes, auto layout, masks, text props), giving an agent a usable mental model. The `ids` parameter's semantics are also conveyed via the selection-defaulting sentence, but neither parameter's value format or constraints are specified.

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?

Specific verb ("Change") plus resource ("layers") with an enumerated list of what can be changed (geometry, fills, strokes, effects, etc.), which lets an agent distinguish it from read-oriented siblings like get_node or inspect_document. It stops short of explicitly contrasting itself with write siblings like create_node or batch, so it doesn't reach 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?

The description gives one clear targeting rule — "Acts on `ids`, or on the selection when none are given" — which is genuinely useful usage context. However it offers no when-to-use vs alternatives guidance, e.g. when to reach for set_properties instead of create_node or batch, leaving usage largely 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?

Annotations already declare destructiveHint=true and non-idempotent, so the safety profile is covered. The description adds the useful detail that the `id` form replaces existing contents, but the remark that 'the edit is ended again' is ambiguous about whether edit mode is committed or exited, leaving an important side effect underspecified.

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?

It is a single sentence with the primary action front-loaded, which is good. The trailing parenthetical ('the text is edited and the edit ended again') is opaque enough to cost clarity rather than earn 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?

For a two-parameter mutation tool with annotations already conveying destructiveness and no output schema, the description covers the two invocation modes and the role of `id`. It nonetheless leaves error/precondition behavior (no active edit, invalid layer id) and the `text` parameter's semantics 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?

Schema coverage is 0%, so the description must carry parameter meaning. It clarifies that `id` identifies the text layer to replace and that omitting it targets the in-progress edit, which is valuable; however it says nothing about `text` beyond its name and does not fully compensate for the zero-coverage schema.

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 (type) and two concrete targets: the text currently being edited, or the contents of text layer `id`. That distinguishes it reasonably from siblings such as `key`, `set_properties`, and `run_command`. The parenthetical clause about the edit being ended is unclear, but the core action is identifiable.

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 implicitly tells you there are two modes (active edit session vs. named layer), which is real usage guidance, but it never says when to prefer this over `key`, `set_properties`, or `run_command`, nor what happens if no edit session exists. Usage 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 destructiveHint=true, non-idempotent and not read-only, so the safety profile is covered. The description adds useful granularity beyond that - it undoes exactly one change, not a whole history - but says nothing about whether the change is recoverable via redo or what happens when there is nothing to undo.

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 zero wasted words, and the scope qualifier in parentheses is compact and informative.

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 no output schema, the description supplies the one fact an agent needs (what unit of work is undone) and nothing more is required to call 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?

Zero parameters, so per the baseline the schema carries no semantics for the description to compensate for. No parameter detail is needed or expected here.

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 its target ('the last change'), and clarifies the granularity by naming what a 'change' can be (command, batch or gesture). This distinguishes it from redo, though the sibling inverse is not named explicitly.

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 verb and the 'last change' scoping, which signals a single-step undo rather than a history rollback. However, it never states when to reach for this instead of redo, nor any precondition (e.g. that an undoable action must exist), leaving guidance at the minimum viable level.

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