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

With no annotations, the description carries the full burden. It discloses deterministic behavior, safe margin respect, and fresh QA, but does not state mutation effects, permissions, or return format beyond the vague 'fresh QA'.

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

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

The description is two sentences, front-loaded with purpose, and then adds two significant behavioral constraints. Every sentence earns its place with no wasteful content.

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

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

Despite a complex schema and no output schema, the description covers main behaviors but leaves gaps: no mention of return structure beyond 'fresh QA', no explanation of 'measured text stacking' or 'semantic vertical rhythm', and no clarification of whether the document is mutated in-place.

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 all 4 parameters, so the baseline is 3. The description adds conceptual mapping to the operation parameter by naming the four operation families (alignment, distribution, stacking, vertical rhythm), which helps the agent select the right operation.

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 ('arrange') and resource ('selected page layers') and enumerates distinct operation types (alignment, distribution, text stacking, vertical rhythm) that clearly differentiate it from sibling tools like resize or autolayout.

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

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

The description implies usage for arranging selected layers and lists supported operations, providing clear context. However, it does not explicitly name alternatives or exclusion criteria, so it earns a 4 rather than a 5.

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

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

With no annotations provided, the description takes on full burden. It discloses the processing order (hard-wrap, shrink, grow, truncate only when requested), the deterministic nature, and the return value (adjusted document, decisions, QA report). It does not explicitly state whether the input is mutated, but 'Returns the adjusted document' suggests a non-destructive operation, adding value beyond a simple mutation statement.

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

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

The description is two sentences, front-loaded with the core action ('Hard-wrap overflowing text'), and every word earns its place. It efficiently summarizes the process and return value without unnecessary elaboration.

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

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

Given the tool's complexity (nested document structure, three parameters, no output schema), the description provides essential context: the algorithm, the condition for truncation, and the composition of the return value. It does not detail failure modes or the QA report structure, but the rich input schema and clear behavioral overview make it sufficiently complete for an agent to understand the tool's role and outcomes.

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 parameters onOverflow and minimumFontScale already well-described and the document param described as 'Design document whose text frames should be repaired'. The tool description adds minimal extra meaning beyond the schema, such as the order of operations, but does not clarify parameter syntax or additional constraints. 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 action ('Hard-wrap', 'shrink', 'grow', 'truncate') on a clear resource ('overflowing text' in a design document), distinguishing it from siblings like resize_design_document or update_element. It clearly conveys what the tool does and its scope.

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

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

The description implies usage for repairing overflowing text but does not explicitly state when to choose this over alternatives or provide exclusions. It lacks direct guidance on suitable scenarios or related tools, so usage context is only implied rather than clearly specified.

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

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

No annotations provided, but description discloses returns latency, accessible files, and troubleshooting suggestions. Does not mention side effects, but likely read-only. Adequate transparency.

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

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

Two concise sentences with no filler. Clearly front-loaded with purpose and usage.

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 no output schema, description covers purpose, usage, and key return items. Could elaborate on return format but adequate for a simple diagnostic tool.

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

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

No parameters defined, schema coverage is 100% trivially. Baseline of 4 per guidelines for 0 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 tool 'Verify Penpot connectivity and authentication', using a specific verb and resource. It distinguishes from sibling tools like list_files or import_figma by being a diagnostic/health check.

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 'Run this first if other tools fail', providing clear usage context. Does not mention when not to use but is sufficient for a diagnostic 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?

With no annotations provided, the description must carry the transparency burden. It states that the tool 'evaluates' and 'returns' results, strongly implying a read-only operation, but it does not explicitly confirm that no mutation occurs, nor does it describe any prerequisites, error behavior, or side effects. 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 that is front-loaded with the verb 'Evaluate' and immediately specifies the resource and context. It wastes no words and is easy to parse.

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

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

The tool has a complex nested schema and no output schema, so the description is the only source for return information. It states that violations and export permission are returned, which is useful but incomplete: the agent does not learn the structure of violations or the exact shape of the export permission flag. Given the complexity, additional context about the output or behavior would make it more complete.

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

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

