Server Quality Checklist

Tool Scores

• skill_server_infoA
  4.4/5.0
  Behavior4/5

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

  With no annotations provided, the description carries the transparency burden. It clearly indicates this is a retrieval operation ('Return server-level documentation') and lists the exact fields returned (name, description, skills_dir, transport), making the behavior predictable. It does not explicitly state 'read-only' or 'no side effects', but the wording and scope strongly imply it.

  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 well-structured with distinct sections (function_purpose, Description, Returns, Usage) and every section adds value. It is slightly longer than strictly necessary, but the return list and usage note are relevant and not redundant with the schema, given that the schema has no properties.

  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 simple, parameterless info tool with an output schema, the description fully covers its purpose, returned values, and usage recommendation. It explains what the tool does, what data it provides, and how to handle it (cache after initial call), making it complete for an agent to select and invoke 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?

  The tool has zero parameters, and the schema shows an empty properties object. The baseline for zero parameters is 4, and there is no additional parameter info to add since none exist. The description's focus on return values and usage is appropriate.

  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 'Return server-level documentation including purpose and usage', clearly stating the tool's verb (Return) and resource (server-level documentation). It distinguishes itself from sibling tools by focusing on server metadata rather than skill operations, which are all covered by other tools like skill_list_all and skill_get_detail.

  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?

  The description provides explicit usage context: 'Call this tool once when connecting, then cache/show details in the client UI or logs.' It also notes it is 'Useful for clients to show contextual info' without needing exclusions since no sibling tool serves the same server-info purpose. This is clear guidance on when and why to use it.

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

• skill_get_detailA
  4.5/5.0
  Behavior4/5

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

  With no annotations, the description carries the full burden. It discloses the default note-appending behavior, the output formats (JSON dict vs markdown string), and the content of the returned dict. This gives a clear picture of what the tool does without relying on annotations.

  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 structured into clear sections (Description, Args, Returns, Usage), with the purpose stated upfront. While somewhat lengthy, every sentence provides necessary detail and there is no redundancy except a slight overlap between the 'function_purpose' line and the first Description sentence.

  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 covers all relevant aspects: what the tool returns (list of dict fields), how to control output, and when to use it. It is complete for a tool with three parameters and one required, especially given the existing output schema.

  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?

  The Args section thoroughly explains each parameter: name, include_notes, and markdown_output, including default values and effects. This fully compensates for the 0% schema description coverage, adding significant meaning beyond the bare schema.

  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 'Get full parsed details for a specific skill by name', which is a specific verb+resource combination. It clearly distinguishes this tool from siblings like skill_list_all and skill_read_asset by focusing on fetching a single skill's parsed content.

  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?

  The Usage section provides explicit guidance: 'Use this when the agent needs the full guidance text and metadata for a skill.' It also advises when to set include_notes=False and markdown_output=True. However, it does not explicitly name alternatives or state when not to use this tool versus sibling tools like skill_read_asset.

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

• skill_list_allA
  4.5/5.0
  Behavior4/5

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

  With no annotations provided, the description carries the burden for behavioral disclosure. It clearly states what is returned (summary metadata, excluding body), where the data comes from (skills directory), and the effect of the markdown_output flag. It does not mention potential side effects, but as a listing tool, this is acceptable.

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

  Conciseness5/5

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

  The description is well-structured with clear sections (purpose, description, args, returns, usage). It is concise, front-loaded with the main purpose, and every sentence adds value without unnecessary fluff.

  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?

  The tool is simple with one parameter and an output schema, and the description covers its return values and usage. It lacks details on edge cases (e.g., no skills found, error handling) or explicit statement of read-only nature, but these are minor for a listing tool. Overall, it is sufficiently complete for an agent to use it correctly.

  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?

  The single parameter markdown_output is fully explained: 'If True, return formatted markdown string instead of JSON list (default: False)'. Since the schema provides no description for this parameter, the description effectively compensates with clear semantics and default behavior.

  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 function: 'List available skills with brief metadata (excluding body)' with a specific verb and resource. It distinguishes from siblings by explicitly noting the exclusion of the markdown body and pointing to get_skill_detail for full content.

  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?

  The description provides clear usage context: 'Use this to present a catalog of available skills' and mentions an alternative (get_skill_detail for full content). It implies when not to use (when full content is needed), but lacks an explicit 'when not' statement, so it falls just short of a 5.

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

