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

Beyond the annotations (readOnlyHint, openWorldHint), it discloses the multi-step nature (GET + downloads), the host restriction, the specific output shape, the skip policy with a default, and explicitly states 'Not canvas mutation' confirming non-destructiveness. This adds meaningful operational context beyond the annotation flags.

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

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

Each of the four sentences carries distinct information: role, endpoint/mechanism, output, skip policy, and non-mutation. There is no filler and the key purpose is front-loaded. Even the final 'Not canvas mutation' earns its place by removing any ambiguity about mutability, reinforced by existing annotations.

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

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

The description gives the essential input-output contract for a read-only helper with no output schema: the mapping result, the default size cap, and host constraint. It doesn't fully cover max_assets or error behaviors, but for a simple parameterized filter-and-bundle operation, agents have enough to invoke it correctly.

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

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

Schema coverage is only 50% (file and image_refs have descriptions; max_bytes and max_assets do not). The description adds the default for max_bytes (250KB) and clarifies the imageRef return mapping, but does nothing to explain max_assets. The description partially compensates for the missing schema coverage, but max_assets semantics remain unclear.

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

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

The description states the specific action and resource: it fetches image fills from GET /v1/files/{key}/images, downloads them, and returns a mapping of imageRef to metadata. It also clearly differentiates from siblings like get_image_fills by adding 'download each fill' and 'Not canvas mutation', so an agent can select the right tool without opening schemas.

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 context ('Design-to-code helper'), a host restriction (Figma/S3 only), and a behavioral constraint (skips assets over max_bytes). However, it never names alternatives or gives an explicit 'use this when X' vs. 'use get_image_fills when Y', so the agent must infer the when-to conditions rather than being told.

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

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

Annotations indicate readOnlyHint=false and openWorldHint=true, so the description doesn't need to restate that it's a write operation. However, it adds no behavioral context beyond the endpoint: no mention of idempotency, whether it overwrites existing resources, what happens on duplicate names, or required auth scopes. The openWorldHint=true suggests unknown side effects, but the description doesn't clarify.

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

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

The description is a single concise sentence with the endpoint and scope front-loaded. It earns its place, though it could be slightly more informative without becoming verbose.

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 create/write tool with no output schema and sparse parameter descriptions, the description is incomplete. An agent doesn't know what the response will be, whether the operation is idempotent, or what the 'name' and 'url' fields semantically represent. The sibling list shows related dev resource tools, but the description doesn't connect to them.

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

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

Schema description coverage is only 25% (only 'file' has a description). The description adds no parameter-level meaning beyond the schema. It doesn't explain what 'name' is for, what format 'url' should take, or how 'node_id' relates to the node. With low coverage, the description should compensate but doesn't.

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

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

The description states a specific verb ('attach') and resource ('Dev Mode URL to a node'), and includes the HTTP endpoint and scope. It is clear what the tool does, though it doesn't explicitly distinguish it from sibling tools like update_dev_resources or delete_dev_resource beyond the create action implied by the name.

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

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

No guidance on when to use this tool versus alternatives. It doesn't mention that update_dev_resources should be used for modifying existing resources, or that delete_dev_resource is for removal. The scope string is present but not explained as a prerequisite or permission requirement.

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

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

Annotations indicate readOnlyHint=false and openWorldHint=true, meaning it's a mutating tool with side effects outside the sandbox. The description adds critical behavioral detail: it triggers a PING verification on creation unless status=PAUSED, and it requires a passcode for endpoint verification. This goes beyond the annotations to explain the side-effect behavior and a prerequisite, which is valuable for an agent deciding if it can proceed.

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

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

A single sentence jam-packed with high-value information: HTTP method, path, side-effect (PING), status override, scope, and passcode requirement. No filler, front-loaded with the most critical fact (PING). It earns its place completely.

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 7-parameter tool with 5 required, no output schema, and mutations, this is highly complete. It tells the agent the essential: it's a POST, it will trigger a verification PING, it needs the webhooks:write scope, and it needs a passcode. The schema covers parameter specifics, and there's no output schema to explain return values. No side-effects or prerequisites are left undisclosed. Add a sibling distinction and it would be flawless.

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 43%, meaning the schema already describes endpoint, passcode, context_id, and event_type (the major ones). The description doesn't add parameter-level details, but it does state the passcode is required for verification (which is in schema but emphasizes its purpose) and clarifies the status enum's effect on PING. It doesn't repeat all schema details, which is fine; the key semantic boost is the PING/status interaction.

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

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

States a specific verb+resource (create webhook) and immediately adds detail: the HTTP method, path, and two critical side-effects (PING on create unless PAUSED, and scope requirement). This distinguishes it from sibling webhook tools like update_webhook or delete_webhook. It is 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?

States the scope requirement (webhooks:write) and the passcode requirement, which is essential when-to-use context for an agent to know it needs authorization and a verification code. It does not explicitly name alternatives (e.g., list_webhooks, update_webhook) but the purpose and side-effect disclosure imply when to create versus update. No when-not-to-use guidance, but for a create tool that's less critical.

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

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

Annotations already mark destructiveHint=true and readOnlyHint=false, but the description adds meaningful context beyond that: the author-only restriction and the required OAuth scope file_comments:write. This helps the agent understand prerequisites and authorization.

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

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

The description is a single, compact sentence that front-loads the action and includes the endpoint, auth constraint, and scope. No wasted words.

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

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

For a simple delete operation with two required parameters, no output schema, and annotations covering destructive behavior, the description adds the necessary auth context. It doesn't mention response format or error cases, but these are not critical for a delete action.

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

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

Schema coverage is only 50% (comment_id has no description). The tool description does not compensate by explaining the comment_id format or any parameter-specific details, leaving a significant gap for a required parameter.

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

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

The description states a specific verb (delete) and resource (comment), and includes the HTTP endpoint, making it unambiguous. It clearly distinguishes from siblings like post_comment and get_comments by its action and target.

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

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

The description provides important context (only the author can delete, required scope) but does not explicitly contrast with alternatives or state when to use this tool versus others. The usage is implied by the name and action, but not explicitly guided.

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

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

Annotations indicate destructiveHint=true and readOnlyHint=false, so the description correctly aligns with a mutating, destructive operation. It adds the author-only restriction, which is behavioral context beyond the annotations. No contradiction exists.

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

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

A single sentence conveys the endpoint, the key restriction, and the resource. No filler or redundancy; all content is purposeful and front-loaded.

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

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

For a simple delete operation with three required parameters and no output schema, the description covers the essential information: what it does and a key constraint. It doesn't mention success/error responses, but annotations and the simplicity of the action make this acceptable.

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

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

Schema description coverage is only 33% (only 'file' has a description). The description mentions comment_id and emoji in the endpoint URL but does not explain their formats or semantics, such as what the emoji value should be (code vs. character) or how comment_id is structured. With low coverage, the description fails to compensate.

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

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

