designforyou

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

Annotations already declare readOnlyHint=true, so the agent knows it's a safe read operation. The description adds value by stating the return format: 'Returns template IDs, names, and previews.' However, it does not disclose other behavioral nuances like pagination, rate limits, or how previews are represented. This is adequate but not rich, so a mid-range score is appropriate.

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

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

The description is two sentences long and front-loaded with the core purpose. The first sentence establishes the action, the second covers filtering and results. Every word serves a purpose; there is no fluff or redundancy. This is a model of conciseness.

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 (2 optional parameters, read-only, output schema present), the description provides sufficient context for an agent to decide when to invoke it. It covers purpose, optional filters, and return content. It could mention subcategory filtering explicitly, but the schema fills that gap. The description is complete enough for this low-complexity 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?

The input schema already provides descriptions for both parameters (category and subcategory) with examples, achieving 100% schema coverage. The description adds a minor detail by listing an additional category example 'living-panels' not present in the schema, but it does not explain subcategory usage. Since the schema fully documents the parameters, a baseline score of 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Browse the DesignForYou template catalog.' It specifies the verb 'browse' and the resource 'template catalog', and distinguishes itself from sibling tools like create_template and recommend_template by focusing on browsing existing templates. It also mentions optional filtering and return values, making the scope 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 this tool: browsing the template catalog with optional category/subcategory filters. It does not explicitly mention alternatives or exclusion criteria, but the purpose is so distinct from siblings (e.g., create_template, recommend_template) that the intended usage is evident. Missing explicit 'when not to use' guidance 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.

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

Annotations already declare readOnlyHint=true, covering the safe read nature. The description adds useful context about the brief contents and intended workflow, which goes beyond the annotations. No contradictions or hidden behaviors are apparent. Minor gaps like response format details are acceptable for a simple getter.

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 action and resource, then provides usage context. Every sentence contributes meaning. The term 'no-server-LLM' is slightly terse but not wasteful.

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 getter with one parameter, the description is complete. It lists the return contents (PanelScript instructions, schema, unit templates, success criteria) and gives usage context. Annotations cover the safety profile. No output schema exists, but the description sufficiently explains what is returned.

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

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

Schema description coverage is 100% (single parameter 'premise' with a clear description). The main description does not add additional parameter semantics. Baseline 3 is appropriate because the schema fully documents the parameter.

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

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

The description uses the specific verb 'Return' and names the resource 'no-server-LLM Living Panels authoring brief' with enumerated contents (PanelScript instructions, schema, unit templates, success criteria). It clearly distinguishes from sibling tools by focusing on the authoring brief and referencing the follow-up tool comic_submit_design.

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 when to use the tool: when the MCP client will do creative direction with its own model. It also connects to the next step (comic_submit_design). However, it does not explicitly say when not to use it or mention alternative tools like comic_revision_brief, so it falls short of a full 5.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false. The description adds valuable behavioral context by enumerating the returned data (stale-write hash, dirty-node contract) and framing the tool as a step in the revision workflow, complementing the read-only annotation without contradicting it.

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

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

The description is two sentences with the return payload front-loaded and the usage context clearly stated. Every word is purposeful; there is no redundancy or unnecessary detail.

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

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

This is a simple read-only tool with one parameter, and the description lists its output components (Story JSON, stale-write hash, allowed patch paths, dirty-node contract) while specifying the workflow position. Given the lack of an output schema, the description provides enough information for an agent to understand the tool's role and invoke it correctly.

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

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

The input schema fully covers the single parameter comic_id with a clear description ('Comic id to revise.'). The tool description adds no additional parameter-level meaning 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 uses a specific verb ('Return') and resource ('current Story JSON, stale-write hash, allowed patch paths, and dirty-node contract'), clearly defining the tool's scope. It also distinguishes this from the sibling comic_submit_revision by explicitly positioning it as the pre-submission brief for client-authored edits.

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 when to use the tool ('when the client will decide the edit with its own model') and directs the agent to the follow-up call ('then call comic_submit_revision'). This provides clear contextual guidance, though it does not enumerate when not to use it or 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?

Annotations already declare readOnlyHint=true, so the description's main contribution is the 'Free to call' note and the semantic meaning of the ready flag (whole comic live at reader_url). This adds useful behavioral context beyond the structured annotations without contradicting them.

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

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

The description is a single, information-dense sentence. It front-loads the purpose, then details the metrics and the ready flag, with 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 one-parameter tool with no output schema, the description fully explains what the tool returns (panels, motion clips, voice lines counts, ready flag) and the significance of ready=true. Combined with strong annotations, this is a complete picture 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?