Schema description coverage is 100% (both 'document' and 'policy' have descriptions). The tool description adds value by enumerating the policy categories ('banned terms, required terms, approval, and workspace capability restrictions'), which helps an agent understand the policy structure, but it does not provide additional semantics beyond the schema's descriptions.

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's function: evaluating a design document against a configurable policy covering banned terms, required terms, approval, and capability restrictions. It also states the output (violations and export permission), which distinguishes it from sibling tools like export_design_document or get_constraints.

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 a clear use case (checking a document before export or as part of policy compliance), but it does not explicitly state when to use this tool versus alternatives, nor does it mention when not to use it. No exclusion conditions are given, so the context is partially clear but not fully explicit.

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

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

No annotations are provided, so the description must disclose behavioral traits. While it indicates the tool returns a report, it fails to mention the 'applyBrandKitNormalization' parameter that can rewrite colors and fonts, a side effect with mutation potential. Without this disclosure, an agent might invoke the tool with normalization enabled and inadvertently modify the document. The description also does not explain the report's return format or whether the input is mutated in any other way.

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: two sentences that front-load the primary action and scope, followed by a clear usage instruction. Every word contributes value—no filler or redundant details.

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

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

For a validation tool with a complex nested input schema, the description explains the report's key coverage areas but omits the report's structure or format (no output schema exists). It also fails to mention the side-effect potential of applyBrandKitNormalization. The 'before exporting' context is helpful, but the gaps around return format and mutation leave the description incomplete for full reliance.

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 descriptions for both parameters (document and applyBrandKitNormalization), giving 100% coverage. The tool description adds no additional parameter semantics beyond what the schema already provides, so the baseline score of 3 applies.

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

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

The description clearly states the tool validates a multi-page design document and returns a QA report, with a specific verb ('Validate') and resource ('multi-page design document'). It distinguishes itself from sibling tools like export_design_document and check_design_policy by explicitly covering canvas bounds, safe area, text contrast, and brand kit compliance. The name 'create_design_document' is somewhat misleading, but the description itself 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?

The description provides clear contextual guidance: 'Use this before exporting.' This tells the agent when to invoke the tool. However, it does not mention alternatives or when not to use it, so it lacks the explicit exclusions needed for a 5.

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

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

No annotations are provided, so the description must fully disclose behavioral traits. It only states that elements are created and lists types, but fails to mention permissions, side effects, or return value. For a 12-parameter mutation tool, this is insufficient.

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: first defines purpose with specifics, second gives a crucial prerequisite. 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?

With 12 parameters, no output schema, and no annotations, the description is too brief. It doesn't cover what happens after creation (e.g., response, element ID), error cases, or constraints like positioning rules.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds no additional meaning beyond summarizing shape types and mentioning get_constraints.

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 'create' and the resource 'shape element on a Penpot page', listing specific types. It distinguishes from siblings like update_element and delete_element.

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 a clear prerequisite: 'Use get_constraints FIRST to understand layout boundaries before creating elements.' This guides when to use this tool relative to a sibling, but doesn't explicitly mention alternative creation methods like import_figma.

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

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

No annotations are provided, so the description carries the burden. It discloses the return value (completed document, filled slots, automated QA report) and implies a non-destructive creation operation. It lacks details on side effects or permissions, but for a create tool this is 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?

The description is two concise sentences, front-loaded with the primary purpose and followed by the return value. Every word adds value without redundancy.

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

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

For a tool with only two parameters and no output schema, the description sufficiently covers what it does and what it returns. It does not address error conditions or prerequisites, but given the tool's simplicity, it 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 description coverage is 100%, so the schema already documents both parameters. The description adds the concepts of 'parameterized' and 'filled slots', reinforcing the template-based input but not providing additional syntax or format details beyond the schema.

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

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

The description clearly states the action ('Create') and the specific resource ('original, parameterized design document from a registered channel template'). It distinguishes itself from sibling tools like create_design_document by emphasizing the template-based source.

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 the tool should be used when a registered channel template exists and a parameterized document is desired. It does not explicitly mention alternatives or exclusions, but the template-specific context provides clear usage direction.

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

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

With no annotations, the description must disclose behavior. It mentions irreversibility, a key trait, but omits details like required permissions, cascading effects, or whether the action is logged.

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 clear, front-loaded sentences with no fluff. The warning could be integrated but is separate; overall efficient.

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 tool with three required parameters and no output schema, the description is minimally adequate. It covers purpose and a key caution, but lacks context on side effects or confirmation.

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

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

