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 discloses the key behavioral trait: requires planKey from whoami, and it explicitly warns against calling when a file is open. It also states the expected output. It does not elaborate on side effects, error handling, or reversibility, but for a file-creation tool the key constraints are covered, making it largely transparent.

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

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

The description is compact and well-structured. It front-loads the purpose, states the expected output clearly, and places the critical usage constraint (planKey and alternative tool) in the IMPORTANT note. Every sentence earns its place with no fluff.

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

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

For a tool with four parameters, three required, and no output schema, the description is complete: it explains the purpose, prerequisites, expected output, and usage boundaries. The combination of schema coverage and description covers everything an agent needs to call it correctly.

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

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

Schema description coverage is 100%, so the schema already documents all parameters, including the planKey pattern, potential values for editorType, and optional projectId. The description adds no new parameter meaning beyond what the schema provides; the only extra mention is that planKey comes from whoami, which is already in the schema description. Baseline of 3 is appropriate.

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

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

The description states a precise verb (creates), a specific resource (new Figma design, FigJam, or Slides file), and the scope (drafts or specified project). It also explicitly distinguishes from the sibling use_figma by specifying when not to use it, so an agent can clearly separate 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.

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

It gives explicit when-to-use context (create a new blank file) and when-not-to-use (if user already has a file open, use use_figma instead). It also names a required prerequisite (planKey from whoami), making the usage conditions unambiguous.

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

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

Annotations are absent, so the description carries the burden of behavioral disclosure. It usefully reveals the output shape: { export, rawImages, svgAssets }, and notes cross-file transfer intent. However, it does not mention auth requirements, possible empty arrays, latency, or failure modes. For a non-destructive download, the disclosed output is adequate but not rich.

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

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

Three short labeled lines—Do what, Expected output, Use when—make the purpose immediately clear. Information is front-loaded, there is no filler, and every sentence earns its place.

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

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

Even without an output schema, the description provides an explicit expected output shape and clear usage scenarios. The schema covers most parameters. The main gaps are the absence of explicit alternatives and operational caveats, but for a straightforward asset-download tool it is largely complete.

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

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

Schema description coverage is 75%, and the schema already documents nodeId, defaultScale, and defaultFormat. The description adds no parameter-level detail and fileKey remains undocumented, but it does not need to restate what the schema already covers. Neutral contribution.

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

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

The description opens with a specific verb and resource: 'Downloads rendered exports and raw source images/SVGs for a single node.' This clearly distinguishes the tool from broader file-level or screenshot-related siblings. The expected output line further reinforces the exact purpose.

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

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

The 'Use when' section explicitly names concrete scenarios: needing a rendered PNG/SVG/PDF of a node or extracting embedded raster fills for cross-file transfer. It gives clear context for when to invoke the tool, though it does not name alternative sibling tools or describe when not to use them.

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

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

No annotations are provided, so the description carries the full burden. It discloses that the tool launches the user's default browser, returns a clickable Markdown URL, and produces a JSON with auth_url, markdown_link, and instructions. This gives the agent a good sense of what happens and what to expect, even without 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.

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

The description is organized with 'Do what' and 'Expected output' sections, which makes it skimmable. It is not overly verbose and each segment adds value. However, the 'LOCAL TOOL' prefix and the split into labeled sections make it slightly less concise than a tight two-sentence description, but still well-structured.

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

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

For a zero-parameter, no-output-schema tool, the description covers the essential context: what action it performs, how it behaves (browser launch), what output to expect, and when to call it. It does not mention edge cases like browser failure or re-authentication flows, but for this simple tool the description is sufficiently complete.

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

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

The tool has zero parameters and the input schema is empty, so per calibration rules the baseline is 4. The description does not need to explain parameters, and it appropriately focuses on behavior and output.

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

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

The description states a specific action (starts interactive one-click OAuth authorization) and a resource (Figma), and clarifies what the tool produces (a URL and instructions). It clearly differentiates from siblings like figma_auth_status by focusing on initiating login rather than checking status.

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

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

Explicitly states when to use the tool ('when authentication is missing, expired, or when the user wants to connect their Figma account'). While it does not name alternative tools explicitly, the conditions imply when not to use it (e.g., when already authenticated). This is clear context without a direct exclusion list.

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

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

With no annotations, the description carries the behavioral disclosure burden. It clearly labels the tool as LOCAL, uses the non-destructive verb "Inspects," and identifies that it reads active access tokens and secure storage. This gives agents a good sense of read-only, local behavior, though it does not explicitly state "no side effects" or discuss permission implications beyond mentioning secure storage.

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

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

