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

Annotations already mark this as a non-read-only, destructive operation, so the bar is lower. The description adds the useful behavioral fact that the layer follows the style afterward, but it does not detail what existing style values are overwritten or whether the action is reversible.

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, then the value proposition. Every sentence earns its place and neither restates the title nor pads with boilerplate.

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 tool with annotations and full schema coverage, the description covers the core behavior and the source of styleId. It could briefly mention what happens to existing local style values, but annotations already signal the destructive nature.

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

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

Schema description coverage is 100%, so the schema already documents nodeId and styleId, including the selection fallback for nodeId. The description adds only that styleId comes from figma_list_library, which is helpful but not enough to exceed the baseline.

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

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

The description opens with a specific verb and resource: applies paint, text, or effect styles from the current file by id. It also clarifies the source via figma_list_library and the intended outcome ('layer follows style'), making it easy to distinguish from raw fill/stroke setters.

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 'right way to make something match' sentence gives a clear when-to-use signal and explains why it beats copying hex codes. It does not explicitly name sibling alternatives or state when not to use the tool, so it stops short of a 5.

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

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

Annotations already indicate readOnlyHint=false and destructiveHint=true, and the description adds a meaningful behavioral trait: the bound value will follow the token rather than remain a copy. It does not detail what gets destroyed by the binding, but the annotation already carries that destructive signal, so the description adds enough beyond the structured metadata.

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

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

The description is two concise sentences with no filler. It front-loads the core behavior and then gives directly actionable field-value guidance. Every clause 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?

All three required parameters are covered by the schema, and the description supplies the necessary semantic guidance for the free-form 'field' parameter. The main context not spelled out—destructive side effects and lack of output format—is already handled by annotations and the absence of an output schema on this mutation tool.

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

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

Schema coverage is 100%, so the baseline is 3, but the description enhances the 'field' parameter by pairing specific values with variable types (color vs. number) and adding useful numeric property examples. This goes beyond the schema's terse 'fill, stroke, or a numeric property' 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?

The description states a specific verb ('binds'), a resource ('a variable from this file'), and a target ('a property'), while clearly distinguishing the behavior from setting a static value ('so the value follows the token rather than being a copy'). It effectively separates this tool from sibling tools like figma_set_fill or figma_set_stroke.

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 concrete guidance on when to use which field values: 'fill' or 'stroke' for color variables, property names like cornerRadius or opacity for numbers. It does not explicitly name alternatives or exclusion conditions, but the 'rather than being a copy' phrasing provides clear context that this tool is for linking to tokens instead of setting independent values.

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, but the description presents the operation as purely additive copying. Nothing in the description explains or supports a destructive side effect, so the description contradicts the annotation. It also does not mention what happens to the cloned node's position or children in edge cases.

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 no filler. The first sentence states the core operation and scope, and the second sentence earns its place by conveying exactly when this tool is preferable.

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 core cloning behavior is clear and simple, and the use case is useful. However, the absence of x/y parameter semantics and the unresolved conflict with destructiveHint leave meaningful gaps for an agent invoking the tool 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?

The schema already documents nodeId and parentId, and the description reinforces parent semantics. However, x and y are completely undocumented in both the schema and the description, despite being two of the four parameters. With 50% schema coverage, the description should have compensated for x/y but 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 states a specific action ('copies a node'), the object ('with everything inside it'), and the destination ('same parent or one you name'). This clearly distinguishes cloning from creating, moving, or deleting nodes, and adds useful context beyond the title.

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

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

It gives a clear use case: 'the cheapest way to make a second row, card or list item that matches the first exactly.' It does not explicitly name alternatives or state when not to use it, but the context is clear enough for selection.

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?

Beyond the readOnlyHint and destructiveHint annotations, the description discloses the key-format behavior ("Label#8:2", not "Label") and that the tool returns current instance values. This surfaces a non-obvious quirk an agent would otherwise only discover after a failed call.

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

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

The description is tightly written: the first sentence defines scope and output, the second gives essential sequencing and the key-format warning. No filler or redundant restating of the tool name appears.

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 what the tool returns, and it does: it lists the property kinds and current values. It also provides the crucial prerequisite relationship to the setter, making the definition complete 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?

The single nodeId parameter is already fully documented in the schema, including the optional behavior of using the current canvas selection. The description adds no additional parameter-level meaning, so the baseline 3 is appropriate.

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

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

The description names a specific verb and resource: it retrieves the properties of a component, component set, or instance, enumerating variants and text, boolean, and instance-swap properties. This clearly distinguishes it from siblings like figma_get_tree and figma_set_instance_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?

It explicitly instructs the agent to call this tool before figma_set_instance_properties, and explains why: the setter requires keys with an id suffix that cannot be guessed. This is direct, actionable usage guidance tied to a concrete sibling.

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 signal mutation via destructiveHint=true, and the description does not contradict that. Yet the description adds no operational detail beyond 'creates': it does not explain where the ellipse is inserted, how parentId interacts with the current selection, or what side effects the creation has. For a create operation, this leaves important behavior undisclosed.

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

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

The description is one tight sentence that front-loads the core action and then adds one valuable nuance. There is no filler or repetition beyond an acceptable restatement of the title.

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

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

For a mutating creation tool with 7 parameters, no output schema, and no explicit insertion semantics, the description is too thin. An agent needs to know where the ellipse lands, whether parentId is effectively required, and what the call returns or affects. None of that is covered.

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?

With only 43% schema description coverage, the description should compensate for undocumented parameters, but it only adds meaning to width/height via the equal-dimensions-circle note. It does nothing for x, y, name, or parentId, so an agent still lacks semantics for most parameters.

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 uses a specific verb and resource: 'Creates an ellipse.' It adds the distinctive geometric behavior that equal width and height produce a circle, which differentiates it from sibling create_* tools such as create_rectangle or create_text.

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

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

The description implies usage via the examples 'an avatar, a dot, a radio button,' suggesting when a circle/ellipse is desired. However, it does not explicitly say when to choose this over alternatives like create_rectangle, nor does it mention exclusions or fallback conditions.

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

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

