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

With no annotations provided, the description carries the full burden. It discloses key behavioral traits: cost ('1 credit per image'), efficiency benefits ('single API call, faster processing'), prerequisites, and detailed return structure. However, it doesn't mention error handling or rate limits.

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

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

The description is well-structured with clear sections (e.g., API, COST, WHEN TO USE, Use cases, PREREQUISITES, RETURNS). It's front-loaded with key info but could be slightly more concise by integrating some details more tightly.

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 (2 parameters with nested objects, no output schema, no annotations), the description is highly complete. It covers purpose, usage, efficiency, prerequisites, cost, return structure, and use cases, providing sufficient context for effective tool invocation.

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

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

Schema description coverage is 100%, so the schema already documents all parameters thoroughly. The description adds minimal param semantics beyond the schema, such as linking 'mockup_uuid' to 'get_mockups' and noting 'export_options' apply to 'ALL renders.' Baseline 3 is appropriate when schema does 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 explicitly states the tool's purpose: 'Render MULTIPLE mockups in a single request' and 'Returns array of image URLs.' It clearly distinguishes from sibling tools like 'create_render' by emphasizing batch processing and efficiency.

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 guidance: 'WHEN TO USE: When user wants to generate 2 or more mockup images.' It contrasts with 'create_render' by stating 'MORE EFFICIENT than calling create_render multiple times' and includes prerequisites: 'Call get_mockups first.'

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 full burden. It discloses the API endpoint (POST /collections) and return values, but lacks details on permissions, error handling, or side effects. It adds some behavioral context but is incomplete for a mutation tool.

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?

Well-structured with clear sections (API, WHEN TO USE, RETURNS). Each sentence adds value: purpose, usage scenarios, API details, and return info. No redundant or wasted 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?

For a 2-param creation tool with no annotations and no output schema, the description is fairly complete: covers purpose, usage, API, and returns. However, it lacks details on authentication, error cases, or behavioral constraints, 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 parameters. The description adds no param-specific info beyond the schema, but with 0 parameters in the description and high schema coverage, the baseline is 3. It earns a 4 because the 'RETURNS' section implicitly clarifies that 'name' maps to the collection's name, adding slight semantic value.

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

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

The description clearly states the verb 'Create' and resource 'new collection' with the purpose 'to organize mockups.' It distinguishes from siblings like 'get_collections' (read) and 'create_batch_render' (different resource).

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

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

The 'WHEN TO USE' section explicitly lists scenarios: creating groups/categories, organizing by project/client/product type. It provides clear context for when to invoke this tool versus alternatives like 'get_collections' or other creation 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes key behaviors: the API endpoint (POST /renders), cost (1 credit per render), and that the returned image URL is valid for 24 hours. It also implies this is a write operation (creating a render) and mentions efficiency considerations. However, it doesn't cover potential error conditions, rate limits, or authentication requirements.

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, API/cost, usage guidelines, prerequisites, parameter details, returns). Most sentences earn their place by providing essential information. However, the 'SMART OBJECT OPTIONS' section is quite detailed and could potentially be more concise while still being informative.

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 (5 parameters with nested objects, no annotations, no output schema), the description does a good job of providing context. It covers purpose, usage, prerequisites, parameter semantics, and return values. The main gap is the lack of output schema, but the description compensates by explaining the return structure. It could benefit from more behavioral context like error handling.

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 description coverage is 100%, so the baseline is 3. The description adds significant value by explaining the 'SMART OBJECT OPTIONS' section in detail, providing practical examples and usage context for parameters like asset.fit, color, blending_mode, and adjustment_layers. This goes beyond the schema's technical descriptions to help the agent understand how to use these parameters effectively.

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: 'Render a SINGLE mockup with design assets. Returns an image URL.' It specifies the exact action (render), resource (mockup), scope (single), and output (image URL), and distinguishes it from the sibling 'create_batch_render' for multiple images.

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 guidance: 'WHEN TO USE: When user wants to generate exactly ONE mockup image. For 2+ images, use create_batch_render instead (more efficient, same cost).' It also includes prerequisites: 'Call get_mockups first - it returns both mockup_uuid AND smart_object uuids needed for rendering.' This clearly defines when to use this tool versus alternatives and necessary steps.

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 full burden. It clearly discloses the destructive nature of the tool ('permanently deleted'), specifies the API endpoint (POST /psd/delete), and describes the return value (success confirmation message). It doesn't mention authentication requirements or rate limits, but covers the critical behavioral aspects for a deletion tool.

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 (API, WHEN TO USE, WARNING, RETURNS). Each sentence adds value: the first states the core action, subsequent sections provide usage guidance, warnings, and return information. No wasted words or redundancy.

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

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