The description clearly states the action (DELETE) and the specific resource (comment reaction) targeted by file key, comment_id, and emoji. It distinguishes from sibling tools like post_comment_reaction and get_comment_reactions by indicating deletion. The author-only restriction adds precise scope.

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

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

It provides a key usage condition (only the author can delete), which informs when this tool is applicable. While it doesn't explicitly contrast with alternatives, the deletion action is unambiguous and the sibling set makes the choice clear. The absence of explicit alternative routing 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.

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

Annotations already include destructiveHint=true and readOnlyHint=false, so the destructive nature is covered. The description adds the scope requirement, which is useful for authorization. However, it does not disclose what happens on success (e.g., response status), irreversibility, or side effects beyond the annotation.

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

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

The description is a single sentence that efficiently conveys the endpoint and scope. It is appropriately short, but it could be slightly more explanatory without adding noise. The key information (method, path, scope) is front-loaded, so it scores well on structure.

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

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

For a simple delete operation with two parameters, the description is minimally sufficient. However, it omits expectations about the response (e.g., 200/204 status), error conditions, or idempotency. Given no output schema, an agent might not know what to expect after a successful call. Annotations cover destructive nature, so it's 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?

Schema description coverage is 50%: only 'file' has a description in the schema, while 'id' is just a string with minLength. The description itself adds no new semantics—it merely repeats the path placeholders {key} and {id}. It does not clarify what 'id' refers to or how to obtain it, leaving the agent under-informed for half the 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 the HTTP method (DELETE) and the resource path (dev_resources), making it unequivocal that this tool deletes a dev resource. The scope line further confirms it's a write operation, and the title reinforces the action. It is easily distinguished from siblings like get_dev_resources or delete_comment by the resource type and method.

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

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

The description provides the required scope (file_dev_resources:write) which is a usage prerequisite, but it does not explicitly state when to use this tool versus alternatives like update_dev_resources or create_dev_resources. There is no mention of conditions favoring deletion over other operations, so guidance is minimal.

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

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

Annotations already mark this as destructive and read-only=false, so the bar is lower. The description adds valuable 'irreversible' language and the required scope ('webhooks:write'), giving the agent a clearer picture of consequences and permission requirements beyond raw annotations.

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

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

The description is extremely concise, front-loads the core action, and each element ('DELETE /v2/webhooks/{id}', 'irreversible', 'scope: webhooks:write') earns its place. No filler or redundancy.

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

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

For a simple single-parameter destructive operation, the description covers the essential context: the HTTP method, resource path, irreversibility, and required scope. It does not describe response behavior, but for a delete endpoint that is often a simple 204 status, so the description is reasonably 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 coverage is 0%, and the description does not directly explain the webhook_id parameter meaning beyond the URL path '{id}'. While the parameter name is self-explanatory, the description adds minimal semantic value beyond what the schema already shows.

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

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

The description names the exact HTTP verb and resource path ('DELETE /v2/webhooks/{id}'), making the tool's action unmistakable. It also distinguishes from sibling tools like get_webhook and update_webhook by clearly indicating deletion.

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 it: when a webhook must be removed or deleted. However, it provides no explicit guidance about when NOT to use it or alternatives that might be more appropriate, leaving usage to inference rather than direct instruction.

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

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

The description discloses the traversal behavior and the returned fields, and notes the default depth. It does not explain important behaviors such as whether hidden/off-canvas text is included, what 'copy' means, or how depth interacts with the optional ids parameter; annotations cover read-only but not these operation details.

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

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

The description is a single compact sentence that packs the operation, output shape, and default depth without padding. It is 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.

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

It gives core behavior and output shape but lacks usage context: no mention of when to use this instead of get_nodes/find_nodes, no user prerequisites, and no discussion of traversal limits beyond the default depth. The 'copy' wording is ambiguous and there is no note about large files or excluded nodes, so an agent may misjudge cost and applicability.

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

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

The schema describes file and ids well, but depth and limit are only defined by type bounds with no semantics. The description adds the default depth but does not clarify whether ids are required for partial extraction or how limit applies to traversal.

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

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

The description clearly states that the tool walks TEXT nodes and returns a structured copy with id, name, characters, and parentId. The title and description together make the core purpose understandableais. It does not explicitly contrast with get_nodes or find_nodes, but the focus on TEXT nodes gives enough distinction.

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 instead of sibling tools like get_nodes, find_nodes, or get_design_context_lite. It provides no exclusions, prerequisites, or alternative recommendations, so the agent is left to infer usage from the title and schema.

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

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

The description discloses the underlying behavior: it fetches a file tree and locally filters to matching nodes, returning only a specific subset of fields. Since readOnlyHint already signals non-mutating behavior, this additional internal mechanism is useful and adequate.

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

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

The description is extremely compact, immediately states the operation, then lists the return subset and key usage caveat. No wasted or vague prose.

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

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

There is no output schema, so listing the returned fields is valuable. The description also explains the internal mechanism (fetch file tree, filter matches) and the precondition (name and/or type). It does not mention rate/cost implications of fetching a large file tree, but covers the essentials for invocation.

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

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

Schema coverage is high, but the description adds meaningful semantic guidance: name and/or type are required as filters, and the return payload is limited to the listed fields. This helps the agent understand how the optional parameters actually function together, despite the schema only enforcing `file`.

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 a specific action: fetch a file tree and return only nodes matching name/type filters, with a limited field subset. It also explicitly positions itself as a utility rather than a REST endpoint, which distinguishes it from sibling tools like get_file and get_nodes.

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

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

Explicitly says 'Prefer this over dumping get_file to locate a frame', giving clear when-to-use guidance. It also states the input precondition 'Requires name and/or type'. It does not explicitly contrast with get_nodes, but the guidance is strong enough to route an agent correctly.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, covering the read-only nature. The description adds one behavioral detail: 'auto-follows pagination.next_page.' This is useful context beyond annotations. However, it does not disclose response format, potential errors, or rate limits, so it provides only minimal added value.

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

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

The description is extremely concise—a single phrase that includes the full endpoint and the pagination behavior. It is front-loaded and every word earns its place. The brevity is appropriate for a simple GET tool, though one could argue it under-specifies the return value.

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

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

Given the tool's simplicity (3 parameters, no output schema) and the context of many sibling tools, the description is insufficiently complete. It does not state what the response includes (e.g., reactions with emoji and user), does not mention any prerequisites, and offers no rationale for when to pick this tool. A single-line endpoint reference leaves the agent guessing about the actual data returned.

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 67% (file and auto_paginate have descriptions; comment_id does not). The description only echoes the endpoint placeholders ({key}, {comment_id}) without adding any semantic explanation, and it fails to compensate for the undocumented comment_id parameter. It adds no insight beyond what the schema already provides.

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

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