The annotations already mark the operation as non-read-only and destructive, and the description adds useful behavior beyond them: the frame starts empty, placement follows the page or parentId, and the node id is returned. It does not explain what the destructive hint refers to, but it does not contradict the annotation.

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 short sentences deliver the core action, placement behavior, and return value with no redundant filler. The most decision-relevant information is front-loaded.

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 creation tool with no required parameters, the description plus schema provides defaults, placement, and the returned id, which is enough to invoke it. The only real gap is that the destructiveHint annotation's side effect is not clarified, though it is not central to calling this tool successfully.

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 descriptions cover 71% of parameters, including fill, name, width, height, and parentId, so the schema does most of the work. The description adds only high-level reinforcement of 'fill' and 'parent' and does not explain x/y coordinates or units.

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

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

The description opens with a specific verb and resource ('Creates an empty frame') and adds placement options ('current page or inside a parent you name'), which is enough to distinguish it from sibling creation tools. It also states the return value, making the tool's role in a build workflow explicit.

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 conveys clear context: frames are created either on the current page or under a named parent, and the returned id is meant to be used by a subsequent call to fill the frame. It does not explicitly name alternatives or exclusion cases, so it stops short of a 5.

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

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

Annotations already mark this as a mutating, destructive-hinted operation. The description adds useful behavior beyond that: placing an instance keeps the link to the component, and naming a variant set results in its default variant. This gives agents expectations about side effects and variant handling that the annotations alone do not convey.

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

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

Four short sentences, each earning its place: core action, required id source, variant nuance, and rationale for preferring the tool. The purpose is front-loaded and there is no filler or repetition of schema details.

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 creation tool with no output schema, the description does not mention return value or resulting node id, which an agent would likely need for follow-up operations like setting properties. It covers purpose, id source, and variant behavior, but omits what the caller gets back and where the instance is placed when parentId is not provided.

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 only 20%, so the description must compensate. It does help by explaining that componentId comes from figma_list_library and by adding variant-set behavior for name. However, x, y, and parentId receive no semantic explanation, so several parameters are still underspecified.

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

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

The description opens with a specific verb and resource: 'Creates an instance of a component in this file.' It also differentiates itself from drawing a lookalike by emphasizing that an instance keeps its link to the component and updates with it, which clarifies what kind of creation this is versus sibling creation 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?

It gives clear context: get the id from figma_list_library and prefer this tool over drawing a lookalike when you want the component link preserved. It does not explicitly name alternative sibling tools or state when not to use it, so it stops short of fully explicit exclusionary guidance.

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

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

Annotations already mark destructiveHint=true and readOnlyHint=false, so the mutation intent is disclosed. The description adds a behavioral detail about the fill parameter ('Omit the fill for an empty one') but does not elaborate on other side effects, such as whether the rectangle is inserted into the current page or a specified parent, or what the return value is. It neither contradicts annotations nor adds substantial new behavioral context.

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

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

The description is two sentences with zero filler. It front-loads the essential action ('Creates a rectangle'), then adds the workhorse use cases and the fill nuance. Every sentence contributes value, and it is appropriately brief for the tool's complexity.

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

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

For a tool with 8 optional parameters and no output schema, the description is too sparse. It omits key operational details like what x and y represent (coordinates, units), what the tool returns (likely a node reference), and the meaning of parameters like name and cornerRadius. The fill note is helpful but the overall context is insufficient for an agent to use the tool correctly without additional information.

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 only 50% (fill, width, height, parentId have descriptions), while x, y, name, and cornerRadius lack any schema description. The description only clarifies the fill parameter ('Omit the fill for an empty one'), leaving the undocumented parameters (x, y, name, cornerRadius) entirely unexplained. With half the parameters undocumented, the description fails to compensate, offering meaning for only one parameter.

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

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

The description opens with a clear verb and resource: 'Creates a rectangle.' It adds practical context by calling it 'the workhorse shape' and enumerating typical uses (dividers, bars, backgrounds, placeholders), which helps an agent understand its primary role. It also conveys a behavioral nuance (omit fill for an empty rectangle), so the purpose is both specific and actionable.

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

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

The description implies common use cases for rectangles but does not explicitly contrast this tool with siblings like figma_create_ellipse or figma_create_frame. There is no 'when not to use' guidance or mention of alternatives. It states 'the workhorse shape' and typical uses, but an agent would need to infer when this is preferred over other shape creators.

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?

Beyond the annotations (readOnlyHint=false, destructiveHint=true), the description adds valuable behavioral detail: the output is real editable paths, not a flattened image, and SVG can round-trip unchanged from extraction. It doesn't describe what destructive effects occur, but annotations already flag mutating behavior, so this is not a major 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?

Three focused sentences with no wasted words. The core transformation is front-loaded, followed by the use case and a round-trip nuance. Every sentence adds distinct value.

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 main behavior is clear, but with 7 parameters, no output schema, and minimal schema descriptions, the agent still lacks guidance on positioning, frame placement, scaling behavior, return value, and what destructive side effects might occur. Adequate for high-level understanding, but not fully complete for reliable 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 only 29%, and the description only reinforces the 'svg' parameter meaning. It does not explain x/y placement, parentId, name, height, or how scaling relates to width/height. With most parameters undocumented in the schema, the description should compensate but doesn't.

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

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

The description states a specific verb and resource: it turns SVG markup into editable Figma vectors, not an image. It explicitly differentiates itself from image insertion and other create tools by saying 'any shape the other create tools cannot express.'

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 usage context: use this for icons, logos, or shapes other create tools can't express, and it implicitly rules out image insertion by emphasizing these are editable vectors. It doesn't name specific sibling tools or state explicit when-not conditions, but the context is strong enough.

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?

Given annotations (readOnlyHint=false, destructiveHint=true), the description adds useful behavioral context beyond them: it discloses the font loading sequence, refusal of unavailable fonts rather than substitution, and the width-to-wrapping behavior. These are meaningful traits that inform the agent about expected side effects and failure modes. It does not contradict the annotations; it complements them with specifics.

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

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

The description is three sentences with no filler. The primary action is front-loaded, and every sentence adds information: the creation action, font handling, and width behavior. It is concise and structured effectively for quick comprehension.

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 somewhat complex tool with 10 parameters and no output schema, the description covers the key behaviors: creation, font loading and substitution refusal, and width semantics. It omits details like parent handling, color, or position, but these are reasonably inferred from the schema. Given the annotations already cover the destructive nature, the description is sufficiently complete for an agent to call the tool correctly in most cases.

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 70%, so some parameters lack descriptions. The description adds context for the width parameter (wrap vs. hugging text) which is already in the schema's width description, and it mentions font behavior that relates to fontFamily but is more behavioral than parameter-specific. It does not clarify the undocumented parameters (e.g., fontSize) or add syntax details. The added value is modest, so a baseline of 3 is appropriate given the 70% coverage.

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

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