The input schema has 100% description coverage for all parameters, so the baseline is 3. The description adds no extra meaning beyond the schema's own descriptions.

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 deletes a shape from a Penpot page, using a specific verb-resource pair. It distinguishes from sibling tools like create_element and update_element by focusing on 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 warns to use with caution due to irreversibility, implying it's for permanent removal. However, it does not explicitly state when not to use or suggest alternatives like update_element for modifications.

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

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

With no annotations, the description carries the full burden and does add meaningful behavioral context: 'Export is refused when automated QA fails' and 'Files are written inside the configured export root only'. It does not disclose return value, overwrite behavior, or permission requirements, but the disclosed constraints are 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 two sentences: the first states the action and formats, the second states two key constraints. It is front-loaded, concise, and every sentence contributes valuable information without 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?

Given the complex input schema and no output schema, the description would benefit from explaining what the export returns (e.g., file paths) and reconciling the format list with the schema enum. The QA refusal and output root constraints are helpful, but important behavioral aspects like return value and handling of existing files are omitted.

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

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

Schema description coverage is 100%, so the baseline is 3. The tool description does not add parameter semantics beyond the schema, and the format list in the description only includes a subset of the schema's enum values, which could cause confusion about valid format 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 action (export), resource (design document), and formats, distinguishing it from sibling tools. However, the format list 'SVG, PNG, JPG, or multi-page PDF' is a subset of the schema enum (which also includes pptx, gif, mp4), creating a potential mismatch that could mislead an agent about supported formats.

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

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

The description provides clear context for using this tool to export design documents, and there is no other export sibling tool, so the usage is implicitly distinct. It does not explicitly mention when not to use it or name alternatives, but the purpose is sufficiently clear to guide tool selection.

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

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

No annotations provided, but description implies read-only 'list' behavior. Discloses that variants are included, adding value beyond schema. No contradictions.

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: first states action, second gives usage context. No fluff, 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?

Description covers purpose and usage context. No output schema, but mentions 'variants' to hint at return content. Could be more explicit about return format, but sufficient for a list tool.

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

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

Schema has 100% coverage with descriptions for both parameters. Description does not add parameter-specific meaning beyond schema. Baseline score of 3 applies.

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

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

Clearly states verb 'list', resource 'components in a Penpot file', and includes 'with their variants'. Distinguishes from siblings like get_tokens and get_constraints.

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 'Use to understand available building blocks before generating UI', providing context for when to use. No mention of when-not or alternatives.

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

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

No annotations present; description carries full burden. It discloses read-only nature and key outputs but omits details like error handling or side effects. Adequate for a simple read operation but not exhaustive.

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

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

Two-sentence description is succinct, front-loads purpose and output, then adds usage guidance. 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?

Covers purpose, key outputs, and when to call. Lacks output schema but describes return contents sufficiently. Minor gap: no mention of response format, but acceptable for tool of this complexity.

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

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

Schema coverage is 100% with clear parameter descriptions. Description adds no further semantic detail beyond what the schema provides, so 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?

Description clearly states the tool retrieves layout constraints and design guardrails, specifying exact return types (spacing, colors, typography, rules). Distinguishes from siblings like get_tokens by including MUST/MUST NOT rules, making purpose 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?

Provides explicit directive to call this tool before generating UI to prevent layout issues. Lacks explicit alternatives but contextually fits as a prerequisite step among siblings.

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

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

No annotations are provided, so the description carries the burden. The verb 'extract' strongly implies a read-only, non-destructive operation. It also mentions 'compressed' and 'token-efficient format,' which are behavioral traits. However, it does not explicitly state safety or lack of side effects.

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, no redundancy. Each sentence adds value: the first defines the action and outputs, the second provides usage guidance. Front-loaded with key information.

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

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

The description explains what is returned (tokens, components, pages, constraints) and the output format variants, but does not detail the structure or presence of an output schema. Given the complexity of aggregating brand context and no output schema, this is moderately complete but could benefit from mentioning response shape.

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 description adds no new meaning beyond the schema. The description does not elaborate on parameter values or provide examples. 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 clearly states it extracts compressed brand context and lists specific outputs (design tokens, components, pages, layout constraints). It distinguishes from sibling tools (get_components, get_tokens, etc.) that focus on individual aspects, making the tool's aggregative purpose obvious.

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

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

Explicit guidance to use this tool FIRST before any UI generation, implying it provides essential context. This also advises against using specialized tools prematurely, establishing a clear usage hierarchy.

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

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