The description explicitly states the HTTP endpoint 'GET /v1/files/{key}/comments/{comment_id}/reactions', which unambiguously identifies the resource and action. The tool name 'get_comment_reactions' reinforces this. It is clearly distinct from siblings like post_comment_reaction and delete_comment_reaction by method and intent, though it does not explicitly say 'retrieves all reactions for a comment'.

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

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

The description provides no guidance on when to use this tool versus alternatives. There is no mention of scenarios where this should be preferred over get_comments or the reaction mutation tools, nor any exclusions or prerequisites. The readOnlyHint annotation hints at safety, but the description itself does not contextualize usage.

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

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

Annotations already provide readOnlyHint and openWorldHint, so the safe-read profile is covered. The description adds useful behavioral detail beyond those annotations by disclosing that the response is the complete comment list and that pagination is not used, plus the optional as_md behavior.

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

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

The description uses two sentences to convey endpoint, operation, pagination behavior, and a parameter option. There is no filler or repetition; each clause earns its place.

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

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

The tool definition is simple enough that the description is mostly adequate: the agent knows what is returned, that it is not paginated, and that as_md is possible. However, because there is no output schema, the description does not otherwise describe the shape or useful fields of the comment objects, which leaves a minor gap.

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

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

The input schema already covers both parameters completely at 100% coverage, so the description is not required to add much. The only additive text, 'Optional as_md,' mostly repeats the schema's boolean/markdown behavior rather than explaining deeper semantics like format details or defaults.

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

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

The description identifies a specific verb and resource: GET /v1/files/{key}/comments and 'Figma returns the full comment list.' The 'not cursor-paginated' qualifier adds a scope that distinguishes it from other comment-related tools such as get_comment, post_comment, and delete_comment.

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

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

Usage is implied: this is clearly the read-all-comments tool for a file. However, it does not explicitly state when to use it instead of get_comment, get_comment_reactions, post_comment, or delete_comment, so the agent must infer the intended selection rather than being told.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds the HTTP method, the endpoint shape, and the required OAuth scope library_assets:read, which are useful behavioral details beyond the annotations.

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

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

One sentence carries the endpoint, resource type, key-type distinction, and auth scope with no filler. The key disambiguation is front-loaded and every clause earns its place.

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

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

For a simple, single-parameter read-only lookup, the description provides enough to select and invoke the tool correctly. The absence of an output schema means some detail about the returned metadata shape is not stated, but the endpoint and scope are sufficient for a metadata fetch.

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

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

Schema coverage is 100% and the schema already fully describes the single key parameter as 'Published component key from library metadata.' The description does not add meaningful parameter semantics beyond the schema, 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?

States a specific verb and resource: GET /v1/components/{key} returns metadata for a published component. It differentiates the scope clearly by noting the key is a library key, not a file key, which separates it from sibling tools like get_file_components and get_team_components.

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 makes clear this is for published component keys from library metadata and excludes file keys, giving the agent a usable decision rule. It does not explicitly name alternative tools, but the context is clear enough to route away from file-level or team-level component tools.

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

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

Annotations already mark readOnlyHint and openWorldHint, but the description adds valuable behavioral context: 'REST-only' implies a different execution path than the full MCP, 'best-effort CSS flex' signals possible approximation, and 'Image fills are refs' reveals that pixel data is not included. These details go beyond what annotations provide.

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

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

The description is three sentences: the first states the core purpose and contents, the second adds the disambiguation from the official tool, and the third explains image fills and alternatives. It is front-loaded with the most critical information and contains no redundant phrasing.

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 snapshot tool with six well-documented parameters and no output schema, the description covers what output to expect (identity, bbox, CSS, text, fills), the nature of image fills, the optional token summary, and a caution about its unofficial status. Nothing essential for correct invocation is missing.

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

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

Schema coverage is 100%, so parameters are already well-documented. The description adds extra meaning for include_tokens, explaining it attaches a compact token summary with variables or labeled fallback and that it's optional to keep the tree small. It also gives context for the overall output, enriching the meaning of 'depth' and 'max_nodes' without repeating schema details.

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

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

The description states a clear verb and resource: 'REST-only codegen snapshot for a subtree' and immediately lists the content (identity, bbox, CSS flex, text, fills, component ids). It distinguishes itself from the 'official MCP get_design_context' and names alternatives for image fills, making it unmistakable among siblings.

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

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

The description explicitly warns 'Not official MCP get_design_context' and instructs to 'use get_images or bundle_image_fills for pixels,' which gives clear when-not guidance and alternatives. It doesn't explicitly compare to other get_* tools like get_nodes or get_file, but the context about REST-only and the 'lite' intent is enough to infer appropriate use.

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

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

Annotations already expose readOnlyHint and openWorldHint, and the description adds important behavior: it requires library_content:read, builds tokens from styles, and marks every inferred token with inferred: true. This clarifies that the result is not actual Figma variable data without contradicting the annotations.

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

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

Two sentences with no filler. The front-loaded warning to skip the variables API is immediately useful, and the inferred: true behavior is stated plainly and concisely.

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

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

The tool has no output schema, so the description must carry the return-value burden. It explains the token source and inferred behavior but does not specify what full/trim/summary modes return or precisely how max_variables affects the result. That leaves an agent with important ambiguity before making a 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?

Description adds real meaning for node_id by explaining the consequence of omitting it, and it maps the inferred token categories to a subtree. However, mode and max_variables remain unexplained beyond their raw schema metadata, so schema description coverage at 50% is only partially compensated.

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

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

The description states a concrete action and resource: build labeled tokens from file styles, with optional inferred geometry/spacing tokens. It also distinguishes itself from the Figma variables API by explicitly saying 'Skip the variables API' and clarifying that inferred tokens are not real variables.

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 useful contextual guidance: this is the fallback path that avoids the variables API, and the optional node_id is tied to whether paint values are available ('Without it, styles may be names-only'). It does not name specific sibling tools like get_file_styles, but the usage intent is reasonably clear.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is clear. The description adds the HTTP method and the required scope 'file_dev_resources:read', but it does not disclose behaviors like response shape, pagination, or whether empty results are possible. This is adequate but not rich.

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

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

The description is a single sentence with no filler. It front-loads the endpoint and purpose, then adds the scope in a compact way. Every word earns its place.

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

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

For a simple read tool with two parameters, high schema coverage, and read-only annotations, the description covers the essential facts: what it returns (Dev Mode links on nodes) and the required scope. It could mention response format, but the lack of an output schema is partially mitigated by the resource definition in the description.

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

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

Schema description coverage is 100%, so the parameters file and ids are already well-documented in the schema. The description adds no additional parameter-level meaning beyond what the schema provides, hitting the baseline for high coverage.

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

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

