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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, covering the safety profile. The description adds valuable context that the user profile is fetched automatically at startup and is a cached lookup, informing the agent about performance and potential staleness. This goes 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?

Two sentences, with the primary purpose front-loaded. The second sentence adds performance context without fluff. Every word contributes meaning, and it is appropriately short for a zero-parameter tool.

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

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

For a zero-parameter, non-destructive, read-only tool, the description fully covers what it does and its operational characteristics. The agent has everything needed to decide when to call it and what to expect.

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

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

There are no parameters, so the schema is trivially 100% covered. Per rubric, a zero-parameter tool gets a baseline of 4. The description correctly avoids fabricating parameter 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 clearly states the verb 'see' and resource 'who you're authenticated as in Figma', making the tool's purpose unambiguous. It naturally distinguishes from siblings like list_team_projects or get_file_info, which deal with different resources (projects, files, comments).

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

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

The description provides clear context that this is a cached lookup of the authenticated user, implying it's the tool to call when you need the current user's identity. However, it does not explicitly name alternatives or state when not to use it, so it falls short of the top score.

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, openWorldHint, idempotentHint, and destructiveHint, covering the safety profile. The description adds value by specifying the returned fields, which helps the agent understand what to expect. No contradictions with annotations.

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

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

Two concise, well-structured sentences. The main purpose is front-loaded, with no unnecessary details or repetition.

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 rich annotations and full schema coverage, the description is complete. It explains the output content and accepted inputs. Missing details like pagination or rate limits are minor and not critical for basic 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?

Schema coverage is 100%, so both parameters are already documented. The description adds no new parameter meaning beyond what the schema provides, aligning with the baseline score 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 tool retrieves all comments on a Figma file, lists the specific attributes returned (who commented, when, message content, resolved status), and mentions the accepted input forms (file key or URL). This distinguishes it from siblings like get_file_info or search_projects.

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 through its specific purpose, but does not explicitly state when to use this tool versus alternatives or mention exclusions. Since it's a distinct read-only operation, the context is clear, but explicit guidance is absent.

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, idempotentHint, and destructiveHint, covering the safety profile. The description adds the behavioral note that it does not download the full document and lists the returned metadata fields, which is useful context beyond annotations. However, it does not disclose potential errors, rate limits, or edge cases, so the added value is moderate.

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

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

The description is two sentences with zero fluff. The core purpose and key constraint ('without downloading the full document') are front-loaded, and the accepted input format is stated concisely in the second sentence. 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-only metadata tool with one parameter and no output schema, the description covers the essential information: what it does, what it returns (metadata fields), and what it accepts. It does not mention potential error scenarios or URL parsing nuances, but given the tool's simplicity and annotation coverage, these are minor gaps. The description is sufficiently complete for an agent to invoke it correctly.

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

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

Schema description coverage is 100%, with the single parameter described as 'A Figma file key or a full Figma URL'. The description repeats this exactly ('Accepts a file key or a Figma URL') without adding format examples, validation rules, or nuance. Since the schema already documents the parameter fully, the description adds no additional semantic value.

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 verb 'Get', the resource 'metadata about a Figma file', and the specific fields (name, last modified, version). It also differentiates from downloading the full document and distinguishes from siblings like get_current_user or get_file_comments. The purpose is unambiguous and contextually distinct.

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 when only metadata is needed ('without downloading the full document'), but it does not explicitly mention when to avoid this tool or refer to alternatives like parse_figma_url or search_projects. No exclusions or comparison with siblings are provided, leaving usage conditions somewhat implicit.

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, idempotentHint, and destructiveHint=false, so the safety profile is fully covered. The description adds that the tool lists 'all files' and depends on a prior list_team_projects call, but it does not disclose return shape, pagination, or error behavior.

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

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

The description is two short sentences with no filler. The main action is front-loaded, and the prerequisite is stated immediately after, making it efficient and easy to parse.

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

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

