mcp

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

The description adds valuable behavioral context beyond annotations. While annotations indicate destructiveHint=true (mutation) and non-idempotent, the description clarifies what gets modified ('applies foundational design tokens... modifying their appearance') and the scope ('to a list of screens'). It doesn't mention authentication needs or rate limits, but provides meaningful operational context that complements the annotations without 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?

The description is efficiently structured with two sentences: the first states purpose and usage context, the second elaborates on what the tool does. Every sentence adds value without redundancy, and it's appropriately front-loaded with the core functionality.

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 (destructive mutation with 3 parameters), the description provides good context about what the tool does and when to use it. With annotations covering safety aspects and an output schema existing (though not shown), the description doesn't need to explain return values. It could benefit from more explicit guidance on alternatives, but is largely complete for agent understanding.

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?

With 100% schema description coverage, the schema already documents all three parameters thoroughly. The description doesn't add specific parameter semantics beyond implying that 'assetId' refers to a design system and 'selectedScreenInstances' are screens to update. This meets the baseline for high schema coverage where the description doesn't need 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 tool's purpose with specific verbs ('applies', 'update', 'modifying') and resources ('design system', 'screens', 'design tokens'). It distinguishes from siblings like 'edit_screens' by specifying it applies design system tokens rather than general editing, and from 'create_design_system' or 'update_design_system' by focusing on application rather than creation/modification.

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 this tool ('when the user wants to update one or more screens to match the style of a design system'). However, it doesn't explicitly state when NOT to use it or name specific alternatives among siblings (e.g., 'edit_screens' for non-design-system modifications), though the purpose differentiation implies 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?

The description adds valuable behavioral context beyond annotations. While annotations indicate this is a destructive, non-idempotent write operation, the description clarifies that this tool 'establishes the foundational design tokens' and requires immediate follow-up with 'update_design_system' to apply changes. It doesn't contradict annotations but provides important workflow 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 well-structured with clear sections: purpose statement, usage context, configuration details, and post-call instructions. It's appropriately sized for a complex tool, though the 'Instructions for Tool Call' section could be more concise. Every sentence adds value without unnecessary 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?

Given the tool's complexity, comprehensive input schema, annotations, and existence of an output schema, the description provides excellent contextual completeness. It covers purpose, usage context, what gets configured, foundational nature of the tokens, and critical workflow instructions. The combination with structured data makes this fully 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?

With 100% schema description coverage, the description doesn't need to explain parameters in detail. It does provide high-level context about what gets configured (color palette, typography, shape, appearance, design MD), which maps to the DesignSystem schema, but doesn't add specific parameter semantics beyond what the comprehensive 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 clearly states the tool's purpose: 'Creates a new design system for a project' with specific details about what it configures (color palette, typography, shape, appearance, design MD). It distinguishes from siblings by establishing foundational design tokens and explicitly mentions the sibling tool 'update_design_system' for applying the system.

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 usage guidance: 'Use this tool when the user wants to set or update the overall visual theme, style, or branding of the application.' It also gives clear post-call instructions to use 'update_design_system' immediately after creation, distinguishing it from other design-related tools like 'apply_design_system' or 'edit_screens'.

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, readOnlyHint=false, etc., covering safety and mutability. The description adds context by explaining what a project is, which is useful beyond annotations. However, it doesn't disclose additional behavioral traits like rate limits, authentication needs, or what 'destructive' entails (e.g., if it overwrites existing projects).

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 front-loaded with the core purpose in the first sentence, and the second sentence adds necessary context without waste. It's appropriately sized and structured for a simple 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?

Given the tool's complexity (simple creation with 1 optional parameter), rich annotations, and an output schema (which handles return values), the description is reasonably complete. It explains what a project is, which aids understanding. However, it could benefit from more usage context or behavioral details.

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 parameter 'title' documented as optional. The description adds no parameter-specific information beyond the schema, so it doesn't compensate or add meaning. With high schema coverage, the baseline is 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 action ('Creates') and resource ('new Stitch project'), and defines what a project is ('container for UI designs and frontend code'). It distinguishes from siblings like 'get_project' or 'list_projects' by specifying creation. However, it doesn't explicitly differentiate from other creation tools like 'create_design_system' beyond the resource type.

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 is provided. It doesn't mention prerequisites, when not to use it, or compare with sibling tools like 'list_projects' for checking existing projects before creation. The context is implied but not 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?

