Server Quality Checklist

Tool Scores

• quickshell_get_typeA
  3.9/5.0
  Behavior3/5

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

  There are no annotations, so the description carries the full burden. It states the operation is a fetch (implying read-only) and mentions the output is Markdown and the default version. However, it does not disclose potential errors, rate limits, or any side effects, which is acceptable for a read-only tool but leaves some unknown.

  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 two sentences, front-loaded with the main purpose and examples, then a usage tip and default. Each sentence earns its place; no 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?

  Given it is a simple doc-fetch tool with an output schema, the description covers the essential usage: what it does, examples, case-sensitivity, and default version. It doesn't mention alternatives like quickshell_get_qt_type, but the 'QML type' phrasing implies the distinction. Overall, an agent has enough to correctly select and invoke the tool.

  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 0%, so the description must compensate. It provides examples for type_name and namespace, and explains case-sensitivity, which helps the agent form valid arguments. However, it does not describe the accepted format for version beyond 'latest', nor how to discover available versions (despite a sibling list_versions). It adds value but not fully comprehensive.

  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 the tool fetches a documentation page for a QML type as Markdown, with concrete examples (PanelWindow, HyprlandMonitor). It distinguishes from siblings by specifying 'QML type' vs Qt types, though it does not explicitly name alternatives. The purpose is unambiguous and specific.

  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 call quickshell_list_types first when unsure of namespace/type name, and notes case-sensitivity. This gives clear when-to-use guidance and references a sibling tool, leaving no ambiguity about prerequisites.

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

• quickshell_list_guide_pagesA
  3.9/5.0
  Behavior3/5

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

  No annotations are provided, so the description must disclose behavior on its own. It mentions the in-process cache and how to bypass it with refresh=True, and the default version behavior. However, it does not disclose error handling (e.g., what happens if an invalid version is given), output format beyond 'list', or any side effects. For a simple listing tool, the disclosed cache behavior adds value, but the lack of error/return specifics leaves gaps.

  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 concise—two sentences—and front-loads the core purpose (listing guide pages) while immediately adding examples. It then covers the two parameters (version, refresh) efficiently. No unnecessary words or repetition. Every sentence contributes value.

  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?

  Given the tool is a simple list operation with no output schema, the description adequately conveys the action and inputs. However, it does not specify the return structure (e.g., an array of page names) or how the list is presented. For an agent, knowing the exact output type would reduce ambiguity, especially when chaining with get_guide_page. The description is adequate but not fully complete in terms of expected results.

  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 fully interpret both parameters. It explains 'version' as a doc version and provides examples (install-setup, introduction, etc.), clarifying expected values beyond the schema's default 'latest'. It also explains the 'refresh' parameter as a cache-bypass flag. This adds meaning the schema lacks, though it could be slightly more explicit about possible version formats (e.g., valid strings) but the examples suffice.

  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 action: 'List the Usage Guide pages available for a given doc version.' It provides concrete examples of pages (install-setup, introduction, etc.), making the resource and scope unambiguous. While it does not explicitly name sibling tools, the verb 'list' versus 'get' in siblings like quickshell_get_guide_page strongly differentiates it without needing further clarification.

  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 offers context on when to use the tool by mentioning it works for a specific doc version and defaults to latest if not provided. It also explains the refresh parameter for cache bypass. However, it provides no explicit guidance on when to choose this tool over alternatives (e.g., when to use list_guide_pages vs get_guide_page), and no exclusions or restrictions are stated. The use case is implied but not contrasted with siblings.

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

• quickshell_get_implementationA
  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 behavioral burden and does meaningful work: it discloses that this is a real-world implementation reference, NOT official documentation, and tells the agent to trust the docs on disagreement — a valuable reliability caveat beyond any schema. It also implies files are large and subject to partial reads, though it doesn't explicitly describe max_chars truncation behavior.

  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?

  Three front-loaded sentences with no filler: purpose first, then parameter usage, then the reliability caveat. The organization is logical and every sentence earns its place, though it could tighten the parameter list slightly.

  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 4 params, 0% schema coverage, and no annotations, the description covers the tool's purpose, the supporting workflow, the find behavior, and a key reliability caveat, while an output schema exists to describe return values. Remaining gaps (max_chars semantics, exhaustive source values) are minor for a documentation-reading 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 is 0%, so the description must compensate, and it does well for most parameters: it explains find's values ('osd'/'workspace'/'ipc') and purpose, and tells the agent where path comes from. Source is only implied via 'Caelestia or Noctalia', and max_chars is left unexplained, leaving minor gaps.

  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 ('Read') with a precise resource ('a QML file from the Caelestia or Noctalia shells'), which clearly distinguishes it from the sibling get_* tools (get_type, get_guide_page, get_example, get_qt_type). The reference to quickshell_search_implementations further differentiates its data source.

  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?

  Explains the workflow for obtaining paths from quickshell_search_implementations before calling, and instructs how to use the find parameter to jump to relevant sections. It implies usage context versus siblings but does not explicitly state when NOT to use this tool in favor of the other get_* tools.

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