The description clearly states the HTTP verb and resource, saying 'GET /v1/files/{key}/dev_resources — Dev Mode links on nodes.' This is a specific verb+resource combination that differentiates it from siblings like create_dev_resources or delete_dev_resource by focusing on the read action for Dev Mode links.

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 implicitly conveys this tool is for retrieving Dev Mode links on nodes, but it does not explicitly state when to use it versus alternatives such as get_nodes or get_file_meta. No exclusions or routing guidance is provided, leaving usage somewhat implied.

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

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

Annotations already mark the tool as read-only and open-world. The description aligns with that by showing a GET operation, and adds the useful behavioral facts that depth defaults to 2 and mode trims/summarizes payloads. It does not discuss response size, limit/error behavior, or what the README clarifies, so it is adequate, not rich.

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

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

The description is short, front-loaded with the endpoint, and immediately surfaces the two most behaviorally relevant options. The reference to '(see README)' is the only weak spot, since it pushes out beyond this definition, but the overall structure is tight.

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

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

With 6 parameters, no output schema, and a large sibling list, the description is minimally sufficient because the schema carries most of the parameter context. It does not explain the response shape beyond 'file JSON', nor does it help the agent choose it over the many closely related tools.

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

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

Schema descriptions cover 100% of the parameters, so the baseline is 3. The description's mention of depth and mode mostly restates what the schema already says, and it adds no meaning for ids, version, geometry, or file key/URL handling.

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

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

The description names the exact REST operation.GET /v1/files/{key} — file JSON' and makes clear the tool returns a Figma file payload. It does not explicitly contrast with siblings like get_file_meta or get_nodes, so differentiation is inferred rather than stated.

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

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

There is no guidance about when to use this tool instead of get_nodes, get_file_meta, get_images, or the other file-scoped tools. The description mentions depth and mode, but offers no conditions, exclusions, or explicit alternative routing.

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

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

The readOnlyHint and openWorldHint annotations already cover the safety profile. The description adds the behavioral detail that only 'published' components are included and communicates the required scope. It does not describe response format or pagination, but for a simple GET the annotations plus description are adequate.

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

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

The description is a single, front-loaded line with the endpoint first, then the result, then the scope. Every word earns its place and there is no redundant content or boilerplate.

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

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

This is a low-complexity read tool with one well-documented parameter and safety annotations. Still, there is no output schema and no mention of what the response contains beyond 'published components,' and no guidance relative to siblings, so an agent is left with a few open questions about usable response structure.

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

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

Schema coverage is 100%, and the input schema already describes the one parameter ('Figma file key or URL') with validation and examples. The description adds no parameter-specific meaning, so the baseline of 3 is appropriate.

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

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

The description states a specific verb and resource ('GET /v1/files/{key}/components') and clarifies what is returned: 'published components in a file library.' It is distinguishably file-scoped, but it does not explicitly contrast itself with related siblings like get_file_component_sets or get_team_components, so the distinction is inferable rather than explicit.

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

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

There is no guidance on when to use this tool instead of a sibling, no exclusions, and no context such as 'use this when you need published components only.' The only additional note is the OAuth scope 'Scope: library_content:read,' which is an access requirement, not a usage guideline.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the agent knows this is a safe read operation. The description adds the scope 'published component sets in a file library' but does not disclose pagination, response format, or any filtering behavior. With annotations covering the safety profile, a 3 is appropriate.

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

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

The description is a single concise sentence that front-loads the HTTP verb and resource path. It is efficient and contains no filler. It could add a bit more context about what 'published component sets' means, but it earns a 4 for brevity and clarity.

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

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

For a simple read-only list tool with one parameter and no output schema, the description is mostly adequate. However, it doesn't mention whether the response is paginated, what fields are returned, or how it differs from get_file_components. Given the sibling tools and the lack of an output schema, a bit more context would help an agent select and invoke it correctly.

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

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

Schema description coverage is 100%, so the schema already documents the single 'file' parameter. The description does not add parameter-level detail beyond the schema, but the schema is sufficient. Baseline 3 is correct.

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

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

The description states a specific verb and resource: 'GET /v1/files/{key}/component_sets — published component sets in a file library.' It clearly identifies what the tool returns and the scope (file library). It doesn't explicitly distinguish from siblings like get_file_components or get_team_component_sets, but the resource path and 'published component sets in a file library' make the purpose reasonably clear.

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

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

The description implies usage context: it is for retrieving published component sets from a file library. It does not explicitly state when to use this tool versus alternatives like get_team_component_sets or get_file_components. The sibling list provides context but the description itself offers no when/when-not guidance.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true. The description adds value by specifying the auth scope and enumerating the returned fields, which is sufficient context for a simple read-only metadata operation.

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

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

One sentence conveys the endpoint, resource, returned fields, and auth scope with no filler. Every piece of information 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?

This is a single-required-parameter, read-only tool with no output schema. The description names the returned fields and the required scope, so an agent has enough context to select and invoke it correctly without major gaps.

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

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

Schema coverage is 100%, including the file key or URL format, so the structured schema already documents the parameter well. The description adds no further parameter-level detail beyond the schema, so baseline 3 is appropriate.

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

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

The description names a specific verb and resource ('GET /v1/files/{key}/meta') and lists the exact metadata fields returned (name, folder, thumbnail, role). 'Lightweight' clearly distinguishes it from the full-file sibling get_file.

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

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

The description implies usage context through 'lightweight file metadata' and the scoped permission 'file_metadata:read', so an agent can infer it is for metadata-only needs. However, it does not explicitly name alternatives or state when not to use this tool.

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

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

Annotations already provide readOnlyHint and openWorldHint. The description adds a concrete auth scope ('library_content:read') and clarifies that only published styles are returned, which is useful beyond the structured annotations. However, it does not disclose response shape, pagination, or any limits.

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-loads the endpoint and primary purpose before including the scope requirement. It wastes no words, though it could have packed slightly more utility into the same space.

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

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

The tool is simple (one param, read-only annotations, no output schema), so the description is nearly sufficient. It does not describe the return value format or clarify what 'styles' includes (e.g., metadata fields), but with low complexity and strong schema coverage, the gap is not critical.

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

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

Schema coverage is 100% for the single 'file' parameter, with the schema already explaining that it accepts a file key or URL. The description adds nothing beyond what the schema provides, so a baseline score of 3 is appropriate.

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

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

The title 'Get file styles' together with 'published styles in a file library' clearly identifies the resource (published styles) and the scope (a single file library). It is reasonably distinguishable from siblings like get_team_styles and get_style, though it does not explicitly name them.

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 such as get_style, get_team_styles, or get_file_components. It only mentions the OAuth scope and the file-library context, leaving the selection decision to the agent.

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

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

Annotations already declare readOnlyHint=true, so the read-only nature is covered. The description adds valuable behavioral details beyond annotations: automatic pagination following and the required OAuth scope (file_versions:read), giving the agent important invocation context.

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

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