• skill_list_notesA
  4.5/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 and does well: it explains that notes are additive records created via store_skill_note() or manually, without editing existing files. It also discloses the two possible return formats based on markdown_output. It does not mention permissions or error cases, but for a read-only listing tool this is sufficient.

  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 well-structured into sections (purpose, description, args, returns, usage) and each sentence contributes value. It is slightly verbose with redundancy between the first line and the description paragraph, but remains efficient and easy to scan.

  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 simple two-parameter list tool, the description is complete: it covers purpose, parameter semantics, return values for both modes, and usage guidance. The presence of an output schema reduces the need to explain return structure, but the description still covers it explicitly.

  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 0%, so the description must compensate. It fully describes both parameters: 'name' is the hyphen-case skill name matching the directory, and 'markdown_output' controls whether output is a formatted markdown string or JSON list. This adds complete meaning beyond the bare schema.

  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 function: 'List notes created under a skill's _notes directory' and expands with 'Enumerates note files stored under a skill's _notes and notes directories.' This is a specific verb+resource, distinct from sibling tools like skill_list_assets or skill_read_asset.

  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?

  The description gives explicit usage context: 'Use this to browse available notes and select one to read with skill_read_asset().' It also explains when to set markdown_output for a more readable format. It does not explicitly name alternatives or exclusions, but the guidance is clear and actionable.

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

• skill_store_noteA
  4.5/5.0
  Behavior4/5

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

  Without annotations, the description carries full responsibility for behavioral disclosure. It transparently states that the tool only creates new note files, never edits existing files, and stores notes under a '_notes' directory. It also reveals the return structure (path, created, message). While it doesn't address error conditions or idempotency, the core non-destructive behavior is well communicated.

  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 well-structured with clear sections (function_purpose, Description, Constraints, Args, Returns) and uses concise bullet points. A few phrases are slightly redundant ('Additions only' and 'never edits existing files'), but overall every sentence serves a purpose and the text is not excessively long.

  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 simple 3-parameter tool with no annotations, the description is exceptionally complete. It covers purpose, usage scope, constraints, all parameters, and the return value. The provided output schema description further enhances completeness, so the agent has all necessary information to invoke the tool correctly.

  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?

  With 0% schema description coverage, the description must compensate, and it does thoroughly. It explains each argument: name must be hyphen-case and match the skill directory, title is a short descriptive label, and content supports Markdown. This goes far beyond the plain string types in the schema, providing critical usage guidance.

  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 specific action ('Append a new note to a skill') and the resource ('a skill'). It also distinguishes from siblings by emphasizing additive note-taking rather than editing or asset management, making the tool's unique role unambiguous.

  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?

  The description provides explicit when-to-use scenarios ('Use this to record observations, corrections, suggested improvements, and example scripts') and a clear when-not-to-use constraint ('never edits existing files'). However, it does not explicitly name alternative tools for editing or asset management, so it stops short of a 5.

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

• skill_add_assetsA
  4.6/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 the full burden. It discloses that a shared overwrite policy applies, that individual entries may be rejected if invalid, and that a follow-up note is mandatory. It also mentions the return type, offering a clear behavioral picture 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.

  Conciseness4/5

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

  The description is well-structured with clear sections (function_purpose, description, important note, args, returns). It is somewhat lengthy due to the IMPORTANT note, but every sentence earns its place, especially the follow-up documentation requirement.

  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?

  The description covers the tool's operation, validation behavior, and return type reference. It points to add_skill_asset for return details, which is acceptable given the output schema exists. It could detail partial failure behavior more explicitly, but it mentions individual rejection.

  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?

  The input schema has no descriptions (0% coverage), but the Args section explains each parameter: name, assets with detailed item structure (path, content, encoding), and overwrite as a boolean. This adds significant meaning beyond the bare schema.

  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 'Bulk add multiple assets to a skill,' clearly stating the verb and resource. It explicitly differentiates from the sibling tool 'skill_add_asset' by identifying itself as a 'convenience wrapper' for efficiency, making its purpose distinct.

  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?

  The description says it is for 'efficiency when scaffolding several files,' which indicates when to use it. It does not explicitly say 'use skill_add_asset for a single asset,' but the contrast with the sibling tool implies this. The shared overwrite policy and rejection behavior provide additional usage context.

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