No annotations are provided, so the description must fully disclose behavior. It explains the output is a compact tree with specific details, implying a read-only operation. However, it does not explicitly state it is non-mutating, list required permissions, or describe potential errors.

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 redundancy: first states purpose, second details output content, third provides usage guidance. Every sentence adds value.

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

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

Given no output schema, the description adequately hints at return type ('compact tree') and content. It could be improved by explicitly stating it is read-only and clarifying the depth parameter's effect. Overall, sufficient for a simple read tool.

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

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

All three parameters are described in the schema (100% coverage). The description adds context about the output but does not enhance parameter meaning beyond the schema. Therefore, a 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 clearly states the tool retrieves the layout structure of a Penpot page as a compact tree, detailing frame hierarchy, layout types, gaps, and sizing. This distinguishes it from siblings like 'create_element' or 'get_components', which have different purposes.

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 context by stating 'Use to understand spatial structure before creating or modifying elements,' indicating when to use it. However, it does not explicitly mention when not to use it nor name alternative tools.

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

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

No annotations are provided, so the description must disclose behavioral traits. It only states 'Extract' (implying read-only) and 'returns structured token data', but lacks details on permissions, side effects, rate limits, or output format specifics.

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 redundant words. The first sentence front-loads the verb and resource, making the purpose immediately clear.

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 extraction tool with 2 well-described parameters, the description is adequate but lacks output schema details and any behavioral guarantees. Given no annotations, more context (e.g., return format) would improve completeness.

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 baseline is 3. The description adds value by contextualizing the output for code generation and explicitly listing the token categories (colors, typography, spacing) that align with the enum, reinforcing parameter meaning beyond the schema.

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

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

The description clearly states the verb 'Extract', the resource 'design tokens (colors, typography, spacing) from a Penpot file', and the purpose 'for use in code generation'. It distinguishes itself from sibling tools like get_components by focusing on token extraction.

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

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

The description implies usage for code generation but does not explicitly state when to use this tool versus alternatives (e.g., get_components, get_design_context). No when-not-to-use or prerequisite guidance is 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?

With no annotations provided, the description must convey behavioral traits. It mentions conversion of design elements and the dry run feature, but lacks details on mutability (overwrite vs. create), idempotency, required permissions, or async behavior. Basic but not comprehensive.

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 consists of two concise sentences. The first sets the purpose, the second provides a key usage tip. No extraneous words, and it is front-loaded with the primary 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?

Given the complexity of an import tool with no output schema or annotations, the description covers core functionality and a dry run recommendation but omits important details like return values (preview vs. actual), error handling, or whether the operation is synchronous. It is adequate but not fully complete.

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

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

The input schema has 100% description coverage for all 4 parameters. The description adds context for the dryRun parameter ('Use dryRun=true first'), but the schema already explains each parameter's meaning. The description does not significantly enhance parameter understanding beyond the schema.

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

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

The description clearly states the tool imports a Figma file's design system into Penpot, specifying the converted elements (colors, typography, components, page structure). It uses a specific verb ('Import') and resource ('Figma file's design system'), and is distinct from sibling tools like get_components or create_element.

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 advises to use dryRun=true first to preview conversion before writing, providing clear usage context. However, it does not specify when not to use this tool or offer alternatives, missing some aspects of full guidance.

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

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

With no annotations, the description carries the burden of disclosing side effects. It reveals conversion scope (shapes, tokens, loss report) and warns about writing, but does not describe what happens on write (overwrite, merge, permissions) or any other side effects beyond the dryRun preview.

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

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

The description is two sentences: the first states purpose and scope, the second gives a specific usage recommendation. Information is front-loaded and every sentence earns its place 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?

For a tool with no output schema, the description explains inputs, conversion behavior, and return value (loss report). It lacks explicit return-value structure, but the loss report mention and dryRun guidance are sufficient for a complex import tool with five parameters.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds minimal extra parameter context: it clarifies the bundle format (manifest.json + SVG + tokens.css) but does not significantly extend understanding beyond the schema's per-property descriptions.

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 ('Import an Open Design handoff bundle') with a defined resource ('into a Penpot file') and enumerates concrete conversion behaviors (SVG shapes, CSS custom properties, tokens, loss report). This differentiates it from sibling import_figma by naming the Open Design format.

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

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

It explicitly instructs to use dryRun=true first for preview, which is a clear usage guideline and implies the alternative of executing the import. It does not explicitly exclude alternative tools, but provides enough context about the intended workflow.

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

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