• quickshell_changelogA
  4.4/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 of behavioral disclosure. It states the return format (Markdown) and the source URL, giving the agent a concrete expectation of the output. It doesn't mention freshness or failure modes, but for an idempotent fetch of public documentation this is adequate.

  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?

  One sentence with the verb and resource front-loaded, plus a source URL and a targeted use-case hint. Every element earns its place and there is no 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?

  With an output schema present and zero parameters, the definition covers the what, the source, and the typical query it answers. It could add a note about which sibling to use for version listings, but nothing essential is missing for this simple 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?

  The tool has zero parameters and the schema coverage is trivially 100%, so there is nothing the description needs to add. The baseline of 4 for a no-parameter tool 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 names a specific verb ('Fetch') and resource ('Quickshell changelog'), and pins the exact use case: answering 'what's new / what changed' questions. This clearly distinguishes it from siblings like quickshell_list_guide_pages and quickshell_list_types, which serve different content areas.

  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?

  It explicitly states when to use this tool: 'Use this to answer what's new / what changed questions,' which gives an agent clear selection criteria. It does not name sibling tools or state exclusions, but for a zero-parameter changelog fetch this context is sufficient.

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

• quickshell_list_qt_typesA
  4.4/5.0
  Behavior4/5

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

  The description discloses that it discovers types from the QtQuick module page, the pinning behavior of qt_version, and the cache bypass via refresh=True. Although it doesn't mention output format or error handling, given no annotations and the read-only nature of a list tool, it provides sufficient 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 compact, with clear separation of purpose, usage guidance, and parameter notes. Every sentence adds value, and key information is front-loaded.

  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 list tool with three optional parameters and no output schema, the description covers the main usage and cache behavior. The ambiguity around the module parameter is a minor gap, but overall the description is sufficient for an agent to call it correctly.

  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 description explains qt_version (pins minor version) and refresh (bypasses cache) but does not explain the module parameter's purpose or allowed values. With schema coverage at 0% in the context signal, the description partially compensates but leaves module semantics unclear, which is a gap for agents.

  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 lists QML types from doc.qt.io for QtQuick and its sibling modules, and explicitly differentiates it from quickshell_list_types for Quickshell-specific types. It uses a specific verb and resource, making its 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 Guidelines5/5

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

  It explicitly instructs when to use (for Qt base types) and when not (for Quickshell-specific types, use quickshell_list_types instead). It also explains the qt_version parameter behavior. This leaves no ambiguity about selection.

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