The description clearly states the tool creates a TEXT layer with given words, using specific verb 'Creates' and resource 'TEXT layer'. It differentiates from sibling creation tools (rectangle, ellipse, svg) by specifying text, and from editing tools like set_text by the creation action. The text is explicit that it adds a new text 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?

The description does not explicitly state when to use this tool versus alternatives like figma_set_text or figma_set_text_style. It implies creation of a new text layer, but offers no guidance on when not to use it or conditions that select this tool over siblings. The behavioral notes about font availability are more akin to constraints than usage guidance, so the tool falls short on this dimension.

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 and destructiveHint=true, covering the destructive nature. The description adds valuable behavioral context beyond annotations by disclosing that the operation is one undo step (reversible by a single Cmd-Z) and includes a caution to communicate the deletion. This exceeds what annotations alone provide.

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

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

The description is extremely concise, with the core operation front-loaded in the first clause and a brief, useful caution appended. No wasted words; every phrase 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 single-parameter tool with annotations covering safety, the description is nearly complete. It discloses reversibility and a precaution. The only missing element is behavior on invalid/nonexistent node IDs, but that is a common expectation and not critical for correct invocation. No output schema exists, but a delete operation typically returns success/void, so the absence is acceptable.

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

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

The schema description coverage is 100% (nodeId has a description: 'The node to delete.'), so the description adds no additional parameter semantics beyond reinforcing that the node is targeted. Per the baseline for high schema coverage, this is a 3.

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 clear, specific verb ('Removes') and resource ('a node'), and explicitly includes the scope ('everything inside it'). This distinguishes it from siblings like figma_move_node or figma_clone_node without ambiguity.

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 does not provide explicit when-to-use or when-not-to-use guidance, nor does it name alternative tools. However, the operation is self-evident as a deletion, so the lack of routing is a minor gap. It does caution to 'say what you are deleting before you do it,' which implies a usage context but does not elaborate on alternatives.

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

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

Annotations already establish readOnlyHint=true and destructiveHint=false, and the description adds a meaningful guarantee beyond that: 'Nothing is stored anywhere.' It doesn't discuss output format details, but the returned picture behavior is stated directly and no annotation contradiction exists.

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 short sentences with no filler. The core rendering behavior is front-loaded, and the second sentence adds a distinct privacy/durability signal rather than repeating the annotations.

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

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

For a simple two-parameter, read-only tool with a documented result ('returns the picture itself'), the description, schema, and annotations together cover everything an agent needs. No output schema exists, but the essential return semantics are stated explicitly.

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 nodeId and scale are already documented in the schema. The description adds nothing about how scale behaves or what nodeId refers to, but it also doesn't have to compensate for missing schema information.

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 action ('Renders one node') and a concrete result ('returns the picture itself'), so an agent knows exactly what the tool produces. It doesn't explicitly name a sibling tool or contrast with one, but the 'rather than read a description' phrase hints at the alternative.

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 intended context is implied: use this when a 'model that can see' needs to inspect the visual design instead of a textual description. However, there is no explicit guidance on when to prefer this over siblings like figma_extract or figma_get_tree, and no exclusion conditions.

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

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

The annotations already mark the tool as read-only and non-destructive, and the description adds substantial behavioral context beyond that: images are inlined, icons are real SVG, batches are capped at 20, failures are isolated per entry, and there is no base64 in the response. This gives the agent a reliable model of how the tool behaves.

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

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

The description is front-loaded with the core purpose and then moves into batch behavior and alternatives. It is longer than minimal, but nearly every sentence carries a distinct fact; only a small amount of redundancy exists between the formats discussion and the later png note.

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

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

For a read-only tool with 11 optional parameters and no output schema, the description provides the essential operational details: output formats, batch result shape, per-entry error handling, the 20-entry limit, and where to route image requests. Nothing an agent needs to choose or invoke this 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 schema already documents all 11 parameters at 100% coverage, so the baseline is 3. The description adds meaningful behavior around those parameters, especially the {results:[…]} contract, the 20-entry cap, and the image/export distinction. It does not walk through every parameter, but it does not need to given the schema's completeness.

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

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

The description names a specific verb and resource: it extracts a Figma node into HTML, figmaCss, React, and CSS variants. It even frames itself as 'the tool that answers what does this design actually say,' making its role unmistakable against siblings like figma_export_png or figma_get_tree.

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

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

It explicitly explains the batch input modes (nodeIds, urls, selection, saved) and when to prefer alternatives: 'ask figma_export_png for a picture, a node at a time.' It also clarifies that batches never return images, giving the agent a clear routing 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?

Beyond the readOnlyHint and destructiveHint annotations, the description explains that filters are optional and narrow together, that searches target the current page unless overridden, that allPages is slower and includes page names in results, and that text implies TEXT. It even notes cost characteristics relative to other tools. This is rich behavioral context well beyond the annotations.

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

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

The description is compact but information-dense: three sentences cover purpose, filter behavior, efficiency, scope options, and cost trade-offs. Every sentence earns its place, and the most important facts are front-loaded in the first sentence.

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

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

For a read-only search tool with zero required parameters and a fully described schema, the description covers everything needed to invoke it correctly: scope, filter semantics, and performance trade-offs. It does not document the exact return fields, but there is no output schema and the description gives enough about rows and page names to make the behavior expectable.

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 input schema already documents all six parameters with complete descriptions, including defaults, constraints, and implications such as 'Implies TEXT' for text. The tool description does not add meaningful parameter semantics beyond what the schema provides, so the baseline of 3 is appropriate.

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

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

States a specific verb and resource: it finds layers by type, name, or contained text. It also explicitly distinguishes itself from tree/children navigation tools, which search layer hierarchies instead of filtering across a scope. The behavior is unambiguous and easy to tell apart from siblings.

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 explicitly contrasts this tool with figma_get_tree and figma_get_children, explaining that this is the cheaper single-call option. It also clarifies scope behavior: current page by default, a specific branch with nodeId, or the whole file with allPages. This gives an agent clear when-to-use conditions and alternatives.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds the useful 'direct children' and 'cheap' performance context, but does not describe recursion behavior with depth, response format, or other runtime traits beyond the schema.

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

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

