figma-unlimited-mcp

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

No annotations are provided, so the description carries the full burden. It states 'Set absolute position, size, or parent container' which implies mutation, but it does not disclose potential side effects like overwriting existing values, behavior on reparenting child nodes, or failure conditions.

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 fluff. First sentence states the function, second gives practical scenarios. It's front-loaded and easy to scan.

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

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

Given the tool's complexity (array of up to 300 items with multiple properties), no annotations, and no output schema, this description is not complete. It covers high-level purpose but lacks behavioral details and parameter semantics needed for safe invocation.

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

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

Schema description coverage is 0%, so the description must compensate. It mentions 'absolute position, size, or parent container' but does not clarify coordinate units, default behavior, or the meaning of parentId values beyond what the schema already says (which itself only explains nodeId and parentId).

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 that the tool sets absolute position, size, or parent container for existing nodes, naming specific capabilities and resource. It distinguishes from sibling tools like create_shapes, delete_nodes, and even update_nodes by focusing on layout operations.

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 provides explicit use cases: tidying a board after content generation and moving nodes into a section. It doesn't explicitly mention alternatives or when not to use it, but the context is clear enough for an 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?

There are no annotations, so the description must disclose side effects or limitations. It only states 'Add' and 'syntax-highlighted' – it does not mention that items are added near viewport by default, that up to 100 items are allowed, or how invalid languages are handled (though some of this is in the schema). This is a narrow behavioral disclosure.

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

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

The description is a single tight sentence that front-loads the action and adds a use case. No fluff or 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?

With no annotations and no output schema, the description leaves important invocation context (item limits, default placement, language fallback) unexplained. Although the schema provides these details, the description does not help the agent decide when to use this vs alternatives beyond a generic 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?

Schema description coverage is 0%. The tool description gives no direct parameter information – it doesn't mention the 'items' array, 'code', 'language', 'x/y' positioning, or 'parentId'. It only implies 'code' and 'syntax' via the phrase 'syntax-highlighted code blocks'. The schema itself is rich, but the description fails to compensate for the low 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 opens with 'Add syntax-highlighted code blocks' – a specific verb and resource. It differentiates from sibling create_texts by specifying syntax highlighting and use case (snippet/schema/config).

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 sentence 'Useful for putting a snippet, schema or config next to the diagram that explains it' provides a clear context for when to use the tool. It does not explicitly mention alternatives or exclusions, but the use case is a sufficient guideline for an 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?

No annotations are provided, so the description carries the burden. It discloses the key behavioral constraint that both endpoints must reference existing nodes, but does not mention potential errors, side effects, or return behavior, leaving some ambiguity.

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, front-loading the core action and immediately providing the key constraint. Every word adds value with no redundancy.

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

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

The description is sufficient for a simple creation tool: it states what it does, the prerequisite, and the sequencing. It does not explain return values or the configurable options, but those are covered by the schema.

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

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

The schema has 0% coverage for the top-level 'items' parameter, but the description partially compensates by implying that connectors have endpoints (from/to) and that these must be existing node ids. It does not describe the array structure or optional properties, which the schema itself documents.

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

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

The description states the tool draws connectors between existing nodes, specifying both the action ('Draw connectors') and the resource ('nodes'), clearly distinguishing it from sibling tools that create shapes or stickies. It also adds a key constraint ('both endpoints must be ids of nodes that already exist') that clarifies its scope.

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 clear usage context by stating the prerequisite that endpoints must be existing node ids and advising to 'create the shapes first, then connect them.' While it doesn't name alternative tools, it explicitly conveys when to use the tool (after node creation) and implies when not to use it.

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

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

With no annotations, the description carries the full burden. It discloses key behavioral traits: creates ~200 nodes in under a second, tags everything it creates, touches nothing else on the board, and supports a clean mode to remove previous runs. This is substantial behavioral information, though it stops short of specifying return values or edge cases like repeated builds without clean.

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

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