For a destructive tool with no annotations and no output schema, the description provides good coverage: clear purpose, usage guidelines, behavioral warnings, and return information. It doesn't specify error conditions or authentication requirements, but covers the essential context for safe tool invocation.

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

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

Schema description coverage is 100%, so the schema already fully documents both parameters. The description adds context about the consequences of setting 'delete_related_mockups' to true, but doesn't provide additional semantic 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 explicitly states the action ('Delete a PSD file') and resource ('PSD file'), and distinguishes it from siblings by specifying the optional deletion of related mockups. It clearly differentiates from tools like 'upload_psd' (creation) and 'get_mockups' (read).

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 'WHEN TO USE' section provides explicit scenarios for tool usage (removing uploaded PSD, cleaning up unused files, optionally removing derived mockups). It also includes a clear warning about the consequences of setting 'delete_related_mockups' to true, offering guidance on when to use that option.

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 of behavioral disclosure. It clearly states this is a knowledge retrieval tool that 'does NOT require an API call - returns cached knowledge instantly,' which informs the agent about performance characteristics and lack of external dependencies. However, it doesn't specify response format, size limitations, or error conditions.

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 (WHEN TO USE, TWO EDITOR TYPES, INTEGRATION APPROACHES, TOPICS AVAILABLE) and uses bullet points for readability. While comprehensive, some sections could be more concise, and the final sentence about 'cached knowledge' could be integrated earlier for better front-loading.

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

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

For a single-parameter knowledge retrieval tool with no output schema, the description provides substantial context: it explains what knowledge is available, when to use it, editor types, integration approaches, and topics. The main gap is the lack of output format details, but given this is a documentation/help tool rather than an operational API, the description is reasonably complete.

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

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

The schema has 100% description coverage with detailed enum descriptions, so the baseline is 3. The description adds value by listing 'TOPICS AVAILABLE' with brief explanations of each topic, providing context beyond the schema's enum list. However, it doesn't explain parameter interactions or provide additional syntax details.

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

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

The description clearly states the tool's purpose: 'Get comprehensive knowledge for embedding the Dynamic Mockups Editor into websites and apps.' It specifies the exact resource (knowledge about embedding the editor) and distinguishes itself from sibling tools which are all about creating, deleting, or retrieving mockups/renders rather than providing integration guidance.

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 includes an explicit 'WHEN TO USE' section listing six specific scenarios when to call this tool, such as when users ask about embedding, integration approaches, or handling events. It also distinguishes from siblings by focusing on knowledge retrieval rather than API operations like create_batch_render or get_mockups.

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

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

With no annotations provided, the description carries the full burden and does well by disclosing key behavioral traits: it specifies the API endpoint (POST /renders/print-files), cost (1 credit per file), and return structure (array of print files with fields). However, it lacks details on error handling or rate limits.

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

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

The description is well-structured with clear sections (purpose, API/cost, usage guidelines, contrast, returns) and front-loaded key information. It is appropriately sized, though the 'WHEN TO USE' bullet points could be slightly more concise.

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 (5 parameters, nested objects) and no annotations or output schema, the description is mostly complete: it covers purpose, usage, behavior, and returns. However, it could benefit from more detail on error cases or advanced parameter usage to fully compensate for the lack of 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?

Schema description coverage is 100%, so the schema already documents all parameters thoroughly. The description does not add significant meaning beyond what the schema provides, such as explaining parameter interactions or use cases, meeting the baseline for high coverage.

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

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

The description clearly states the specific action ('export high-resolution print files') and resource ('for production use'), distinguishing it from sibling tools like 'create_render' by specifying it outputs print-ready files rather than full mockups.

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 provides a 'WHEN TO USE' section with three bullet points detailing scenarios (production-ready files, high DPI output, separate smart object files) and contrasts it with 'create_render', offering clear alternatives and exclusions.

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 of behavioral disclosure. It clearly states that this tool 'does NOT require an API call - returns cached knowledge instantly,' which is crucial behavioral information about performance and data source. However, it doesn't specify response format, error handling, or data freshness details.

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

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

The description is well-structured with clear sections (purpose, when to use, important details) and every sentence adds value. It could be slightly more concise by combining some of the bullet points, but overall it's efficiently organized and front-loaded with the core 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?

For a single-parameter tool with no annotations and no output schema, the description provides comprehensive context about what information is returned, when to use it, and behavioral characteristics. The main gap is the lack of output format details, but given this is a knowledge retrieval tool rather than an action tool, the description is quite 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 the 'topic' parameter with its enum values. The description adds meaningful context by explaining when to use specific topics (e.g., 'use topic="integration" to get base URL, headers, code examples'), which provides practical guidance beyond the schema's technical specification.

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: retrieving API knowledge base information including integration details, billing, rate limits, formats, and best practices. It specifies the exact resources (API knowledge base) and distinguishes itself from sibling tools that perform actions like creating renders or deleting 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?