Two short sentences with no wasted words; the core action and scope are front-loaded, and the guidance about cheap traversal is packed into the second sentence.

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

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

For a read-only, simple listing operation with fully documented parameters and a readOnlyHint annotation, this description is nearly sufficient. It does not explain return shape, but the tool's purpose is simple enough that 'direct children' plus the schema gives an agent what it needs.

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

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

Schema description coverage is 100%, and both nodeId and depth are already documented there. The description's 'by id' and 'direct children' wording adds slight clarification but does not significantly extend the schema's parameter semantics.

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: 'direct children of one node, by id.' The phrase 'the cheap way to explore a page a branch at a time' also distinguishes it from tree-wide navigation tools like figma_get_tree.

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

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

The description gives clear usage context — use this to traverse a page incrementally branch by branch — and implies it is cheaper than fetching a full tree. It does not explicitly name alternatives or exclusion conditions, so it falls short of a 5.

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

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

Annotations already provide readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds that the tool reads live selection state and returns specific attributes, but it does not mention edge cases such as an empty selection or whether an active document is required.

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 short sentences: the first front-loads what the tool returns, the second gives usage guidance. Every word earns its place and nothing is repeated from the schema.

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

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

For a zero-parameter read-only getter, the description adequately covers what is returned and when to use it. The lack of an output schema means the exact response envelope is unspecified, but the key attributes are listed and this is a minor gap.

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

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

The tool has zero parameters and the schema already reflects this with an empty object and 100% coverage. The description reinforces that no input is needed beyond the current Figma context, which is appropriate.

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

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

States a specific verb and resource: it returns the currently selected layers with their ids, names, types, and sizes. This distinguishes it clearly from sibling tools like figma_select and figma_get_tree.

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

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

Explicitly says when to use it: 'Start here when the request says "this", "the selected frame", or names nothing at all.' This gives clear contextual guidance, though it does not name specific alternative tools or exclusion cases.

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 (readOnlyHint=true, destructiveHint=false). The description adds genuine behavioral context beyond that: it discloses that the operation walks the layer tree from the page down, that depth is the mechanism, and that a deep page yields thousands of rows — a scale warning an agent needs before calling. It stops short of describing the return structure, so it doesn't reach 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?

Two sentences with zero waste. The core purpose is front-loaded first, and the depth caveat plus sibling routing come second. Every clause earns its place; no redundancy with the schema or annotations.

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

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

Complete enough for a single-parameter, read-only navigation tool. The only gap is that the return format of the layers (node IDs, names, types) isn't described, and there's no output schema to fill that in. But for walking a layer tree, the missing structure detail is minor against a strong purpose, usage, and scale warning.

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 depth parameter is already well documented ('How many levels to walk. Default 1.'). The description adds minor value by contextually framing depth as walking down and tying it to the row-volume trade-off, but the schema already does most of the work, so the baseline 3 is appropriate.

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

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

States a specific verb and resource ('The top-level layers of the page the designer is looking at') with a clear scope tied to the current page. Explicitly names the sibling it is not — 'prefer figma_get_children on one branch' — so an agent can distinguish it from the closest alternative 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 an explicit alternative (figma_get_children) and the condition that selects it (walking down one branch vs. the whole page). Also warns about the cost of increasing depth ('a deep page is thousands of rows'), which directly informs the agent's decision to stay shallow or switch 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?

The description adds meaningful behavioral detail beyond the annotations: grouping places the new group inside the first node's parent, and ungrouping returns the released children. Since destructiveHint=true already flags mutation, this additional placement and return behavior is valuable and non-contradictory.

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

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

The description is compact, front-loads the core operations, uses a clear 'group — ... / ungroup — ...' structure, and ends with a useful routing guideline. Every sentence contributes meaning without repetition or filler.

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

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

For a two-action mutation tool with four parameters and no output schema, the description covers the main behavior, placement, and the main alternative. Ungroup's return behavior is stated. Minor gaps remain, such as what group returns and edge-case constraints, but these are not critical 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 coverage is 100% and each parameter has a clear description (name for group, action for which operation, nodeId for ungroup, nodeIds for group with a max of 20). The main description adds only the parent-placement nuance already reflected in the schema, so it does not need to compensate further.

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 precisely defines both supported actions: group puts nodeIds into a new group inside the first node's parent, and ungroup dissolves a group or frame and returns its children. It clearly distinguishes this dual-purpose tool from sibling creation tools like figma_create_frame.

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 states when grouping is the right choice ('several layers are one thing but need no layout of their own') and names the alternative figma_create_frame with auto layout when layout is needed. This gives an agent a clear decision rule between 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 indicate destructiveHint=true and readOnlyHint=false. The description adds context beyond annotations: the reason for base64 (network constraints), the 700KB cap, and the behavior of becoming the fill of a node (implying replacement). It does not contradict annotations and provides useful operational constraints.

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

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

The description is well-structured and economical: a single opening sentence states the core behavior, followed by a short paragraph explaining modes and constraints. No redundant fluff, and the key limitation is front-loaded.

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

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

For a tool with 9 parameters and no output schema, the description covers the essential behavioral choices (modes, size semantics, network limitation, cap). Parameters are sufficiently documented in the schema, and the description fills gaps not covered elsewhere. It does not explain edge cases like invalid nodeId, but that's not required 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?

With 67% schema coverage, the description adds meaningful value: it explains the base64 vs URL rationale, the cap, and clarifies the two use modes (fill vs. new rectangle). It complements the schema descriptions for parameters like data, width/height, and nodeId by giving real-world context.

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 ('Places'), resource types (PNG, JPG, GIF), and the input format (base64). It also clearly differentiates the two operational modes (fill vs. new rectangle), which distinguishes it from siblings like figma_set_fill or figma_create_rectangle.

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 intended use case (e.g., placeholder images) and why base64 is used (network restrictions in the manifest). It gives clear context for when to use it, but does not explicitly name alternative tools or conditions for when not to use it, leaving some inference 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 declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds useful context about the ids being prerequisites for other tools, but it doesn't describe output shape, result size, or edge cases. No contradiction with 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?