The description is concise and well-structured. The first sentence front-loads the purpose, the middle lists contents, and the second paragraph covers usage and cleanup. Every sentence adds value with no redundancy or fluff.

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

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

Given the tool's complexity (composite board with ~200 nodes), the description is thorough: it covers what gets created, the performance, use cases, cleanup, and safety. No output schema exists, but the description does not need to explain return values as this is a build/clean operation rather than a query.

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% for the single mode parameter. The description adds semantic value by explaining what 'clean' does: "Pass mode 'clean' to remove it again." It also implies the default 'build' behavior. This enriches the schema's enum/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 and resource: "Build a complete architecture review board in one call." It enumerates the board's contents (system architecture diagram, request lifecycle, etc.) and explicitly distinguishes this from sibling tools that create individual elements by highlighting the composite nature and ~200 nodes.

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

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

The description gives clear usage context: "Use it to show what this server can do, or to check that a fresh install actually works." It also explains the cleanup mode with "Pass mode 'clean' to remove it again." It does not explicitly exclude alternatives, but the demo/smoke-test purpose is clear from 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 no annotations, the description carries the burden. It discloses key behaviors: automatic layered layout, wiring nodes with connectors, and referencing nodes by `key` strings. It also mentions the one-call nature and the overlap-avoidance benefit, adding context 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?

The description is two short paragraphs, front-loaded with the core purpose in the first sentence. Each sentence adds value: the first explains the build process and benefit, the second clarifies key referencing. No redundant text.

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

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

For a tool with 9 parameters and no output schema, the description covers the high-level behavior (layout, connectors, keys) and usage context (multi-node diagrams). It doesn't mention edge cases like unknown keys (schema does) or return values, but the schema is rich and the description is sufficient for an agent to select and invoke the 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 89%, so the baseline is 3. The description reinforces the `key` contract ('Refer to nodes by your own key strings; edges use those same keys') but adds no detailed parameter semantics beyond what the schema already documents. The layout parameters are not explained in the description, but the schema handles that.

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+resource: 'Build a complete flowchart or graph in one call.' It clearly distinguishes from siblings by positioning as 'the preferred tool for any multi-node diagram' and contrasting with hand-placing nodes, unlike create_shapes or create_connectors.

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 to use: 'preferred tool for any multi-node diagram' and explains the benefit: 'avoids the overlapping shapes you get from placing nodes by hand.' It doesn't name alternative tools explicitly for single-node cases, but the guidance for multi-node diagrams is clear.

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

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

Annotations are absent, so the description carries the burden of disclosing behavior. It states the tool adds sections and implies they are visual containers via the swimlane analogy, but it does not mention limits (e.g., maxItems 50), permissions, or side effects. The description adds some context beyond the name but lacks depth.

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, actionable, and free of redundancy. The description front-loads the core purpose and then adds a critical cross-tool usage note, earning its place entirely.

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

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

Given one parameter (nested object) and no output schema, the description gives a high-level picture and a usage tip, but it omits any guidance about the 'items' parameter structure. The schema's nested descriptions partially fill this gap, but the top-level parameter remains unexplained, leaving a moderate completeness 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 description does not mention any parameters. The input schema has nested descriptions for the section properties, but the top-level 'items' parameter itself lacks a description, and the tool description does nothing to clarify its structure. With schema description coverage reported as 0%, the description was expected to compensate 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 clearly states the tool creates 'named sections' and provides a helpful analogy ('FigJam equivalent of a labelled swimlane or column'). It distinguishes this tool from siblings like create_stickies or create_shapes by focusing on sections as a distinct container-like resource.

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 how to use the tool in conjunction with other create tools ('Pass a section id as parentId on other create tools to place content inside it'). This conveys both the purpose and a key usage pattern, though it does not explicitly mention when to avoid using this tool or name alternative 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?

With no annotations, the description must carry the burden of behavioral disclosure. It states the core behavior (adds shapes with text labels) and its contextual role, but does not mention permissions, side effects, or return values. Since it is a creation tool, the add-only behavior is somewhat implicit, but richer context would improve transparency.

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

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