The description provides explicit guidance on when to use this tool, listing specific user query scenarios (integration, pricing, rate limits, formats, best practices, support). It also clarifies when NOT to use it (for direct API integration vs. using MCP tools) and distinguishes it from sibling tools that perform actual API operations.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes the tool as a retrieval operation (implying read-only), specifies it's for the authenticated user, and outlines the return format. However, it lacks details on error handling, rate limits, or authentication requirements beyond the user 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 and front-loaded with the core purpose, followed by usage guidelines and return details. Each sentence adds value: the first states the action, the second provides the API endpoint, the third gives usage context, the fourth explains what catalogs are, and the fifth describes the output. There is no wasted text.

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 (0 parameters, no output schema, no annotations), the description is largely complete. It covers purpose, usage, and return values adequately. However, it could improve by mentioning any limitations (e.g., pagination) or linking to sibling tools like get_collections for more specific operations.

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 0 parameters with 100% coverage, so no parameter documentation is needed. The description appropriately omits parameter details, focusing instead on usage and output. A baseline of 4 is applied since it doesn't need to compensate for any schema gaps.

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

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

The description clearly states the verb ('Retrieve') and resource ('all available catalogs for the authenticated user'), distinguishing it from siblings like get_collections or get_mockups. It explicitly defines catalogs as 'TOP-LEVEL containers that hold collections,' which helps differentiate its scope from other list operations.

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 includes an explicit 'WHEN TO USE' section with three bullet points: seeing workspace structure, finding catalog UUIDs for filtering, and understanding mockup organization. This provides clear context on when to invoke this tool versus alternatives, though it doesn't name specific sibling tools for comparison.

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

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

With no annotations provided, the description carries the full burden and does well by disclosing key behavioral traits: it specifies the API endpoint ('GET /collections'), default filtering behavior, and return format details (array with specific fields like 'uuid' and 'mockup_count'). However, it lacks information on potential rate limits, error handling, or authentication needs, which are relevant for a read operation.

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

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

The description is well-structured with clear sections (API, WHEN TO USE, RETURNS), front-loaded key information, and no wasted sentences. Each part earns its place by adding distinct value, such as usage scenarios and return details, making it efficient and easy to parse.

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

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

Given the tool's moderate complexity, no annotations, and no output schema, the description is largely complete: it covers purpose, usage, behavior, and return values. However, it could improve by mentioning any limitations (e.g., pagination) or prerequisites, which would enhance completeness for a tool with two parameters and no structured output documentation.

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, so the baseline is 3. The description adds minimal value beyond the schema by mentioning 'optional filtering by catalog' and the default catalog behavior, but it doesn't provide additional syntax or format details for the parameters, relying on the schema's thorough documentation.

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

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

The description clearly states the specific action ('Retrieve collections') and resource ('collections'), distinguishing it from siblings like 'get_catalogs' or 'get_mockups' by focusing on collections that group mockups. It explicitly explains that collections 'GROUP related mockups together within a catalog,' providing a precise purpose beyond just the tool name.

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

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

The description includes a dedicated 'WHEN TO USE' section with three bullet points listing specific scenarios (e.g., 'Browse available mockup groups/categories'), and it explicitly states the default behavior ('only returns collections from the default catalog'), guiding when to use this tool versus alternatives like 'get_catalogs' for catalog UUIDs.

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 of behavioral disclosure. It effectively describes the tool's behavior: it retrieves detailed information for a single mockup via a GET API call, specifies it's for refreshing data, and outlines the return structure (e.g., uuid, smart_objects, text_layers). However, it lacks details on error handling or rate limits, keeping it from a perfect score.

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, usage guidelines, returns) and uses bullet points for readability. It is appropriately sized but could be slightly more concise by integrating some bulleted lists into prose. Most sentences earn their place by adding value, such as differentiating from siblings.

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 (1 parameter, no output schema, no annotations), the description is largely complete. It covers purpose, usage, and return values in detail. However, it could improve by mentioning potential errors (e.g., invalid UUID) or authentication needs, which would enhance completeness for a tool with no annotations.

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, with the 'uuid' parameter documented as 'The mockup UUID. Get this from get_mockups response.' The description adds minimal value beyond this, mentioning 'by its UUID' and referencing 'get_mockups' for obtaining the UUID, but doesn't provide additional semantic context. 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 specific action ('Get detailed information about a SINGLE specific mockup') and resource ('by its UUID'), distinguishing it from sibling tools like 'get_mockups' which handles listing/browsing. The verb 'Get' combined with the resource scope is precise and 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 explicit guidance with a 'WHEN TO USE' section listing specific scenarios (e.g., user has a UUID, needs details for one template) and a 'NOT REQUIRED for rendering!' note that references the alternative 'get_mockups' tool. It clearly defines when to use this tool versus its sibling.

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 full burden and does well by disclosing: this is a read operation (GET API), it returns comprehensive data (both mockup and smart-object UUIDs), and clarifies workflow dependencies. It doesn't mention rate limits or authentication needs, but provides substantial behavioral context.

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

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