• quickshell_aboutA
  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 behavioral disclosure burden. It discloses that the tool fetches a remote page and returns it as Markdown, which clearly signals a read-only network retrieval. It does not mention rate limits or error behavior, but for a simple fetch operation this is adequately transparent.

  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 filler: the first sentence states the action, resource, and output format; the second gives concise usage guidance. Every component 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?

  For a no-parameter tool with an output schema, the description is complete. It identifies the exact URL, the output format, and the type of questions it answers, which is enough for an agent to select and invoke the tool correctly alongside its siblings.

  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 100% schema coverage, so there is nothing for the description to add about parameter semantics. The baseline of 4 applies because no parameter documentation is needed.

  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 a specific verb ('Fetch'), a specific resource ('the Quickshell About page'), and an output format ('as Markdown'). It also defines the intended use case ('high-level questions like what Quickshell is, who maintains it, and how it's licensed'), which distinguishes it from sibling tools focused on versions, changelogs, guide pages, types, examples, and search.

  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 concrete usage context: use for high-level questions about what Quickshell is, maintainership, and licensing. It doesn't explicitly mention when not to use it or name alternative sibling tools, but for this simple no-argument fetch tool the guidance is sufficient to route an agent correctly.

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

• quickshell_get_qt_typeA
  4.5/5.0
  Behavior4/5

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

  With no annotations present, the description carries the full burden and discloses genuine behaviors: output is Markdown from an external source (doc.qt.io), the module parameter disambiguates names that exist in several modules, and qt_version defaults to the newest doc set unless pinned to a minor. It does not cover failure behavior (unknown type name or ambiguous names without module), but the disclosed traits go well beyond a bare fetch statement.

  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?

  Three sentences with zero filler: purpose and output format front-loaded, followed by examples, the use-case trigger, then the two optional parameters. Every sentence earns its place and the structure is easy to scan.

  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?

  Selection context, invocation details for all three parameters, source, and output format are all covered, and the output schema handles the return-value contract. The only gap is unspecified failure behavior when a name is unknown or ambiguous and module is omitted, which is minor for a doc-fetch 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%, so the description must compensate — and it does for all three parameters. name gets concrete examples and the notion of value types (color, vector3d); module gets a purpose ('disambiguate names that exist in several modules') plus examples like 'qtquick' and 'qtquick-controls'; qt_version gets a rationale ('match your installed Qt instead of the newest') with a format example ('6.8').

  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 and resource: 'Fetch one Qt type's reference page from doc.qt.io as Markdown,' backed by concrete examples (Rectangle, Text, MouseArea, Timer, Item, RowLayout, color, vector3d). The explicit mention of doc.qt.io and QtQuick/QtQuick.Controls/QtQuick.Layouts cleanly distinguishes it from the sibling quickshell_get_type, which targets Quickshell's own types, and from the list/search siblings.

  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?

  Gives an explicit trigger condition: 'Use this when a Quickshell config imports QtQuick / QtQuick.Controls / QtQuick.Layouts types and you need their properties, signals, or syntax.' It does not name when-not-to-use conditions or directly point to an alternative like quickshell_get_type, though the use-case framing strongly implies the boundary.

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

• quickshell_list_typesA
  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 behavioral disclosure burden. It usefully discloses that the tool defaults to the latest doc version and uses an in-process cache that can be bypassed with refresh=True. This adds meaningful behavioral context beyond a basic one-line description.

  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 and front-loaded. It opens with what the tool does, immediately gives examples, and then covers the remaining parameters in short, unambiguous sentences with no 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?

  For a low-complexity listing tool, the description is nearly complete. It covers all three parameters and the main usage modes, but since there is no output schema, it could have briefly described the return shape or structure. This is a minor gap.

  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 no per-parameter descriptions, so the description must compensate. It does so effectively: namespace is illustrated with concrete examples, the no-namespace behavior is specified, version defaults to 'latest', and refresh=True is explained as bypassing the cache.

  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 Quickshell QML types'. It also clarifies optional namespace filtering, distinguishing this from siblings like quickshell_list_qt_types by explicitly saying 'QML types' rather than 'Qt types'.

  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 clear usage context: call with no namespace to see all namespaces, or pass a namespace to filter. It also explains when to use refresh=True and that it defaults to the latest version, though it does not explicitly name alternatives or exclusion conditions.

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

• quickshell_get_exampleA
  4.6/5.0
  Behavior4/5

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

  With no annotations provided, the description must carry the full behavioral burden. It clearly indicates a read operation ('read one file') and notes content is returned verbatim. It also hints at the dependency on list_examples for path validity. Missing details like error handling or output format are mitigated by the presence of an output schema, so the description covers the essential behavior well.

  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 zero redundancy. The purpose is front-loaded, followed by a clear directive on obtaining inputs and a recommendation. Every word earns its place.

  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 single-parameter read tool with an output schema defined, the description is nearly complete. It covers purpose, input sourcing, and usage preference. It omits explicit error scenarios, but these are likely standard and not required for a straightforward get operation. The combination of description, schema, and output schema suffices for correct invocation.

  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 compensate. It provides indirect but effective guidance: the 'path' should be a valid path obtained from quickshell_list_examples. This tells the agent how to find permissible values, which is highly useful. It doesn't detail path format or constraints, but the reference to the list tool is a strong semantic anchor.

  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 ('read') and resource ('official Quickshell examples repo') and clarifies it returns file content verbatim (QML configs, READMEs). It also distinguishes from siblings by mentioning quickshell_list_examples as the source of valid paths, so an agent can tell this is the getter for example files rather than guide pages or types.

  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 to first call quickshell_list_examples to obtain valid paths, and recommends preferring these maintained examples over writing config from memory. This gives clear when and how to use the tool, and implies when not to (avoid writing from memory). It fully covers usage context without requiring inference.

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

• quickshell_list_versionsA
  4.6/5.0
  Behavior4/5

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

  With no annotations, the description carries the transparency burden. It discloses the live source, newest-first ordering, the latest-version reporting, and the in-process cache behavior with the refresh=True bypass. This gives the agent the key behavioral traits beyond the raw schema.

  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?

  Three short sentences, each earning its place: purpose/ordering/latest, usage context, and parameter clarification. No filler or repetition.

  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 tool with one optional parameter and no output schema, the description is complete. It states what the return behavior is (list, newest first, latest identified) and how to control caching, which is all an agent needs to call it effectively.

  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 only parameter, 'refresh', has no schema description, but the tool description fully explains its meaning: 'Set refresh=True to bypass the in-process cache.' The default false behavior is implied by the schema and the cache explanation, so the parameter is completely covered.

  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 operation: list all Quickshell documentation versions from quickshell.org, ordered newest first, and identify the latest. This clear verb+resource phrase distinguishes it from siblings like quickshell_get_version and quickshell_get_page.

  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?

  It explicitly advises using this tool 'before fetching a page if you're unsure which version to use,' giving a concrete decision context. It does not name alternatives or exclusions, but the guidance is unambiguous enough for an agent to route correctly.

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

• quickshell_search_implementationsA
  4.6/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 of behavioral disclosure. It clearly states the results are practical references, not authoritative API docs, and directs verification to other tools, setting expectations about result reliability. It does not explicitly state read-only status, but that is implied by 'search'. It also explains the source-filtering behavior and the need to call per shell. Slight gap: no mention of rate limits or response format, but the core behavioral caveat is covered.

  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 the core purpose, then provides a long but highly useful list of example queries that clarifies the tool's scope, followed by concrete usage guidance and tool differentiation. Every sentence adds value: the example list helps agents craft appropriate queries, the source guidance prevents misuse, and the API-verification note prevents incorrect assumptions. It is dense yet structured, with no 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 the lack of an output schema, the description should clarify what the tool returns. It implies results are references to implementations, as it says to fetch file contents via quickshell_get_implementation. It also covers source filtering and how to compare shells. It does not explicitly state the return format (e.g., list of paths or metadata), but given the existence of a dedicated content-fetching sibling and the clear search role, the description is reasonably complete for an agent to use 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?

  The schema has 0% description coverage, so the description must compensate. It extensively documents the query parameter with many example values ('find a bar implementation', 'find a control center example', etc.), and explains the source parameter's allowed values ('caelestia' or 'noctalia') and its purpose. The limit parameter is not mentioned, but it is a standard integer with a default, so its semantics are easily inferred. Overall, the description adds strong meaning beyond the raw schema for the critical parameters.

  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 clear, specific purpose: searching real-world Quickshell shell implementations (Caelestia, Noctalia) for concrete code patterns, with a long list of example query intents. It explicitly distinguishes itself from API documentation tools ('These are practical references, NOT API docs') and from quickshell_get_implementation (which retrieves file contents), so an agent can easily tell it apart from siblings.

  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 gives explicit when-to-use instructions: restrict to one shell via the source parameter ('source=caelestia' or 'source=noctalia') and call per shell to compare approaches. It also names when to use other tools: verify API surface with quickshell_search/quickshell_get_type, and get file contents via quickshell_get_implementation. This is concrete, actionable guidance leaving nothing to inference.

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

• quickshell_statsA
  4.7/5.0
  Behavior4/5

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

  With no annotations, the description must disclose behavior. It explicitly lists what data is reported (call counts, fetch vs cache hits, uptime) and mentions the 30-minute cache, which clarifies the meaning of cache hits. It implies a read-only operation without stating it outright, but 'report' strongly signals no side effects. Slightly better would be an explicit note that it does not mutate state, but the description is transparent about its output.

  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 concise sentences. The first immediately enumerates the tool's output categories, and the second adds a practical usage context. There is no fluff or redundancy; information is front-loaded.

  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 tool is simple (no parameters, no output schema) yet the description fully conveys what an agent needs: what the tool reports, why it would be used, and the meaning of cache hits. The mention of the 30-minute cache helps interpret results. Nothing essential is missing for this diagnostic 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?

  The tool has zero parameters, so schema coverage is 100% and there is nothing to explain. The description adds no param details, but none are needed. A baseline 4 is appropriate given the absence of parameters.

  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 ('Report') and resource ('session usage stats for this MCP server') and enumerates the exact contents (per-tool call counts, network fetches vs cache hits, process uptime). It clearly distinguishes itself from sibling tools that retrieve content, making it obvious this is a diagnostic tool.

  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 second sentence explicitly says 'Use this to check how much the server has been consulted and how much it hit the live site vs its 30-minute cache,' providing a concrete use case. Since no sibling tool offers stats, no alternative routing is required, 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.

• quickshell_get_guide_pageA
  4.8/5.0
  Behavior4/5

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

  Since annotations are absent, the description carries the burden. It discloses the read-only nature implicitly via 'Fetch', specifies the output format (Markdown), and mentions the default version and the need to list first. It does not cover error cases or authentication, but for a simple get tool this is largely sufficient.

  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?

  Three short sentences with no redundancy. The core action is front-loaded, followed by practical guidance. Every sentence adds value.

  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 simple nature of the tool and the presence of an output schema, the description covers the essential inputs, the default behavior, and how to obtain valid slugs. 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 coverage is 0%, so the description must explain parameters. It gives concrete examples for slug and states the version defaults to 'latest', fully clarifying both 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?

  Clearly states it fetches one Usage Guide page as Markdown, with concrete slug examples. It distinguishes from sibling list_guide_pages by instructing to call it first if slug unknown, and from other guide tools (types, examples) by the resource type.

  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 says to call quickshell_list_guide_pages first if the exact slug is not known, providing a clear alternative. It also notes the version defaults to latest, which sets expectations. Does not explicitly list exclusions for other siblings, but the resource type is distinct enough.

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

• quickshell_list_examplesA
  4.8/5.0
  Behavior4/5

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

  No annotations are provided, so the description must carry the safety and behavior info. It conveys read-only listing and implies direct children via 'drill into a folder', but does not explicitly state output format or non-recursive behavior. Still, for a simple list tool, it is reasonably transparent.

  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, no filler. The core purpose is front-loaded and the practical usage guidance is concise. Every word 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?

  For a one-parameter list tool with no output schema, the description covers invocation, default behavior, and how to get file contents via a sibling. Nothing essential is missing 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 'path' parameter has no schema description coverage, but the description fully explains its meaning and default behavior ('Call with no path to list the root, then drill into a folder using its path'). This adds meaningful semantics 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?

  States a specific verb ('list') and resource ('files and folders in the official Quickshell examples repo'). It also differentiates from siblings like quickshell_get_example and implies the set of examples, making it clear what it does.

  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 says how to start ('with no path'), how to drill down ('using its path'), and how to pair with quickshell_get_example to read files. This gives clear usage context and differentiates from the read tool.

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

• quickshell_searchA
  4.9/5.0
  Behavior5/5

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

  With no annotations, the description carries full behavioral burden and delivers. It discloses that matching is case-insensitive substring, that namespace/type results are separated to avoid flooding, that include_type_pages triggers a slow first-call caching behavior, and that refresh bypasses the cache. It also states defaults (latest version) and return-value usability. This exceeds what is expected from a description alone.

  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: core purpose, imperative instruction, usage examples, parameter clarifications, and return behavior. It is front-loaded with the most critical takeaway ('ALWAYS call this...'). A few redundancies (default version noted inline and in schema) and the extensive example list add length, but nearly every sentence earns its place. Slightly overlong relative to strict conciseness, hence a 4 rather than 5.

  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 search tool with 5 parameters and no output schema, the description is complete. It explains what results look like ('matches with enough info to call quickshell_get_type or quickshell_get_guide_page directly'), covers caching/refresh, and distinguishes itself among a large sibling set. Nothing an agent needs to select and invoke this tool correctly 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 0%, so the description must explain every parameter. It does: query (substring match), include_content (full-text search of guide bodies), include_type_pages (deep-search type reference pages), refresh (bypass cache), and version (defaults to latest). Each parameter is tied to a concrete use case, adding meaning far beyond the bare boolean/string types 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 opens with a specific verb and resource: 'Search Quickshell type names, namespaces, and guide page slugs for a substring match (case-insensitive).' This clearly defines what the tool does and distinguishes it from sibling tools like quickshell_list_types and quickshell_get_type, which retrieve known items rather than searching. The explicit instruction to 'never guess property/type names, verify them here first' further anchors the tool's role.

  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 and actionable: 'ALWAYS call this before writing any QML that references a Quickshell type or property from memory' and includes concrete examples mapping user intents to search terms. It also explains when to set include_content=True for prose questions and include_type_pages=True for deep type-page searches, effectively covering both when and when-not-to-use scenarios. This is a textbook example of usage guidance.

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