Two sentences front-load the resource and outcome, then immediately give practical usage guidance. The examples and rationale earn their place 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 read-only tool with one optional parameter and full schema coverage, the description is complete: it says what the tool returns, why those ids matter, and when to call it. No output schema is needed for this simple listing use case.

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?

There is only one optional enum parameter and its schema description already documents 'Narrow the answer. Default all three.' The prose description adds no further parameter-level meaning, so the baseline 3 applies.

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

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

The description clearly names the resource: the file's components, styles, and variables, and states the outcome: returning the ids other tools need. It is specific and understandable, though it does not explicitly differentiate itself from siblings like figma_list_saved.

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 explicit when-to-use guidance: 'Read this before "make it match our button" or "use our brand colour"'. It explains why the ids matter, but it does not mention alternative tools or when not to use this tool.

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 and destructiveHint=false, so the safety profile is covered. The description adds useful context about the curated, folder-scoped nature of the data, but does not disclose what happens with an unspecified folder, the response shape, or whether the listing is a flat array or grouped structure. This is acceptable for a simple read-only list, but not richly transparent.

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

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

The description is two sentences with no filler, and the central concept—curated nodes by folder—is front-loaded. The second sentence adds practical guidance about why this tool is useful rather than redundant praise. 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 read-only tool with one optional parameter, an understood resource, and no output schema, the description gives enough conceptual orientation for an agent to invoke it correctly. It could be slightly more complete by stating the default folder behavior or the return shape, but the low complexity and annotation coverage keep this gap minor.

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 only parameter, folder, is fully described in the schema as 'Restrict to one folder', so schema coverage is 100%. The description's mention of 'by folder' reinforces the parameter's meaning but adds no syntax, value formats, or edge-case behavior beyond the schema. This matches the baseline for high schema coverage.

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

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

The description identifies the resource as 'the nodes the designer curated in the panel' and the operation as listing them 'by folder', which is specific and distinguishes it from broader page- or library-oriented tools. It does not use an explicit imperative like 'list', but the meaning is clear. Its sibling figma_list_library points to a different content type, so the curation focus provides enough differentiation.

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 'usually a better starting point than the whole page' gives an implied use case: prefer this when you want the designer-curated shortlist rather than everything. However, it does not name alternatives or state when not to use it, so the agent is left to infer routing from the sibling tool names rather than explicit guidance.

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

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

Beyond the destructiveHint annotation, the description adds concrete ordering semantics: index 0 means back of canvas/top of layer list, and omitting index appends last. It also reinforces the default parent behavior. No contradiction with 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?

Two compact sentences: the first states the purpose, the second clarifies the key index behavior. No filler or redundant restating of the tool name.

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 mutation with no output schema, the description covers core intent, the two operational modes, and the important index default. It could mention side effects of reparenting, but the destructiveHint annotation already signals risk.

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

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

The schema already documents all three parameters, so the baseline is 3. The description adds meaningful detail for 'index' by explaining layer order and default placement, which goes beyond the schema's simple 'Position among siblings'.

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 ('Moves') and resource ('a node') and clearly covers both reparenting and sibling reordering. This distinguishes it from nearby mutators like figma_delete_node or figma_clone_node without requiring the agent to infer intent.

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 concrete conditions for both use cases: moving into another parent or changing position among siblings, and explains the default when index is omitted. It does not explicitly name alternative tools or exclusions, but the context is clear enough for correct selection.

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

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

The description goes beyond annotations by disclosing that opening a page moves the designer's view, changes nothing in the file, has nothing to undo, and is not gated by the Edits switch. These are meaningful behavioral details that an agent cannot infer from readOnlyHint or destructiveHint alone.

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

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

The two actions are front-loaded in a compact, scannable format, and the second paragraph earns its place by explaining when and why the tool matters. No sentences are 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 two-action navigation tool, the description covers both operations, parameter selection, the side effect of moving the designer's view, and the relationship to sibling tools. There is no output schema, but list's return meaning is stated clearly enough for an agent to use the tool 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?

All three parameters are already fully documented in the input schema, so the baseline is 3. The description adds only a light restatement of the 'by pageId or by name' routing, which does not provide meaning beyond the 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 and resource for each action: list returns every page and the current one, open switches to a page by pageId or name. This makes it easy to distinguish from the sibling reading tools, which are all page- or node-focused.

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 explicitly says to call this before concluding something is missing, because every other reading tool only answers about the current page. It also contrasts open with figma_select and explains that it is not behind the Edits switch, giving clear when-to-use and when-not-to-use context.

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

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

With readOnlyHint=true and destructiveHint=false already provided, the description adds useful behavioral context: it handles one or more links, resolves them to nodes, and has no export side effect. This clarifies the operation beyond the bare annotation flags.

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 carries all needed information, opens with the action, and wastes no words. The exclusion clause 'without exporting anything' earns its place by preventing confusion with export tools.

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 one-parameter, read-only tool with strong annotations, the description is largely complete: it names the input, the transformation, and a key non-behavior. A small gap is that it does not describe the shape or granularity of the returned node information, and there is no output schema to fill that in.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning by specifying the input must be 'one or more Figma links' and that resolution yields named nodes. This goes beyond the schema's minimal 'Figma links to resolve.'

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 identifies a specific verb ('Turns'), a concrete resource ('Figma links'), and the expected outcome ('into the nodes they name'). It also distinguishes itself from export-related siblings by explicitly saying 'without exporting anything.'

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

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

The description implies the tool is for resolving links to node identity, and the phrase 'without exporting anything' hints that export tasks belong elsewhere. However, it does not explicitly state when to use this tool versus alternatives like figma_extract or figma_export_png.

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

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

The description discloses important non-obvious behavior beyond the annotations: changes live in plugin storage, are not behind the Edits switch, cannot be undone with Cmd-Z, and deleteFolder returns entries to root by default unless deleteEntries is true. This is rich, accurate behavioral context with no contradiction against 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?

The description is long but appropriately so for nine distinct actions. It front-loads the overall purpose, then uses a compact action-by-action list, and each sentence carries operational meaning. The closing rationale, while not strictly necessary, reinforces the intended use without bloating the definition.

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 multi-action tool with no output schema, this description is exceptionally complete: it covers every action, all parameter scoping rules, defaults, special cases, and persistence semantics. An agent has enough to call the tool correctly across all nine actions.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds action-level semantics that the schema alone does not fully convey: omitting nodeIds on save means current selection, "" means root, and deleteFolder's default non-destructive behavior. These details help an agent bind parameters correctly per action.

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

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