• skill_search_indexA
  4.6/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 the full burden. It discloses case-insensitive substring matching across name/description/body and precisely defines both return modes. The read-only nature is implied but not explicitly stated; no contradictions exist.

  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?

  Uses labeled sections (function_purpose, Description, Args, Returns, Usage) with front-loaded purpose. However, 'function_purpose' and the first bullet under Description restate the same information, adding minor redundancy.

  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?

  Captures search semantics, all parameters, return formats, and usage intent. It doesn't discuss when to prefer sibling list/detail tools or limitations like empty results, but overall the description is sufficient for a simple two-parameter search tool.

  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 has 0% description coverage, so the description must define parameters. It explains 'query' as a case-insensitive substring and 'markdown_output' as a toggle for markdown vs JSON output, adding meaning beyond the schema's type/default alone.

  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 'Search skills by case-insensitive substring across name, description, and body' with a specific verb and target resource. Clearly distinguishes from sibling list/get/create tools by specifying search semantics and searchable fields.

  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 an explicit usage instruction: 'Use this to quickly locate relevant skills by topic or keywords' and advises setting markdown_output=True for readability. Doesn't explicitly mention when to use alternative tools like skill_list_all or skill_get_detail, so it lacks exclusions.

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

• skill_add_assetA
  4.7/5.0
  Behavior5/5

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

  With no annotations, the description fully carries the transparency burden. It discloses path safety enforcement, parent directory creation, binary support, overwrite behavior, and the return dict. The IMPORTANT note about always creating a documentation note is valuable behavioral guidance.

  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 well-structured with function_purpose, description, IMPORTANT callout, and Args/Returns sections. It is front-loaded and organized, though the IMPORTANT note is slightly verbose. Overall it 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?

  The description covers prerequisites (existing skill directory), file path rules, encoding, overwrite behavior, return values, and a required follow-up documentation step. This is complete for the tool's complexity and coordinate with the output schema.

  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 0%, but the description compensates by explaining each parameter in the Args section, including types, defaults, and encoding/overwrite semantics. This fully clarifies the meaning of all five parameters beyond the bare schema.

  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 adds (or overwrites) a single asset file in an existing skill directory. The verb 'Add' and the resource 'asset file' are specific, and the scope 'single' distinguishes it from sibling skill_add_assets.

  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?

  The description provides clear context: existing skill directory, single asset, optional overwrite, and a mandatory follow-up note via skill_store_note. However, it does not explicitly mention when to prefer skill_add_assets for bulk operations or other alternatives, so it stops short of full when/when-not guidance.

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

• skill_createA
  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 fully carries the transparency burden. It discloses the exact actions (creates directory, writes SKILL.md), the additive non-overwriting constraint, failure conditions (name invalid or already exists), and the placeholder insertion for empty bodies. This is thorough behavioral disclosure beyond what structured annotations could provide.

  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 structured into labeled sections (function_purpose, Description, Constraints, Args, Returns) making it highly scannable and organized. While longer than the minimal ideal, each section contributes necessary information without redundancy or filler, earning a solid 4.

  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 6-parameter creation tool with no annotations, the description is remarkably complete. It covers purpose, detailed constraints, parameter semantics, failure conditions, and return value structure. The agent has everything needed to select and invoke the tool correctly in context.

  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?

  The schema has 0% parameter description coverage, but the Args section directly compensates by explaining all 6 parameters with types and semantic meaning. It adds valuable guidance like 'hyphen-case recommended' for name, 'optional list of tool names' for allowed_tools, and the behavior for empty bodies, going beyond mere type definitions.

  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 pair: 'Create a new skill directory containing a SKILL.md per Agent Skills Spec.' This clearly identifies the tool's function and distinguishes it from sibling read-only tools like skill_list_all and skill_get_detail. It also clarifies the deliverable (SKILL.md file), making 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.

  Usage Guidelines4/5

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

  The description provides clear contextual guidance: it is for creating new skills, is additive only, and fails if the skill already exists or the name is invalid. However, it does not explicitly specify when NOT to use this tool or point to alternatives (e.g., for updating existing skills), so it stops short of a 5.

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

• skill_list_assetsA
  4.7/5.0
  Behavior4/5

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

  No annotations are provided, so the description carries the full burden. It discloses recursive enumeration, exclusion of SKILL.md, and the exact return shapes (list of dicts vs markdown string). It does not cover error behavior for missing skills, but for a read-only listing tool this is acceptable and significantly above baseline.

  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 organized into clear sections (function_purpose, Description, Args, Returns, Usage) and is front-loaded with the core purpose. It is slightly verbose at ~150 words for a two-parameter tool, but every section adds value and nothing feels redundant.

  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 covers purpose, parameter semantics, return formats, usage flow, and points to the companion read tool. An output schema exists (per context), but the description is self-sufficient even without it. This is complete for a listing tool.

  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 0%, but the description fully compensates: 'name: str The hyphen-case name of the skill whose assets to list' and 'markdown_output: bool If True, return formatted markdown string instead of JSON list (default: False).' This adds meaning beyond the bare type/default in the schema.

  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 states a specific verb and resource: 'List non-SKILL.md files within a skill folder (recursive).' This clearly differentiates it from siblings like skill_list_all (lists skills) and skill_read_asset (reads file contents). The scope (excluding SKILL.md, recursive) is also explicit.

  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?

  Provides explicit usage context: 'Call before reading assets to present available files to the agent or user.' It also names the alternative for reading content: 'For reading actual content, use skill_read_asset() with the returned path.' This is strong when-to-use and when-not-to-use guidance.

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