Annotations indicate destructiveHint=true (mutation), readOnlyHint=false (not read-only), openWorldHint=false (closed-world), and idempotentHint=false (not idempotent). The description adds valuable behavioral context: it notes the action 'can take a few minutes to complete' (latency warning), advises 'DO NOT RETRY' (non-idempotency reinforcement), and warns that 'connection error' failures may still succeed (partial success behavior). This goes beyond annotations by detailing timing, retry policies, and error handling.

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 front-loaded with the core purpose in the first sentence, followed by bullet-point instructions. It avoids unnecessary repetition and wastes no words. However, the bullet points could be integrated more smoothly, and the structure slightly separates operational notes from the main description, but overall it's efficient and well-organized.

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 (destructive mutation with 5 parameters), annotations cover safety aspects, and an output schema exists (so return values are documented elsewhere). The description adds crucial behavioral details like latency and error handling, which are essential for a slow, non-idempotent tool. It could improve by mentioning sibling alternatives or prerequisites, but it's largely complete for guiding agent 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 description coverage is 100%, with all parameters well-documented in the schema (e.g., projectId, selectedScreenIds, prompt, modelId, deviceType). The description adds no additional parameter semantics beyond mentioning 'text prompt' (implied by the prompt parameter). Since the schema fully covers parameter meanings, the baseline score of 3 is appropriate, as the description doesn't compensate but also doesn't detract.

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 ('Edits existing screens') and resource ('within a project'), specifying it uses a text prompt. It distinguishes from siblings like 'generate_screen_from_text' (creates new) and 'get_screen' (reads), but doesn't explicitly differentiate from 'generate_variants' or 'apply_design_system' which might also modify screens. The purpose is clear but sibling differentiation could be more 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?

The description implies usage through the phrase 'Edits existing screens,' suggesting it's for modifying rather than creating or reading screens. However, it lacks explicit guidance on when to use this tool versus alternatives like 'generate_variants' or 'apply_design_system,' and doesn't mention prerequisites (e.g., needing existing screens). The 'Instructions for Tool Call' provide operational advice but not contextual usage rules.

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 significant behavioral context beyond annotations. Annotations indicate destructiveHint=true (mutation) and non-idempotent, but the description elaborates with timing constraints ('few minutes'), retry warnings, and error handling specifics. It also describes output interpretation logic for 'output_components' and conditional re-calling behavior, which annotations don't cover. No contradiction with annotations 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?

The description is well-structured with clear sections (purpose, instructions, output handling) and uses bullet points for readability. It's appropriately sized for a complex tool, though the output section is somewhat verbose and could be more streamlined. Every sentence adds value, with no redundant 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?

Given the tool's complexity (destructive mutation, conditional output handling), the description is highly complete. It covers purpose, behavioral nuances (timing, retries, errors), and output interpretation logic. With annotations providing safety/behavior hints and an output schema existing (though not shown), the description fills all necessary gaps without over-explaining structured data.

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?