The description is two sentences, front-loaded with the action, and includes a clear distinction from a sibling tool without redundancy. Every sentence adds value, making it highly concise and well-structured.

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 effectively conveys purpose and usage, and the rich input schema fills in parameter details. However, with no output schema and no annotations, the description omits what the tool returns after creation and does not mention constraints like the 200-item maximum or coordinate behavior. This leaves gaps for an agent trying to fully predict tool behavior.

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 description contains no explanation of the 'items' parameter or its structure, even though schema description coverage is 0% at the top level. Although the nested schema has detailed descriptions for each field, the description does not compensate for the low coverage, leaving the agent to infer the array-of-shapes structure solely from 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 clearly states the tool's action ('Add FigJam shapes that carry a text label') and resource, and differentiates it from the sibling create_diagram by specifying that create_diagram lays out and connects shapes. This makes the purpose unambiguous and distinguishes from alternatives.

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

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

The description explicitly recommends using create_diagram for whole diagrams, providing a clear when-not-to-use scenario and an alternative. While it implies using this tool for individual labeled shapes, it does not explicitly enumerate all when-to-use cases beyond the building-block 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 no annotations, the description carries the full burden of behavioral disclosure. It states the tool 'adds' stickies and describes their nature, but it doesn't disclose important behaviors such as defaults (position, color, wide variant), effects on existing elements, or whether the operation is append-only. It also fails to mention any side effects, permissions, or return behavior.

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: a clear action statement followed by context for tool selection. It is front-loaded with the verb and resource, and every sentence earns its place. No filler or 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?

The description gives a strong sense of purpose and tool applicability, but it lacks completeness for a creation tool with nested parameters and no output schema. It doesn't explain defaults (position, color), constraints (maxItems), or what happens to existing content. The schema covers param details, but behavioral and output context 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 description mentions no parameters, and the schema description coverage is 0%. The schema itself provides rich descriptions for each property (x, y, text, wide, color, parentId), but the description adds no additional meaning or context. Since coverage is low, the description should compensate, but it 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 clearly states the tool's function: 'Add one or more sticky notes.' It uses a specific verb ('Add') and resource ('sticky notes'). It also differentiates from sibling tools like create_texts by noting that stickies are the native FigJam unit for ideas, votes, and retro items and should be preferred over text nodes for draggable content.

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 clear usage context: 'prefer them over text nodes for anything a human might want to drag around.' This explicitly guides the agent when to choose this tool over an alternative (create_texts). It doesn't list exclusions, but the guidance is actionable and sufficient for most 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?

With no annotations provided, the description carries the full burden. It discloses the cell format and header behavior, which is useful, but does not mention side effects, permissions, or whether the operation is reversible. It also fails to note the array-wrapped input structure, which is a key behavioral aspect.

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

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

The description is concise, with two sentences, and front-loads the core purpose. It includes essential cell formatting instructions without unnecessary verbosity. Every sentence adds 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 schema has decent nested descriptions, but the description misses the critical fact that the input is an array of table objects (`items`), not a direct `cells` array. It also omits any mention of return value or behavior for multiple items. Given the lack of annotations and output schema, the description is insufficient for complete understanding and 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 description says to pass `cells`, but the actual top-level parameter is `items`, an array of objects. It fails to explain this nested structure, potentially leading to incorrect invocation. While the schema offers some documentation for x, y, cells, and parentId, the description adds little beyond the header row note and may even mislead about the required input shape.

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 'Add a FigJam table and fill its cells,' using a specific verb and resource. It distinguishes itself from sibling tools like create_shapes or create_stickies by focusing on tables. The additional detail about cell structure reinforces the purpose.

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

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

The description implies usage for adding tables but does not explicitly state when to use this tool versus alternatives. It lacks exclusions or alternative tool suggestions, providing only implicit context that this is for tables.

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

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