Well-structured with clear sections (API, WHEN TO USE, IMPORTANT, WORKFLOW, RETURNS) but somewhat verbose. Every sentence adds value, though some redundancy exists (e.g., 'This is the PRIMARY tool' could be integrated more tightly).

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

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

For a read operation with no annotations and no output schema, the description provides exceptional completeness: clear purpose, detailed usage guidelines, behavioral context, workflow integration, and a thorough specification of return values that compensates for the missing 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?

Schema description coverage is 100%, so the schema already documents all four parameters thoroughly. The description mentions 'optional filtering' but doesn't add specific parameter details beyond what the schema provides, meeting 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 verb ('Retrieve') and resource ('mockups from My Templates'), specifies it's the PRIMARY tool for discovery, and distinguishes it from sibling get_mockup_by_uuid by emphasizing it returns everything needed for rendering without requiring additional calls.

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 provides a 'WHEN TO USE' section with four specific scenarios, names an alternative tool (get_mockup_by_uuid) and explains when NOT to use it, and outlines a complete workflow (get_mockups → create_render) with clear sequencing.

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 of behavioral disclosure and does so effectively. It discloses cost (6 credits per request), input requirements (mutually exclusive image_url or image_data_b64), output behavior (temporary URL that should be downloaded), and practical tips for best results. The only minor gap is lack of explicit rate limit or error handling information.

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 (API, COST, WHEN TO USE, INPUT, TIPS, RETURNS) and every sentence earns its place by providing essential information. It's appropriately sized for a tool with cost implications and specific usage scenarios, with no redundant or unnecessary 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 tool's complexity (image transformation with cost implications), no annotations, and no output schema, the description provides comprehensive context. It covers purpose, usage guidelines, behavioral aspects (cost, input constraints, output handling), parameter semantics, and practical tips. The description fully compensates for the lack of structured metadata.

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 description coverage is 100%, so the baseline is 3. The description adds significant value by explaining the mutual exclusivity requirement ('Only ONE input method is required per request'), providing context about supported formats, and offering practical guidance for best results. This goes well beyond what the schema provides, though it doesn't add syntax 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 tool's purpose with specific verbs ('Transform any image into a realistic embroidery/stitched effect') and distinguishes it from siblings by focusing on embroidery transformation rather than rendering, mockup editing, or file management. It provides concrete use cases that make the purpose 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 explicitly includes a 'WHEN TO USE' section with four specific scenarios for using this tool, such as converting artwork to embroidery style or preparing designs for print-on-demand products. This provides clear guidance on when this tool is appropriate versus other tools in the sibling list that handle different tasks like rendering, collections, or file management.

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 full burden and does well by disclosing key behavioral traits: it describes the upload-to-creation workflow (auto vs. manual), specifies the PSD requirement (smart object layers), and outlines the return format ({uuid, name}). However, it doesn't mention potential rate limits, authentication needs, or error conditions.

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, API, usage, workflow, returns), front-loaded with the core purpose, and every sentence adds value—no redundant or vague statements. It efficiently covers necessary information without waste.

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

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

Given the complexity (4 parameters with nested objects, no output schema, no annotations), the description is mostly complete: it explains the purpose, usage, workflow, and returns. However, it lacks details on error handling, authentication, or how the tool integrates with sibling tools like create_collection for the collections parameter.

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 parameter semantics beyond the schema—it mentions 'create_after_upload: true' in the workflow but doesn't explain other parameters like psd_category_id or mockup_template properties. It relies heavily on the schema for parameter details.

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

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

The description clearly states the specific action ('Upload a PSD file') and resource ('to create custom mockup templates'), distinguishing it from siblings like delete_psd (deletion) or get_mockups (retrieval). It explicitly mentions the purpose of adding user-owned PSD mockup templates.

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 includes a dedicated 'WHEN TO USE' section with explicit scenarios (adding custom templates, creating from Photoshop files) and prerequisites (PSD must contain smart object layers). It also distinguishes usage from alternatives by specifying the workflow options (auto-create vs. manual creation).

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