A single compact sentence packs the endpoint, purpose, pagination behavior, and scope without waste. It is front-loaded with the key information, though a slightly clearer separation between purpose and behavior could make it even more readable.

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 moderately simple read tool with three parameters and no output schema, the description covers the essential behavioral context: endpoint, pagination, and scope. It does not explain the response format, but 'version history' gives a reasonable expectation; annotations cover the read-only safety profile.

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 67%, so the schema documents 'file' and 'auto_paginate' but not 'page_size'. The description's auto-pagination note reinforces the meaning of auto_paginate, but it does not address page_size sizing or behavior, leaving a gap that the schema does not fully fill.

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 ('get') and resource ('/v1/files/{key}/versions') and clarifies the purpose as 'version history'. This distinguishes it from sibling file tools like get_file and get_nodes, none of which target version history.

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

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

Usage is implied by the phrase 'version history' and the endpoint path, making it clear the tool is for retrieving version data. However, it does not explicitly state when to choose this over alternatives or when not to use it, which is a moderate gap.

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

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

Annotations already declare the tool read-only and open-world. The description adds that it returns download URLs for existing image fills, not a rendered node, which is a meaningful behavioral distinction. No contradictions found.

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

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

Two sentences front-load the primary purpose and then state the key exclusion/alternative. No wasted words.

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

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

The description fully explains what the tool returns (URLs) and how it differs from get_images. No output schema exists, but the operation is simple and annotations cover safety, so no critical missing detail.

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

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

Schema coverage is 100% for the single file parameter opportunely described as key or URL. The description doesn't add parameter-specific semantics beyond the schema, which meets the baseline.

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

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

The description names a specific verb and resource ('download URLs for images already uploaded as fills (imageRef)') and explicitly contrasts with get_images ('Not a node render'). This makes the tool's exact function unmistakable relative to its siblings.

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

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

It clearly identifies what this tool is for (fills that are already uploaded) and gives an explicit alternative with a condition: 'use get_images to rasterize frames.' An agent knows when to pick this tool over the sibling and when not to.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, covering the safety profile. The description adds that URLs are 'short-lived', which is useful context beyond the annotations. However, it does not mention rate limits, output structure (e.g., map of IDs to URLs), or limits on node count, so it adds only modest value.

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

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

A single sentence plus a one-line sibling distinction, with the core endpoint and behavior front-loaded. Zero wasted words and the key differentiator is placed last for emphasis.

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

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

The tool is simple; no output schema exists, but the description states the return format (image URLs) and default. It does not mention the alternative render_nodes_as_data_uri, which an agent might need to choose between, but the openWorldHint and readOnly annotations reduce the burden. Overall adequate.

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

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