With no annotations, the description must carry the behavioral disclosure burden. It only states the primary action and typical use cases, but does not mention return values, permissions, side effects, or error behavior. The 'free-floating' hint is useful but insufficient for a creation tool.

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

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

Two concise, front-loaded sentences. The action is stated first, followed by guidance and a distinguishing alternative. No wasted words.

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

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

For a simple creation tool with a rich input schema, the description is mostly complete on purpose and usage, but it omits return value behavior and failure/side-effect details. Since no output schema is provided, the description could have explained what the API returns on success.

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?

Description has 0% parameter coverage. While the input schema contains detailed property descriptions, the tool description itself adds no parameter semantics, so it fails to compensate for the low coverage as required.

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 ('Add') and resource ('free-floating text') and immediately distinguishes from stickies by naming use cases (board titles, column headers, annotations). This clearly sets it apart from sibling tools like create_stickies.

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 to use this tool ('Good for board titles, column headers and annotations') and provides an alternative ('use stickies for content the user will rearrange'). This gives clear when-to-use and when-not-to-use 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 crucial behavioral context: the deletion is irreversible ('cannot undo it from your side') and requires user confirmation for non-session-created content. This tells the agent about the impact and safety protocol, which is exactly the kind of context that helps avoid harmful actions.

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: the first states the action and permanence, the second conveys the destructive consequence and confirmation requirement. Every word earns its place, with 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 single-parameter destructive tool with no output schema, the description covers all necessary aspects: what it does, the irreversible nature, and the required confirmation step. The schema handles the nodeIds format and source, while the description provides the behavioral guardrails. Combined, they form a complete picture.

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 description does not mention the nodeIds parameter at all, and schema description coverage is 0% at the property level. Although the items schema includes a useful example and source hint, the tool description itself fails to compensate for the low schema coverage, leaving the agent without parameter guidance in the 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 opens with 'Permanently remove nodes from the board', which uses a specific verb ('remove') and resource ('nodes'), clearly distinguishing it from siblings like update_nodes or create_diagram. The title and description are consistent, leaving no ambiguity about the tool's function.

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 clear context for when to use this tool (permanent removal) and includes an important usage guideline: confirm with the user before deleting anything not created in the session. It does not explicitly name alternatives or when-not-to-use scenarios, but the destructive nature and confirmation requirement offer practical 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?

The readOnlyHint annotation already establishes the operation is non-mutating. The description adds the practical purpose (visual self-check) but doesn't disclose other behavioral details like output format, size limits, or performance implications. Since annotations cover safety, a 3 is 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?

Two sentences, front-loaded with purpose and usage guidance. No filler or redundant repetition of schema information. 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 read-only rendering tool with no output schema and all-optional params, the description covers the essential use case and outcome. It doesn't specify return format (e.g., URL vs binary), but 'return it as an image' is sufficient given the tool's simplicity and optional params.

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% with clear descriptions for all three parameters (scale, nodeIds, maxDimension). The description adds a small amount of context by mentioning page/selection/nodes, which maps to nodeIds, but doesn't significantly augment the schema's already thorough parameter documentation. Baseline 3 is warranted.

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 function: 'Render the page, a selection, or specific nodes to a PNG and return it as an image.' It names the exact resource (page/selection/nodes) and output (PNG image), distinguishing it from sibling tools like create_diagram or list_nodes.

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

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

Provides explicit usage context: 'This is how you visually check your own work — look at the result and fix layout problems before telling the user you are done.' It implies when to use (before finishing a task) but doesn't list alternatives or when not to use it, 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?

Beyond the readOnlyHint annotation, the description adds that matching is case-insensitive and limited to the current page, which is valuable context. It also notes the cost advantage. 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-loaded with the primary action and followed by a cost-benefit note. Every word contributes, with no redundancy or filler.

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

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

For a straightforward read-only search tool, the description covers purpose, scope, and use-case context. Without an output schema, a note on return format or pagination would improve completeness, but it's not critical given the low complexity.

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

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