The description is compact and well-structured: a headline "LOCAL TOOL — Checks current Figma authentication status," followed by a concise "Do what" line and an explicit "Expected output" JSON shape. Every sentence adds value, no fluff, and key information is front-loaded.

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

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

For a zero-parameter, read-only status tool with no output schema, the description is complete. It enumerates all expected output fields (authenticated, user, email, expires_at, is_expired, storage_path), making the return value fully understandable without an output schema. No prerequisites or edge-case behavior seems missing for correct invocation.

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

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

The tool has zero parameters and the schema is fully empty (100% coverage, no required properties). The baseline for 0 params is 4, and the description appropriately focuses on output rather than inventing parameter details. No compensation is needed.

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

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

The description uses a specific verb and resource: "Checks current Figma authentication status," then elaborates with details about inspecting access tokens, user seat, expiry time, and storage location. This clearly conveys the tool's purpose, but it does not explicitly differentiate it from sibling tools like whoami, which may also return user/email information.

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

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

The description does not state when to use this tool versus alternatives. There is no mention of using it before Figma API calls or choosing it over whoami for user identity. The intended context is only implied by the tool's name and purpose, giving no explicit guidance or exclusion criteria.

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

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

No annotations exist, so the description carries the full burden. It does disclose that the tool is local, detects an open desktop file, and returns a specific JSON structure. However, it leaves ambiguous whether authentication may be triggered and what happens if the desktop app is not running or 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.

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

The description is compact and well-structured with labeled sections: 'LOCAL TOOL', 'Do what', and 'Expected output'. The most important instruction, calling this first, is front-loaded, and every sentence contributes useful information.

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

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

For a zero-parameter tool with no output schema, the description provides the critical context: when to call it, what it detects, and what JSON it returns. It stops short of covering failure modes or authentication edge cases, but the included instructions array and expected output offer enough guidance for an agent to proceed.

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

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

The input schema has zero parameters, so it is already complete; the description does not need to document parameter meaning. The expected-output block mentions fileKey and nodeId, but those are return values, not inputs, so no additional parameter semantics are required.

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

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

The description names a specific verb and resource: 'Detects which Figma file the user currently has open in Figma desktop app', and lists the returned fields. It also differentiates itself from siblings by explicitly saying to call it first before any other Figma tool when no URL/fileKey is provided.

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

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

The description gives an explicit invocation condition: use this tool first whenever the user has not provided a Figma URL or fileKey. This clearly tells the agent when to use it and implies the reverse condition for skipping it, making the usage boundary unambiguous.

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

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

With no annotations, the description carries the full behavioral burden, but it only discloses the expected URL and the markdown-link instruction. It does not mention side effects, authentication or plan requirements, error behavior, or whether a new file is created versus an existing file modified.

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

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

The description is concise and well-structured, with the action and expected output front-loaded in two short sentences. There is no filler or redundant restating of the tool name.

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

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

For a mutation tool with no annotations and no output schema, the description is incomplete. It fails to explain prerequisites like planKey from whoami, the role of fileKey, or behavior around new versus existing files, leaving important context gaps for correct invocation.

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

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

Schema description coverage is 100%, so parameters are already documented in the input schema. The description adds no extra meaning beyond tying the tool to Mermaid.js syntax, which is sufficient for a baseline score.

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

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

The description states a specific action, resource, and input format: creates flowchart, sequence, state, gantt, or ER diagrams in FigJam from Mermaid.js syntax. It also names the expected output, making the tool's purpose unmistakable even without reading the schema.

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

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

No explicit guidance is given about when to use this tool versus alternatives like create_new_file. It also omits prerequisites such as needing planKey from whoami or an existing fileKey, so the agent must infer usage context from the description alone.

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

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

With no annotations, the description carries the behavioral burden. It clearly identifies the tool as a READ operation, specifies the expected output shape ({ code, screenshot, assets, metadata }), and describes a required call-order dependency on figma_get_current_context. It doesn't mention auth/rate limits or failure modes, but for a read-only tool these gaps are minor.

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

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

The description is organized into short labeled blocks (Do what, Expected output, IMPORTANT) and every sentence carries practical guidance. It is slightly longer than necessary but remains easy to scan and free of filler.

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

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

For a tool with 7 parameters, no output schema, and no annotations, the description provides purpose, expected output shape, usage preference, prerequisite, and required-parameter handling. It doesn't explain failure behavior or all optional-parameter effects, but the schema covers most parameter semantics and the description covers the operational essentials.

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

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

Schema description coverage is 71%, and the schema already documents most parameters well (nodeId extraction, fileKey, clientLanguages, etc.). The description reinforces that nodeId is required and must not be empty, but adds little semantics beyond the schema for optional params like forceCode or disableCodeConnect.

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

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