No annotations are provided, so the description carries the full burden. It discloses the deterministic ordering and the location, which is useful. However, it does not describe the return format (e.g., array of project objects, only IDs), pagination, or error conditions, leaving the agent to infer the output.

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 sentence that conveys the essential information without redundancy. It is appropriately sized for a simple list operation.

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

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

For a tool with no annotations, no output schema, and zero parameters, the description is minimal. It states what is listed and the ordering, but it omits the return structure and any edge cases. While adequate for a simple tool, it lacks full completeness for an agent to know exactly 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?

The tool has zero parameters, and the schema coverage is 100% (empty schema). The description adds no parameter details, which is expected. Per the baseline for zero parameters, this scores 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 tool's function: 'List design projects' with a specific scope ('saved inside the configured project root') and a distinguishing detail ('deterministic id order'). This differentiates it from sibling tools like list_files.

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 on when to use this tool over alternatives such as list_files or load_design_project. The description only gives the scope (configured project root) but no exclusions or alternative recommendations.

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

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

No annotations, so description carries burden. States it lists files accessible to user (implying read-only), but lacks details on pagination, ordering, or what subset of files are returned.

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?

Ultra-concise single sentence with front-loaded action. 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?

Sufficient for a simple parameterless list tool. Mentions target users and purpose, but could specify file type or result structure more precisely given no output schema.

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

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

No parameters, schema coverage 100%. Description adds no parameter info since none exist. Baseline 4 for 0-param tools.

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?

Explicitly states it lists Penpot files and mentions discoverability, clearly distinguishing from sibling tools like create_element or get_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?

Says to use for discovering available design files, providing clear context. Does not explicitly mention when not to use or alternatives, but the purpose is straightforward.

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

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

With no annotations, the description carries the full burden. It implies a read-only operation ('List') and provides context ('so the canvas matches the target channel'), but it does not disclose return format, pagination, authentication requirements, or any limitations. This is adequate but lacks depth for a tool with no structured safety hints.

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 exactly two sentences, with the primary action front-loaded. Both sentences are informative: the first states what the tool does, the second explains when to use it. There is no redundant or filler content.

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 simplicity of the tool (one optional parameter, no output schema), the description adequately covers its purpose and use case. It does not describe the exact structure of the returned presets, but the tool's function is clear and the missing details are minor in context.

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

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

The schema already documents the only parameter 'category' with a description ('Optional preset category filter') and an enum covering all categories. The tool description adds no additional detail beyond the schema, so it stays at the baseline for 100% 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 tool's action: 'List canvas size presets' and specifies the resource (canvas size presets) plus the categories (social, video, blog, presentation, and print). This distinguishes it from sibling tools like get_page_layout or get_design_context, which serve different purposes.

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 explicit when-to-use guidance: 'Call this before creating a design document so the canvas matches the target channel.' This clearly explains a key use case, but it does not mention when not to use the tool or name alternative tools, falling short of the highest standard.

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

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

No annotations are provided, so the description must fully disclose behavioral traits. It does not state whether the operation is read-only, whether any side effects occur (e.g., opening an editing session), or what the return value contains. The metaphor of 'envelope' and 'normalized document' is left unexplained, leaving the agent uncertain about the operation's effects.

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 conveys the essential purpose and context without unnecessary details. It is well-structured and front-loaded with the action and object.

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, yet the description does not explain what is returned or what state changes occur after loading. Given the absence of annotations and output details, the description is incomplete for a tool that is a prerequisite for editing workflows.

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

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

The schema already describes the 'id' parameter as 'Saved project id' with full coverage. The tool description adds no additional meaning beyond calling it 'saved', so the baseline of 3 is appropriate because the schema does the heavy lifting.

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

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

The description uses a specific verb 'Load' and clearly identifies the resource ('saved design project envelope and its normalized document') and the purpose ('for further editing'). It distinguishes itself from sibling tools like save_design_project and list_design_projects by focusing on loading a specific project for editing.

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

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

The phrase 'for further editing' provides clear context for when this tool should be used—when an existing project needs to be loaded as a precursor to modification. It does not explicitly name alternatives or exclusions, but the usage context is sufficiently 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 description discloses important behavioral traits: operations are 'ordered deterministic' and background removal is 'classical, not AI matting'. This adds context beyond the schema, especially since no annotations are provided, though it does not cover failure modes or permissions.

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 only two sentences, highly concise, and front-loaded with the core capability before detailing the operation types. Every word contributes value, with no redundancy or filler.

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

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