The description opens with a specific verb-resource pair: 'Read and change the designer’s shortlist of nodes in this file, and the folders it is grouped into.' It then enumerates all nine actions, making the scope unmistakable and distinguishing this curation tool from read-only siblings like figma_list_saved.

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

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

The description gives clear context for when this tool is appropriate: it manages a persistent bookmark list separate from the design, and the closing sentence provides a concrete use case. It does not explicitly name sibling alternatives or say when not to use it, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=true, so the agent knows this is a mutating operation. The description adds useful context about creating a restore point versus relying on undos, but it does not disclose what the destructive aspect might involve or what happens to existing version-history entries. This is adequate but not rich.

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

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

The description is two sentences with no wasted words. It front-loads the core action ('Saves a named point...') and then provides a practical usage rationale without repeating schema details or annotation information.

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

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

For a simple two-parameter write tool, the description covers the core purpose and when to use it. However, it leaves the 'description' parameter unexplained and does not mention return behavior. Since there is no output schema, these gaps make the definition minimally viable rather than complete.

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

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

Schema description coverage is only 50%. The 'title' parameter is explained in the schema as 'What this checkpoint is for,' but the 'description' parameter has no schema documentation and the tool description adds nothing about it. The description therefore fails to compensate for the undocumented parameter.

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

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

The description states a specific verb and resource: 'Saves a named point in the file’s version history.' This clearly differentiates the tool from siblings like figma_list_saved, figma_set_fill, or figma_delete_node, and the title 'Checkpoint the file' reinforces the intent.

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 explicit guidance on when to call it: 'before a run that will change several things...' and explains the benefit of a single fallback point. It does not mention when not to use it or name specific alternatives, but the context is clear enough to route an agent 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?

The description adds substantial behavioral context beyond the generic annotations: it changes no design data, works without Edits, leaves no undo step, and moves the viewport. It even warns the agent to narrate what it is showing the designer.

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 paragraphs with the core action front-loaded. Every clause earns its place: timing, side effects, and a caveat about moving the viewport are all useful and non-redundant.

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

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

For a side-effect-only viewport tool with no output schema, the description covers effect, timing, mutation safety, and the viewport caveat. The optionality of nodeId/nodeIds is clear enough from the schema and description.

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

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

The schema already fully describes both parameters: nodeId as one node and nodeIds as several nodes up to 20. The description adds no parameter-specific meaning beyond what the schema provides, so the baseline of 3 applies.

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

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

The first sentence states a specific verb ('Selects'), resource ('one or more layers'), and the canvas-scroll effect. This clearly distinguishes it from data-mutation and tree-walking siblings like figma_set_fill or figma_get_tree.

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 explicitly prescribes when to use it: before describing a tree-walked node and after an edit. It does not explicitly name alternatives or give when-not-to-use guidance, so it stops short of a 5.

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

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

Annotations already mark the operation as destructive/non-read-only, so the bar for behavioral disclosure is lower. The description adds a useful caveat—'Only the properties you name are changed'—which clarifies the partial-update behavior. It does not warn about potential side effects like layout recalculation or child position changes, but the destructiveHint annotation covers the main mutability signal.

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

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

The description is two concise sentences with no filler. The core action comes first, the NONE behavior is immediately stated, and the partial-update caveat is included without redundant 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?

The description covers the essential behavior and the NONE escape hatch, and the schema documents required and enum parameters. However, for a tool with 10 parameters and no output schema, it leaves important edge cases unaddressed, such as whether layout properties still apply when mode is NONE, and what happens if a non-frame node is targeted. The destructive semantics are present in annotations, not in the description.

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 60%, and the description adds a high-level framing by naming direction, spacing, padding, and alignment. This helps relate concepts like itemSpacing and the alignment enums, but it does not compensate for undocumented parameters such as paddingTop, paddingLeft, paddingRight, and paddingBottom. An agent still has to infer their exact meaning from context.

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

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

The description clearly identifies the resource ('a frame') and the specific action ('Turns auto layout on'), and enumerates the exact property categories affected: direction, spacing, padding, and alignment. This distinguishes it from sibling tools like figma_set_fill or figma_set_layout_sizing.

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

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

The description implies when to use the tool: whenever auto layout needs to be enabled, configured, or disabled on a frame. However, it does not explicitly mention when not to use it or name alternative tools that a user might consider, leaving the routing to the agent to infer.

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 indicate readOnlyHint=false and destructiveHint=true, so the description is not burdened with basic safety disclosure. It adds useful context about the auto-layout behavior, but does not elaborate on what destructive changes may occur, coordinate semantics, or the outcome when size parameters are omitted.

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 the core function front-loaded. The second sentence earns its place by providing a critical usage caveat and routing to the sibling tool. No filler or redundant restatement.

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

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

Covers the most important exclusions (auto-layout behavior) but leaves gaps for a 5-parameter tool with poor schema coverage: units, coordinate space, whether size is also ignored in auto-layout, and what 'sets' implies for existing bounds. The description is adequate for a simple case but not fully complete.

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

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

