paper-cdp-mcp

by vvmahesh0

Overview Schema Related Servers Score Discussions

JavaScript

Local

Server Quality Checklist

Profile completionA complete profile improves this server's visibility in search results.

Latest release: v1.0.0
Disambiguation2/5
Many tools have heavily overlapping purposes: scene information is split across get_basic_info, get_tree_summary, inspect_scene_context, get_node_info, get_children, query_nodes, and find_nodes, while mutations are scattered across apply_node_patch, apply_document_transaction, update_styles, set_text_content, rename_nodes, and move_nodes. The detailed descriptions help, but the boundaries are blurry enough that an agent could easily select the wrong tool.
Naming Consistency4/5
Tool names overwhelmingly follow a clear verb_noun snake_case pattern (create_artboard, get_node_info, set_tokens, export_combined_pdf). Minor deviations exist—bare 'export', 'write_html' with lowercase noun, and compound verbs like 'autofix' and 'batch_write'—but these do not seriously undermine the predictable naming convention.
Tool Count1/5
With 73 tools, this server far exceeds even the 50+ extreme-mismatch threshold. While the server covers a broad design domain, the sheer number of tools bloats context, complicates selection, and creates unnecessary overlap; a more focused surface of 15-25 tools would likely cover the same workflows more coherently.
Completeness4/5
The server provides deep coverage of node lifecycle, styles, design tokens, comments, checkpoints, export formats, responsive/generation, QA checks, and file/page management. Obvious gaps remain—no file deletion/rename, no page deletion, and no way to create or reply to comment threads—but core design-automation workflows are well represented.
Average 3.8/5 across 73 of 73 tools scored. Lowest: 2.9/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 1 commit in the last 12 weeks
- No stable releases found
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI status not available
This repository is licensed under MIT License.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
Add a glama.json file to provide metadata about your server.
If you are the author, simply .
If the server belongs to an organization, first add glama.json to the root of your repository:
```
{
  "$schema": "https://glama.ai/mcp/schemas/server.json",
  "maintainers": [
    "your-github-username"
  ]
}
```
Then . Browse examples.
Add related servers to improve discoverability.

How to sync the server with GitHub?

Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.

To manually sync the server, click the "Sync Server" button in the MCP server admin interface.

How is the quality score calculated?

The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).

Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.

Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).

Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.