The schema describes query and types but not limit. The description adds that query is a case-insensitive substring match on text or name, which helps clarify the query parameter's meaning. However, the limit and types behavior are not addressed, and schema coverage is only 67%.

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 searches the current page for nodes by text or name substring, case-insensitively. It uses a specific verb ('Search') and resource ('nodes'), and the 'Cheaper than listing a large board' note distinguishes it from list_nodes.

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

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

It explicitly frames this as a cost-effective alternative to listing a large board, giving clear context for when to use it. While it doesn't name sibling tools directly, the reference to listing is an implicit alternative, so guidance is present.

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

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

No annotations are provided, so the description carries full responsibility for behavioral disclosure. It states the core behavior (scroll/zoom) and mentions that selection is optional, which implies selection only changes when select=true. However, it does not describe the return value or explicitly note that the operation is non-destructive, which could be relevant for agents deciding to call it.

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

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

The description is two sentences long, with no wasted words. The first sentence defines the action and scope, the second gives timing guidance. It is front-loaded and easily parsed.

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 viewport manipulation tool with two optional parameters and no output schema, the description covers the essential what and when. It does not mention return behavior or error cases, but those are not critical for this straightforward, non-destructive operation.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds minimal extra meaning beyond the schema—it repeats 'specific nodes' and 'optionally select them'—but does not provide additional syntax or constraints. The schema itself already documents each parameter fully.

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 specific verbs and resources: 'Scroll and zoom the user's Figma viewport onto specific nodes,' which clearly distinguishes it from sibling tools that read or modify node data. It also mentions the optional selection behavior, adding further clarity.

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

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

The description gives an explicit usage context: 'Call this after building something so the user is looking at it when you report back.' It does not mention exclusions or alternative tools, but the context is clear enough. The schema's note about omitting nodeIds to fit the whole page adds an additional hint, though it's in the schema rather than the description.

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

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

Annotations already declare readOnlyHint=true, and the description adds meaningful behavioral context: it confirms plugin connection and provides placement guidance ('tells you where there is free space to place new content'). It also lists the scope of the read operation without contradicting the read-only 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?

The description is two sentences, front-loads the core purpose, and every clause adds value. It avoids redundancy and is appropriately sized for the tool's simplicity.

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

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

Given the tool has no parameters, no output schema, and a simple read-only nature, the description fully covers what it returns and when to call it. It notes the key outputs and the initial-call context, making it complete for an agent to decide and invoke.

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 are zero parameters, so the schema inherently has 100% coverage. The description does not need to elaborate on parameter meaning. Baseline 4 applies because no parameter documentation is needed.

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 'Describe' and clearly identifies the resource (the connected FigJam board). It enumerates exactly what information is returned (file name, current page, node counts, content bounds, viewport, selection), which distinguishes it from sibling tools like get_node or list_nodes that focus on individual nodes or selections.

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

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

The description clearly states when to use this tool: 'Call this first' — establishing it as the entry point to confirm connectivity and find free space. This gives strong contextual guidance, but it does not explicitly name alternatives or exclusions, 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 declare readOnlyHint=true, and the description confirms a read operation. It adds context about what data is included (text, fills, geometry, connector endpoints) but does not disclose behaviors like depth-induced response size or potential errors. With annotations covering the safety profile, the description provides moderate additional 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 a single sentence with no unnecessary words. It front-loads the action and resource, then lists deliverables, making it highly concise and well-structured.

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 provides a good overview of the tool's purpose and key output fields, even without an output schema. The schema fills in parameter details, and the annotations confirm safety. Minor gaps remain, such as not mentioning depth limits or the shape of the full response, but overall it is sufficiently complete.

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

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

Schema description coverage is 100%, with both depth and nodeIds having detailed descriptions, including an example and guidance on obtaining node IDs from other tools. The description itself adds no parameter-specific meaning beyond the schema, so the baseline of 3 applies.

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

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