Schema description coverage is only 20%, with just nodeId documented. The description maps loosely to x/y/width/height by saying 'Sets position and size,' and adds one semantic constraint for x/y inside auto-layout, but it does not explain units, coordinate systems, optionality, or what happens when individual parameters are omitted.

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: 'Sets position and size.' The title 'Move or resize' is clarified, and the description distinguishes itself from figma_set_layout_sizing by explicitly naming that sibling tool in the auto-layout caveat.

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 states when not to rely on this tool: inside auto-layout frames, position is ignored. It also names the alternative approach (figma_set_layout_sizing and parent spacing), leaving no ambiguity about the correct tool selection.

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 destructiveHint=true and readOnlyHint=false, so the mutation profile is known without the description. The description does add useful behavioral context by distinguishing uniform versus per-corner application. However, it does not disclose what happens when both 'radius' and individual corner parameters are supplied, whether existing radii are overwritten, or what occurs when called with only nodeId and no radius values. The annotation coverage lowers the bar, making 3 appropriate.

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 13-word sentence that front-loads the verb and packs both operating modes into minimal space. Every word earns its place with no boilerplate or repetition of schema fields. It is efficiently structured, though additional edge-case detail could still have been added without hurting conciseness.

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 6-parameter mutation tool with 33% schema coverage and no output schema, the description is under-specified. It omits edge-case behavior (mixing uniform and per-corner radii), node-type applicability (which Figma nodes support corner radius), and the effect of invoking with only the required nodeId and no radius values. An agent could call it incorrectly without further information.

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 only 33% — nodeId and radius are described, while the four corner parameters have bare schema entries. The description partially compensates by mapping 'one radius for every corner' to the radius parameter and 'each corner on its own' to the four corner parameters, giving those undocumented params meaning. It does not clarify conflict resolution between uniform and per-corner inputs or units, so compensation is only 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 uses a specific verb ('Sets') with a clear resource (corner radius) and conveys the two operating modes: a single uniform value versus independent per-corner values. The title 'Round the corners' reinforces intent. It earns a 4 rather than 5 because sibling differentiation is implicit — no sibling is named — though no other sibling handles corner radius, so confusion risk is low.

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, exclusions, or alternatives are provided. The description implies rounding corners but never states prerequisites (e.g., the node must support corner radius) or when to prefer this over sibling set tools like figma_set_bounds or figma_set_effects. An agent gets no help choosing among the many figma_set_* siblings.

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 the description aligns by saying 'Replaces' (overwrites existing effects). It additionally discloses that an empty list clears all effects, which is not in the annotations. The description adds useful context (design-system meaning) without contradicting 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?

Three short, purposeful sentences. The main action is front-loaded, the edge case (empty list) is stated early, and the design-context note is a single salient sentence. No fluff or repetition of schema details.

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 setter with fully documented parameters, the description covers the core behavior, the clearing scenario, and the semantic intent. It doesn't mention multi-node behavior or side effects, but those aren't critical given the schema and annotations. Slight room to note that it replaces all existing effects on the node, though 'replaces' already implies that.

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% — both parameters and their nested properties are documented in the schema, including defaults and the order/clearing semantics for the effects array. The description adds no new parameter information beyond what the schema already provides, so the baseline score of 3 is appropriate.

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

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