Tool Scores

Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It does not state whether the tool is read-only, what happens on assertion failure (e.g., returns report, throws error), whether it requires specific permissions or file access, or any side effects. The phrase 'Executes' implies running checks but leaves the outcome and side effects unspecified.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The single sentence is concise and front-loaded with the core action ('Executes programmatic design assertions') and a compact list of supported types. Every word earns its place; there is no fluff or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has a moderately complex schema (assertions array with many nested properties) but no output schema. The description only mentions the assertion types and the 'self-verifying' use case. It lacks essential context: what the return value is, how results are reported (pass/fail, detailed report), error handling, or examples. An agent would need more to correctly invoke and interpret the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so all parameters (fileId, assertions) are described in the schema, including nested properties. The description lists assertion types that exactly mirror the enum in the schema, adding no new meaning. It does not clarify parameter relationships, defaults (e.g., tolerancePx), or how to scope assertions. Thus it meets the baseline for high schema coverage but adds little beyond it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool executes programmatic design assertions and lists the specific types (alignment, uniform dimensions, etc.). This gives a specific verb and resource (assertions on design), making the tool's purpose clear. It is distinct from siblings like calculate_design_quality_score and autofix_contrast_issues, though it doesn't explicitly name alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description offers no guidance on when to use this tool versus alternatives. The only contextual hint is 'for self-verifying agent workflows,' which is vague and doesn't specify conditions, prerequisites, or when to prefer other tools like autofix_contrast_issues or calculate_design_quality_score. There is no exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits itself. It mentions atomicity and speed, but fails to explain whether the operation creates new artboards or overwrites existing ones, what happens on partial failure (though atomicity implies rollback), or any side effects. This is insufficient 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that front-loads the primary action and key attributes. It avoids fluff and is easy to parse, though it could benefit from a brief mention of typical use cases or constraints.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a batch write operation with nested parameters and no output schema, the description is incomplete. It doesn't clarify return behavior (e.g., success status, errors), the role of fileId, or any constraints on artboard properties beyond schema. The atomicity mention is helpful but not enough for an agent to confidently call the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so parameters are well-documented in the schema. The description adds little beyond confirming that artboards contain HTML UI. It doesn't explain the optional fileId or the meaning of x/y/width/height beyond schema descriptions, so it meets the baseline 3 for high coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: generating multiple artboards and populating their HTML UI. It mentions the batch nature and the atomic transaction, which distinguishes it from singular create_artboard. However, it doesn't explicitly contrast with sibling tools like write_html or apply_document_transaction, so it's not a perfect 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as create_artboard for single artboards or write_html for individual HTML updates. The description lacks context about prerequisites, preferred scenarios, or exclusions, leaving the agent to infer usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description alone must disclose behavioral traits. It mentions the binding/populating behavior but does not clarify whether existing list items are replaced, how many records are expected, what side effects occur on the canvas, or whether any data is destroyed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single focused sentence with no filler. It front-loads the core action and clearly names the object and purpose without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has a nested itemTemplate parameter and no output schema, but the description is minimal. It leaves the agent without enough context about mapping records to fields, required template behavior, or the resulting list behavior, which is significant for a data-binding tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 75%, and the description mainly restates the concept of records and templates without adding much detail beyond the input schema. The field names in itemTemplate are self-explanatory, but the description does not explain how records map to template fields or the role of fileId.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Binds an array of structured JSON records to a repeated template card/row') and names the resource being acted on. It clearly conveys the tool's function, though it does not explicitly differentiate it from sibling tools such as populate_mock_data.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives, and no exclusions or prerequisites are mentioned. The description implies a use case but does not help an agent select it over similar data-population or design-binding siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It conveys that the tool mutates layout settings, but it does not mention whether existing layout constraints are overwritten, whether the frame must already support auto-layout, what side effects occur, or any prerequisites or limitations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single focused sentence with no filler. The verb and target are front-loaded, and every phrase adds relevant information about the tool's scope.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a mutation tool with no annotations, no output schema, and a nested parameter object. The description provides only a high-level summary and leaves out important operational context such as whether existing layout settings are replaced, what node types are valid, and when to prefer sibling tools like auto_layout_grid. This is insufficient for reliable invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 67% and the description adds useful plain-language grouping ('alignment, and sizing constraints') that maps to nested schema fields like alignItems, justifyContent, and min/max dimensions. However, it does not elaborate on the 'layout' object semantics or clarify undocumented fields such as flexWrap and direction, so it only partially compensates for schema gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies a specific action ('Configures auto-layout...'), a target resource ('container frame'), and enumerates the affected properties (direction, padding, gap, alignment, sizing). However, it does not explicitly differentiate this tool from the closely related sibling 'auto_layout_grid', so it stops short of full sibling distinction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no explicit guidance on when to use this tool versus alternatives like auto_layout_grid or apply_node_patch. The description implies layout configuration on a frame, but it does not state conditions, exclusions, or a preferred alternative, leaving the agent to infer selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of explaining behavior. It only says a visual card/indicator is 'generated,' but does not disclose whether this mutates the document, creates a connector, alters artboards, requires specific permissions, or is reversible. For a tool that likely modifies design structure, this is a significant gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler. The phrase 'or user-journey indicator' introduces slight ambiguity, but overall the text is concise and easily parseable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation-like design tool with no annotations, no output schema, and a long list of siblings, one sentence is insufficient. The agent cannot tell whether the tool creates a permanent flow connection, a transient overlay, or a separate indicator, nor can it distinguish confidently from generate_journey_storyboard.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so each parameter is already documented. The description adds the high-level 'between two screens' context but no parameter-level detail beyond what the schema already provides, which keeps this at the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Generates') and a clear resource ('visual flow connection card or user-journey indicator between two screens'), which is meaningful and tied to the fromNodeId/toNodeId parameters. It does not explicitly contrast with closely related siblings like generate_journey_storyboard, so sibling differentiation is only implicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance about when to use this tool versus alternatives such as generate_journey_storyboard, diff_design_nodes, or other artboard utilities. The description gives no prerequisites, no context of intended workflow, and no exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure, and it does not carry it. It is ambiguous whether the tool modifies the document (linking screens by creating/modifying nodes) or produces a standalone report. It does not state what the return value is, whether fileId is required for mutation, or any side effects — a significant gap for a generative tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence that front-loads the verb and resource, with zero wasted words. It is appropriately compact for the information conveyed, though the brevity comes partly at the expense of behavioral depth.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no annotations and no output schema, the description is under-specified. It does not explain the return value of the generated storyboard, what occurs when fileId is omitted, or how artboardId relates to the screens being linked. An agent invoking this tool would be uncertain about both the result and the side effects. Several close siblings heighten the need for more context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 parameters (steps, fileId, flowTitle) are already documented in the schema. The description hints at how steps map to 'step indicators, user goals, and action annotations', which adds modest meaning, but it does not elaborate on artboardId semantics or the role of fileId. It barely exceeds what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Generates') and resource ('a structured user journey storyboard'), and lists the components it produces: step indicators, user goals, action annotations. This is clear, but it does not explicitly distinguish itself from the semantically close sibling connect_artboards_flow, which also deals with linking screens in a flow.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool versus alternatives. Given close siblings like connect_artboards_flow (linking screens) and generate_design_spec_doc (producing design documentation), an agent has no way to know which one fits a given intent. No exclusions or selection criteria are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It indicates the tool is read-only (provides a model), but does not clarify output format, potential performance implications (e.g., scope=viewport might be expensive), or whether any state changes occur. The phrase 'compact, AI-optimized' hints at a summarized response but lacks specifics.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no redundant phrases. The list of included elements is somewhat lengthy but necessary to clarify scope. It is appropriately concise for the amount of information conveyed.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no output schema, so the description should explain what the returned 'semantic scene model' looks like, but it does not. It lists components but not their structure or how they interact. Additionally, the behavior for different scopes (e.g., viewport vs selection) is not detailed, leaving gaps for an agent trying to interpret results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so each parameter already has a clear description (scope enum with default, nodeId requirement). The tool description adds no extra parameter-level semantics beyond the schema, but does not contradict it either. This meets the baseline for high coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it provides a semantic scene model of the current working context, listing specific components (selection, parent containers, siblings, layout, tokens, off-canvas). This distinguishes it from simple getters like get_selection or get_node_info, which focus on isolated elements. The intent is evident, though 'AI-optimized' adds minor ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 such as get_selection, get_node_info, or query_nodes. The description does not mention any preconditions, exclusions, or complementary tools. An agent must infer the appropriate context from the name alone, which is insufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
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 action (revert) but does not explain the effects (e.g., what happens to the transaction record, whether it is destructive, if it affects future transactions, or if it requires specific permissions). The behavior when both parameters are omitted is also undefined. This is a significant gap for a state-modifying tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that front-loads the core purpose. It contains zero wasted words and meets the standard of efficient communication.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with two optional parameters, no annotations, and no output schema, the description is too minimal. It fails to explain the default behavior (revert last transaction for the current file?), how the parameters affect the operation, or any constraints. Given the existence of closely related sibling tools, this lack of differentiation and operational context makes the description incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline applies. The description adds no additional semantics about how the optional fileId and transactionId parameters interact or what happens when neither is provided. The schema already provides basic descriptions, so the description neither helps nor hurts, but does not compensate for any ambiguity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('revert') on a specific resource ('most recent committed agent transaction') with a scope ('on the canvas'). It is clear and distinct from many other tools, though it does not name alternative tools or explicitly differentiate from rollback_checkpoint or apply_document_transaction, leaving some ambiguity for agents unfamiliar with the domain.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like rollback_checkpoint or apply_document_transaction. The description does not mention prerequisites, conditions, or exclusions, leaving the agent to infer usage solely from the name and one-line summary.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description bears the full burden of behavioral disclosure. It states what the tool does (scans and checks) but does not disclose side effects, whether it is read-only, rate limits, or any state changes. It also does not mention what happens with unresolved issues or if it returns details. The description adds minimal behavioral context beyond the stated checks.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that front-loads the primary action and the key checks (compliance, token consistency, WCAG AA). It avoids filler and is directly informative. Slightly more detail on output or usage could earn a 5, but it is appropriately compact.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no output schema and no annotations, so the description must carry the contextual load. It fails to mention what the audit returns (e.g., a report, list of issues, severity levels), whether it is a read-only operation, or any opinions about token sources. Given the moderate complexity of an audit tool, this is incomplete; an agent cannot fully predict the tool's behavior or consequences.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%: both fileId and nodeId are described in the schema. The description does not add any extra meaning to the parameters—it only mentions scanning an artboard, which maps to nodeId. Since the schema already fully documents the parameters, the baseline of 3 applies; the description does not enhance parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool scans an artboard/container specifically for design system compliance, token consistency, and WCAG AA contrast. This is a specific verb and resource, and it distinguishes itself from siblings like calculate_design_quality_score (which computes a numeric score) and autofix_contrast_issues (which fixes issues), making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no guidance on when to use this tool versus alternatives. It does not mention prerequisites, exclusions, or which sibling tools to use instead for other scenarios (e.g., extract_design_system_tokens, assert_design_rules). The agent must infer usage context solely from the purpose, which is insufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. The verb 'calculates' implies a read-only operation, but the description does not explicitly state that it makes no changes to the design, nor does it mention any side effects, performance characteristics, or permissions. This ambiguity could lead an agent to assume side effects or lack thereof incorrectly.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that front-loads the purpose and lists the key metric categories concisely. It contains no filler or redundancy, efficiently conveying the essential information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with only two parameters (one required) and no output schema, the description adequately explains what the tool computes and the output range. It does not explain error cases or edge behaviors, but for a straightforward scoring tool, it covers what an agent needs to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so both parameters (fileId and artboardId) are already documented in the input schema. The description does not add additional meaning about parameter usage, format, or dependencies, keeping it at the baseline expected when the schema already covers the parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb ('calculates') and resource ('design quality metrics'), enumerating concrete metric dimensions (8pt alignment, token coverage, WCAG contrast, layout consistency) and the output scale (0-100). It distinguishes itself from siblings like audit_design_tokens or assert_design_rules by focusing on an overall score, but it doesn't explicitly name a sibling it is not.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as audit_design_tokens or assert_design_rules. The description does not mention prerequisites, target scenarios, or exclusions, leaving the agent to infer usage from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry the full behavioral disclosure. It does not state whether the operation is read-only, whether it has side effects, how long it might take, or what the response format is (e.g., code string, file save, or something else). The phrase 'directly into production-ready code' is vague and does not clarify the operational behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that gets straight to the point, with the verb and resource front-loaded. It is efficient and easy to parse. It could be slightly more structured by listing formats as a bullet list, but the current form is concise and readable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of an output schema and annotations, and the presence of sibling tools that generate code, this description is incomplete. It does not tell the agent what the tool returns, whether it mutates anything, or how it relates to sibling code-generation tools. An agent would lack essential information to call it correctly and interpret the result.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already explains each parameter. The description adds no extra semantic detail about the parameters; it only mentions 'layer hierarchies' which relates to nodeId indirectly. Baseline of 3 is appropriate since the schema does the heavy lifting and the description does not conflict with it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('transpiles'), a clear resource ('Paper nodes and layer hierarchies'), and the exact output forms (SwiftUI, React + Tailwind, Flutter, CSS Tokens). This clearly distinguishes it from sibling export tools that target assets, PDFs, or JSON, and from code-oriented tools like get_jsx or write_html by covering multiple production-ready formats.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance about when to use this tool versus alternatives such as get_jsx, write_html, or export. No context is provided about the intended use case, limitations, or conditions that would make this tool the right choice. The description leaves the agent to infer usage from the purpose alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, so the description must carry the burden of disclosing behavioral traits. It reveals the output states but does not say whether the tool mutates the document, creates new nodes, overwrites existing content, or requires a particular file/document state. This is a meaningful transparency gap for a generation tool with side-effect potential.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler or repetition. Every word adds value by naming the resource and the concrete states included, making it an appropriately sized definition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a three-parameter tool with fully documented schema, the description is adequate but not complete. It names the required inputs and the expected output content, but with no output schema and no annotations, it omits behavioral context such as whether this is a mutating operation and what the agent should expect after invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%: all three parameters have meaningful descriptions, so the baseline is 3. The tool description adds no parameter-specific meaning beyond the schema, but it doesn't need to because the schema already documents each parameter adequately.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Generates') and a concrete resource ('component interaction state sheet') and enumerates the exact states included, making the tool's function unmistakable. However, it does not explicitly distinguish itself from sibling generation tools like generate_responsive_variants or generate_theme_variant, so it stops short of full sibling differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states only what the tool does, not when to use it or when to prefer an alternative. No prerequisites, exclusions, or comparisons to sibling tools are provided, leaving the agent to infer the appropriate context from the tool name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. It discloses that the tool 'explicitly sets' the zoom, implying a direct override of the current state, but it does not mention side effects (e.g., whether it persists, affects all views, or requires any permissions). The minimal disclosure is insufficient 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-formed sentence that front-loads the key information. It includes concrete examples and avoids unnecessary words, making it highly concise and easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter setter with full schema coverage, the description covers the primary zoom parameter but omits any mention of the optional 'fileId' or how it behaves when omitted. It also lacks routing to the sibling 'zoom_to_fit', leaving the description incomplete for a tool that has a clear alternative.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds 'canvas' context and example percentages, but the schema already provides similar examples. It does not clarify the optional 'fileId' parameter beyond what the schema states, so it adds marginal value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('sets') and a clear resource ('canvas zoom percentage') with concrete examples. It implicitly differentiates from the sibling 'zoom_to_fit' by emphasizing an explicit percentage rather than fitting to content, but it does not name the alternative directly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus the sibling 'zoom_to_fit' or 'pan_to_node'. There is no mention of conditions, exclusions, or alternative tools, leaving the agent to infer usage context from the tool name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It does convey that the tool captures and compares screenshots, but it omits important behavior: whether an existing baseline is required, whether screenshots get persisted, whether the tool is read-only, or what the comparison returns. This is a significant transparency gap for an agent planning a call.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no waste. The verb, resource, and purpose are all front-loaded, and every clause contributes necessary information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, no annotations, and closely related sibling tools, this description is incomplete. It does not explain the return format, how a baseline is established, whether a missing baseline produces an error, or how the tool's result relates to tolerancePercent. An agent cannot fully anticipate the tool's behavior or response.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all three parameters. The description adds only marginal context by framing the tool around 'visual screenshots of a node or artboard' and implying tolerancePercent controls regression sensitivity, but it does not meaningfully extend the schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('captures and compares visual screenshots') with a target resource ('node or artboard') and an explicit outcome ('detect unexpected visual regression or layout drift'). However, it does not explicitly distinguish this tool from closely related siblings like get_screenshot or diff_design_nodes, leaving the baseline/comparison semantics largely implied.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The stated purpose, 'detect unexpected visual regression or layout drift,' provides an implied use case, telling an agent when this tool might be helpful. But it gives no explicit guidance on when to choose this tool over alternatives, no exclusions, and no mention of prerequisites such as an existing baseline screenshot or comparison target.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, so the description carries the full burden of behavioral disclosure. It explains the default-settings policy but not the side effects of exporting, whether files are created/returned, or what happens to the document state. This is a significant gap for a tool that produces external artifacts.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no redundancy. The purpose is front-loaded, and the second sentence adds a meaningful behavioral constraint without wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations and no output schema, the description is too thin. It does not explain what a successful export returns or how an agent knows where the output went, nor does it mention fileId targeting or when to prefer sibling export tools. The rich schema covers parameter syntax, but the real-world invocation context is incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already provides detailed descriptions for type, nodes, and fileId, with about 67% coverage. The description adds no per-parameter meaning; its default-settings warning is already reflected in the schema's guidance to set nodes to an empty array for defaults.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb and resource: 'Export nodes as image or video files.' This distinguishes it from most siblings like export_code, export_combined_pdf, and export_figma_compatible_json, though it does not explicitly name the closest alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
'Unless the user specifies, do not override the default export settings' gives an important conditional behavior. However, it does not explicitly say when to use this tool instead of batch_export_assets or export_code, so alternative selection is largely implied rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It only states that a document is generated, leaving unclear whether this mutates the file or returns content, what the output format is, and whether prior data (tokens/components) must already exist on the artboard. For a generation tool with no annotation coverage, these gaps are significant.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, well-structured sentence that front-loads the action and packs the deliverables into parenthetical detail. No fluff. It is slightly lean given the behavioral gaps elsewhere, but as written the sentence is efficient and readable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The core purpose is fully conveyed, and the tool is simple (2 params, 1 required). However, with no output schema and no annotations, the description omits behavioral context an agent needs to call it safely and appropriately — notably the return format and whether it is a pure read or produces a persistent artifact. Adequate but incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so both parameters (fileId, artboardId) are documented in the schema itself, setting the baseline at 3. The description adds only marginal context by hinting at what content the resulting spec relies on (tokens, components, dimensions), but does not elaborate on parameter semantics or interaction beyond the schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Generates') and a specific resource ('comprehensive design handoff specification document for engineering'), detailed with concrete content areas (tokens, components, dimensions, spacing redlines). This naturally distinguishes it from siblings like export_code, export, and write_html, which produce different artifacts (code or binary files). The purpose is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no guidance on when to use this tool versus alternatives. Among siblings there are several export/generation tools (export_code, generate_component_states, write_html), and the description does not state conditions that select this handoff-spec tool over them, nor any exclusions or prerequisites (e.g., artboard must contain design tokens). Usage context is only implicitly derived from the purpose.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
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 says data is 'populated into' cards or text layers, but it does not say whether existing content is overwritten, whether new nodes are created, what node types are valid, or whether the operation is destructive. This is a significant gap for a mutation-style tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that conveys the action, target, and content scope without wasted words. It is concise and easily parsed by an agent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with three parameters, no output schema, and no annotations, the description is too thin to be fully actionable. It omits target-node requirements, overwrite behavior, and whether the tool creates or only modifies existing layers, leaving essential invocation context unspecified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and all parameters including the domain enum have descriptions. The description only repeats the domain examples already present in the schema and adds no meaningful parameter-level detail, 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.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Populates') and names both the resource ('artboard cards or text layers') and the data domains ('users, financial ledger, SaaS spaces, metrics'), making the function clear. It does not explicitly distinguish itself from siblings like bind_data_repeater or set_text_content, but the mock-data scope is evident enough to avoid major confusion.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The action implicitly communicates when to use it—when realistic mock data is needed in design nodes—but there is no explicit when/when-not guidance, prerequisites, or alternatives. The description implies a use case but leaves decision-making against sibling tools to the agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It correctly signals a mutating operation ('rearranges', 'aligns') but does not disclose whether artboard positions are permanently overwritten, whether the operation is undoable, or whether it requires an open file or selected context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, tightly written sentence that front-loads the core action and outcome. Every word earns its place with no filler or redundant restatement of the tool name.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Adequate for a straightforward layout operation: the schema documents all seven parameters and the description conveys the effect. However, without annotations or an output schema, it leaves unstated whether the tool returns the new positions, reorders artboards in place, or only works on a specific file/selection.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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's terms 'multi-column', 'grid', and 'gutters' loosely map to columns, gutterX, and gutterY, but it adds no parameter-specific meaning beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('rearranges and neatly aligns') and a specific resource ('a list of artboards') with a clear outcome (multi-column grid matrix with consistent gutters). This clearly distinguishes it from siblings like move_nodes or connect_artboards_flow.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains what the tool does but provides no guidance on when to use it versus alternatives such as configure_layout_constraints, move_nodes, or batch_write_artboards. No exclusions, prerequisites, or selection criteria are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states the intended output but does not say whether new artboards are created, whether the file is mutated, whether existing variants are overwritten, what permissions are needed, or what the return value looks like.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence with no filler. It communicates the essential purpose and key dimensions efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a generation tool with no annotations and no output schema, so the agent needs more context about side effects, result format, and the role of optional parameters like fileId. The current description is too thin to fully prepare an agent to invoke it confidently.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds value by mapping breakpoint values to concrete dimensions (390px and 820px) and clarifying that artboardId refers to the source desktop artboard.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: it generates mobile and tablet artboard layouts adapted from a desktop design. It clearly conveys the tool's core function, though it does not explicitly differentiate itself from siblings like generate_component_states or generate_theme_variant.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool should be used when you have a desktop artboard and need responsive mobile/tablet layouts. It does not explicitly state when not to use it or name alternatives, leaving usage guidance to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full disclosure burden. It does reveal meaningful behavioral detail — that output is JSX, that node descendants are included, and that tailwind is the default format with inline-styles as an option. It does not, however, describe any size/recursion limits or error behavior for large node trees, which would strengthen transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tightly written sentences with the core action front-loaded and no filler. Every phrase earns its place, and the format options are stated compactly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description responsibly indicates the return type (JSX code representation), and the tool is simple enough that the main gap is moderate. The biggest omission is usage differentiation against export_code and write_html, plus a hint of the return's scope for large trees, which keeps this at a solid but not complete level.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 marginal value by reinforcing that tailwind is the default format and that descendant nodes are included, which maps to the format and nodeId parameters respectively, but it does not go beyond what the schema already documents.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb-resource pair: 'Get the JSX code representation of a node and its descendants,' clarifying both the action and the scope. It also names the two output formats. It does not explicitly contrast itself with overlapping siblings like export_code or write_html, so it stops short of full differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to select this tool over alternatives such as export_code, write_html, or get_computed_styles, several of which are plausible competitors in the sibling list. There is no stated context, precondition, or exclusion, so an agent must infer usage purely from the name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
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, but it only states the insertion action. It does not disclose whether an existing fill is replaced or layered, what node types accept the fill, or whether media is fetched from a remote source. These are material side effects for a mutation tool with no annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence that wastes no words, front-loads the main action and object, and packs useful semantic detail into a compact structure. Every phrase earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple 3-parameter tool, the schema plus description is mostly sufficient for a straightforward call. However, the lack of output schema and annotations leaves gaps around the return value, target node constraints, and the effect on existing fills. These are notable but not critical for using the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds natural-language meaning for some enum values ('portraits/avatars, landscape, tech mockups') and clarifies that targetNodeId receives the fill. However, it omits the 'architecture' and 'abstract-dark' enum values and does not fully explain the semantic differences between them, so it only partially compensates.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Inserts'), a concrete resource ('curated stock imagery' or 'procedural mesh gradients'), and the effect ('directly as fills'). The media categories distinguish it from the sibling insert_icon, which focuses on icons, so an agent can differentiate them without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no guidance on when to use this tool versus alternatives such as insert_icon, apply_node_patch, or get_fill_image. It neither states ideal scenarios nor excludes sibling tools, leaving the agent to infer usage from the verb alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It indicates a mutating operation ('rolls back') but does not state that current node state will likely be overwritten or whether the operation is reversible. It also omits failure modes and scope-of-effect details.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that front-loads the action and target. The phrase 'rolls back and restores' is mildly redundant but does not significantly bloat the definition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a potentially destructive mutation tool with no annotations and no output schema, the description omits important context: irreversibility, which nodes are affected, how the optional fileId changes scope, and what the tool returns. The schema covers parameter names but not operation-level expectations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already documents both parameters with descriptions, achieving 100% schema description coverage, so the baseline is 3. The tool description itself adds no extra meaning about checkpointId or optional fileId beyond the schema. No parameter semantics are enriched.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb phrase ('rolls back and restores') with a clear resource ('canvas nodes') and object ('earlier checkpoint state'). This clearly distinguishes it from sibling checkpoint tools like create_checkpoint and list_checkpoints. It unambiguously states 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.
Usage Guidelines3/5
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, nor does it mention exclusions or sibling tools like undo_last_transaction or apply_document_transaction. However, the implied usage scenario—restoring nodes to an earlier checkpoint—is reasonably clear from the wording.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, so the description carries the full behavioral disclosure burden. It mentions 'Executes' and 'dry-run support', but it does not disclose whether patches apply atomically, what happens on partial failure, whether destructive operations like delete require extra guardrails, or whether the operation is reversible. For a mutation tool handling delete and move, this is a significant gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no wasted words. The core verb, target resource, supported operations, and dry-run capability are all included in a compact, scannable format.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite broad schema coverage, this is a complex tool with seven patch operations, nested layout objects, no annotations, and no output schema. The one-sentence description is too thin to tell an agent how patches interact, what a successful response looks like, whether ordering matters, or when the tool should be preferred over the many sibling mutation tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 the parameters and nested patch fields. The description adds the 'unified declarative patch list' framing but does not add meaningful semantic detail beyond what the schema already provides, which earns the baseline score of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb ('Executes') and a specific resource ('canvas nodes'), and enumerates exactly which patch operations are supported (setStyle, setText, rename, move, delete, duplicate, setLayout). This clearly distinguishes it from single-purpose sibling tools like move_nodes or delete_nodes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this is for applying a batch of declarative patches to one or many nodes, and dry-run support is a useful conditional. However, it never explicitly says when to choose this over siblings like apply_document_transaction, batch_write_artboards, or individual mutation tools, and it does not state any exclusions or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavior. It mentions what is checked but does not describe side effects, return format, authentication requirements, or whether the operation is read-only. An agent cannot infer what the output looks like or if the call might alter state. This is a notable gap for a diagnostic tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that front-loads the action and lists the specific components checked. There is no filler or unnecessary detail, making it efficient and easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that there is no output schema, the description should explain what the health check returns and how to interpret it. It also does not mention any preconditions (e.g., open document) or potential side effects. For a tool that checks multiple subsystems, this is insufficient for an agent to understand the full context and expected results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% (the fileId parameter is described as 'Optional target file ID to check'). The description does not add any extra semantics beyond the schema; it simply restates that the file is the target of the check. Since coverage is high, the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('performs a comprehensive diagnostic health check') and enumerates the specific resources it checks (Paper Desktop, CDP connection, in-memory rate-limit bypass, active document state). This is precise and distinguishes it from any sibling tools, none of which appear to offer a health-check function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is used to diagnose system health, but it does not explicitly state when to use it, when not to, or mention any alternatives. Since no sibling performs a similar role, there is no competitive routing, but explicit usage context (e.g., 'use when troubleshooting connection issues') is missing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden. It transparently states the return fields and the error condition if the node does not exist. However, it does not disclose side effects (or lack thereof), potential limits, or sorting order. For a simple read operation, this is adequate but not rich; it describes behavior beyond the schema but leaves some behavioral aspects unaddressed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with zero fluff. The purpose is front-loaded ('Get the direct children of a node') and the return details are listed compactly. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a straightforward 'get children' tool with no output schema, the description covers the essential return values and error handling. It lacks details like ordering or empty-list behavior, but these are minor for a simple tool. The complexity is low, and the description is sufficient for an agent to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 both parameters. The description does not add extra meaning to the parameters; the fileId handling is fully explained in the schema. Baseline 3 is appropriate because the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get' and the resource 'direct children of a node', specifying what it returns (list of child nodes with fields). It differentiates from siblings like get_tree_summary by explicitly saying 'direct children' rather than a full tree, but it does not name the alternative. This is a clear, distinct purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool over alternatives. It does not mention when to use get_tree_summary or find_nodes, nor any exclusions or prerequisites. The only hint is 'direct children', which implies a need for immediate children, but no explicit comparison is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations present, the description carries the full burden of behavioral disclosure. It reveals the transformation intent and token application, but does not state whether the original artboard is mutated in place or a new artifact is created, whether the operation is reversible, or what side effects applying design tokens may have.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The entire description is one efficient sentence that front-loads the core transformation and includes the key qualifier about design tokens. There is no filler or repetition of the tool name.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The absence of an output schema and annotations means the description should explain the result and side effects, but it only describes the high-level transformation. It does not clarify what the caller receives, whether the source artboard is preserved, or how fileId/theme affect execution, leaving important operational context missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 confirms that artboardId refers to the low-fidelity input, but it adds little detail beyond the schema about theme selection, optional fileId, or how these interact with active design tokens.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific action ('Upgrades'), a precise input type ('low-fidelity wireframe or mockup artboard'), and a concrete outcome ('polished, high-fidelity production screen'). This makes it readily distinguishable from siblings like create_artboard or generate_theme_variant.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The intended use case is implied: select this when a low-fidelity wireframe or mockup needs to become a high-fidelity screen. However, there is no explicit when-not-to-use guidance or comparison to sibling tools that might also alter design fidelity, such as generate_theme_variant or update_styles.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
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 reveals that the tool 'corrects' issues and targets specific contrast ratios, but it does not explain what actually gets modified, whether the operation is reversible, whether permissions are needed, or what happens when correction is impossible.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence communicates the core action, target, and compliance thresholds without any filler or repetition. Every phrase earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a straightforward tool with fully documented parameters, the description is mostly sufficient. However, since there is no output schema and no annotations, it should ideally mention what the caller can expect after execution, such as whether a correction report or success status is returned.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all parameters and defaults. The description adds only the WCAG threshold ratios for AA and AAA, which slightly enriches the standard enum but does not substantially extend parameter meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses specific active verbs ('analyzes and corrects') tied to a clear resource ('color contrast issues') and names the exact compliance targets (WCAG 2.1 AA/AAA with ratios). This clearly distinguishes it from broader audit, analysis, and style tools in the sibling list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The intended use is implied: call this when you need automated color contrast correction to meet WCAG standards. However, it gives no explicit comparison with related tools such as assert_design_rules or audit_design_tokens, and no exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral disclosure burden. It mentions parallel execution but does not disclose whether the export creates files, returns binary data, requires specific permissions, or how failures or partial exports are handled. This is a significant transparency gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single dense sentence with no filler. It front-loads the action and resource, then packs in format, scale, and parallelism. Every element earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a three-parameter tool with full schema coverage, the description is mostly sufficient for selection and straightforward invocation. However, with no output schema or annotations, the missing information about what the call returns or where outputs are delivered leaves a notable gap for an agent deciding how to handle the result.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and all three parameters (nodeIds, scale, fileId) are already explained in the input schema. The description only echoes scale values and 'multiple' nodeIds, adding no meaningful parameter-level detail beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Batch exports'), a concrete resource ('multiple artboards or layers'), and output characteristics ('as PNG/SVG at 1x, 2x, or 3x resolutions'). It clearly distinguishes this from single-asset export tools and other export variants like export_code and export_combined_pdf.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The word 'batch' implies the tool is for exporting multiple nodes at once, which is a soft usage cue. However, there is no explicit when-to-use vs single-item 'export' or other export siblings, and no exclusion like 'for single-node exports, use export instead'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations present, the description carries the burden of behavioral disclosure. It indicates the kinds of information the diff covers, which is useful, but it does not explicitly state that the operation is read-only/non-mutating, nor does it describe the output shape or any constraints like cross-file support. This is a moderate disclosure—enough to suggest purpose but not complete behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler. It communicates the core purpose first and then compresses the key dimensions into a parenthetical list, making it efficient and scannable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has only three parameters, two required, and no output schema, so the description need not be exhaustive. However, without annotations or an output schema, it would benefit from stating the return type (the diff result) and that no mutation occurs. It is adequate for basic usage but leaves some operational context implicit.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the schema already documents sourceNodeId as 'Base/reference node ID' and targetNodeId as 'Comparison node ID.' The description adds that these can be nodes or artboards, and that the diff is semantic, but it does not add deeper meaning beyond the schema's own parameter descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's specific action ('Computes a deep semantic design diff') and its resource ('between two nodes or artboards'). The parenthetical enumerates the kinds of deltas (structural, styling, text, dimension shifts, token bindings), which distinguishes it from a purely visual comparison sibling like compare_visual_regression.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no explicit guidance on when to choose this tool over siblings such as compare_visual_regression or apply_node_patch. It implies usage for semantic diffing, but it does not state exclusions, alternatives, or the specific conditions under which this tool is preferred.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
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 describes the core behavior (analyzing and extracting tokens) and what kinds of tokens are discovered, but it does not clarify whether the operation is read-only, what side effects might occur, or what the result structure looks like. This is adequate but not fully transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that fronts the action and resource, lists concrete outputs, and includes the purpose. Every phrase earns its place, with no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given there is no output schema and no annotations, the description provides a reasonable overview but omits important operational context: the response format, whether the operation modifies anything, and how the optional parameters alter behavior. It is complete enough for a basic understanding but not fully sufficient for confident invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the two optional parameters (fileId, artboardId) are already documented in the schema. The description adds no additional parameter-level guidance, such as how the parameters affect token discovery scope, 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.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Analyzes ... extracts') and a clear resource ('existing design document'), and lists the token categories returned (color palette, typography scale, radius steps, spacing values). It does not explicitly differentiate from siblings like audit_design_tokens, but the phrase 'implicit design tokens' makes the intent distinct.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool: when an existing design document needs to be analyzed to derive tokens for system creation. It does not explicitly state when not to use it or name alternatives such as audit_design_tokens, get_tokens, or create_tokens.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It does mention that the tool 'tests for layout truncation,' which is useful, but it does not clarify whether the translation mutates the artboard directly, whether changes are reversible, what happens when truncation is detected, or what output or side effects are produced.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that front-loads the core action and follows with the key special behavior. Every phrase earns its place, and there is no filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with only three simple parameters, the description is reasonably complete, but the lack of annotations, output schema, and any mention of return behavior leaves meaningful gaps. An agent would not know what success or failure looks like, especially for the truncation test, which is central to the tool's purpose.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all three parameters, including the enum values for targetLanguage. The description adds no additional semantic meaning beyond restating the language codes in prose, 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific action ('Translates and localizes an artboard'), a precise set of target languages (de, ja, es, fr), and a distinctive additional behavior (testing for layout truncation). This clearly differentiates it from the many sibling design tools, such as set_text_content or generate_responsive_variants, which might otherwise overlap.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied rather than explicit: an agent can infer this tool should be used when an artboard needs translation/localization into one of the listed languages. However, there is no explicit guidance on when not to use it, no mention of alternatives, and no stated prerequisites such as needing an open file or existing artboard.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the behavioral disclosure burden. It conveys a read-only intent and lists the returned details, which is helpful. However, it does not disclose behavior for an empty selection, whether multiple nodes may be returned, or how file resolution behaves.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
One single-sentence description with a front-loaded verb and valuable detail. Every phrase earns its place, with no redundant words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the low complexity, one optional parameter, and no output schema, the description provides the core expected return content. It lacks an explicit note about empty or multiple selections, but it is otherwise sufficiently complete for a simple getter.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema documents the single optional fileId parameter with full coverage and clear semantics. The description adds no parameter-specific information, 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.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Get') and resource ('currently selected nodes') and enumerates the main returned fields. It is clear and distinct, though it does not explicitly contrast with sibling get_* tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'currently selected nodes' implies when to use this tool, but it does not provide explicit when-not-to-use guidance or name alternatives among the many sibling get_* and query tools. The intended usage is reasonably inferable but not stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry the behavioral burden. 'List' signals a non-mutating read operation, but the description provides no further detail about defaults, return structure, or scoping behavior beyond what the schema states.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence communicates the operation and scope with no filler. The parenthetical gives useful examples without elongating the description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only list operation with a fully documented 4-parameter schema, this description plus the input schema is sufficient to invoke the tool correctly. It lacks sibling differentiation and an explicit statement of read-only semantics, but these are partially recoverable from the tool name and verb.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the structured declaration already documents all four parameters. The description's inline examples ('colors, spacing, typography') echo enum values already present in the schema rather than adding new parameter-level meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Names a specific verb ('List'), a resource ('the file's design tokens'), and enumerates representative token categories. This clearly distinguishes it from mutation/audit siblings such as set_tokens, create_tokens, and audit_design_tokens.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to choose this tool over audit_design_tokens, extract_design_system_tokens, or set_tokens. The read-only use case is implied only by the verb 'List' and the tool name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description is the sole source of behavioral context. It discloses the read-oriented nature ('search engine', 'pagination', 'projections') and the query language (logical conditions), but it does not explicitly state that the operation is non-destructive, nor does it describe return value structure or side effects. It is adequate but not exhaustive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, information-dense sentence that front-loads the core value proposition ('high-performance structured search engine') and then enumerates all key capabilities. There is no redundancy or filler; every phrase contributes.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers all major dimensions: filter types, logical operators, pagination, and projections. However, it omits sorting (sortBy) and the compact flag's specific effect on token usage, which are defined in the schema. Given the tool's complexity and the absence of an output schema, these small omissions leave minor gaps but overall the definition is quite complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers 86% of parameters with descriptions, so the baseline is 3. The description adds conceptual grouping (e.g., 'bounds' mapping to min/max width/height, 'parent hierarchy' to parentId/artboardId, 'logical AND/OR/NOT' to the filter sub-object), but it does not enhance each individual parameter beyond the schema. Overall, it adds moderate interpretive value without extending detail.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it is a 'high-performance structured search engine' for querying canvas nodes, enumerating specific filter dimensions (type, name regex, text content, bounds, parent hierarchy) and operational features (logical AND/OR/NOT, pagination, projections). This precisely distinguishes it from sibling tools like get_children (hierarchy) or find_nodes (likely basic search).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention simpler search options (e.g., find_nodes) or spatial queries (query_spatial_relationships), nor does it state conditions for choosing this over others. The agent must infer from capabilities alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. It does disclose dry-run support and hints at safety, which is helpful, but 'safely' is vague and it does not state whether changes are reversible, create checkpoints, or have side effects on the broader document.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
One sentence with no filler: the verb and resource come first, strategies are compactly grouped, and dry-run support is appended. Every phrase earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the core purpose and strategies but leaves gaps for a mutating tool: no output format, no statement about side effects or reversibility, and no guidance on how dry-run output relates to the real refactor. The schema fills parameter details, but the tool's operation is not fully specified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds value by translating the enum strategies into natural-language meanings: 'semantic layer renaming', '8pt spacing normalization', and 'flattening redundant wrappers', plus it references the dryRun capability beyond the bare schema field.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('refactors') and a clear resource ('canvas structure'), then enumerates the exact refactor strategies it covers. It is clear and distinguishable from generic sibling tools like rename_nodes or update_styles, though it never names a sibling explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The parenthetical list implies when the tool is appropriate: semantic layer renaming, spacing normalization, or wrapper flattening. However, it gives no explicit guidance about when to use an alternative tool or when not to use this one.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
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 conveys the essential transformation — converting a Paper artboard hierarchy into Figma node schema JSON — but does not state whether the operation is non-mutating, how the JSON is delivered (inline payload, file artifact, URL), or what happens on invalid artboardId.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single 20-word sentence conveys action, resource, output format, and purpose with zero filler. The verb and target format are front-loaded, and every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter tool with full schema coverage, the description covers the essentials adequately. The notable gap is the absent output schema combined with no return-value explanation — an agent cannot tell whether calling this tool returns the JSON text, writes a file, or produces a downloadable artifact, which is the central question for an export tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with both 'artboardId' and 'fileId' already explained in the input schema, so the baseline of 3 applies. The description adds no parameter-specific meaning beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Begins with the specific verb 'Exports' followed by the resource ('Paper artboard hierarchy') and a precise output contract ('standardized Figma REST/Plugin node schema JSON'). The exact target format cleanly distinguishes this tool from generic siblings like 'export' and 'export_code' without needing to open their schemas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The clause 'for cross-tool interoperability' implies the intended scenario, and the Figma-specific output format signals when this tool applies. However, with numerous export-oriented siblings (export, export_code, batch_export_assets, export_combined_pdf, get_jsx, write_html), the description names no alternative and gives no explicit 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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. The verb 'Calculates' implies a non-mutating, read-only operation, and the list of relationship types gives some insight. However, it does not disclose return structure, how tolerance affects results, or behavior when compareNodeIds is omitted.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence with no filler. Every phrase contributes: the verb, the scope, and the catalog of computed relationships. It remains readable despite enumerating many relationship types.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers what the tool computes but not the shape of the returned data, which matters because there is no output schema. It also does not clarify how the optional compareNodeIds and tolerancePx parameters affect the set or precision of results. Adequate for a basic understanding, but with clear gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 does not add parameter-level meaning beyond the schema; it mentions relationship types like distances and alignments, but tolerancePx and compareNodeIds semantics are left to the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Calculates') and a precise resource ('2D canvas spatial relationships between nodes'), and enumerates the exact relationship types. This clearly differentiates it from sibling query tools like query_nodes or get_basic_info, which are more general-purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for spatial relationship queries, but it does not explicitly state when to use it versus alternatives or when not to use it. It provides no named sibling alternatives or exclusion conditions, leaving the agent to infer applicability from the relationship vocabulary.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral burden. It accurately states that the tool changes the zoom level to fit content into view, which is the core behavior, but it does not disclose potential side effects, persistence, validation failures, or whether it affects the current file selection/context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence that states the action, target, and outcome with no filler. The key behavior is front-loaded and every phrase earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple and the schema covers parameters, but there is no output schema or annotation context. The description leaves implicit what the return value is, what happens when fileId is omitted, and how this compares with related camera/pan tools, which weakens end-to-end completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already covers both parameters fully (100% coverage), so the description does not need to add much. It does slightly enrich nodeIds by framing it as 'single node, multiple nodes, or entire canvas,' but it adds no new meaning to fileId.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies a specific action ('adjusts the canvas zoom level') and its scope ('fit a single node, multiple nodes, or the entire canvas into view'). This differentiates it from camera-related siblings like set_camera_zoom and pan_to_node by emphasizing automatic fitting rather than manual control.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool: when the agent wants to frame a node, a set of nodes, or the whole canvas. However, it does not explicitly distinguish this from set_camera_zoom or pan_to_node, and there is no guidance about when not to use it or alternatives to prefer.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral burden. It discloses atomicity and scope, which is useful, but it does not mention effects on existing checkpoints, retention limits, or whether a checkpoint identifier is returned for later rollback.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, well-structured sentence with no filler. The core behavior is front-loaded and every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple, has full schema coverage, and the description conveys the essential purpose and rollback relationship. It does not explain the return value or checkpoint lifecycle, but those are secondary for a low-complexity creation operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all three parameters. The description adds context about 'current artboards or nodes' but does not meaningfully extend parameter understanding beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Saves') and a specific resource ('atomic snapshot checkpoint of current artboards or nodes'). It clearly distinguishes this creation action from related siblings like list_checkpoints and rollback_checkpoint.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'for 1-click rollback' implies this should be used before making changes that might need to be reverted, but there is no explicit when-to-use guidance or mention of alternatives. The tool's relationship to undo_last_transaction or apply_document_transaction is not addressed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden of behavioral disclosure. It does disclose the output format and batch capability, and 'Get' implies a read-only operation, but it does not mention error behavior, missing nodes, performance implications of batch requests, or whether styles are computed recursively. These are meaningful gaps for a tool with no annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences contain exactly the necessary information: action, target, output shape, and batch capability. The most important information 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.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only getter with two parameters, the description is largely complete: it names the purpose, the return structure, and batch behavior. It could add a note about the shape or semantics of CSSProperties or behavior for invalid node IDs, but the absence of an output schema is partially mitigated by the explicit return-type description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already explains both fileId and nodeIds. The description reinforces nodeIds with 'one or more nodes' and 'batch requests,' but it adds no additional parameter-level semantics beyond what the schema provides. The baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Get') and resource ('computed CSS styles for one or more nodes'), and it clearly distinguishes this from sibling tools like update_styles by focusing on read-only computed styles. The return shape ('map of nodeId to CSSProperties object') is also stated, leaving no ambiguity about 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.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies its use case through the phrase 'computed CSS styles' and mentions batch support, but it does not explicitly contrast with alternatives such as get_jsx, get_basic_info, or update_styles. There is no 'use this when' or 'instead of' guidance, so an agent must infer appropriate usage from the verb and resource alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of behavioral disclosure. It explicitly discloses atomic execution, validation, precondition checks, dry-run preview, and automatic rollback on failure, which are non-obvious behaviors an agent needs to know before calling it. It does not, however, describe the return value or the consequences of failed preconditions when dryRun is false, leaving some behavioral ambiguity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence that leads with the core action ('Executes') and front-loads the defining properties (atomic, validated, multi-step, precondition checks, dry-run, rollback). Every phrase carries distinct information with no filler, making it efficient and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex tool with six parameters, nested operation objects, and no output schema, the description provides a solid high-level orientation but omits any mention of return format or result payload, which is a meaningful gap since no output schema exists. It also does not explain ordering guarantees or how preconditions interact with the atomic execution, though the schema partially covers these.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is high (83%) and most parameters, including atomic, dryRun, operations, and preconditions, are already described in the schema. The description adds only high-level labels ('dry-run preview', 'precondition checks') that map to existing properties and does not explain parameter semantics beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Executes') and identifies the resource ('multi-step document mutation'), distinguishing it from single-operation siblings like apply_node_patch or batch_write_artboards by emphasizing atomicity, validation, precondition checks, dry-run preview, and rollback. This gives an agent a clear model of what the tool does without needing to open the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for multi-step mutations needing atomicity and validation, but it never explicitly contrasts with sibling tools like apply_node_patch or batch_write_artboards, nor states when one would choose this over separate mutation calls. The context is clear about the tool's nature but lacks explicit when-to-use/when-not-to-use guidance, so the agent must infer selection criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
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 a key behavior: the returned data is a compact summary/context snapshot rather than full detail. It also clarifies coordinate semantics (worldX/worldY vs x/y). However, it does not mention side effects, performance characteristics, or whether it works when no file is open.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: the first sentence states exactly what is returned, the second gives an immediate usage directive, and the two bullet points clarify important coordinate semantics. Every sentence earns its place with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only context-gathering tool with one optional parameter and no output schema, the description covers the essential information an agent needs: what data comes back, when to call it, and how to interpret coordinate fields. Minor gaps include return shape details (e.g., units or format of dimensions), but these are not critical for invoking the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema coverage is 100% and the fileId parameter is well described in the schema itself. The description adds value by not repeating the parameter details, and the 'current design' phrasing clarifies that the default target is the active canvas/file. Since the schema fully covers the single optional parameter, a baseline 3 applies; the description's contextual framing nudges it to 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Get essential context about the current design' and enumerates concrete contents (file name, page name, node count, artboards, fonts, tokens). It is clear about what the tool returns, though it does not explicitly differentiate itself from siblings like get_node_info or get_tree_summary.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly instructs 'Call get_basic_info first to understand the canvas situation.' This gives a clear when-to-use directive. It does not state when not to use it or name alternatives, but the 'first' framing strongly implies it is the entry-point context tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry behavioral disclosure. It implies a read-only operation by using 'lists', but it does not state side effects, output format, or any limitations. The minimum is met, but it could add context about the return structure or ordering.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is front-loaded with the action and subject. It is appropriately sized for a parameterless tool, though it could be slightly more informative without becoming verbose. It avoids redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (no parameters, no output schema), the description sufficiently conveys what the tool does. It is clear that it returns a list of checkpoints and timestamps, which covers the essential requirements for an agent to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With zero parameters, the baseline is 4 per the rubric. The schema is empty, and the description correctly adds no parameter details since there are none. No semantic gap exists.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists all available design checkpoints and timestamps. This is a specific verb (list) on a specific resource (design checkpoints) and naturally distinguishes it from siblings like create_checkpoint or rollback_checkpoint, which perform different actions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage by the nature of the operation (inspect checkpoints before rollback or decision), but it does not explicitly mention alternatives or when not to use it. For a simple listing tool with no parameters, this is adequate but not explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the behavioral disclosure burden. It does this well by explaining deep clone behavior, automatic artboard positioning, and the exact shape of returned identifiers including the descendantIdMap. It is not exhaustive about edge cases or side effects, but covers the core behaviors clearly.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is moderately detailed with five sentences, each contributing operational or output information. The example of using the map to call setTextContent is useful, though the final sentence could be slightly trimmed without losing meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutating tool with no annotations and no output schema, the description covers the essential behaviors: what gets cloned, how artboards are handled, and what is returned, including a mapping to reference clones directly. This gives an agent enough context to invoke the tool and use its result correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with both nodes and fileId already described in detail. The description adds context about deep cloning and the descendant map, but it does not meaningfully expand on 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb and resource: 'Duplicate one or more nodes in the design,' and adds that it creates a deep clone including descendants. This distinguishes it from sibling tools like move_nodes, delete_nodes, or create_artboard.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied: an agent should call this when it needs clones of existing nodes, and the descendantIdMap guidance hints at how to use the result. However, the description does not explicitly state when to prefer this over alternatives or any conditions where duplication is inappropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral burden and does substantive work: it reveals the transformation logic (inversion of surfaces/borders/typography) and the preservation constraint (brand accents), and implies the source artboard remains unchanged by using 'existing' and 'variant'. It could disclose output/return behavior more explicitly, but the core side effects are visible.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
One tightly packed sentence front-loads the core action and resource, then adds behavior details without repetition or filler. Every phrase earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 5-parameter create operation with no output schema and no annotations, the description gives enough context to select and invoke it correctly: source artboard, target mode, and transformation behavior. It stops slightly short of describing the result/return of the new variant, which would make it fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already names artboardId, targetMode, and optional positioning. The description reinforces the semantic distinction between the two modes and what gets inverted, but adds no parameter-specific detail beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description names a specific verb ('creates'), a specific resource ('Light or Dark mode variant of an existing artboard'), and a distinctive mechanism (inverting surfaces, borders, typography while preserving brand accents). This clearly separates it from siblings like create_artboard and generate_responsive_variants.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The intended use is implicit: invoke when a Light/Dark variant of an existing artboard is needed. However, it never states when not to use it or names alternatives such as generate_responsive_variants or duplicate_nodes, leaving routing to the agent's inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It makes clear this is a read-only lookup and specifies the exact data sources: the user's machine and Google Fonts. It does not describe error behavior or return format, but those are minor for this simple lookup.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences deliver the core purpose, scope, and data sources with no wasted wording. The main outcome is front-loaded, and the supporting detail about lookup sources is placed efficiently in the second sentence.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a simple one-parameter, side-effect-free lookup, and the description is nearly complete: it states what information is returned, where it is looked up, and what input is needed. The main omission is a detailed response shape, but there is no output schema and the domain is straightforward enough that the description is sufficient for tool selection and invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and the single 'familyNames' parameter is already clearly documented as an array of font family names. The tool description adds no additional parameter nuance beyond what the schema 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific action ('get information'), a specific resource (font family), and the outcomes: availability plus all weights and styles. It also adds the two lookup sources, local machine and Google Fonts, which distinguishes it from generic info-gathering siblings like get_basic_info or get_node_info.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is useful when font family availability or weight/style details are needed, and it provides context about where fonts are searched. However, it does not explicitly state when to prefer this tool over alternatives, nor does it mention exclusions, prerequisites, or fallback behavior.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully carries the behavioral burden. It discloses that the artboard auto-places in the best empty spot, defaults to flex column layout, conditions paper-gen:// URL image generation on user request plus guide reading, and requires a status bar for mobile with a specific get_guide call. This is exceptionally transparent 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is structured with a clear opening sentence and bullet points, front-loading the core purpose and return value. It is relatively long but every section adds distinct value—default sizes, mobile handling, and follow-up action. It does not repeat schema content, so it is efficiently organized for its complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a create tool with a nested styles object and no output schema, the description covers the return value, default sizes by device, mobile-specific instructions, and a follow-up action (fit-content via update_styles). It lacks error-handling or edge-case detail, but given the rich schema and cross-tool references, it is sufficiently complete for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so all parameters (name, fileId, styles) are defined in the schema. The description adds default size presets and some styles guidance, but these are more behavioral defaults than parameter semantics. The added value over the schema is marginal, so a baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb-resource pair: 'Creates a new artboard (top-level frame) on the canvas' and mentions the returned node ID for subsequent use. However, it does not explicitly distinguish from sibling tools such as batch_write_artboards or create_page, though the purpose is unambiguous and specific to a single artboard.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides clear contextual guidance: when to use default sizes, when to call get_guide for mobile status bar, and how to handle clipping with update_styles. It does not explicitly name alternatives or state when not to use this tool, but the guidance is actionable and covers key usage decisions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral disclosure burden, and it covers the key mutation ('create'), the scope ('active team'), and the result (returns ID). It does not discuss permissions, persistence details, or edge cases, but for a straightforward file-creation action the main behavior is transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences with no wasted words: the first states the action, scope, and return value; the second gives the essential next step. 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.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a low-complexity create tool with fully documented optional parameters, the description is complete enough: it states the return value (file ID), clarifies that the file is created but not automatically opened, and points to the follow-up tool. No output schema or extra return-value explanation is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Both parameters, name and cloneFileId, are already fully documented in the schema, so the description does not need to repeat them. The description adds no new parameter-level meaning, but this is acceptable because schema coverage is 100%.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Create'), a concrete resource ('new Paper file'), and the scope ('user's active team'), and it names the returned value (file ID). It also distinguishes itself from open_file by specifying the follow-up call. Sibling tools like create_page and create_artboard target different object types, so the file-level purpose is clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives useful workflow context: after creating a file, call open_file with the returned ID. However, it does not explicitly say when to choose create_file over sibling creation tools or when not to use it, so selection guidance is mostly 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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must cover behavioral disclosure. It explains the per-entry return format, the ordering dependence, and aliasing, but does not mention idempotency or whether existing tokens are overwritten. It also doesn't explicitly state that duplicate names are allowed (though that's in the schema). This leaves some ambiguity about conflict behavior, so 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single compact paragraph that leads with the action, then returns format, then ordering rules. It contains only necessary details and is logically ordered, though the ordering rules are a bit dense.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema, the description specifies the return object shape. It covers aliasing, ordering, and reuse preference, and the schema covers fileId and token fields. The only missing aspect is explicit error handling specifics, but the return format handles that. For a creation tool, this is complete enough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already covers all parameters at 100%, so the baseline is 3. The description adds value by detailing the `value` parameter's use of `var()` for aliasing and providing ordering constraints that depend on parameter values. This goes beyond the schema, so a 4 is justified.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb-resource pair ('Create one or more design tokens') and clarifies scope via the alias instruction and return format. It clearly distinguishes from siblings like set_tokens (which implies modification) and audit_design_tokens (which is analysis).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly provides ordering rules and a preference for reuse over creation, which serves as a guideline for when to use this tool versus reusing existing tokens. It does not explicitly compare to set_tokens, but the context implies creation is for new tokens.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden and covers meaningful behavior: imageGeneration status transitions (processing/ready/error), the need to poll for completion, and the error result when the node does not exist. It does not discuss side-effect safety or failure modes beyond missing nodes, but for a read operation the disclosure is strong.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the purpose and main return fields, and every sentence adds information about behavior or sibling routing. It is somewhat dense and could be structured into bullet points, but there is no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Without an output schema, the description covers the return shape in enough detail for an agent to know what to expect, including the async image-generation fields. Minor ambiguities such as what 'size' means and lock-state value formats are not clarified, but the overall context is sufficient for a node-info getter.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents nodeId and fileId. The description mostly restates nodeId as 'specific node by ID' and does not add parameter-specific meaning beyond what the schema's fileId and nodeId descriptions already provide, so it stays at the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
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: 'Get detailed information about a specific node by ID,' then enumerates the exact fields returned (size, visibility, lock state, parent, children IDs, text, positions, imageGeneration). This is unambiguous and distinguishes it from sibling getters like get_basic_info or get_children by the depth and scope of the returned data.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives context for the polling workflow ('poll this to know when generation completes') and routes image output to the correct sibling tools ('Raster fills are read with get_fill_image; SVG output is read with get_jsx'). It does not explicitly contrast with get_basic_info or get_children or give a when-not-to-use condition, so it is slightly short of full guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the burden. It openly says 'searches' and 'injects,' making the mutation and lookup behavior explicit. It could say more about what happens on failure, whether the icon is appended or replaces content, or how the result is reflected in the document, but it does not mislead.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence with no filler. Every phrase contributes either the action, the resource type, the icon families, or the insertion target.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Inputs and the insertion target are well covered by the description and fully documented schema. However, with no output schema and no annotations, the description does not state what the tool returns or how the agent can confirm the icon was inserted, leaving a small but real gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds meaningful context by identifying the allowed icon libraries and framing `name` as a search term, which goes beyond the schema's examples and helps the agent choose valid values.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a precise action ('searches and injects') on a specific resource ('vector icon ... directly into a container node in Paper'). Naming Lucide, Phosphor, and Heroicons clearly distinguishes this from media-insertion siblings like insert_curated_media.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'directly into a container node' gives clear context for when this tool applies. It does not explicitly name alternative tools or say when not to use it, but the icon-specific wording provides enough guidance for an agent to select it over non-icon options.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
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 explicitly discloses a critical behavior (cascading deletion of descendants) and warns about a potential pitfall related to incorrect parents. While it doesn't cover all behaviors (e.g., reversibility, permissions), it highlights the most important ones for safe invocation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, consisting of one sentence for the main action and a second sentence for the important caution. The core purpose is front-loaded, and the caution is placed immediately after, making it efficient and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with no annotations and no output schema, the description provides the essential information: what it does, the cascading effect, and a safety verification step. It lacks details on return values or error handling, but those are not critical for correct invocation given the simplicity of the operation. The description is sufficiently complete for an agent to call it appropriately.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 100%, with both parameters (fileId and nodeIds) already fully described in the input schema. The description adds no additional semantic detail about the parameters, so it does not exceed the baseline expected when the schema is thorough.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific action (delete) on a specific resource (nodes) and adds the cascading behavior (deletes all descendants). This distinguishes it from siblings like duplicate_nodes, move_nodes, and rename_nodes, which perform different operations on nodes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a concrete usage guideline: before deleting nodes with a suspected incorrect parent, verify using get_node_info. This is a specific prerequisite that helps the agent decide when to use this tool vs. gathering more info. However, it does not explicitly name alternatives or when not to use the tool, leaving the main usage selection implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. It discloses non-obvious behavior: files are listed in two groups (open first, then recently accessed) and timestamps are missing for files outside the active team. This goes beyond what the input schema reveals.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short, information-dense sentences with no filler. The core result is stated first, and the important caveat about timestamps is placed second. Every clause contributes value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only list with one optional parameter and no output schema, the description is nearly complete. It clearly says what is returned and the caveat about missing timestamps; the only minor gap is that it does not describe the overall response envelope or that page/pagination is absent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for the single limit parameter, which already documents default, range, and sorting by updatedAt. The tool description adds no parameter-specific meaning, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: 'Lists Paper files' and immediately distinguishes what it includes (open files, then recently accessed files in active team). This makes it clearly different from sibling tools like open_file, create_file, and list_checkpoints.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context about what subset of files is returned and the ordering, so an agent can infer when to call it. It does not explicitly name alternatives or exclusion conditions, but the purpose is specific enough that selection is not ambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
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 explicitly reveals the important stateful side effect of setting the working file, and it discloses that the return value matches get_basic_info. It does not mention persistence, permissions, or cancellation semantics, but the key behavioral trait is clearly stated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences, each serving a distinct purpose: the primary action, the stateful side effect, and the return value. There is no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter tool with no output schema, the description covers the input formats, page behavior, stateful consequence, and return value by referencing get_basic_info. The only minor omission is a more exact return shape, but the reference to get_basic_info is acceptable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 fileId formats (bare ID, /file/<id> route, full URL) and pageId behavior. The description adds no new semantic detail beyond restating ID/URL and page selection, so it earns the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action and resource: 'Open a Paper file by its ID or URL, optionally at a specific page.' It also distinguishes itself from get_basic_info by noting the stateful side effect of targeting subsequent calls, which makes its unique role clear among the large sibling toolset.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly signals the intended use case by explaining that after calling it, subsequent calls without fileId will target this file. It does not explicitly state when to avoid it (e.g., preferring get_basic_info for one-off reads), but the behavioral context is strong enough to guide selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of behavioral disclosure. It communicates a smooth, view-only camera movement and does not imply data mutation. It could add an explicit note that this is non-destructive, but 'pans and centers the camera' is reasonably transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence with no filler. It front-loads the action, then states the goal, making it easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a low-complexity camera tool with two parameters and no output schema, the description is mostly complete. A minor gap is that it doesn't state what happens when fileId is omitted (e.g., current file), but the schema and overall simplicity keep this from being a serious omission.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 restates 'node or artboard' but does not add meaning beyond the schema; fileId semantics remain only 'Optional target file ID.'
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb phrase ('pans and centers') with a clear resource ('Paper canvas camera') and target ('specific node or artboard'). It also states the purpose (letting the user see what the agent is working on), which separates it from camera tools like set_camera_zoom or zoom_to_fit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'so the user can see what the agent is working on' gives clear context for when to invoke the tool. It does not explicitly name alternative tools or say when not to use it, but the usage intent 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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It meaningfully discloses that the tool mutates display names, truncates names over 50 characters, and supports batching. It does not cover failure behavior or undo/reversibility, but the core mutation is clearly communicated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three short sentences with no redundancy. It front-loads the core action, then adds the display-name detail, truncation rule, and batch capability, each earning its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter tool with complete schema coverage, the description is nearly sufficient. It covers the core operation and key edge-case behavior, though it does not describe return values or what happens when an update targets a nonexistent node.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents both parameters. The description adds value beyond the schema by specifying the 50-character truncation rule for the name parameter and clarifying that updates accepts batch renames in a single call.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb and resource: 'Rename one or more layers in the design' and specifies the exact effect, 'Sets the display name shown in the layer tree.' This distinguishes it from sibling tools like delete_nodes, duplicate_nodes, and move_nodes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The intended use is implied from the description, but there is no explicit comparison to alternatives or conditions for when not to use this tool. The batch-rename mention provides some capability context, but no guidance on when to choose this over related node-manipulation tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits on its own. It clearly indicates this is a state-changing operation by using 'set', but it does not mention any side effects, permissions required, reversibility, or what happens if the thread is already in the target status. While the operation is straightforward, the description lacks depth on consequences, which is important for a mutation tool without annotation support.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is composed of three concise sentences. The first sentence states the core purpose, the second explains when to use each status, and the third provides a pointer to find the required ID. Every sentence has a purpose, and the structure is front-loaded with the most critical information. There is no redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple setter with no output schema, the description covers the purpose, the usage context, and how to find a required parameter. It does not describe return values or error behavior, but for this type of operation, that is often obvious (success/failure). Given the low complexity and complete parameter documentation, the description is sufficiently complete, though it could mention idempotency or permission requirements.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already documents all three parameters with 100% coverage, so the baseline is 3. The description adds value by explaining the semantics of 'status': it clarifies that 'resolved' is used when feedback is fully addressed and 'open' for reopening, which goes beyond the enum definition. It also contextualizes how commentThreadId relates to other tools. However, it does not add information about fileId, which the schema already covers, so the added value is moderate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'Set the workflow status of one comment thread to resolved or open.' It specifies the resource (comment thread), the verb (set), and the two allowed states. It also explains when to use each state, distinguishing it from siblings like get_comment_thread or list_comment_threads which read or list, while this one mutates.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says when to resolve ('once its feedback has been fully addressed') and when to reopen ('if more work turns out to be needed'). It also recommends using list_comment_threads or get_comment_thread to find the commentThreadId, which is practical guidance. However, it does not explicitly mention when not to use this tool or what to do if the thread is already in the desired state, which is a minor gap.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It usefully discloses the Text-node restriction and batch behavior, but it does not mention side effects such as whether existing formatting is preserved, whether the operation is reversible, or what happens when a node is not a Text node. For a mutation tool this is a meaningful gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three tight sentences, each adding distinct value: what the tool does, when to use it, and its batch capability. No fluff or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter setter with a fully documented schema, the description covers the core invocation details, constraints, and alternative routing. It does not elaborate on error behavior or formatting effects, but those are not necessary for an agent to select and call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so both parameters are already fully described in the input schema. The description reinforces the batch concept and node-type restriction, but adds no new parameter-level detail 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb and resource ('Set the text content of one or more Text nodes'), states the exact node type it applies to, and explicitly distinguishes itself from writeHTML replace. An agent can immediately understand what this tool does and how it differs from close alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit guidance: use this instead of writeHTML replace when only text needs to change. It also notes the Text-node-only restriction and batch support, making it clear when this tool is the right choice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
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 key behaviors: combining nodes, one page per node, auto-ordering by canvas position, and quality/resampling being the highest among existing PDF settings. It does not mention side effects (e.g., whether it modifies files, overwrites, or requires auth), but for a non-mutating export operation, the disclosed details are substantial and add 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences and front-loads the core function, then provides the comparative usage and quality detail. No extraneous information; every sentence contributes.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and two params, the description covers the essential context: what it does, ordering, and the alternative. It does not explain the return value or any error conditions, but for a straightforward export tool these are minor gaps. The description is adequate for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers both parameters thoroughly (fileId and nodeIds) with descriptions, so the schema provides the necessary semantics. The description adds no additional parameter-specific information, 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'Export multiple nodes combined into a single PDF file, one page per node.' It identifies the resource (nodes) and the output (PDF), and differentiates from the sibling 'export' by noting it merges nodes into one file instead of separate files. This distinguishes it from alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly specifies when to use this tool: 'Use this instead of "export" when the user wants the nodes merged into one PDF rather than separate files.' This gives a clear condition and names the alternative, fulfilling the 'explicit when/when-not/alternatives' criterion.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full burden of behavioral disclosure. It states the tool only reads a guide, implying no side effects, but it doesn't explicitly confirm read-only behavior or describe what the response contains (e.g., text, format). This is a minor gap, but users can infer the operation is non-destructive from the verb 'read'. A brief note on return type would elevate this, but the current description is adequate for a simple informational tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, with the primary function and key recommendation in the first sentence, followed by a compact list of additional topics. Every sentence contributes practical information, and there is no redundancy or filler. The structure front-loads the critical 'call first' advice, making it highly efficient for an agent to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only guide tool, the description and schema together cover the essential aspects: what the tool does, when to use it, and what parameters to pass. The absence of an output schema is compensated by the description's clarity that it 'reads a guide', implying a textual return. The only minor gap is not specifying the response format or any potential latency, but these are non-critical for an informational tool. Overall, it is complete enough for an agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides thorough descriptions for the 'topic' parameter, covering all valid values and their meanings (100% coverage), which sets a baseline of 3. The description adds value by recommending a specific topic for initial usage ('paper-mcp-instructions'), which is actionable guidance not present in the schema. This extra usage hint justifies a score above baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'read' and the resource 'detailed guide on a specific topic', making the tool's function unambiguous. It also lists example topics, which reinforces what it operates on. While it doesn't explicitly differentiate from siblings, it is obviously distinct from design manipulation tools, so no confusion arises.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly instructs to call with topic 'paper-mcp-instructions' before using other Paper tools, providing concrete when-to-use guidance. It also enumerates available topics, giving the agent a clear set of valid inputs. There are no alternatives to rule out, so the guidance is complete.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries the full burden. It discloses the base64 return format, automatic size capping, and the practical implication of scale choices. It does not mention potential failure modes or whether the capture is viewport-dependent, but the disclosed behavior is meaningful.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Four sentences, no filler. The purpose is front-loaded, the output format follows, and the scale guidance is structured as a clear conditional. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description still conveys return type and size-limiting behavior. The fileId parameter is fully explained in the schema. Minor omissions like error cases and exact cap thresholds do not prevent correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds real value by explaining when to use scale=1 vs scale=2 and the child-node workaround, which the schema does not fully convey.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Capture a screenshot of a specific node by ID') and describes the return format (base64-encoded data). This clearly differentiates it from sibling tools like export, get_fill_image, or get_jsx.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance on when to use scale=1 vs scale=2, and advises capturing child nodes for higher resolution. It does not compare against alternative output tools, but the scale and node-capture guidance is concrete and actionable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the transparency burden. It adds meaningful behavior details: only visible messages are counted, and deleted threads/messages are never counted. It also states what data is returned. It could additionally mention read-only behavior or ordering/pagination, but the core behavioral semantics are covered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences deliver the purpose, output fields, usage context, and a key behavioral rule. The primary action is front-loaded and every sentence earns its place with no repetition of schema content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The definition covers purpose, usage context, returned fields, and the deleted-item exclusion. With no output schema, the description supplies enough return-shape information. It omits minor details like sort order or pagination, but for a simple optional-parameter listing tool the agent has what it needs to call correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with fileId and pageId both already explained in the input schema. The description's mention of 'open file' aligns with fileId but does not add parameter-specific syntax or constraints beyond what the schema provides, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb ('List'), a precise resource ('every user who has started a comment thread or written a visible message in the open file'), and the output fields. It clearly differentiates from the sibling list_comment_threads by focusing on authors rather than threads.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly states when to use the tool: 'Use this to resolve a person's name to a userId before filtering list_comment_threads by participantUserId or threadAuthorUserId.' This names the relevant sibling and the exact condition that selects this tool, leaving no ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden of disclosure. It clearly states mutating behaviors (update, rename, delete) and adds useful runtime detail: one result per entry and in-band per-entry errors. It does not discuss persistence implications or rollback, but the destructive action is explicitly surfaced.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact, front-loaded with the main purpose, and uses bullets to enumerate operation modes without redundancy. Every sentence contributes operational value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers all core operations and return behavior, which matters because there is no output schema. It relies on the schema for fileId and description-param details, which is acceptable given 100% schema coverage. A concrete example would improve completeness slightly, but nothing essential is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds meaningful semantics beyond the schema, especially the alias pattern 'Use var(--other-token) to alias' and the optionality relationship between name, newName, value, and delete.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb-resource pair: 'Update or delete existing design tokens', and further specifies targeting by 'full CSS variable name'. This clearly differentiates it from related siblings like create_tokens and audit_design_tokens.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives concrete usage branches (rename, update value, delete), making it clear when this tool applies. It stops short of explicitly naming alternatives or saying 'use create_tokens for new tokens', but the word 'existing' provides an implicit exclusion.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It discloses key behaviors: inert styles are dropped and returned under ignoredStyles, top/left on artboards move the canvas, and paper-gen URLs require explicit user request and guide reading. This is substantial, though it does not cover all potential side effects (e.g., reversibility, permission requirements).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the primary purpose, then uses concise bullets for important caveats. Every sentence adds actionable information without fluff. The structure is easy to scan and understand.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (array of updates, no annotations, no output schema), the description covers key behavioral aspects like batch support, ignored styles, and URL handling. It does not mention error handling or return format beyond ignoredStyles, but for a style update tool, the provided information is sufficient for an agent to use it correctly in most cases.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
While the schema already documents all parameters (coverage 100%), the description adds meaning by noting that top/left on artboards affect position, and that design tokens can be used as CSS variables. It also explains the ignoredStyles return property, which relates to parameter outcomes. This goes beyond the schema's baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (update), the resource (styles on nodes), and the scope (one or more nodes, targeted changes). It also highlights batch support. This distinguishes it from sibling tools like move_nodes (positions) and set_text_content (text), making its purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly says 'Use this for targeted style changes,' providing a clear context of use. It also gives specific guidance for edge cases (top/left on artboards, paper-gen URLs, ignoredStyles). However, it does not explicitly mention alternative tools for other types of changes or exclusion scenarios, which prevents a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the transparency burden. It clearly discloses the side effect (creates a page), the non-switching behavior, and the returned page ID. It omits edge-case behavior such as duplicate-name handling or persistence details, but covers the main behavioral traits an agent needs.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the core purpose, and no redundant or repetitive content. Every clause contributes useful information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple creation tool with two optional parameters and no output schema, this description is complete. It tells the agent what the tool does, how to target a file, what it returns, and what follow-up call is needed to work in the new page.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds meaningful context for fileId by explaining the active-file vs explicit-file distinction and the multi-agent parallel scenario, which goes beyond the schema's wording. The name parameter is also tied to the display name behavior.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource ('Creates a new page') and clarifies the two possible targets: the active file or an explicit file via fileId. It also notes the return value, making it easy to distinguish from sibling tools like create_artboard and create_file.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides clear context on when to omit fileId (active file) versus pass it (reliable targeting when multiple files are open), and it explicitly directs the agent to call open_file afterward. It does not, however, explicitly contrast create_page with sibling creation tools or state 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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral disclosure burden. It discloses the state-changing effect, the all-or-selected behavior, and the no-argument default. It doesn't cover edge cases like repeated calls or what happens when no indicators exist, but for this simple lifecycle action the core behavior is transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short, front-loaded sentences with no filler. The 'MUST call' instruction is first, followed by the behavioral summary and parameter guidance. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is low-complexity: no required parameters, no output schema, and both optional parameters are fully documented. The description explains when to call it, what it does, and how to choose between releasing all or a subset, so an agent has enough to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 both parameters fully. The description adds little beyond a slight rewording, and it refers to 'artboard IDs' where the schema says 'node IDs,' so it doesn't meaningfully improve parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action and resource: removing the working indicator from artboards/nodes being edited, which distinguishes it clearly from the many read/write siblings. The verb 'release' and the object 'working indicator' are concrete, and the scope is specified.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly says 'MUST call this when done working,' giving a clear trigger condition. It also explains the choice between no arguments (release all) and specific IDs (release only some), which is exactly the decision guidance an agent needs.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden and does well: it lists the returned aspects, states it works for any status, and explicitly notes deleted threads/messages are never returned. This gives the agent useful expectations without requiring an output schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences with zero filler: the main action and scope come first, followed by the prerequisite routing hint and a key exclusion. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple, the schema fully covers parameters, and the description explains what will be returned and when to call the sibling list tool. No critical information needed to invoke it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already fully documents both parameters with 100% coverage, so the description need not add much. It implies the commentThreadId is required and that fileId targets a specific file, but this aligns with schema descriptions. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with a specific verb and resource ('Get full details for one visible comment thread') and enumerates exactly what is included. It clearly differentiates from siblings like list_comment_threads and set_comment_thread_status.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit guidance to call list_comment_threads first when the commentThreadId is unknown, which is a clear routing hint. It stops short of stating when not to use this tool or comparing to all close siblings, but the usage context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
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 return format (base64 JPEG), resizing behavior, inclusion of original URL in metadata, and all error/message outcomes. This is exceptionally transparent for a tool with no structured annotation context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a compact paragraph with no redundancy. It front-loads the core action, then efficiently covers resizing, the URL fallback, and all error cases. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given there is no output schema, the description covers the return format (base64 JPEG), handling of large images, the original URL, and all failure modes (missing node, no image fill, SVG, still generating). It references the relevant sibling for SVG and the polling mechanism for pending images. Nothing essential is missing for an agent to call this correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% – both fileId and nodeId have explicit descriptions. The tool description adds no additional parameter-level meaning beyond the schema. Since the schema already documents semantics, the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Extract'), a resource ('image data from a node that has an image fill'), and clearly distinguishes itself from siblings by explicitly naming get_jsx for SVG cases. Its purpose is unambiguous and immediately actionable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear conditions for use: it works on nodes with image fills, and explicitly routes SVG cases to get_jsx. It also advises polling get_node_info when images are still generating. It lacks broader exclusions (e.g., when to use get_screenshot or export instead), but the primary alternative is addressed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It clearly states the output shape (compact indented text tree), the information included per node, and the error condition when the node does not exist. It does not explicitly state that the operation is read-only or describe any side effects, but the 'get' prefix and summary nature make the mutation profile clear enough.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences with no wasted words. It front-loads the core purpose and output format, then immediately provides comparative guidance against a sibling tool, and closes with the error behavior. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple, the schema covers all parameters, and the description compensates for the absent output schema by describing the return value (indented tree with node fields). It also covers failure mode and usage intent. An agent has enough information to decide whether to call this tool and to interpret its result correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 schema fully documents nodeId, depth, and fileId. The description does not add new parameter-level meaning beyond what the schema already provides, and that is acceptable given the complete schema coverage. It does reference the depth-limited behavior indirectly by describing the summary, but no additional semantic value is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb ('Get'), a resource ('a node's subtree hierarchy'), and the exact output format (indented tree with component type, name, ID, and dimensions). It also differentiates itself from sibling get_jsx by emphasizing that it is a cheap, compact alternative. An agent can confidently identify what this tool does and how it differs from similar tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly compares this tool to getJSX ('Much cheaper than getJSX for understanding structure') and tells the agent exactly when to use it: 'for orientation before diving into specific nodes.' This provides clear routing guidance and implies when not to use it, without requiring the agent to infer usage from the schema.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description covers all critical behavioral details: exact matching logic (wildcard anchoring, color equivalence, token resolution), case-insensitivity, AND semantics, and the result shape ('matched' array with fragments). It even explains edge cases like composite values (gradient/border). This is thorough and goes well beyond what a schema could convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but information-dense, with a logical flow: purpose → scoping → filter semantics → text matching → result details. Every sentence adds unique value; there is no fluff or repetition. However, it could be slightly more compact by grouping related matching rules, and front-loading the purpose is done well. The length is justified by the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex search tool with no output schema and no annotations, this description is exceptionally complete. It covers all parameters, matching subtleties, AND logic, result structure, and edge cases. An agent would have everything it needs to invoke the tool correctly and interpret results. No obvious gaps remain given the tool's scope.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although schema coverage is 100%, the description adds substantial semantic value beyond the schema. It explains the structure of filters objects, the meaning of wildcards in styleName and styleValue, token vs. literal matching, color equivalence, and the special behavior of finding token-bound usages. It also clarifies textValue pattern anchoring and case-insensitivity. This goes far beyond the schema's per-field descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb+resource: 'Find nodes by computed style and/or text content.' It explicitly mentions the use case for locating tokens, literal values, or copy before bulk updates, which distinguishes it from generic node traversal tools like get_children or query_nodes. The specificity of matching modes (style, text, AND) makes its purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides concrete guidance on when to use the tool (e.g., 'before a bulk update') and how to scope the search (whole page vs. node subtree). It clearly explains the AND combination of filters and textValue, and describes wildcard and matching rules. However, it does not explicitly name alternative tools or state conditions for choosing this over query_nodes or get_computed_styles, 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.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It reveals the default open-only filter, that results are compact summaries, that only "visible" threads are returned, and that "Deleted threads/messages are never returned." It also explains the "current-user" sentinel for user ID filters. These are meaningful behaviors beyond what a minimal read/list tool would imply.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is efficiently structured: the core action comes first, followed by a brief domain definition, default behavior, routing to siblings, filter summary, user ID note, and the deleted-item exclusion. Every sentence adds value for a tool with 14 parameters and no annotations, with no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (14 parameters, no output schema, no annotations), the description provides enough context for an agent to call it correctly. It explains the concept of comment threads, the open/resolved status model, the default behavior, the workflow with sibling tools, and key exclusions. Nothing critical is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 a high-level summary of filter categories ("page, node, status, author, search, sort, and pagination filters") and notes the "current-user" sentinel, but these details already exist in the schema's parameter descriptions. The description does not need to compensate for any schema gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: "List visible comment threads in the open file as compact summaries." It also defines what a comment thread is (a conversation pinned to a node with messages and status), and implicitly distinguishes itself from siblings by naming get_comment_thread for full replies and set_comment_thread_status for marking threads done.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-to-use and alternatives: "Use this first to discover relevant discussion, then call get_comment_thread for full replies." It also explains when to use set_comment_thread_status, and describes the default filter ("Lists only open threads by default"). This gives clear routing compared to sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and delivers extensively. It discloses real-time visual feedback, the one-item-per-call behavior, interaction constraints (e.g., avoid full-artboard absolute elements), unsupported features, and asset URL conventions. This richly compensates for missing annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but organized into clear sections with imperative rules, which is justified given the tool's complexity. It front-loads the most critical behavioral instructions with IMPORTANT. Some repetition occurs around incremental creation, but each rule earns its place because violations materially affect output quality.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex, high-guidance tool with no annotations and no output schema, the description is exceptionally complete. It covers layout rules, styling constraints, fonts, colors, asset handling, layer naming, code blocks, and AI image generation caveats. An agent has enough context to call this tool correctly in a wide range of design scenarios.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds substantial meaning to the html parameter by specifying valid HTML/CSS patterns, disallowed properties, and required inline-style conventions. It also clarifies expected output granularity, which helps agents form correct calls even though it does not add new detail to fileId, targetNodeId, or mode.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: each write_html call creates one visual item (header, list row, button bar, paragraph block) on the canvas. It also specifies the intended granularity, distinguishing it from broader or bulk operations like batch_write_artboards. The purpose is concrete and actionable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage instructions: write incrementally, create one visual item per call, prefer cloning over recreating nodes, and use the duplicate tool for repeated elements. It also explains how to structure repeated elements (container first, then children). This is strong, operational guidance beyond a simple when-to-use statement.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It covers identity preservation, sequential batch application, flex vs freeform parent behavior, style adjustments, invalid targets, and what is returned. This is exceptionally transparent 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but tightly organized into purpose, two shape alternatives, selection guidance, notes, and return behavior. Every section earns its place and the most important usage guidance is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex mutating operation with no output schema and no annotations, the description is complete: it explains both input shapes, edge cases, constraints, return values, and even how to refresh the tree model efficiently using affectedParents. Nothing needed for correct invocation is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although schema coverage is 100%, the description adds significant meaning beyond the schema: the 'root' shortcut, index clamping semantics, sequential application across moves, and inferred parent behavior for sibling-relative moves. It substantially improves the agent's ability to construct correct parameter payloads.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description begins with a specific verb and resource: 'Move one or more existing nodes.' It also explicitly distinguishes itself from alternatives like duplicate+delete or rewriting HTML, and the sibling list includes duplicate_nodes/delete_nodes, making the differentiation meaningful.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit when-to-use guidance: 'Prefer this over duplicate+delete or rewriting HTML when you just want to reposition or reparent existing layers.' It also tells the agent which shape to choose: sibling-relative when a neighbor is known, parent-absolute when targeting a specific parent or appending.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

GitHub Badge

Glama performs regular codebase and documentation scans to:

Confirm that the MCP server is working as expected.
Confirm that there are no obvious security issues.
Evaluate tool definition quality.

Our badge communicates server capabilities, safety, and installation instructions.

Card Badge

Copy to your README.md:

[![paper-cdp-mcp MCP server](https://glama.ai/mcp/servers/vvmahesh0/paper-cdp-mcp/badges/card.svg)](https://glama.ai/mcp/servers/vvmahesh0/paper-cdp-mcp)

Score Badge

Copy to your README.md:

[![paper-cdp-mcp MCP server](https://glama.ai/mcp/servers/vvmahesh0/paper-cdp-mcp/badges/score.svg)](https://glama.ai/mcp/servers/vvmahesh0/paper-cdp-mcp)

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/vvmahesh0/paper-cdp-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server