Schema description coverage is 100%, and the schema already documents all parameters including the normalization of IDs and format defaults. The description does not add meaning beyond the schema (e.g., explains 'short-lived' URLs but that's not parameter-specific). Baseline 3 is appropriate.

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

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

The description states a specific verb ('render'), resource ('nodes'), and output ('short-lived image URLs'), with a default format. It also explicitly names a sibling tool it is distinct from (get_image_fills), making it easy to differentiate without reading schemas.

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 clearly distinguishes from get_image_fills, but does not mention the alternative render_nodes_as_data_uri or other rendering tools. There is no explicit 'when not to use' beyond the one sibling, leaving some inference needed for an agent choosing between rendering options.

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

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

Annotations already cover read-only nature. The description adds meaningful behavior: it is a raw REST call (no transformation/fallback) and includes consumed remote variables, which could surprise users expecting only local. No annotation contradiction.

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

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

One compact, information-dense sentence. Endpoint, auth, scope, and alternative tool all included without 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?

Single well-documented parameter; purpose, access requirements, and differentiation are all covered. Missing only explicit response shape, though 'raw REST' implies standard Figma API JSON, so the gap is 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 already fully explains the file parameter (Figma file key or URL, 100% coverage). The description's endpoint path reinforces the parameter's role but adds no new semantic detail beyond what the schema provides.

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

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

States the specific HTTP verb (GET), resource path (/files/{key}/variables/local), and scope (local + consumed remote). Distinct from siblings, and explicitly contrasts with get_variable_defs.

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?

Names the alternative tool (get_variable_defs) and the condition favoring it (codegen shape, automatic fallback). Also mentions access requirements (Enterprise, file_variables:read). Does not explicitly state 'use this when you want raw REST,' but that is strongly implied.

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

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

Annotations already establish readOnlyHint=true and openWorldHint=true, so the ethical bar is lower. The 'GET' verb and the mode list (trim|summary|full) are consistent with a read-only fetch and give a bit of functional context, but the description adds little detail about payload size behavior, limits, or results beyond what the schema properties already explain.

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

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

A single compact sentence that leads with the endpoint and the core selection mechanism, followed by the mode feature. There is no filler, and every word earns its place.

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

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

For a 5-parameter tool with no output schema and an unexplained 'geometry' parameter, the description is too thin: it gives no guidance on selection (why get_nodes vs find_nodes vs get_file), no mention of the undocumented parameter, and no expectations for results other than vague 'payload size' hints. The annotations cover safety, but the operational context is incomplete.

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 80%, and the description only reiterates the mode values already in the schema. It does not clarify the undocumented 'geometry' property or add format details for ids/file that aren't already in the schema. With high coverage, a baseline 3 is appropriate; the description neither compensates for the 20% gap nor conflicts with 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 the verb (GET), the resource (nodes in a file), and the scope ('specific nodes by id'), which lets an agent distinguish it from whole-file retrieval like get_file. It does not, however, contrast itself with find_nodes or get_design_context_lite, so sibling differentiation is partial rather than explicit.

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

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

There is no guidance about when to use this tool instead of alternatives. With siblings like find_nodes, get_file, and get_design_context_lite all dealing with node access, the agent must infer from the name and endpoint when this tool is the right choice; the description offers no when/when-not conditions.

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

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

Annotations already declare readOnlyHint and openWorldHint. The description adds useful behavioral context beyond that: it is a raw REST endpoint, omits valuesByMode, and requires Enterprise plan plus file_variables:read permission. This is meaningful transparency for a read-only API call.

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

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

The description is extremely compact: endpoint, key behavioral caveat, auth requirement, and preferred alternative are all packed into one short string. Every fragment earns its place and the endpoint 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 one-parameter read-only tool with no output schema, the description covers the essentials: what it returns, what it does not include, required permissions, and the preferred sibling. It is slightly terse about the overall response shape, but adequate for selection and 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 only parameter, file, is fully described in the input schema (100% coverage), so the description does not need to compensate. The URL template merely repeats the same parameter without adding new semantic meaning, so baseline 3 is appropriate.

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

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

The description names the exact endpoint and states the resource and behavior: raw REST published variable names without valuesByMode. It also distinguishes the tool from the sibling get_variable_defs by pointing to the preferred alternative, 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?

The description explicitly says 'Prefer get_variable_defs.' That gives an alternative and a clear preference signal. It does not fully spell out the conditions under which this raw REST endpoint should be used instead, but the 'raw REST' and 'no valuesByMode' qualifiers imply when this tool is appropriate.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds the scope requirement and the library-key clarification, providing useful behavioral context beyond the annotations. It does not contradict any annotation, and for a read-only tool, this is adequate.

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

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

The description is a single concise sentence that front-loads the endpoint and purpose, then adds the key-type clarification and scope. There is no wasted text, and all information is immediately relevant to correct invocation.

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

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

For a simple tool with one parameter and no output schema, the description covers the essential information: what it does, the key type, and the required scope. It does not describe error handling or the exact metadata fields returned, but that is not critical for successful invocation. Overall, it is sufficiently complete.

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

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

Schema coverage is 100% and the parameter description is present, but the tool description adds the critical nuance that the key is a library key, not a file key, which the schema alone does not convey. This extra semantic meaning justifies a score above the baseline of 3.

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

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

The description clearly states the HTTP GET endpoint, specifies that it returns metadata for a published style key, and explicitly distinguishes that the key is a library key, not a file key. This precise scope separates it from sibling tools like get_file_styles and get_component, and it uses a specific verb+resource pattern.

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

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

The description provides the required scope (library_assets:read) and clarifies the key type, which helps avoid misuse. However, it does not explicitly name alternatives or conditions for when to use this tool over get_file_styles or other style-related siblings, leaving some inference to the agent.

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

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

The annotations already declare readOnlyHint=true but the description adds meaningful behavior beyond that: auto-pagination via 'meta.cursor.after' and the required OAuth scope. It discloses the endpoint's operational behavior without contradicting the read-only annotation.

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

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

The description is a single compact line that front-loads the endpoint and resource, then adds key behavioral details (auto-pagination, scope). Every token contributes useful information with 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 list operation with no output schema, the description covers the essential context: the resource type, team scope, pagination behavior, and required OAuth scope. It does not explain result shape, but the absence of an output schema and the read-only annotation reduce that need.

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 all four parameters are already documented. The description itself only restates the team path parameter indirectly; it does not add semantic detail beyond the schema, so the baseline score of 3 is appropriate.

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

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

The description states the exact endpoint and resource: GET /v1/teams/{team_id}/components, describing them as 'published team library components.' This is precise and distinguishes the tool from siblings like get_file_components and get_team_component_sets by naming both the team scope and the component resource.

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

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

The description gives context—team library components—but provides no explicit guidance on when to use this tool over alternatives such as get_file_components or get_team_component_sets. There are no exclusions or selection criteria stated.

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

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

The description adds 'Auto-paginates meta.cursor.after' and 'Scope: team_library_content:read', which are behavioral traits not present in the annotations (readOnlyHint and openWorldHint). This provides useful context on pagination and authorization, exceeding what annotations alone convey.

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

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

A single sentence packs the endpoint, resource scope, pagination behavior, and required auth scope. All information is front-loaded, with zero 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 read-only list endpoint without an output schema, the description covers the resource, pagination, and auth scope. It does not describe the return format, but that is not required without an output schema. Minor gap: no mention of how the 'team' parameter relates to the path, but the schema handles that. Overall, sufficiently complete.

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

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

Schema coverage is 100%, so the baseline is 3. The description does not add parameter-level meaning beyond the schema; it merely reflects the endpoint. No additional semantics are provided, so a 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 clearly states the HTTP verb and resource ('GET /v1/teams/{team_id}/component_sets') and specifies 'published team library component sets', distinguishing it from team components, team styles, and file-level component sets. It is unambiguous and 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?

The description does not provide any guidance on when to choose this tool over alternatives like get_team_components or get_file_component_sets. It states the resource but gives no contextual cues about use cases, exclusions, or prerequisites beyond the endpoint itself.

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

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

Annotations already indicate readOnlyHint and openWorldHint, and the description adds meaningful behavioral detail about pagination: 'Auto-paginates meta.cursor.after.' It also discloses the required OAuth scope, which goes beyond the structured annotations and helps an agent anticipate prerequisites.

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: endpoint and resource first, then pagination behavior, then scope. Every sentence earns its place; nothing is redundant or padded.

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

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

For a list-oriented read-only tool, the description covers the core invocation details: team path, published styles, automatic pagination, and authorization scope. With no output schema, the return shape is not explained, and the schema's zero required parameters leave room for ambiguity, but the main calling context is adequately described.

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

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

The schema has 100% description coverage, so the baseline is 3; the tool description does not elaborate on team, team_id, page_size, or auto_paginate. The mention of auto-pagination clarifies the pagination mechanism and somewhat enriches the auto_paginate parameter, but it does not add per-parameter meaning for the others.

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

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

The description states a specific verb and resource: 'GET /v1/teams/{team_id}/styles — published team library styles.' It clearly identifies the entity as team-scoped published library styles, distinguishing it from siblings like get_file_styles and get_team_components. The REST path and scope further pin down the exact operation.

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

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

The description implies when to use the tool by specifying 'published team library styles' and the team_library_content:read scope, but it does not explicitly contrast it with alternatives like get_team_components or get_file_styles. An agent can infer the use case from the resource type, but there is no direct when-to-use/when-not-to-use guidance.

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

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

Beyond the readOnlyHint/openWorldHint annotations, the description reveals authentication requirements (Enterprise + file_variables:read), fallback behavior using styles and inferred tokens, alias resolution depth, and the output shape. This is substantial behavioral context that helps an agent predict side effects and edge cases.

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

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

Three dense sentences front-load the tool's role, then cover behavior, fallback, output shape, and parameter guidance. Every sentence earns its place; there is no filler or repetition of annotation data.

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 composite tool with no output schema, the description provides enough to call it correctly: primary path, auth requirement, fallback condition, inference behavior, and return shape. The remaining details are covered by the input schema, making this complete for selection and invocation.

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

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

Schema coverage is 83%, so most parameters are already documented. The description adds meaningful context for node_id ('so fallback can resolve style usage'), fallback ('uses file styles + inferred subtree tokens'), and alias resolution, going beyond the schema. Only max_variables is left unexplained, but its schema bounds are self-explanatory.

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?

Description states a specific purpose: retrieving variable/token definitions via REST. It explicitly differentiates from the official Desktop get_variable_defs and describes the primary path plus fallback, so an agent can distinguish this composite tool from related siblings.

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

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

The phrase 'Preferred token path (REST, not official Desktop get_variable_defs)' gives clear selection guidance. It also describes the fallback trigger ('If variables 403/empty and fallback is on'), but it does not explicitly name sibling alternatives such as get_local_variables or get_file_styles or state when to prefer 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?

The description discloses meaningful behavior beyond the schema: the passcode is redacted by Figmachers and the required scope is `webhooks:read`. This is useful security/response information and is consistent with the `readOnlyHint` annotation. No contradiction found.

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

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

The description is extremely concise and front-loaded: it begins with the HTTP verb and endpoint, then notes the required scope and the passcode redaction behavior. No filler or redundant restatements.

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

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

For a straightforward fetch-by-ID operation with a single parameter)Skip, the description covers the essential request scope and a key response behavior (passcode redaction). It does not document error cases or the full response shape, but those omissions are minor given the simplicity of the operation.

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

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