The description opens with 'Primary READ tool for design-to-code' and enumerates exactly what it returns (layout, styles, component props, reference code snippet, screenshot, asset URLs). It explicitly distinguishes itself from the sibling get_metadata with 'Always prefer this over get_metadata for design inspection,' making the tool's role unambiguous.

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

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

The description states when to prefer this tool over get_metadata and gives an explicit prerequisite: 'Call figma_get_current_context first if you do not know the fileKey.' It also warns about nodeId extraction. It doesn't cover exclusions for other sibling tools (e.g., get_screenshot) but provides clear context for the main alternative.

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

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

No annotations are provided, so the description carries the burden. It discloses the /design/ file restriction, the root-at-nodeId vs top-level-pages behavior, and the output format (XML string). It doesn't mention auth requirements or rate limits, but the sibling auth tools and the read-only nature of the operation are reasonably inferable. The description adds meaningful behavioral context beyond the schema.

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

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

The description is compact and front-loaded: the main action and output are stated first, then usage guidance, then the critical restriction. Every sentence earns its place; no filler.

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

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

For a read-only exploration tool with a clear output format and explicit usage guidance, the description is nearly complete. It doesn't describe pagination or depth limits of the XML tree, and it doesn't mention auth requirements, but the sibling auth tools and the simple two-parameter schema make those gaps minor.

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

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

Schema description coverage is 100%, so the schema already documents both parameters. The description adds the semantic meaning of omitting nodeId (lists pages) and the fileKey extraction hint is already in the schema. It doesn't add much beyond the schema, but the 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.

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

The description states a specific verb ('Returns'), a specific resource ('XML document outline for a Figma design file'), and enumerates the content (node IDs, layer names, types, positions, sizes). It also distinguishes itself from get_design_context by name, so an agent can tell them apart.

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

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

Explicitly says to use this to explore unfamiliar files before calling get_design_context, and to prefer get_design_context for design-to-code. It also states the /design/ file restriction and the nodeId-omitted behavior. This is clear when-to-use and when-not-to-use guidance.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It mentions a 'short-lived CDN URL' and provides the expected output structure, which is useful. However, it does not disclose authentication requirements, rate limits, side effects (e.g., read-only nature), or failure behavior. This is a significant gap 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.

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

The description is reasonably concise, using a 'Do what' and 'Expected output' structure that is easy to parse. It front-loads the action and output, with no redundant filler. The 'IMPORTANT' note is slightly redundant with the schema but serves as a quick reminder.

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

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

For a tool with 5 parameters and no output schema, the description provides the output structure, which is helpful. However, it lacks details on error scenarios, authentication context, and usage scenarios. Given the complexity and lack of annotations, the description is adequate but not complete.

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

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

The input schema has 100% description coverage for all 5 parameters, each with a clear description. The tool description does not add semantic meaning beyond what the schema provides, merely restating that fileKey and nodeId are required. Per calibration, a baseline of 3 applies when schema fully documents parameters.

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

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

The description clearly states it renders a PNG screenshot of any node and returns a CDN URL and curl command. This distinguishes it from metadata and design-context tools, though it does not explicitly name alternatives. The verb 'renders' and resource 'node' make the purpose specific.

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

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

No guidance is given on when to use this tool versus siblings like get_metadata or download_assets. It only notes that both fileKey and nodeId are required, which duplicates schema information. There is no mention of use cases, exclusions, or prerequisites beyond required parameters.

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

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

With no annotations, the description carries the full burden, and it delivers a stated output contract: a map of variable names to resolved values with an example. It also clarifies the scope ('referenced by a node'), though it does not mention auth prerequisites, empty results, or failure modes.

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

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

Three short labeled sentences each carry distinct information: behavior, output format, and use case. No filler or redundant restatement, and the key action is front-loaded.

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

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

For a two-parameter read operation with no output schema, the description gives enough to invoke it correctly: what it takes, what it returns, and when to use it. It lacks only edge-case or auth details, which are non-critical for this simple call.

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

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

Schema coverage is 100%: both required parameters, fileKey and nodeId, already have descriptions with patterns and examples. The tool description adds no parameter-specific semantics, so the baseline 3 applies.

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

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

The description opens with a precise verb-resource pair: 'Returns all design variables (tokens) referenced by a node', listing concrete categories (colors, spacing, typography) and the output shape. This makes it clearly distinguishable from sibling tools like get_metadata and get_screenshot, which target different resources.

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

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

The last sentence gives an explicit intended use case: 'Use to extract the design system token palette before writing code or creating new nodes.' This is clear context, though it does not state alternatives or exclusion conditions relative to tools like get_design_context.

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

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

