Server Quality Checklist

Tool Scores

• optimize_imagesA
  4.3/5.0
  Behavior4/5

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

  With no annotations, the description fully discloses the destructive default: 'the source file is replaced by the optimized output' and explicitly notes how to preserve originals. It also discloses other behavioral traits like never upscaling, auto-applying EXIF rotation, and returning final dimensions for <img> tags — all beyond what any annotation would provide. It does not mention error handling or permission requirements, but the core behavioral risks are well covered.

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

  Conciseness4/5

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

  The description is dense but well-organized, front-loading the core operation (resize/re-encode) before detailing optional behavior and usage guidance. Each sentence earns its place, covering defaults, side effects, and a concrete use case. Slightly long but every part is functional; the final 'Typical landing use' sentence is actionable rather than filler.

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

  Completeness4/5

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

  Given no annotations, the description thoroughly compensates: it explains the destructive default, the returned dimensions and sizes, directory support, and the typical workflow. The output schema exists, so the description correctly avoids detailing return fields further. The only gap is the absence of mention of required permissions or error scenarios, but for a local file-processing tool this is acceptable.

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

  Parameters3/5

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

  Schema coverage is 100%, so the description does not need to repeat every parameter definition. It adds semantic context for key parameters like max_width (default 1920, never upscales), format (webp default; jpeg/avif available), widths (srcset variants, wider variants skipped), and keep_originals (default false meaning replacement). This adds value beyond the schema while staying within the baseline-3 expectation for high coverage.

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

  Purpose5/5

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

  The description clearly states the tool resizes and re-encodes images for production web use via sharp, listing specific operations (downscale, convert to webp, EXIF rotation, srcset variants) and distinguishing its scope from siblings like create_image or create_website. It names the resource (images) and the verb (optimize/resize/re-encode), making the purpose unambiguous and differentiated.

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

  Usage Guidelines5/5

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

  The description explicitly states when to use it ('Typical landing use: generate images into assets/img, then optimize the whole directory in one call') and implies alternatives by contrast ('heavy originals don't leak into production', 'keep_originals: true preserves them'). It provides clear context for accepting files or directories and notes default vs. optional behaviors, giving the agent enough guidance for invocation.

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

• get_iconA
  4.4/5.0
  Behavior3/5

  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 that the tool returns 'raw SVG markup' and requires an 'exact name', adding some behavioral context. However, it does not mention error handling, case sensitivity, or what happens when an icon is not found, leaving gaps in transparency.

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

  Conciseness5/5

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

  The description is two sentences long, front-loads the primary action, and contains no unnecessary words. Every sentence earns its place, making it highly concise and well-structured.

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

  Completeness4/5

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

  Given that the schema fully documents all parameters and an output schema exists, the description's brevity is acceptable. It clearly conveys the tool's purpose and usage, and the remaining unknowns (such as precise error behavior) are minor for a simple fetch tool.

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

  Parameters4/5

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

  Schema coverage for parameters is 100%, so the schema already documents each parameter. The description adds meaningful semantic context by explaining that lucide is for 'generic UI icons' and simple-icons for 'brand logos', and by emphasizing 'exact name' for the name parameter. This goes beyond the schema's descriptions.

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

  Purpose5/5

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

  The description clearly states what the tool does: 'Fetch one icon's raw SVG markup by exact name' from two specific icon sets. It distinctly differentiates itself from the sibling tool search_icons by focusing on exact-name retrieval of one icon.

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

  Usage Guidelines5/5

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

  It explicitly instructs to 'Use search_icons first if the exact name/set isn't already known,' providing clear guidance on when to use this tool versus the alternative. This is a direct and useful usage guideline.

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

• install_skillA
  4.6/5.0
  Behavior5/5

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

  With no annotations provided, the description carries the full behavioral burden. It discloses idempotency (existing files kept), execution of third-party CLIs for proxied skills, the session-start timing issue, the gitignore behavior relative to bootstrap_project, and the scoping of manual_only. This is exceptionally transparent about side effects and prerequisites.

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

  Conciseness4/5

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

  The description is dense but each sentence carries essential information: installation method, restart warning, gitignore note, and manual_only scope. It is not minimal, but the complexity (two installation modes, session caveat) justifies the length. Mildly verbose but well-structured.

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

  Completeness5/5

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

  For a tool with two distinct install methods and a session-restart caveat, the description covers all critical context: mechanics, side effects, idle-token behavior for manual_only, and integration with existing project tooling. An output schema exists, so omitting return format is appropriate. No significant gaps.

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

  Parameters4/5

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

  Schema coverage is 100%, so baseline is 3. The description adds value beyond the schema by clarifying that manual_only only applies to bundled skills, that proxied skills run an official CLI, and that .claude/skills/ is gitignored. These enrich parameter understanding beyond the schema's own field descriptions.

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

  Purpose5/5

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

  States a specific verb+resource: 'Install a personal skill into a project.' Clearly differentiates between bundled and proxied installation methods, and the tool name itself disambiguates from sibling tools like bootstrap_project or install_guard. Purpose is unmistakable.

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

  Usage Guidelines4/5

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

  Provides clear context on when and how to use: explains bundled vs. proxied mechanics, and the critical instruction to ask the user to restart after installing. However, it does not explicitly mention alternatives or say 'use this tool when the user wants to install a skill and not for X.' Lacks an explicit exclusion statement, but context is strong.

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

• install_guardA
  4.7/5.0
  Behavior5/5

  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 richly covers the safety implications: idempotency, no clobbering of existing settings, required jq dependency, session restart need, and the specific commands guarded. This is far beyond minimal disclosure.

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

  Conciseness5/5

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

  The description is a single dense paragraph, but each sentence earns its place: purpose, mechanics, safety guarantees, prerequisites, activation, and usage guidance. It is front-loaded with the core verb and resource, and the structure is logical, moving from what it does to when to use it.

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

  Completeness5/5

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

  For a two-parameter tool with an output schema, the description is remarkably complete. It covers installation targets, idempotency, command blocking rules, prerequisite (jq), activation requirement, and the relationship to a sibling tool. This leaves no obvious gaps in understanding what the tool does and how to use it safely.

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

  Parameters3/5

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

  The input schema already provides complete descriptions for both parameters, including the default for target and the requirement for project_path when target='project'. The tool description mostly paraphrases this information, adding no new semantic meaning beyond the schema, 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.

  Purpose5/5

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

  The description opens with a clear verb-resource pair: 'Install the destructive-command guard.' It specifies scope (global vs. project) and differentiates itself from the sibling tool bootstrap_project, which is the primary alternative. This is specific and immediately clear.

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

  Usage Guidelines5/5

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

  The description explicitly states when to use this tool directly ('target="project" or to re-check after a manual jq install') and when not to ('bootstrap_project already checks for the global guard and installs it if missing'). It also names the alternative tool, making the decision tree obvious.

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

• search_iconsA
  4.7/5.0
  Behavior4/5

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

  With no annotations, the description carries the burden. It discloses that the icon sets are local, their sizes and content types, and that exact slugs are unpredictable. It does not explicitly state read-only behavior, but 'search' implies it, and the description adds meaningful context about what the search covers.

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

  Conciseness5/5

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

  Two well-structured sentences with no redundancy. It front-loads the core action and set details, then the usage guidance. Every clause earns its place.

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

  Completeness5/5

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

  An output schema exists, so return-value details are covered. The description provides all necessary context: what sets exist, why search is needed, and how it relates to get_icon. For a search tool with three params, this is fully complete.

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

  Parameters4/5

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

  Schema coverage is 100%, so baseline is 3. The description adds value by giving concrete query examples ('wrench', 'repair', 'github') and the concept of 'English keyword/concept', which clarifies the query parameter's semantics beyond the schema's generic description.

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

  Purpose5/5

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

  The description opens with a specific verb+resource: 'Search two local icon sets by English keyword/concept', clearly naming both icon sets with sizes and examples. It distinguishes itself from the sibling get_icon by stating this tool is for finding the exact name/set to fetch.

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

  Usage Guidelines5/5

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

  Explicitly instructs 'Use this before get_icon' and explains why: 'exact slugs aren't always guessable.' This tells the agent when to use this tool versus the obvious alternative and provides the rationale.

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

• bootstrap_projectA
  4.8/5.0
  Behavior5/5

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

  With no annotations, the description fully discloses behavioral traits: idempotency ('existing files are never overwritten'), conditional install of the destructive-command guard only if missing, the fact that skills load only at session start, and the 'never calls install_guard again once it's there' behavior. This is rich, non-obvious context beyond what any schema could encode.

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

  Conciseness4/5

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

  The description is a single dense paragraph, but every sentence adds a unique behavioral or usage fact. It front-loads the main action and then covers edge cases (guard idempotence, session restart). Slightly long, but the complexity of the tool warrants it; no filler words are present.

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

  Completeness5/5

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

  Given the tool's complexity (5 params, profiles, skill installation, guard checks, session note) and the presence of an output schema, the description covers all necessary context: it explains the next_steps output, preconditions (collect brief in chat), and post-conditions (restart required). It is complete enough for an agent to select and invoke the tool correctly.

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

  Parameters4/5

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

  Schema coverage is 100%, so baseline is 3. The description adds behavioral mapping beyond the schema: profile determines docs/ and skill installation (S vs M/L), stack drives .gitignore and permissions, and vision is used in the brief. This clarifies how parameters influence outcomes, though it doesn't add syntax details. The extra value justifies a 4.

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

  Purpose5/5

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

  The description starts with a specific verb+resource: 'Materialize a new project skeleton in one call' and enumerates concrete artifacts (.gitignore, .editorconfig, .claude/, docs/, Auto-memory). It clearly distinguishes this from siblings like create_website or install_skill by framing it as a one-call project bootstrapper that also installs skills and a guard.

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

  Usage Guidelines5/5

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

  Usage guidance is explicit: 'Collect the brief (name/stack/profile/vision) in chat first, then call.' It also explains when to use the S profile vs M/L ('S skips it and goes straight to code'), instructs to offer skill picks via AskUserQuestion rather than installing the whole catalog, and notes the session restart requirement for new projects. This provides clear context and alternatives.

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

• create_imageA
  4.9/5.0
  Behavior5/5

  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 failure modes (refuses when skill missing or prompt_source empty; installs the skill and directs to SKILL.md), requirements (OPENROUTER_API_KEY in server .env), limitations (mask-based inpainting not supported), data output (searching paths, measured cost), and warns that raw output is full-resolution and the wrong format for production, mandating optimize_images. It also explains the silent behavior of omitting resolution on Gemini (defaults to '1K', worst $/MP).

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

  Conciseness4/5

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

  The description is long but well-structured with labeled sections (MANDATORY FIRST STEP, EDITING, AFTER GENERATING, etc.) and front-loads the primary purpose. However, some information is duplicated from the schema's parameter descriptions, such as model pricing and size rules, which makes it longer than strictly necessary. Every sentence carries useful information, but a bit of trimming could improve conciseness.

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

  Completeness5/5

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

  The description is comprehensive for a tool with 13 parameters and an output schema: it covers prerequisites, failure conditions, model decision table, sizing, editing, post-processing, and integration with the landing build workflow. It even states return values (inline image, saved paths, measured cost), and the output schema covers the detailed return structure, so nothing critical is missing.

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

  Parameters5/5

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

  Schema description coverage is 100%, so baseline is 3, but the description adds significant cross-parameter meaning: it defines the relationship between size and aspect_ratio for Seedream ('do NOT pass size... it just LOWERS what you get'), mandates resolution:'2K' for Gemini, and clarifies how to satisfy the required prompt_source by using the 'image' skill. It also extends parameter usage to the editing workflow via reference_images and naming what must stay unchanged.

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

  Purpose5/5

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

  The description opens with a specific verb phrase: 'Generate or edit image(s) via OpenRouter and save them into the project, returning the image inline in chat plus the saved paths and the measured cost.' This clearly identifies the tool's action, resource, and outputs, and distinguishes it from sibling tools like optimize_images, which is explicitly contrasted as a separate post-processing step.

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

  Usage Guidelines5/5

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

  The description gives explicit workflow guidance: it states when to use this tool in a landing build ('mandatory last step of the image stage... generate the whole series first... then one optimize_images call on assets/img at the end') and names optimize_images as the alternative for resizing/format conversion. It also instructs on model selection ('Seedream covers essentially every task; read the model description before picking anything else'), making clear when to use which model.

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

• create_websiteA
  4.9/5.0
  Behavior5/5

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

  With no annotations provided, the description carries the full transparency burden. It discloses best-effort skill installation with failure handling, idempotency (existing files never overwritten), the deliberate absence of a template for multipage, and the critical need to stop after the call and restart the session for skills to load.

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

  Conciseness5/5

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

  The description is long but well-structured with bullet points, bolded keywords, and explicit 'IMPORTANT' flags. Every sentence contributes unique information about flows, files, failure modes, and post-conditions. It is appropriately sized for the tool's complexity and front-loads the key decision point ('pick with kind').

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

  Completeness5/5

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

  Given the complex two-flow nature of the tool, the description covers purpose, usage conditions, side effects, failure handling, and next steps comprehensively. It references the output schema (task tracker, report, skills_failed field) and does not need to explain return values since an output schema exists.

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

  Parameters4/5

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

  Schema coverage is 100% and the schema descriptions are already detailed. The description adds significant value by elaborating on the 'kind' parameter (detailing what each flow generates) and clarifying 'install_deps' behavior for multipage (ignored). This goes beyond the schema, though some enrichment is redundant.

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

  Purpose5/5

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

  The description clearly states the tool's purpose: 'Set up a website project and hand back a task tracker.' It distinguishes between two distinct flows (landing and multipage), each with a specific use case, making it clear how it differs from generic tools like bootstrap_project.

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

  Usage Guidelines5/5

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

  Explicitly provides when-to-use guidance: 'Use for a new site with no reference' for landing and 'Use when the user points at a site to copy/redo' for multipage. It also instructs the agent to ask via AskUserQuestion when kind is ambiguous, and provides post-call steps (stop, restart session).

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