Server Quality Checklist

Tool Scores

• perch_docsA
  3.9/5.0
  Behavior4/5

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

  With no annotations, the description carries full responsibility for disclosing behavior. It transparently describes the three output modes: a list of page metadata without 'page', a full page with 'page', and search results for 'search'. It does not mention error handling (e.g., invalid page paths) or edge cases like both parameters being set, which are minor gaps. Overall, it adds meaningful behavioral context.

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

  Conciseness5/5

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

  The description is remarkably concise, fitting all essential information into two sentences (semicolon-separated). It front-loads the core purpose ('modding and API documentation') and then efficiently details the three operation modes. There is zero filler, and every clause contributes to understanding.

  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?

  For a tool with only two optional parameters and no output schema, the description covers the necessary ground: it explains how parameters alter the response and what the list output includes (id, title, description). It lacks explicit handling of invalid input or interactions between 'page' and 'search', but these are edge cases. Given the complexity, it is nearly 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 description coverage is 0%, so the description must explain the parameters itself. It does so effectively: 'page' changes the output from list to specific page, and 'search' triggers a text search. It even provides example page paths ('modding/your-first-widget', 'api/host'). This goes beyond the bare schema, though it doesn't cover all potential parameter combinations or validation rules.

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

  Purpose4/5

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

  The description clearly states it provides modding and API documentation, with specific behaviors: lists pages without 'page', returns a specific page with 'page', and searches with 'search'. It uses a clear verb-resource structure and distinguishes itself from a generic 'docs' title. However, it does not explicitly differentiate from sibling tools like perch_guide or perch_vocabulary, so it falls short of a 5.

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

  Usage Guidelines3/5

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

  The description gives concrete usage instructions for its own parameters (when to use 'page' vs. 'search', and the default list behavior). This implies the appropriate use cases. However, it does not explicitly state when to choose this tool over sibling tools (e.g., perch_guide) or provide any 'when not to use' exclusions. The guidance is self-contained but lacks comparative context.

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

• perch_vocabularyA
  3.9/5.0
  Behavior3/5

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

  With no annotations, the description must carry the disclosure burden. It implies a read-only fetch operation and lists the sections, but it does not explicitly state that it is non-destructive, nor does it mention default behavior when 'part' is omitted, error handling, or return format. The description covers the basic behavior but leaves some details unstated.

  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, efficient sentence. It front-loads the core purpose and then explains the parameter. No wasted words, and it covers the essential information needed to invoke the tool.

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

  Completeness3/5

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

  For a simple fetch tool with one optional parameter, the description provides the main content areas and the parameter role. However, it does not specify what happens when 'part' is not provided (e.g., returns all sections) or the structure of the returned data. Given the absence of annotations and output schema, a bit more detail would round out the picture.

  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 schema provides only an enum for 'part' with no property description (0% coverage). The description adds meaning by explaining that passing 'part' fetches one section, clarifying the parameter's role. This goes beyond the raw schema, though it does not list the possible values (already in the enum) or elaborate on the default.

  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: it is the canonical vocabulary (api-spec.json) covering display components, props, colors, host functions, handlers, scopes, and contexts. It names the specific resource and the content types, and it stands apart from sibling tools like perch_guide or perch_docs, which serve different reference needs.

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

  Usage Guidelines3/5

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

  The description implies when to use it (when you need vocabulary definitions) and mentions the 'part' parameter for fetching a section. However, it does not explicitly state when not to use it or how it relates to alternatives such as perch_docs or perch_guide, leaving the choice somewhat implicit.

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

• perch_runA
  4/5.0
  Behavior3/5

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

  With no annotations, the description must disclose behavioral traits. It explains the side effect (launches an external application) and the effect on the widget, but does not describe what happens after launch (e.g., blocking vs. async, return values, error behavior). It also doesn't mention any required prerequisites beyond the environment variable. This is a moderate disclosure—adequate for a launcher but missing potential status/output details.

  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 sentences with no redundant words. The main action is front-loaded ('Launches Perch...'), followed by the effect, platform constraint, and environment variable tip. Every sentence carries meaningful information, making it highly efficient.

  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?

  For a simple launcher with one param and no output schema, the description covers the essential details: what it does, platform, environment setup, and expected effect. It lacks explicit mention of return behavior or post-launch outcomes, but given the simplicity and the absence of annotations, it is reasonably complete. Siblings are clearly different, so no additional disambiguation is needed.

  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 schema already describes the single parameter (package_dir: 'Absolute path of the package folder') with 100% coverage, so the description adds little semantics beyond rephrasing it as 'folder that contains this package.' Since the schema fully documents the parameter, the description doesn't need to add more; baseline 3 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 clearly states the action: 'Launches Perch with PERCH_MOD_DEV pointed at the folder...' and names the specific resource (the package folder). It distinguishes the tool from siblings by focusing on execution (run) versus documentation/validation (perch_guide, perch_validate, etc.), and even describes the observable effect (widget appears in Settings → Layout → Widgets and on the notch). Purpose is 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 context for when to use this tool (to run a package) and includes important platform constraints ('Windows only') and environment setup ('Set PERCH_EXE if Perch is not installed through Steam'). It does not explicitly state when not to use it or mention alternatives (like perch_validate), but the sibling tools are clearly different in nature, so the usage intent is inferable without explicit exclusions.

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