The description opens with a specific verb ('Replaces') and a clear resource ('a node’s effects'), and it immediately explains the empty-list behavior. This distinguishes it from sibling tools like figma_set_fill or figma_set_stroke, which target different properties. The added design-systems hint ('what make it look raised means') reinforces the intent.

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 provides a clear trigger condition ('this is what

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?

Beyond the annotations (destructiveHint=true), the description discloses that the operation destroys all existing fills, that the response includes the read-back color so failed writes are detectable, and that one call maps to one undo step. This is rich behavioral detail well beyond the boolean annotation flags.

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

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

Three sentences, each earning its place: the core action, the read-back safety behavior, the destructive replacement warning, the stroke routing, and the undo granularity. It is front-loaded with the primary purpose and avoids redundancy with the schema.

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

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

Despite having no output schema, the description explains what the tool returns (the read-back color and what was replaced). It also covers the destructive nature, the undo behavior, and the boundary with strokes, making it complete for an agent to safely invoke this tool on a node with any fill type.

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 schema already fully documents nodeId, color, and opacity. The description adds context about the fill being solid and the replace-all behavior, but it does not add new meaning to the individual parameters beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description uses a specific verb ('Replaces') and a precise resource ('a node’s fills') with the outcome 'one solid colour'. It also distinguishes itself from the sibling figma_set_stroke by noting that borders are strokes, not fills, which removes ambiguity about what the tool operates on.

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

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

It explicitly states when not to use this tool: 'Borders are strokes, not fills: use figma_set_stroke for those.' It also warns about a key contextual consideration — the tool replaces every existing fill — which is exactly the kind of guidance that helps an agent decide whether this is the right tool for a gradient or photograph.

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 mark this as destructive, and the description adds useful behavioral details: it mutates the existing instance, tolerates keys missing their id suffix, and refuses invalid keys by returning the list of valid ones. No contradiction with annotations is present.

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 in the first paragraph carry the core behavior and validation rules, and the second paragraph gives a helpful analogy to create_instance. It is efficient and front-loaded, though the analogy could be trimmed without losing essential content.

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

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

For a mutating instance-property tool with only two params, the description covers what the tool changes, where to get valid keys, how key matching works, and how failure behaves. The nodeId omission behavior is handled in the schema, so nothing critical 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 schema already describes both parameters well, so a 3 is the baseline, but the description adds meaningful semantics: properties should use keys from figma_component_properties, variant values are option names, booleans are true/false, and text properties are strings. This enriches what the schema alone 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?

The description clearly states the tool sets an instance's variant, text properties, and boolean properties. It also distinguishes itself from placing a component (figma_create_instance), so an agent can tell exactly what this tool does beyond its name.

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

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

It explicitly instructs the agent to take keys from figma_component_properties, explains id-suffix matching behavior, and says what happens when a key matches nothing. It also names when to use this instead of figma_create_instance, making the usage boundary 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 mark this as destructive and not read-only. The description adds behavioral meaning by explaining what HUG, FILL, and FIXED do to the child. It does not elaborate on destructive side effects, but the annotations carry that responsibility, so the added semantics are sufficient.

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 deliver the core concept, define all enum values, and provide a routing rule away from a sibling tool. Every sentence earns its place and the key guidance is front-loaded.

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 focused mutator with few parameters and no output schema, the description gives the enum semantics, the relevant context (auto-layout frame), and sibling disambiguation. It could add a note about prerequisites, but the essential information for correct invocation is present.

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 only 33%, but the description meaningfully defines the three enum values shared by the vertical and horizontal parameters. NodeId is already well described in the schema, and the parameter names make the axis association clear.

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 title and description clearly identify the tool as controlling child sizing behavior inside auto-layout frames, distinguishing HUG, FILL, and FIXED. It also explicitly differentiates itself from figma_set_bounds, making the tool's purpose and scope immediately understandable.

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 explicitly states that this tool, not figma_set_bounds, is the correct way to set widths inside auto layout. This directly gives the agent a when-to-use and when-not-to-use signal with a named alternative.

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 mark this as readOnly=false and destructiveHint=true, so the description does not need to restate the mutation. It adds value by explaining the consequence: renaming affects generated code class names, making it a real change rather than cosmetic. No contradiction with annotations, but no further behavioral detail such as undo, required permissions, or effects on references.

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

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

The description is two short sentences with no filler. The core action is front-loaded, and the second sentence adds important context without 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 two-parameter rename tool, the description plus schema and annotations cover the essential facts: what it does, the key consequence, mutability, and parameter meaning. No output schema is needed for a rename operation. Could be slightly more complete with explicit mention of scope or return behavior, but it is largely sufficient.

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

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

The schema documents nodeId, including an example and the fallback to the current selection. 'name' is left without schema description, but the tool description gives it meaning by explaining that names become class names in generated code. This partially compensates for the 50% schema coverage, though no format, length, or uniqueness constraints are mentioned.

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

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

The description clearly states the action ('Renames a layer') and the target resource, matching the title. It adds meaningful context by explaining that layer names map to generated code class names, which clarifies why the tool exists. However, it does not explicitly distinguish this from siblings, though no direct rename sibling exists.

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 guidance is provided about when to use this tool versus alternatives or when to avoid it. The note about generated code is a rationale for why the change matters, not a usage condition. An agent is left to infer the appropriate context solely from the name and title.

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 signal mutability and destructiveness, and the description adds useful behavioral detail: replacing all existing strokes rather than appending, and removing the stroke entirely with remove: true. This goes beyond the annotations without contradicting them.

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

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

Three sentences with no filler: the main behavior, the removal mode, and the key alternative are each front-loaded and useful. 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?

The description is nearly complete for a 5-parameter mutation tool with rich schema coverage. It covers the primary behavior, the remove variant, and the fill-vs-stroke distinction. It doesn't describe return values or side effects on unmentioned stroke properties, but those are minor given the schema and annotations.

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

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

Schema description coverage is 100%, so the schema already documents color, nodeId, remove, weight, and opacity. The description adds conceptual meaning around stroke-as-outline and the role of remove, but doesn't substantially extend parameter-level semantics beyond the 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 and resource: 'Replaces a node’s strokes with one solid colour'. It also explicitly distinguishes strokes from fills and from figma_set_fill, so an agent can tell this tool apart from the closest sibling.

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 direct when-to-use guidance: 'a row outline or an icon drawn as an outline needs this rather than figma_set_fill'. It also explains the remove: true case for clearing strokes, giving clear conditions for both configuration modes.

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 indicate this is a destructive write operation. The description adds meaningful non-obvious behavior: the font is loaded first, and missing fonts cause a refusal rather than silent substitution. This gives the agent important expectations about failure modes beyond what annotations provide.

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 with no filler. The first sentence states the core purpose, and the second adds the critical font-loading behavior. 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 two-parameter mutation tool with rich annotations and full schema coverage, the description adequately covers the operation and a key edge case. It does not describe return values or explicit error behavior beyond missing fonts, but those are not essential for correct invocation of this simple tool.

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

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

Schema description coverage is 100%, so the input schema already documents both nodeId and text clearly. The description adds no additional parameter-specific meaning beyond restating that text is 'new characters' and nodeId is the 'TEXT node to retype,' which is already covered by the 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 ('Replaces'), a specific resource ('the text of one TEXT node'), and clearly distinguishes this from sibling text-related tools like figma_create_text or figma_set_text_style. It is immediately obvious what the tool 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?

The intended use is implied: use this tool to change the text content of an existing text layer. However, there is no explicit guidance on when to prefer this over alternatives such as figma_create_text or figma_set_text_style, and no mention of constraints like requiring a selected node or a text layer.

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

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

The destructiveHint annotation already signals mutation, and the description adds meaningful behavioral context by clarifying that only named properties are overwritten and others are preserved. It doesn't describe reversibility or what exactly gets destroyed, but the partial-update disclosure is valuable beyond the annotation.

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

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

Three sentences with no filler: the first gives scope, the second defines update semantics, and the third supplies routing rationale. The most important caveat ('Only what you name is changed') is front-loaded right after the scope.

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 no output schema, the description covers what to change and when to prefer an alternative. Minor gaps remain: it doesn't describe return behavior, failure modes, or the autoResize parameter, but the schema compensates for the parameter details and the annotations cover the destructive nature.

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 56%, so the schema carries some parameter descriptions. The description adds value by grouping the parameters into readable categories (font, size, line height, etc.) and by explaining that each named parameter is applied independently. It does not mention autoResize, leaving one parameter semantically under-covered.

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 exact operation (set type on a text layer) and enumerates the specific attributes it affects: font, size, line height, letter spacing, alignment and colour. It also differentiates itself from the most confusable sibling, figma_apply_style, by framing hard-coded values as a fallback rather than a substitute for named styles.

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 last sentence gives explicit routing: prefer figma_apply_style when a text style exists, with a concrete reason (a named style survives redesigns). The phrase 'Only what you name is changed' also tells the agent this is a targeted partial update, not a full style reset.

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?

Beyond the annotations (readOnlyHint=false, destructiveHint=true), the description adds the important behavioral detail that hidden layers are skipped by extraction. This helps an agent understand a non-obvious side effect. It does not contradict the destructive hint, though it could say more about the consequences of locking or changing opacity.

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

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

The description is two short sentences with no wasted words. The core action is first, and the extra behavioral context is front-loaded and directly useful. 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 simple setter tool, the description plus annotations cover the basics: what it does, that it can be destructive, and why hiding matters. However, with three undocumented parameters and no output schema, more detail about parameter behavior and interaction would make the tool fully self-contained for an agent.

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 only 25% (only nodeId is documented). The description merely lists 'opacity, visibility and lock' without explaining their semantics, interactions, or defaults. With low coverage, the description should compensate, but it does not meaningfully clarify the parameter meanings beyond their names.

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

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

The description clearly states the exact operation: 'Sets opacity, visibility and lock.' The title reinforces the same intent with 'Hide, lock or fade a layer,' which makes the tool's purpose immediately obvious and distinguishes it from sibling setter tools like figma_set_fill or figma_set_stroke.

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 concrete use case: hiding layers so extraction skips them ('which is often the point'). However, it does not explicitly say when to use this tool over alternatives, nor does it mention when not to use it. The guidance is implied rather than explicit.

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