With 100% schema description coverage, the schema already documents all parameters thoroughly. The description doesn't add any parameter-specific semantics beyond what's in the schema (e.g., it doesn't explain 'prompt' formatting or 'projectId' sourcing). However, it implies parameter usage in the output handling section by referencing 'prompt' for re-calls, adding marginal context.

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: 'Generates a new screen within a project from a text prompt.' This specifies the verb ('generates'), resource ('screen'), and context ('within a project'). However, it doesn't explicitly differentiate from sibling tools like 'generate_variants' or 'edit_screens', which could also involve screen creation or modification.

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 usage guidance in the 'Instructions for Tool Call' section, including timing expectations ('can take a few minutes'), retry behavior ('DO NOT RETRY'), and error handling. It also references an alternative tool ('get_screen') for follow-up. However, it doesn't explicitly state when to use this tool versus alternatives like 'generate_variants' or 'edit_screens' for screen-related tasks.

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 destructiveHint=true (mutation) and readOnlyHint=false (non-read-only), which the description aligns with by implying creation of new variants. The description adds minimal behavioral context beyond annotations—it mentions using a 'text prompt' but doesn't explain what happens to original screens, whether variants are saved automatically, or any rate limits. With annotations covering the safety profile, this meets baseline expectations.

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, efficient sentence that front-loads the core purpose without unnecessary words. Every part earns its place by specifying the action, resource, and method ('using a text prompt'), making it appropriately sized for a tool with rich schema support.

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 (6 parameters, destructive operation) and the presence of both detailed schema (100% coverage) and annotations, the description is reasonably complete. It states the core function, and with an output schema existing, it needn't explain return values. However, it lacks guidance on usage context or sibling differentiation, leaving minor 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 description coverage is 100%, so the schema fully documents all parameters. The description adds no parameter-specific information beyond mentioning 'text prompt' (which maps to the 'prompt' parameter) and implying variant generation. It doesn't clarify semantics like how 'selectedScreenIds' relate to 'projectId' or what 'variants' output entails. Baseline 3 is appropriate when 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 clearly states the action ('Generates variants') and resource ('existing screens within a project'), making the purpose immediately understandable. However, it doesn't explicitly differentiate from sibling tools like 'generate_screen_from_text' (which creates new screens from text) or 'edit_screens' (which modifies existing screens), missing the opportunity for clear sibling 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?

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention when to choose 'generate_variants' over 'generate_screen_from_text' (for creating new screens from scratch) or 'edit_screens' (for direct modifications), nor does it specify prerequisites or constraints beyond what's implied by the parameters.

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

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

Annotations already indicate this is a read-only, non-destructive, closed-world operation. The description adds minimal behavioral context by specifying retrieval by 'project name', but doesn't elaborate on error handling, authentication needs, or rate limits. It doesn't contradict annotations, so it meets the baseline for tools with good annotation coverage.

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

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

The description is a single, efficient sentence that directly states the tool's purpose without unnecessary words. It's front-loaded and appropriately sized for a simple retrieval 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?

Given the tool's low complexity (one parameter), comprehensive annotations, and the presence of an output schema, the description is reasonably complete. It covers the core action and resource, though it could benefit from more contextual guidance about sibling tools to fully aid the 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 has 100% description coverage, fully documenting the 'name' parameter with format and examples. The description adds no additional parameter semantics beyond implying the 'name' is used for retrieval, so it meets the baseline score of 3 where the schema carries the burden.

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 ('Retrieves') and resource ('details of a specific Stitch project'), making the purpose evident. However, it doesn't explicitly differentiate from sibling tools like 'list_projects' or 'get_screen', which would require mentioning it fetches a single project by name rather than listing all projects or retrieving screens.

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. It doesn't mention siblings like 'list_projects' for browsing projects or 'create_project' for creating new ones, leaving the agent to infer usage from context alone.

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

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

Annotations provide readOnlyHint=true and openWorldHint=false, indicating a safe read operation with closed-world data. The description adds minimal behavioral context beyond this, as it doesn't disclose additional traits like error handling, rate limits, or authentication needs. With annotations covering key safety aspects, the description meets a baseline but adds little extra 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 a single, efficient sentence that directly states the tool's purpose without unnecessary words. It's front-loaded with the core action and resource, making it easy to parse. Every part of the sentence earns its place by conveying essential 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?

Given the tool's simplicity (a read operation with 3 parameters), high schema coverage (100%), annotations providing safety context, and the presence of an output schema (which handles return values), the description is reasonably complete. It could be improved by adding usage guidelines or more behavioral details, but it adequately covers the basics for this 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?

Schema description coverage is 100%, with detailed descriptions for all three parameters (name, screenId, projectId), including formats, examples, and deprecation notes. The description doesn't add any parameter semantics beyond what the schema provides, so it meets the baseline score of 3 for high schema coverage without compensating 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 ('Retrieves') and resource ('details of a specific screen within a project'), making the purpose unambiguous. It doesn't explicitly differentiate from sibling tools like 'list_screens' or 'get_project', but the specificity of retrieving a single screen is implied. This is clear but lacks explicit 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 provides no guidance on when to use this tool versus alternatives. It doesn't mention sibling tools like 'list_screens' for multiple screens or 'get_project' for project details, nor does it specify prerequisites or contexts for usage. This leaves the agent without explicit 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?

Annotations provide readOnlyHint=true and openWorldHint=false, indicating a safe read operation with limited scope. The description adds valuable context by explaining the optional projectId parameter behavior ('If empty, lists all global design systems'), which clarifies the tool's scope beyond what annotations convey. No contradictions with annotations exist.

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, well-structured sentence that efficiently conveys the core functionality. It's front-loaded with the main action and resource, with no redundant or unnecessary information—every word serves a clear purpose.

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 low complexity (one optional parameter), rich annotations (readOnlyHint, openWorldHint), and the presence of an output schema, the description is reasonably complete. It covers the basic purpose and parameter behavior, though it could benefit from more explicit differentiation from sibling tools to fully guide the 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?

With 100% schema description coverage, the input schema fully documents the single optional parameter. The description adds minimal semantic value by mentioning 'for a given project', which aligns with the schema's projectId description. This meets the baseline for high schema coverage without significant enhancement.

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 ('Lists') and resource ('all design systems for a given project'), making the purpose immediately understandable. However, it doesn't explicitly distinguish this tool from sibling tools like 'list_projects' or 'list_screens', which would require mentioning what makes design systems distinct from those other 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 implies usage context by specifying 'for a given project', but it doesn't provide explicit guidance on when to use this tool versus alternatives like 'list_projects' or 'get_project'. No exclusions or prerequisites are mentioned, leaving the agent to infer appropriate usage scenarios.

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=true and openWorldHint=false, indicating a safe, non-destructive read operation with limited scope. The description adds context about accessibility ('accessible to the user') and default filtering, but doesn't disclose additional behavioral traits like pagination, rate limits, or authentication needs beyond what annotations cover, resulting in moderate 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 two concise sentences with zero waste: the first states the core purpose, and the second clarifies default behavior. It's appropriately sized and front-loaded, efficiently conveying essential information without unnecessary 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?

Given the tool's low complexity (one optional parameter), rich annotations (readOnlyHint, openWorldHint), and the presence of an output schema (which handles return values), the description is mostly complete. It covers purpose and default behavior adequately, though it could improve by mentioning sibling differentiation or more usage context, but gaps are minor in this 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?

Schema description coverage is 100%, with the input schema fully documenting the optional 'filter' parameter, including its type, description, and examples. The description doesn't add any parameter-specific information beyond what the schema provides, so it meets the baseline score of 3 for high schema coverage without compensating 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 ('Lists') and resource ('all Stitch projects accessible to the user'), with additional clarification about default behavior ('projects owned by the user'). However, it doesn't explicitly differentiate from sibling tools like 'get_project' (which retrieves a single project) or 'list_screens' (which lists screens within projects), missing full sibling distinction.

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

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

The description implies usage by specifying the default behavior ('lists projects owned by the user'), but it doesn't provide explicit guidance on when to use this tool versus alternatives like 'get_project' for single projects or 'list_screens' for project contents. No exclusions or clear alternatives are mentioned, leaving usage context partially 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 declare readOnlyHint=true and openWorldHint=false, indicating this is a safe, read-only operation with a closed world. The description adds no additional behavioral context beyond what annotations provide, such as pagination, rate limits, or error handling, but doesn't contradict 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 a single, efficient sentence that front-loads the core purpose without unnecessary words. It's appropriately sized for a simple list operation, with every part earning 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?

Given the tool's low complexity (one required parameter), rich annotations (readOnlyHint, openWorldHint), and existence of an output schema, the description is mostly complete. It states what the tool does, but lacks usage guidelines, which is a minor gap in this 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?

Schema description coverage is 100%, with the parameter 'projectId' fully documented in the schema. The description adds no extra meaning about parameters beyond implying a project context, so it meets the baseline for high schema coverage without compensating 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 ('Lists') and resource ('all screens within a given Stitch project'), making the purpose immediately understandable. However, it doesn't explicitly differentiate from sibling tools like 'get_screen' (which retrieves a single screen) or 'edit_screens' (which modifies screens), missing full sibling distinction.

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

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

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention when to prefer 'list_screens' over 'get_screen' for individual screens or 'edit_screens' for modifications, nor does it specify prerequisites like needing a valid project ID.

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 destructiveHint=true and readOnlyHint=false, indicating this is a mutation operation. The description adds useful context about what gets updated ('foundational design tokens that apply across all screens') but doesn't disclose additional behavioral traits like permission requirements, rate limits, or what happens to existing configurations. With annotations covering the safety profile, this earns a baseline score for adding some 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 appropriately sized and front-loaded: the first sentence states the purpose and usage context, followed by a bulleted list of configurable aspects. Every sentence adds value, though the final sentence about 'foundational design tokens' could be integrated more tightly. Minor room for improvement in flow prevents a perfect score.

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 (mutating design systems with nested objects), annotations provide safety context, and an output schema exists (so return values needn't be explained). The description covers purpose, usage context, and configurable aspects adequately. However, it doesn't address prerequisites (e.g., needing an existing design system) or potential side effects, leaving a small 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?

Schema description coverage is 100%, so the schema already documents all parameters thoroughly. The description lists configurable categories (Color Palette, Typography, Shape, Appearance, Design MD) which map to some schema properties, but doesn't add significant meaning beyond what's in the schema descriptions. This meets the baseline for high schema 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 purpose with specific verbs ('Updates a design system') and resource ('for a project'), and distinguishes it from siblings like 'create_design_system' by specifying it's for updates rather than creation. It elaborates on what aspects can be updated (visual theme, style, branding) and provides concrete examples of configurable elements.

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

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

The description explicitly states 'Use this tool when the user wants to change the overall visual theme, style, or branding of the application,' providing clear context for when to use it. However, it doesn't mention when NOT to use it (e.g., vs. 'apply_design_system' or 'edit_screens') or provide explicit alternatives, which prevents a perfect score.

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