Schema coverage is 100%, with the parameter comic_id described as 'Comic id returned by create_comic'. The description reuses this context but adds no new parameter-specific details, so it meets the baseline without exceeding it.

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

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

The description clearly states the tool's function: checking asset-production progress for a comic. It specifies the resource (comic created with create_comic) and the exact metrics (panels, motion clips, voice lines done vs total, ready flag), distinguishing it from sibling tools like audition_status.

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—after creating a comic with create_comic—and adds the 'Free to call' guideline. It does not explicitly mention alternatives or when-not-to-use, but the context is sufficient for a status-checking 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?

Beyond annotations, the description discloses that the tool validates, saves, generates character sheets, panel/unit art, motion clips, voice-over, and assembles the public reader. This conveys significant side effects and mutation, consistent with readOnlyHint=false and destructiveHint=false. It does not mention costs or return values, but annotations already cover the safety profile.

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 front-loads the purpose and then details the pipeline. Every clause adds actionable context, with 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?

The description covers the input and processing pipeline comprehensively, but omits what the function returns or how the agent should follow up. Since there is no output schema, this return-value gap is a notable omission, though sibling tools like comic_status may imply monitoring.

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 five parameters well-described in the input schema. The description does not add param-specific semantics beyond the overall workflow, so the baseline of 3 is appropriate.

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

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

The description clearly states the tool accepts a client-authored Living Panels Story JSON and starts artifact production, including the specific pipeline (validate, save, generate, assemble). It distinguishes itself from sibling tools like comic_submit_revision and create_comic by emphasizing client-directed input and avoiding the server story LLM.

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 client authors the story directly, without relying on a server LLM. It implies a workflow but does not explicitly name alternatives or exclusions, making it helpful but not fully prescriptive.

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 a key behavioral trait: it does not invoke a server revision LLM, and it regenerates only inferred dirty producer nodes (e.g., panel:<id>, motion:<id>, tts:<bubble_id>). This adds meaningful context beyond the readOnlyHint=false and destructiveHint=false annotations, which are consistent with the described write-and-regenerate behavior.

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

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

Two sentences, front-loaded with the primary action, and every clause contributes to understanding purpose and behavior. 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?

The description, combined with a 100% schema-covered parameter list and clear annotations, is sufficient for an agent to select and invoke the tool. It could mention return values or status, but since there is no output schema, the description covers the core behavior adequately without major gaps.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value by giving concrete examples of dirty producer nodes and explaining that targeted changes regenerate only those nodes, reinforcing the distinction between the 'changes' and 'story' parameters. This goes beyond the schema alone.

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 names the exact resource ('client-authored Living Panels revision'), while the qualifier 'without using a server revision LLM' distinguishes it from server-driven revision workflows. This clearly separates it from siblings like comic_revision_brief or comic_submit_design.

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

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

The description gives clear context: use this tool when applying a client-authored revision, not a server LLM revision. It also notes that targeted changes are the preferred path for small edits. It doesn't explicitly name alternative tools, but the guidance is sufficient for an agent to decide when to invoke it.

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 goes far beyond annotations by revealing asynchronous behavior: 'starts generating every asset in the background,' 'Returns immediately,' and 'Production takes several minutes — poll comic_status.' It also discloses the output (story summary, reader_url) and the need for polling. No contradiction with annotations (readOnlyHint=false, openWorldHint=true, destructiveHint=false).

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 four sentences, front-loaded with the main verb and resource, and every sentence adds unique value: scope, background generation, immediate return, and follow-up polling. No fluff 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?

Despite no output schema, the description gives a complete picture of the tool's behavior and result: what is created, what is returned, how long it takes, and how to check status. It even mentions details like '~13 panels of art with character consistency' and 'per-line voice-over,' making it fully self-contained for a complex creation 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 coverage is 100% for the single parameter 'premise,' and the schema already explains it as 'The story premise, one paragraph is plenty.' The description only repeats 'one-paragraph premise' without adding new meaning about parameter formatting or constraints. Baseline 3 is appropriate since the schema handles the semantics.

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: 'Write and produce a Living Panels interactive comic from a one-paragraph premise.' It details the full scope (5-page comic, panels, dialogue, motion, voice casting) and distinguishes it from lower-level tools in the sibling list (e.g., cast_character, generate_scene_frame) by emphasizing it's a single all-in-one call.

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

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

The description implies when to use the tool (for creating a full comic from a premise) and provides a workflow ('Returns immediately... poll comic_status until ready... share the reader_url'). However, it does not explicitly contrast with alternatives like comic_revision_brief or comic_design_brief, so it lacks a clear 'when-not-to-use' statement.

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

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