The input schema provides only `webhook_id` with `minLength` and no description, and the tool description does not elaborate on the parameter beyond showing `{id}` in the endpoint path. With 0% schema coverage, the description should compensate, but it does not define what the ID is, its format, or how to obtain it.

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 a read operation on a single webhook via `GET /v2/webhooks/{id}`, distinguishing it from create/update/delete sibling tools. The `webhooks:read` scope reinforces the purpose. An agent can easily infer this is a fetch-by-id tool.

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 endpoint and scope imply the tool is for retrieving a single webhook by ID, but the description gives no explicit guidance on when to prefer this over alternatives such as listing webhooks or creating one. Context is clear enough for a simple GET-by-ID, but no exclusions or sibling routing are provided.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds the endpoint and scope, but does not disclose behavior like pagination, response shape, or whether branch_data affects results. With annotations covering the read-only nature, a 3 is appropriate.

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

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

The description is a single concise sentence with the endpoint and scope. It is front-loaded and contains no wasted words.

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

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

For a simple list tool with read-only annotations, the description is mostly adequate. However, the undocumented 'branch_data' parameter and lack of any mention of pagination or response format leave some gaps. The output schema is absent, so a bit more context on what is returned would help.

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 50%: the 'project' parameter is well described, but 'branch_data' has no description. The description does not explain branch_data's meaning or effect. Since half the parameters are undocumented in both schema and description, the description does not fully compensate for the gap.

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

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

The description states a specific verb ('list') and resource ('files in a project'), and includes the HTTP endpoint. It is clear what the tool does. However, it does not explicitly distinguish itself from sibling tools like get_file_meta or list_projects, though the resource is distinct enough.

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

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

The description implies usage: call this to list files in a project. It does not state when to use it versus alternatives like list_projects or get_file_meta, nor does it mention any exclusions. The scope 'projects:read' hints at required permission but not when to prefer this tool.

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

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

Annotations already indicate readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds the auth scope (projects:read) and the visibility constraint ('projects visible to the PAT'), which is useful behavioral context beyond the annotations. However, it doesn't disclose pagination, result format, or error behavior, which would be valuable for a list endpoint.

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

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

The description is a single concise sentence that front-loads the endpoint and purpose. Every word earns its place: endpoint, visibility, parameter guidance, and scope. 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 simple list operation with no output schema, the description covers the essential invocation details: how to identify the team, the required scope, and what the tool returns (projects visible to the PAT). It doesn't mention pagination, but given the low complexity and openWorldHint, this is a minor gap. 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.

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 ('team' and 'team_id'). The description adds the FIGMA_TEAM_ID environment variable alternative, which is not in the schema, providing a small extra hint. This is slightly above the baseline but not substantial enough to warrant a 4.

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

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

The description clearly states the action (list projects) and the resource (team projects), and includes the specific HTTP endpoint. It also specifies the auth scope, which helps an agent understand exactly what it returns. While it doesn't name sibling tools, the verb+resource combination is 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?

It provides clear context on how to specify the team (via the 'team' parameter or the FIGMA_TEAM_ID environment variable) and notes the required scope. It doesn't explicitly mention alternatives or when not to use this tool, but the purpose is obvious from the name and description, so no exclusions are needed.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the agent knows this is a safe read operation. The description adds useful behavioral context: it auto-paginates next_page, requires the webhooks:read scope, and explains a common 403 failure mode. This goes beyond the annotations without contradicting them.

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

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

Three sentences with no filler. The endpoint and core behavior are front-loaded, followed by the scope requirement and a practical error hint. Every sentence earns its place.

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

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

For a read-only list tool with no output schema, the description covers the essential invocation details: endpoint, scoping options, pagination, required scope, and a common error. It does not describe the response shape, but the absence of an output schema and the read-only annotations make that a minor gap. The description is complete enough 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.

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

Schema description coverage is 75%, so the schema already documents most parameters. The description adds the meaning of the context/plan_api_id split and the auto-pagination behavior, but it does not add detail about the format of context_id or plan_api_id beyond what the schema provides. Baseline 3 is appropriate because the schema carries most of the parameter documentation.

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 ('list'), resource ('Webhooks v2'), and the scoping dimensions ('context (team/project/file) or plan_api_id'). It also names the HTTP endpoint, which disambiguates it from sibling tools like get_webhook, create_webhook, update_webhook, and delete_webhook. The scope and pagination behavior are clearly identified.

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

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

The description gives clear context for when to use the tool: to list webhooks for a context or plan_api_id. It also provides a troubleshooting hint ('403 usually means missing scope or plan without webhooks'), which helps an agent decide whether this is the right tool or whether a different action is needed. It does not explicitly name alternatives or exclusions, but the sibling list and the endpoint make the distinction clear.

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

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

The annotations already indicate this is a mutating operation. The description adds the required file_comments:write scope and explicitly frames the action as an additive POST operation, which supplements the annotation without contradicting it.

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

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

The description is a single sentence loaded with the action, endpoint, and scope. It is concise, front-loaded, and contains 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 tool with 8 parameters and no output schema, the description is too thin. It does not explain return behavior, the relationship between x/y and new pins, or how offset_x/offset_y interact with node_id.

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

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

The description repeats the comment_id reply concept already present in the schema but adds no meaning for other parameters. Notably, message, offset_x, and offset_y are not idocumented in the schema and the description does not help compensate for this gap.

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

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

The description clearly identifies the tool as adding a comment or reply and names the HTTP endpoint and required scope. It is easy to distinguish from siblings like get_comments, delete_comment, or post_comment_reaction.

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 covers the main usage cases: posting a new comment or replying to a root comment via comment_id. However, it does not explicitly mention exclusions or point to alternative tools for related actions.

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

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

Annotations already indicate readOnlyHint=false and openWorldHint=true. The description adds the HTTP method and endpoint, aligning as a mutation, but it doesn't disclose potential side effects, idempotency, or duplicate handling beyond the basic POST behavior.

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

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