For a single-parameter, read-only tool with no output schema, the description covers the core action and the prerequisite. It lacks explicit return-value or pagination detail, but the simplicity of the tool and the annotations make this a minor gap rather than a blocking one.

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 covers project_id with 100% description coverage, including its source from list_team_projects results. The description repeats that source in prose without adding new semantic detail, so it meets the baseline but does not exceed 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 states a specific verb ('List') and resource ('all files in a Figma project'), making the tool's function immediately clear. It also distinguishes itself from siblings like list_team_projects (projects, not files) and get_file_info (single file), so an agent can select it confidently.

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 instructs the agent to use list_team_projects first to obtain project IDs, providing a clear prerequisite and sequence. It does not mention exclusions or alternatives, but the context for when to use this tool is clear enough.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds the key behavioral detail that it uses the configured default team when team_id is absent—valuable context not present in 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 tight sentences with zero waste. The primary purpose is front-loaded, and the default-team behavior is stated succinctly.

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 one optional parameter, no output schema, and annotations covering read-only behavior, the description covers purpose and default behavior adequately. It does not describe the return format, but that is not critical given no output schema exists and the operation is straightforward.

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% (team_id has a description), and the description adds meaning by explaining the optional nature and default behavior. This goes beyond the schema's basic field description, giving the agent practical invocation guidance.

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 ('all projects in a Figma team'), clearly distinguishing it from siblings like list_project_files (files in a project) and search_projects (search). It also mentions the fallback default team, which further clarifies 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?

Provides clear context that this is the tool for listing all projects in a team, and notes the optional team_id with a default. It does not explicitly mention when not to use it or name alternatives, but the sibling list makes the distinction obvious.

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, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds that the tool extracts specific fields from the URL but does not discuss invalid URL handling or return structure. This is adequate but not rich behavioral detail.

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

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

Two sentences, front-loaded with the action and extracted outputs, followed by a clear usage condition. Every word earns its place with no repetition or filler.

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

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

For a simple single-parameter read-only tool, the description is complete: it states what is extracted, when to use it, and the annotation profile covers side effects. Since no output schema exists, listing the exact outputs in the description satisfies the completeness requirement.

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

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

The single parameter 'url' is fully described in the schema with an example, so schema coverage is 100%. The description confirms the URL is a Figma link but adds little beyond what the schema already states. Baseline 3 is appropriate.

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

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

The description uses a specific verb ('Extract') and names the exact resource (Figma URL) and outputs (file key, file name, node ID). It clearly differentiates this tool from siblings like get_file_info or search_projects by focusing on parsing URLs rather than querying Figma 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?

It gives an explicit usage condition: 'Use this when a user provides a Figma link instead of a raw file key.' This tells the agent when to invoke it, though it does not name specific alternative tools for raw file keys.

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 readOnly, idempotent, non-destructive behavior, so the description does not need to repeat those. It adds value by explaining the configured default team behavior when team_id is absent. No contradictions with annotations; no additional behavioral traits like result format or pagination are disclosed.

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

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

Two concise sentences: the first states the core purpose and scope, the second explains the fallback behavior. Every word earns its place and the most important information is front-loaded.

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

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

For a simple read-only search tool with two fully documented parameters, complete safety annotations, and no output schema requirement, the description covers the necessary behavior. Nothing essential is missing for an agent to select and invoke the tool correctly.

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

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

Schema description coverage is 100%, so the parameters are already well documented. The description adds the useful nuance that omitting team_id uses the configured default, but otherwise does not need to compensate for 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 states a specific action (search by name) and resource (Figma files across all projects in a team), which clearly distinguishes it from siblings like list_project_files or get_file_info. The scope is precise and immediately actionable.

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

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

The description conveys clear context: use this when searching files by name across a team, and it explains the default behavior when team_id is omitted. It does not explicitly name alternative tools or state when not to use it, but the intended use case is apparent.

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