With no annotations present, the description carries the full burden and does a good job by disclosing supported formats, single-use URLs, the need to POST raw bytes, and the expected output shape. It does not mention authentication requirements or side effects on the Figma file, but the core behavioral contract 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.

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

The description is compact, front-loaded with the purpose, and every sentence carries useful information: formats, return URLs, the follow-up POST action, and the expected output. There is no filler or redundancy.

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

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

For a tool with no annotations and no output schema, the description provides the crucial output contract and workflow. Still, it omits context such as authentication prerequisites, how fileKey relates to the target file, the meaning of scaleMode, and whether providing nodeIds immediately mutates fills.

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

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

Schema description coverage is 60%, and the description adds no direct parameter-level meaning. The required fileKey and the scaleMode parameter are left undocumented in both the schema and the description, and there is no explanation of how count or nodeIds map to the upload workflow.

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

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

The description clearly identifies the action: 'Uploads images (PNG, JPG, GIF, WebP) or SVGs into a Figma file.' It also names the output behavior and separates this tool from siblings like download_assets by specifying the upload direction and exact workflow.

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

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

The description implies when to use the tool: whenever images or SVGs need to be uploaded into Figma. However, it gives no explicit when/when-not guidance or alternatives, such as mentioning download_assets for retrieval or use_figma for broader operations.

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

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

With no annotations, the description carries the full behavioral burden. It discloses that mutations are applied live to the canvas, that the output is JSON-serializable, and it lists critical constraints: required use of setCurrentPageAsync, forbidden APIs (loadAllPagesAsync, setPluginData, createImageAsync), and specific font-style spelling. This is thorough and goes beyond the schema, which is essential for a tool that executes arbitrary code.

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

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

The description is well-structured with clear sections: 'Do what', 'Expected output', and 'CRITICAL RULES'. The purpose is front-loaded, and every sentence contributes to understanding the tool's behavior or constraints. It is detailed but not verbose, making it easy to parse efficiently.

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

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

For a complex tool with arbitrary code execution and no output schema, the description covers expected output format, live mutation behavior, and critical API usage rules. It does not explain error handling or authentication, but those are likely handled by other tools and the schema. The omission of the optional `skillNames` parameter is minor given that the schema documents it. Overall, an agent has enough to call this tool correctly.

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

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

The schema already describes all parameters with 100% coverage. The description adds significant value beyond the schema by clarifying the `code` parameter's execution context (access to `figma` global, sandbox constraints) and emphasizing that `fileKey` and `description` are required. It also documents the font-style convention, which is critical for correct code generation but not present in the schema.

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

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

The description states 'PRIMARY WRITE TOOL' and explicitly says it 'Executes arbitrary JavaScript against the Figma Plugin API sandbox to create, edit, delete, or query any design element.' This is a specific verb+resource+scope that clearly distinguishes it from sibling tools like figma_auth_login or get_design_context, which are read/auth oriented.

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

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

The description explicitly labels itself as the 'PRIMARY WRITE TOOL', making it unambiguous that any mutation to the Figma canvas should go through this tool. While it doesn't name read siblings, the contrast between 'write' and the read-only tools is sufficient to guide selection. It also gives critical usage rules (e.g., must use setCurrentPageAsync) that affect invocation.

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

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

With no annotations provided, the description carries the full burden and does well: it reveals the output structure ('Expected output: { handle, email, plans: [...] }') and indicates a read-only, identity-introspection behavior. It doesn't discuss failure modes or authentication requirements, but for a simple whoami tool 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.

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

Three short, labeled sentences: 'Do what', 'Expected output', and a usage warning. Each sentence serves a distinct purpose, information is front-loaded, and there is no wasted text. This is a model of concise, structured tool documentation.

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

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

For a zero-parameter, no-output-schema tool, the description fully equips an agent: it provides the return shape venue and the exact scenario (permissions errors, create_new_file prerequisite) in which this tool must be called. Nothing critical is missing for successful invocation.

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

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

The tool has zero parameters和一 empty schema, so the baseline is 4. The description does not need to explain parameter semantics, and it adds no irrelevant parameter information. The expected output structure actually compensates for the absence of an output schema.

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

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

The description states a specific verb ('Returns') and a precise resource: the authenticated user identity (handle, email), plans/teams, and available seats. It is unambiguous and clearly distinct from sibling tools like figma_auth_status or get_current_context by naming the exact payload elements.

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

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

The description explicitly says 'MUST call this if experiencing permission errors or before calling create_new_file to resolve planKey.' This gives a clear, actionable trigger. It does not explicitly name alternatives or state when not to use it, but the directive is strong enough for an agent to know when it is the right tool.

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