Given the rich input schema that fully explains all parameters, the description gives a solid high-level overview. However, with no output schema, it does not mention the return value or confirmation of file output, leaving a minor gap for agents expecting a response.

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 parameters with meaningful details (paths, filename constraints, operation arrays). The description's listing of operation types adds no new semantic meaning beyond what the schema already provides, so it remains at 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 uses a specific verb 'Apply' and enumerates the exact operations (crop, scale, pad, remove-flat-background, trim-transparent), making the tool's function unambiguous. It clearly distinguishes from sibling design/layout tools which are unrelated to image processing.

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 the tool is used for image operations that require ordering, but it does not explicitly state when to use it versus alternatives or when not to use it. No exclusions or alternative tool references are given, so usage guidance relies on inference.

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

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

No annotations are provided, so the description carries the transparency burden. It partially discloses behavior by describing fill, fit, and original modes, but omits the 'adapt' mode and does not clarify whether the resize mutates the document in-place, affects all pages, or returns a new document. This is a moderate gap.

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

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

The description is compact and well-structured, with the primary action front-loaded in the first sentence and mode behaviors in the second. Every sentence provides useful information without 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 complex tool with a nested document object and no output schema, the description is underspecified. It does not explain the return value, side effects, whether all pages are resized, or the meaning of the 'adapt' mode, leaving significant behavioral gaps for an agent.

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 provides descriptions for all parameters (100% coverage), including mode semantics that are nearly identical to the tool description. The description adds only a condensed restatement and omits 'adapt', providing little extra meaning beyond the schema.

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

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

The description clearly states the tool's purpose with a specific verb ('Resize') and resource ('design document'), and explains the primary modes (fill, fit, original), distinguishing it from sibling tools like autolayout or arrange layers. The action and target are unambiguous.

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

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

The description provides clear context for when to use the tool (to resize a design document) and explains the behavior of the key modes, guiding mode selection. However, it does not explicitly mention alternatives or exclusions relative to sibling tools like autolayout_design_document.

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

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

With no annotations provided, the description carries the full burden. It usefully discloses that QA-failing drafts are saved intentionally and that the response reports QA status. However, it omits other behavioral traits such as overwrite behavior, permissions, or error handling, leaving the transparency incomplete.

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

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

The description is two sentences, front-loaded with the primary purpose, and every clause adds value. It is concise and well-structured with no redundant wording.

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 complex nested parameters and no output schema, but the schema fully describes inputs. The description covers the core behavior and QA reporting, but lacks details about return values beyond QA status, idempotency, or failure modes. This makes it adequate but not fully complete.

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

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

Schema description coverage is 100% for all 4 parameters, so the schema already documents parameters. The description adds no extra parameter-level meaning beyond what the schema provides, so the baseline of 3 applies.

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

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

The description clearly states a specific action ('Save') with a specific resource ('reusable design project') and a scoped location ('configured project root'). This distinguishes it from siblings like load_design_project or create_design_document by emphasizing persistence and reusability.

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 provided on when to use this tool versus alternatives. The description does not mention any alternative tools, exclusions, or prerequisites. The QA-failure note implies a scenario but does not explicitly frame 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?

With no annotations, the description must disclose behavioral traits. It states 'update' implies mutation, but fails to explain whether updates are partial (PATCH) or full, required permissions, side effects on other elements, or error behavior (e.g., shape not 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, 20 words, front-loaded with action and modifiable attributes. Efficient but could be more structured with a sentence on typical usage or 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?

The tool has 11 parameters and no output schema. The description does not explain what the tool returns (e.g., updated shape object, confirmation). For a mutation tool, this is a significant gap in completeness.

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 baseline is 3. The description adds semantic grouping of parameters by category (name, position, size, etc.), providing context beyond the schema. However, it does not detail format constraints (e.g., hex color format, coordinate system).

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 (update), the resource (existing shape on a Penpot page), and lists the modifiable attributes (name, position, size, fill color, corner radius, visibility). This distinguishes it from sibling tools like create_element or delete_element.

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, nor does it mention prerequisites (e.g., obtaining shape ID via get_components) or contexts where this tool is inappropriate.

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