The description uses a specific verb (Fetch) and resource (specific nodes), and lists concrete details (text, fills, geometry, connector endpoints). This clearly distinguishes it from siblings like list_nodes or find_nodes, which are about listing or searching rather than fetching full details by ID.

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 'for specific nodes' implies that the tool is used when you already have node IDs, but it does not explicitly state when to prefer this over alternatives like list_nodes or find_nodes. The sibling tools are not mentioned, so usage 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.

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

The annotation readOnlyHint=true covers the read-only safety profile. The description adds context about what is returned (current user selection) and implies no side effects. It does not disclose edge cases like empty selection, but for a simple getter this is acceptable and adds value 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?

The description is two sentences, front-loaded with the core purpose and then usage context. Every word earns its place with no redundancy.

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

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

Despite having no output schema, the description clearly states the return value ('the nodes'). For a simple read-only selection getter, this is complete and fully sufficient for an agent to invoke it correctly.

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

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

The tool has zero parameters, and the schema reflects this with 100% coverage. No description of parameters is needed, so the baseline of 4 for no-parameter tools 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 ('Return') and resource ('nodes the user currently has selected in Figma'), clearly distinguishing it from sibling tools like get_node or find_nodes. It precisely defines the scope of the operation.

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

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

Explicit usage guidance is provided: 'Use this when the user says "this", "these", or "the selected ones".' This gives concrete triggers and helps the agent know when to select this tool over 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?

The annotation readOnlyHint=true already covers safety. The description adds that the tool returns id, type, name, text, position, and size, and can operate on the current page or inside a container. This supplements the annotation with specific behavioral details without contradicting it.

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

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

Three short sentences deliver purpose, return payload, and use case. There is no redundancy; each sentence is informative and front-loaded with the core action.

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

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

With 4 optional params and no output schema, the description explains return fields, scope, and intended use. It leverages the schema for parameter details, making it sufficiently complete for a read-only list operation. The use case is clear and aligned with the tool's role.

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 baseline is 3. The description mentions 'specific container' (mapping to parentId) but does not elaborate on depth, limit, or types. It adds marginal value beyond the schema, which already fully describes each 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 'List nodes on the current page, or inside a specific container,' clearly identifying the action and scope. It lists return fields and the use case 'to understand an existing board before editing it,' which distinguishes it from sibling tools like find_nodes or get_node. This is a specific verb+resource with clear 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 description provides an explicit use case: 'Use this to understand an existing board before editing it.' This implies a read-only exploration context, but it does not explicitly state when not to use the tool or name alternative tools such as find_nodes for searching. Clear context with no exclusions or 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?

With no annotations provided, the description carries the full burden. It discloses the key behavioral trait that only passed fields are modified, which goes beyond the schema. However, it does not mention required permissions, error behavior (e.g., non-existent nodeId), atomicity across multiple items, or reversibility. These gaps would matter for a mutation tool.

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

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

Two concise sentences. The first lists the actions, the second clarifies the partial-update behavior. No wasted words, and the information is front-loaded and easy to parse.

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

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

The tool accepts an array of up to 200 items, but the description does not mention that it is a batch operation or address potential batch errors (e.g., partial success). There is no output schema, so return details are not required, but the description could be more complete about handling non-existent nodes or invalid fields. Overall adequate but with notable gaps for a mutating batch tool.

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

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

The schema provides descriptions for most parameters (name, text, color, nodeId) but not locked. The description lists the changeable fields ('text, colour, name or lock state') and adds meaning by clarifying partial updates. Since schema coverage is high, the baseline is 3, and the description contributes modest additional semantic clarity.

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

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

The description clearly states the tool's function: 'Change text, colour, name or lock state on nodes that already exist.' This is a specific verb with a specific resource (existing nodes) and distinct fields. It distinguishes itself from sibling tools like create_*, delete_nodes, and list_nodes by focusing on modification of existing nodes.

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

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

The phrase 'nodes that already exist' provides clear context that this tool is for updating existing nodes, not creating new ones. The partial-update semantics ('Only the fields you pass are touched') gives practical guidance on how to invoke it. However, it does not explicitly name alternatives or when-not-to-use, 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.