Annotations already mark this as non-read-only and non-destructive; the description adds meaningful context: it stores a user-owned template in the canonical catalog, does not publish to the anonymous gallery, and the returned id is immediately usable with other tools. This goes beyond the annotations by clarifying side effects and integration behavior.

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

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

Two sentences, 46 words, with the action and resource front-loaded. Every clause adds value—what it creates, how the result is used, where it is stored, and what it does not do.

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 10 parameters and no output schema, but the description covers the essential return behavior (template_id) and its integration with get_text_fields and generate. It does not enumerate all parameters, but the schema already handles that. The description is sufficient for the agent to select and invoke the tool correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds little parameter-specific detail beyond calling it a 'structured brief', but the schema already thoroughly documents each parameter, so no significant gap exists.

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 starts with a specific verb ('Create') and resource ('private reusable DesignForYou template') and clearly states it derives from a structured brief. It distinguishes itself from siblings like browse_templates and generate by emphasizing privacy, reusability, and catalog storage.

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 explains that the returned template_id works with get_text_fields and generate, and explicitly states it does not publish to the anonymous gallery, giving the agent a clear sense of when this tool is appropriate. It lacks an explicit alternative name, so it doesn't fully earn a 5, but the context is strong.

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 behavioral traits beyond annotations: it explains that session_id triggers refinement (editing previous image), context_ids provide visual context for consistency, and model selection with H3 aliases. It details how context_labels work for multi-reference models, and skip_prompt_merge bypasses compression. Annotations already show write intent (readOnlyHint=false) and non-destructive nature (destructiveHint=false), so the description adds rich operational context 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 three sentences with no wasted words. It front-loads the main purpose and then efficiently covers all major parameters and usage patterns. Every sentence earns its place by explaining a core aspect of the tool's behavior.

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 12 parameters and 100% schema coverage, the description provides a thorough workflow overview. It explains the required parameters, optional refinements, and model options. It could clarify the relationship between context_ids and reference_urls (are they mutually exclusive?) and note that context_labels only applies to gpt-image-2. However, it covers the core use cases well and the output schema exists to document return values.

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 baseline is 3. The description adds significant semantic context: explains that variants support expressions/time-of-day, context_ids ensure character consistency, and skip_prompt_merge retains detail for complex scenes. It also clarifies model aliases ('h3 balanced' == 'minimax-h3-image-balanced'). This goes beyond the schema's descriptions and helps the agent understand parameter interactions.

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 'generate' and the resource 'finished images from a template plus a description'. It distinguishes itself from sibling tools like recommend_template by explicitly stating the prerequisite of having a template_id, differentiating it from other generation tools. It covers a wide range of use cases across categories (Instagram, logo, etc.).

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 guidance: 'Use this after the user has selected or explicitly supplied a template_id; otherwise call recommend_template first'. Also explains when to use variants, session_id, context_ids, skip_prompt_merge, and model aliases. This directly helps the agent decide between this tool and its 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?

Annotations already mark readOnlyHint=true, so the read-only nature is known. The description adds value by specifying the authenticated-user requirement, the exact data returned (balance, usage, Stripe status), and that it is free to call. No contradictions with annotations.

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

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

The description is a single sentence, front-loaded with the verb and resource, and contains no filler. Every word adds meaning, earning a high 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 there are no parameters and no output schema, the description is sufficiently complete for a simple read-only balance check. It clearly lists what the user gets. It could mention response format, but that is not essential for such a straightforward 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?

The tool has zero parameters, and schema description coverage is 100%. With no parameters, the baseline is 4, and the description correctly focuses on the return value rather than explaining non-existent 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's function with a specific verb 'Return' and the exact resource: 'the authenticated user's current credit balance, usage, and Stripe subscription status.' It fully distinguishes from siblings, none of which relate to credits.

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

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

The description implies when to use it (checking credits) and adds 'Free to call' as a usage hint. However, it does not explicitly mention alternatives or exclusions. Since no sibling tools cover this functionality, the lack of explicit alternatives is acceptable.

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, so the read-only nature is covered. The description adds behavioral context by stating the operation is free and that it returns current values of editable fields, which provides useful information beyond the annotations without contradicting them.

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

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

The description is two sentences long and every word adds value. The first sentence states the function, and the second provides precise usage guidance without any 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?

For a simple read-only listing tool with one parameter and no output schema, the description is complete: it explains what is returned (current values of editable text fields), when to use it, and how it relates to the generate tool. No further information is needed for an agent to select and invoke it correctly.

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

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

