Server Quality Checklist

Tool Scores

• sweep_statusA
  4/5.0
  Behavior3/5

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

  With no annotations, the description carries the transparency burden. It explains that the tool scans, checks CI status, and returns attention-requiring repos, implying read-only network polling. However, it does not disclose authentication needs, rate limits, error behavior, or explicitly confirm that it makes no mutations.

  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 concise, purposeful sentences. The main function is front-loaded, the manual-workflow replacement is stated, and the multi-root usage tip is separated clearly. No redundant or filler content.

  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 no output schema and no annotations, the description covers the core behavior, what counts as attention-worthy, the default root, and the multi-root option. It does not specify the exact return shape or network/auth caveats, but it gives an agent enough to decide when and how to 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?

  The input schema has 100% description coverage for all 5 parameters, so the baseline is 3. The description adds a useful default (~/Projects) and emphasizes roots-vs-root use, but much of that is already reflected in the schema descriptions.

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

  Purpose5/5

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

  The description states a precise verb and resource: it scans all git repositories under a root and returns which ones need attention (uncommitted changes, unpublished commits, failed/unfinished CI). This clearly differentiates it from the sibling tools like check_docs or write_doc through its batch git-status purpose.

  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 frames the tool as replacing a manual loop of git status + gh run list, which gives clear usage context. It also gives conditional guidance for the root vs roots parameters. It does not explicitly mention when not to use the tool, but the context is clear enough for selection.

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

• check_release_driftA
  4.2/5.0
  Behavior3/5

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

  With no annotations, the description carries the behavioral disclosure burden. It does disclose an important behavior: the tool does not guess source→release mappings and requires explicit pairs. However, it does not explicitly state that the tool is read-only, what happens for invalid pairs, or whether it depends on local git state, leaving some behavioral ambiguity.

  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. It front-loads the core computation, then provides the critical caveat and an example. Every sentence contributes useful information.

  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 no output schema and no annotations, the description covers the essential inputs, the core computation, and a key limitation. It could be more complete by describing the output format or edge cases, but the description is strong enough for correct selection and 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 100%, so the schema already documents all parameters. The description adds value beyond the schema by clarifying the pair semantics and providing a concrete example of the expected pair structure, which helps the agent construct valid input.

  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 operation: counting commits in a source repo since the last release tag and measuring the age of the oldest such commit. This clearly identifies the tool's function and distinguishes it from the sibling tools, which concern sweep status, docs, and doc writing.

  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: the tool works on explicit source→release pairs and explicitly warns that the relationship is not auto-detected from folder structure. It does not explicitly discuss alternatives or when not to use the tool, but the provided context is sufficient for an agent to invoke it correctly.

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

• write_docA
  4.2/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 transparency burden. It discloses the file write, the commit-hash capture, the downstream benefit for check_docs, and the limitation that documentation text is not generated. It does not detail overwrite behavior or failure conditions, but these are minor for this kind of persistence 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 three focused sentences: what it writes, why the commit-hash matters, and what it does not do. The operational facts are front-loaded and every sentence carries distinct information without 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?

  For a write tool with a fully documented schema, the description gives enough context for correct invocation: output path pattern, content expectation, commit-hash recording, and the relationship to check_docs. It does not specify return values or explicit prerequisites, but no output schema exists and the provided context is otherwise adequate.

  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 description coverage is 100%, so all four parameters are already documented and the baseline is 3. The description adds a little contextual meaning, such as repo being used in the output filename and content being pre-existing text, but it does not materially change the parameter semantics beyond 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 names a concrete action — writes documentation to ~/Projects/Architecture/<repo>.txt — and uniquely adds the commit-hash side effect. It also clearly states what the tool does not do (does not generate documentation text), which distinguishes it from siblings like check_docs and check_release_drift.

  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 makes the intended sequence clear: write with this tool first, then check_docs can use the recorded commit hash for accurate counting. It also explicitly says the tool only saves already-prepared text, so an agent knows not to invoke it for generation. It stops short of naming explicit alternatives or when-not-to-use conditions, but the context is sufficient.

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

• check_docsA
  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 burden. It discloses that the tool is non-destructive (never generates/rewrites docs), defines all four statuses, and reveals the two tracking methods (exact commit-count for write_doc-created docs vs coarse mtime fallback), which materially affects how an agent interprets results. Lacks a concrete return-format statement but is otherwise strong.

  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?

  Every clause earns its place—core behavior and statuses are front-loaded, then tracking methods, non-goal, and the points edge-case follow in rough priority order. Slightly dinged because it is one dense run-on paragraph where the important non-goal line and the points branching guidance are buried mid-text rather than structured.

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

  Completeness4/5

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

  No output schema exists, but the description compensates well by naming all four status categories, explaining both invocation modes (single root pair vs points), and covering the tracking-method distinction. The remaining gap is the absence of a concrete example or stated return format, which is minor for a status-check tool with fully self-documenting parameters.

  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 100%, so the baseline is 3. The description adds real value beyond the schema by explaining when to pass points instead of projectsRoot/docsRoot (scattered independent root/doc pairs, e.g., a repo moved out of ~/Projects) and by clarifying trackingMethod semantics tied to how documents are processed.

  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?

  Uses a specific verb ('Перевіряє актуальність') with a specifiic resource (архітектurнa documentatіon per git repo) and enumerates the four outcome catеgorіes (missing/stаle/current/no-commits). The non-goal statement 'НЕ генерує/переписує документацію сам' explicitly disambiguates іt from the sibling write_doc.

  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?

  States the intended usage context clearly: it tells the agent where to look so the assistant writes/updates purposefully instead of re-reading everything each session. The explicit non-goal ('НЕ генерує/переписує документацію сам') implicitly routes writing to write_doc, but no explicit when-not-to-use guidance is given for sweep_status or check_release_drift.

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