• perch_guideA
  4.2/5.0
  Behavior3/5

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

  No annotations are provided, so the description carries the burden of behavioral disclosure. It implies the tool is informational (a guide), but does not explicitly state that it is read-only, returns text, or has no side effects. For a non-mutating guide, this is acceptable but not explicit.

  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, well-structured sentence that front-loads the core purpose ('short authoring guide for Perch mods') and then lists the covered topics. The instruction 'Read this first' is terse and actionable. There is no wasted wording.

  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?

  For a guide tool with no parameters and no output schema, the description covers the main aspects an agent needs: what it is, what topics it covers, and its role as an entry point. It does not mention the return format, but for a text guide this is implied and not a critical gap.

  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, so the baseline is 4. The description does not need to add parameter semantics, and it correctly avoids mentioning any. This is appropriate given the empty input 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 purpose: it is a short authoring guide for Perch mods, and enumerates the specific topics it covers (package shape, Lua declarations, handlers, scopes, style). This is distinct from sibling tools like perch_vocabulary or perch_examples, and the resource is 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 phrase 'Read this first' gives an explicit usage instruction, indicating this should be the starting point before consulting other Perch-related tools. However, it does not explicitly name alternatives or conditions when not to use this tool, so it stops short of full guidance.

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

• perch_examplesA
  4.3/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 behavioral burden. It clearly states the two modes: without id, list packages; with id, return all files of that package. This is transparent about the core read-only behavior. It doesn't mention edge cases like invalid ids or output format, but it covers the primary behavior sufficiently.

  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 with no fluff. It front-loads the purpose and concisely captures the conditional branching behavior. Every word earns its place, making it highly efficient.

  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?

  For a one-parameter tool with no output schema or annotations, the description covers the essential behavior. The only gap is the lack of detail on what 'returns every file' means (e.g., file paths, contents, or metadata) and how invalid ids are handled. These are minor for a tool this simple, so it is nearly complete.

  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 zero description coverage for the only parameter `id`. The description fully compensates by explaining that absent `id` triggers a list operation, while present `id` returns the files of that package. This adds concrete semantic meaning beyond the raw string type 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 clearly states the tool's function: 'lists' builtin packages without an id and 'returns every file of that package' with an id. It identifies the resource (Perch packages) and the conditional behavior, distinguishing it from sibling tools like perch_guide or perch_docs by framing these as 'complete worked examples of the vocabulary.'

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

  Usage Guidelines3/5

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

  The description implies usage: use it to see the builtin examples, with or without an id. However, it does not explicitly contrast with sibling tools (e.g., when to use perch_examples vs perch_docs or perch_vocabulary), nor does it state any prerequisites or exclusions. Usage context is clear but not fully articulated.

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

• perch_validateA
  4.3/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 full burden. It discloses the scope of validation (static checks only) and, importantly, its limitation (not authoritative), steering the agent to the definitive check. It does not explicitly state it is non-destructive, but 'checks' implies read-only, and the absence of any side-effect warning is acceptable for a validation 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 compact, with each sentence earning its place. It front-loads the core checks and ends with a practical routing note. No filler or repetition.

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

  Completeness3/5

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

  For a tool with no output schema, the description does not mention what the tool returns (whether a boolean, list of errors, or some other verdict). An agent needs to interpret the result, and that gap makes the description not fully self-sufficient. However, the list of checks is thorough, so it partially covers the context.

  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%: the single parameter is fully documented with 'Absolute path of the package folder (the one holding mod.json)'. The description adds no extra semantics beyond that, so the baseline of 3 applies—adequate but not additive.

  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 names a specific verb ('checks'), a specific resource ('package folder'), and enumerates the exact validation dimensions (mod.json schema, entry existence, lua parsing, widget declaration, display types). It is also clearly distinguished from sibling perch_run, which the description explicitly contrasts as the definitive check.

  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 versus the alternative: 'The definitive check is Perch's own loader — run the package (perch_run) and read Settings → Installed mods for the loader's verdict.' This tells the agent that this validation is preliminary and gives a concrete condition for preferring the sibling.

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