The input schema has full coverage (100%) for the single parameter template_id, with a description already stating 'The template ID to get text fields for.' The tool description does not add further semantic detail about the parameter, so the baseline of 3 applies since the schema handles the meaning adequately.

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 lists a template's editable text fields (headline, subhead, CTA, etc.) with current values. The verb 'list' and specific resource 'template text fields' make the purpose unambiguous, and it distinguishes itself from sibling tools like generate by explicitly positioning itself as a pre-generation step.

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

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

The description explicitly says to use it right after a template is chosen and BEFORE generate when precise field filling is desired instead of a freeform description. This provides clear when-to-use guidance and contrasts with the alternative, making the usage context unmistakable.

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

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

Beyond the readOnlyHint annotation, the description discloses key behaviors: auto-detecting category, ranking by relevance, returning recommendations for user selection, and the exact condition to call generate. This adds meaningful context not present in annotations.

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

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

Two sentences, front-loaded with the main verb and resource, and every clause serves a purpose: purpose, workflow, and explicit guardrail. No fluff 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?

Given the output schema and complete parameter descriptions, the description fully covers the tool's purpose, usage flow, and key constraints. It is sufficient for the agent to select and invoke correctly without additional 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 input schema already covers all parameters with descriptions (100% coverage), including auto-detection for category. The description adds only a general 'Describe what you need' which overlaps with the use_case parameter. Minimal added semantic value beyond schema.

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

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

The description opens with a specific verb and resource: 'Recommend the best matching templates for any use case.' It clearly distinguishes from siblings like browse_templates (generic browsing) and generate (template generation) by focusing on auto-detection and relevance ranking.

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 when-to-use guidance ('any use case') and an explicit exclusion: 'do not call generate in the same turn unless the user explicitly names a template_id or asks you to skip selection.' This is concrete, actionable direction for the agent.

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

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

Annotations are minimal (readOnly=false, destructive=false, openWorld=true), so the description carries the transparency burden. It discloses credit costs (base 3, +2 per hi-res cell), the background-removal behavior, the fixed-grid cropping, and the cell-resolution limitation that hi_res_cells addresses. This goes far beyond the structured 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 dense and front-loaded: the first sentence captures the full pipeline, and the optional hi-res details are placed after the base behavior. No filler or repeated schema information; every sentence adds material context like credits, resolution limits, or model override behavior.

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 (8 parameters, nested objects, output schema), the description is remarkably complete. It explains the main workflow, costs, optional hi-res enhancement, and model routing. Because an output schema exists, the absence of return-value details is acceptable.

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

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

Schema description coverage is only 25%, so the description must compensate. It does add significant meaning for quality.hi_res_cells and quality.hi_res_model by explaining costs, purpose, and model routing, but it leaves most other core parameters (character, style, sheet, cells, output, provider) to the schema. The schema's nested titles and defaults help, but the description only partially fills the gap.

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

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

The description uses a specific verb ('Generate') plus resource ('visual-novel character sprite sheet') and enumerates the exact pipeline steps: crop, chroma-key removal, validation, and manifest output. It clearly distinguishes this tool from siblings like generate_character_video or generate_scene_frame by scoping it to VN sprite sheets.

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

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

The description gives clear context for when to use the tool: to produce a VN Creator-ready sprite sheet with fixed-grid cropping and background removal. It does not explicitly name alternatives or exclusion criteria, but the specificity and billing details make the intended use unambiguous.

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

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

The annotations already declare readOnlyHint=true and openWorldHint=false, but the description adds valuable behavioral context: 'no-cost,' 'does not generate images, use an LLM, or charge credits,' and 'fixed' payload. This goes beyond the annotations to clarify side-effect-free behavior and tool limitations, though it doesn't detail the return payload shape (but output schema 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 two sentences, front-loaded with the core purpose, and every clause earns its place. It is concise without being under-specified.

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

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

For a simple tool with one optional parameter, existing output schema, and clear annotations, the description fully covers the context: what it does, when to use it, what it avoids, and its cost behavior. No additional context is needed to use it correctly.

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

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

Schema coverage is 100% and the parameter 'mode' has a clear description ('Which widget payload shape to return without generation') and a pattern defining allowed values. The description adds little extra meaning beyond the schema, just emphasizing 'fixed' and the debugging context. Baseline 3 is appropriate since 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 tool's purpose: 'Return a fixed, no-cost DesignForYou widget payload for ChatGPT Apps debugging.' It specifies the verb (return), resource (widget payload), and purpose (debugging). It also distinguishes itself from siblings by explicitly noting it 'does not generate images, use an LLM, or charge credits.'

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

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

The description gives explicit when-to-use guidance: 'Use this only to verify the template gallery/result iframe renders correctly.' It also provides exclusions by stating what it does NOT do (generate images, use an LLM, charge credits), effectively telling the agent when not to use it and implying alternatives.

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