A single front-loaded sentence that states the HTTP method, endpoint, and key emoji example. Every component is necessary and structured efficiently, leaving no waste.

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 three required parameters and no output schema, the description plus schema give enough information to make a basic call. But it omits any context on the reaction-add behavior, such as whether existing reactions are updated or special validation, leaving the agent without complete picture of the mutation outcome.

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 covers the file and emoji parameters with descriptions, and the tool description reinforces the emoji shortcode format with the path. However, comment_id remains undocumented in the schema and the description only mentions it in the URL, offering no additional meaning beyond the parameter name.

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

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

The title 'Add a comment reaction' and the description's POST endpoint clearly identify a specific verb and resource. However, it does not explicitly contrast with sibling reaction tools such as get_comment_reactions or delete_comment_reaction, so it lacks sharp sibling differentiation.

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

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

The description does not state when to use this tool versus the related reaction tools. An agent gets no explicit cue that this should be used to create a reaction, while get_comment_reactions retrieves and delete_comment_reaction removes them, so the intended context must be inferred.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, covering safety and open-world assumptions. The description adds that it downloads renders as data URIs and mentions size/SSRF caps similar to bundle_image_fills, which is useful behavioral context. However, it doesn't disclose details like rate limits, pagination, or what exactly happens to the nodes (e.g., conversion). Given annotations cover the main safety profile, the description adds some but not extensive behavioral context.

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

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

The description is concise, one sentence with a technical phrase, and front-loaded with the action. It mentions key constraints (same caps) and purpose (design-to-code) without fluff. It is appropriately sized for the information it conveys.

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

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

Given the tool has an output schema? No, but has 6 parameters with 50% schema coverage and annotations covering read-only/open-world. The description mentions the main constraints (size/SSRF caps) and use case, but doesn't mention return format details (though that's not needed if output schema exists, but it doesn't). It lacks clarity on how the data URIs are returned (e.g., as a map) but given annotations and schema, it's fairly complete for an agent to 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 description coverage is 50%, meaning the schema covers half of the parameters' descriptions. The description itself doesn't elaborate on any parameters beyond the mention of node ids in the schema. It doesn't add extra meaning to parameters like 'file', 'scale', 'format', etc., beyond what schema provides. However, the schema description for 'ids' mentions normalization, which is helpful. Since coverage is moderate at 50%, the description does not compensate much beyond schema.

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

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

The description clearly states the tool's action: GET /v1/images/{key}, download renders (Figma/S3 only) as data URIs. It names the resource (images) and the specific output format (data URIs). It distinguishes itself from sibling tools by mentioning same caps as bundle_image_fills and its purpose (design-to-code). However, it doesn't explicitly differentiate from other similar download/render tools in the sibling list, but the mention of data URIs and design-to-code purpose helps.

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 mentions 'For design-to-code, not writing back to Figma,' which implies usage context (design-to-code) and an exclusion (not for writing to Figma). It also references bundle_image_fills for caps, indicating a comparison. However, it doesn't explicitly state when to use this over siblings like get_images or bundle_image_fills; it only references caps similarity. More explicit 'when to use this vs alternatives' would push to 5.

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

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

Annotations already indicate readOnlyHint=false and openWorldHint=true, so the mutation risk is known. The description adds the HTTP method (PUT) and the required scope, providing useful context. But it does not disclose possible edge behavior such as whether a PUT request overwrites both fields, what happens when the id is unknown, or any side effects beyond the direct update.

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

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

The description is a single sentence that front-loads the endpoint and action, lists the affected fields, and ends with the scope. There is no filler or redundancy; every piece of information adds value.

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

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

For a simple three-parameter update tool with no output schema, the description covers the core invocation details: what is being updated, by what id, and with what permission. It lacks guidance on whether a partial update is allowed, error responses, or success indicators, which are relevant for a write operation but not strictly blocking 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 low (33%), so the description must compensate. It does clarify that 'name/url' are the updatable fields and 'id' is the resource identifier. However, it does not explain whether name/url are optional, if a full replacement is expected (PUT semantics), or the expected format of the url. This is partial but not complete compensation for the schema gaps.

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 a specific verb ('update'), a specific resource ('dev_resources'), what fields can be updated ('name/url'), and the key mechanism ('by dev resource id'). This naturally distinguishes it from the sibling tools create_dev_resources and delete_dev_resource, as well as the read-only get_dev_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 description gives clear context: use this tool to update an existing dev resource's name/url identified by its id. It also provides a scope requirement (file_dev_resources:write). It does not explicitly enumerate when not to use it or name alternatives, but the sibling names and the update-specific wording make the intended usage fairly 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?

Beyond the annotation readOnlyHint=false, the description discloses a non-obvious behavioral rule ('Empty description deletes it') and the required OAuth scope (webhooks:write). It does not explain full vs. partial update semantics, but the added caveat is valuable.

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

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

The description is extremely compact: a method+path fragment, a scope note, and a critical behavioral warning. Every piece earns its place, and the key caveat is called out without obscuring the action.

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

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

With six parameters, zero schema descriptions, and no output schema, an agent lacks enough context to correctly craft the request body or understand how to specify webhook_id. The description only highlights the empty-description deletion case, leaving most invocation details uncovered.

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

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

Schema description coverage is 0%, yet the description only explains behavior for the description parameter ('Empty description deletes it') and leaves status, endpoint, passcode, and event_type undocumented. It adds a little value over the schema but fails to compensate for the missing parameter explanations.

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 with 'PUT /v2/webhooks/{id}' and the title 'Update webhook', which distinguishes it from create/delete/get/list siblings. However, it does not enumerate what aspects of the webhook can be updated, so it stops short of a 5.

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

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

No explicit guidance is given about when to use this tool instead of create_webhook, delete_webhook, or get_webhook. The scope and the 'Empty description deletes it' rule are constraints, not usage directions, so an agent must infer that this tool targets an existing webhook.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds the key behavioral limitation—that the response excludes team_id—which is useful context an agent would not infer from annotations alone. It doesn't detail output shape, but for a trivial identity call that's acceptable.

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

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

One tight sentence (plus a caveat) that front-loads the purpose and immediately adds the team_id limitation. Every word 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 no-param, read-only identity tool with no output schema, the description covers what the tool returns (the owning user) and its main limitation (no team_id). An agent can call it correctly without further context. Slight deduction for not mentioning the response fields explicitly, but it's not critical for usage.

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?

Tool has zero parameters, so the baseline is 4. The description correctly implies there are no configurable inputs; it only clarifies the token context. Nothing further 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?

States a specific verb-resource ('GET /v1/me') and clarifies it returns the user owning the access token. It also distinguishes itself from local variants by noting it does not include team_id, and names list_projects as the sibling for that need – making the tool's unique purpose unmistakable.

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 tells when to use this tool (to identify the current user) and when not to (when team_id is needed), pointing to list_projects and the FIGMA_TEAM_ID env var as alternatives. This is clear, actionable routing with no ambiguity.

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