• skill_read_assetA
  4.8/5.0
  Behavior5/5

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

  With no annotations provided, the description fully carries the burden of behavioral disclosure. It reveals path-traversal prevention, size limiting via max_bytes, UTF-8 vs base64 fallback, the inclusion of a MIME type guess, and a truncation flag. This is exceptionally transparent 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.

  Conciseness5/5

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

  The description uses clear, labeled sections (function_purpose, Description, Args, Returns, Usage) and every sentence carries useful information. It is detailed but not verbose, and the structure makes scanning easy.

  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 covers purpose, safety properties, parameters, return format, and usage context. It even notes edge-case behavior like truncation and encoding fallback. For a read tool with an output schema, this is complete and actionable.

  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 0%, so the description must compensate entirely. It does: name is defined as 'hyphen-case skill name (must match skill directory)', path as 'Relative file path within the skill directory', and max_bytes with its default. It also describes the return fields, giving complete semantic meaning beyond the bare schema.

  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 'Read a specific asset file within a skill (returns text or base64 data)', using a specific verb and resource. It clearly distinguishes this from sibling tools like skill_list_assets and skill_add_asset, which either list or add assets rather than reading a single asset's content.

  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?

  The description explicitly says to 'Use after listing assets to fetch the content of a specific file for analysis or display', which gives clear usage context. It also advises increasing max_bytes for large assets, but does not explicitly mention when not to use the tool or name alternative tools, so it falls short of a 5.

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

• skill_trash_user_assetA
  4.8/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 discloses that the operation is a move to trash rather than a delete, specifies the destination format (trash/assets/<skill_name>/<timestamp>__<relative_path>), details path restrictions for different skill types, and notes that operations are logged. This is comprehensive 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.

  Conciseness5/5

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

  The description is well-structured and front-loaded with the primary purpose. Each section (Purpose, Policy, Args, Returns) earns its place with unique information. The bulleted policy list is scannable, and there is no redundant or filler text.

  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 and the existence of an output schema, the description is remarkably complete. It covers action, constraints, target path, parameter meanings, and logging behavior. The return values are already depicted in the output schema, so no further explanation is needed. There are no significant gaps for an agent to correctly select and invoke this tool.

  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?

  The schema provides zero description coverage, so the description must compensate. The Args section explicitly defines 'name' as 'Skill name' and 'path' as 'Relative path within the skill directory,' which adds crucial meaning beyond the bare schema. The Policy section further clarifies valid path patterns, making the parameters well-understood.

  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 action: 'Move a user-created asset or note into trash instead of deleting it.' The verb 'move' and resource 'user-created asset or note' precisely define the tool's scope. It also distinguishes from the sibling tool skill_trash_user_skill, which trashes an entire skill, by focusing on individual assets/notes.

  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?

  The Policy section provides clear usage boundaries: it enumerates exactly which subtrees are allowed for bundled/Anthropic skills, states core assets cannot be trashed, and explains that user-created skills allow any asset path. This effectively tells the agent when the tool applies and when it does not, though it does not explicitly name alternative tools for other scenarios.

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

• skill_trash_user_skillA
  4.8/5.0
  Behavior5/5

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

  With no annotations provided, the description fully carries the behavioral disclosure burden. It discloses that the operation moves rather than deletes, uses a timestamped trash path, logs operations, and rejects non-user-created skills—far beyond minimal expectations.

  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 front-loaded with a clear purpose statement, followed by concise policy, args, and return sections. Every section provides necessary information without filler or redundancy.

  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 covers the operation's behavior, constraints, argument semantics, and return value shape. Even with no annotations and a minimal schema, an agent has enough information to invoke the tool correctly and interpret results.

  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?

  The input schema only provides name and force with types/defaults. The description adds meaningful semantics: name identifies the skill to trash, and force requires explicit confirmation with False producing a dry refusal. This fully compensates for the 0% schema description 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 states a specific action: moving a user-created skill directory into a trash location rather than hard deleting it. It clearly differentiates from the sibling skill_trash_user_asset tool by targeting skills specifically.

  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?

  The description provides explicit policy: only user-created skills may be trashed and bundled/Anthropic skills are rejected. It also explains the force flag behavior, but it does not explicitly name alternatives for trashing assets, so it stops short of full alternative guidance.

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