Server Quality Checklist

Tool Scores

• sdlc_generate_estimationA
  4.1/5.0
  Behavior4/5

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

  The description adds behavioral context beyond the annotations by outlining the output structure (traditionalEstimate, aiAssistedEstimate, savings, assumptions), listing the SDLC phases covered, and noting the dependency on upstream artifacts. It does not contradict the annotations (idempotentHint, readOnlyHint). The behavior is well-communicated, though it could mention error states or whether the tool stores anything.

  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 a summary line, detailed behavior, prerequisites, args, and returns. It is somewhat verbose with the full phase enumeration, but this is useful given the output complexity. Each section is clear and earns its place, making it appropriately sized for the tool.

  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 is fairly complete: it explains what the tool does, what it returns, and what prerequisites are required. Given the simple input and the output schema availability, the description sufficiently covers the tool's context. It could mention failure scenarios when prerequisites are missing, but overall it provides enough information for an agent to use the tool effectively.

  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 only parameter, project_id, is already well-documented in the schema with a description of its type and the prerequisite artifacts. The tool description's Args section only says 'The project UUID,' adding no new meaning. Since schema coverage is effectively high for this parameter, a baseline of 3 is appropriate; the description does not significantly enhance parameter understanding.

  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: 'Generate Traditional vs AI-Assisted cost estimates for a project.' It specifies the action (generate), the resource (cost estimates), and distinguishes itself from sibling tools that list projects or get artifacts. The detailed explanation of side-by-side estimates per SDLC phase further reinforces its unique role.

  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 a clear usage prerequisite: 'Requires all upstream artifacts to be generated first (PRD, architecture, data model, API contract, screens, implementation plan).' This effectively tells the agent when to use the tool (after those artifacts exist). It does not explicitly name alternative tools or state when not to use it, but the context is strong.

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

• sdlc_get_screensA
  4.1/5.0
  Behavior4/5

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

  Beyond the annotations (readOnlyHint, idempotentHint), the description adds useful behavioral details: returns a Markdown-formatted screen inventory grouped by epic, and warns that include_prototypes can be very large. This helps the agent anticipate output size and format.

  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 purpose, return details, and args sections. It is front-loaded with the main action, though slightly verbose with the full Args breakdown. Each 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 read-only listing tool with good annotations and schema, the description covers the main usage, return format, and potential size issue. It is sufficient for an agent to select and invoke correctly, though it does not discuss error cases or pagination.

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

  Parameters3/5

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

  The input schema already provides descriptions for both project_id (UUID) and include_prototypes (default false, can be large). The description's Args section largely repeats this information without adding new meaning, so it does not significantly enhance schema coverage.

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

  Purpose5/5

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

  The description clearly states 'List all UI screens defined for a project with their metadata', using a specific verb and resource. It distinguishes from sibling tools by focusing on screen listings rather than projects, summaries, or artifacts.

  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 the tool (to obtain screen inventory and metadata). It does not explicitly mention alternatives or exclusions, but the purpose is evident and sibling names give additional context.

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

• sdlc_get_tech_preferencesA
  4.1/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is clear. The description adds value by specifying the return format (Markdown-formatted summary) and the behavior when preferences haven't been set (a message). This goes beyond the annotations without contradicting them.

  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 a clear opening sentence, a list of returned fields, an Args section, and a Returns section. It is slightly redundant by mentioning the returned fields twice (once in prose and once in the Returns line), but it remains compact and readable.

  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, read-only tool with one parameter, the description is adequately complete. It explains the return value and the fallback message when preferences are unset. It does not discuss error cases like a non-existent project, but this is acceptable given the tool's simplicity and strong annotations.

  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?

  With schema description coverage at 0%, the description carries the burden of explaining the parameter. It states 'project_id (str): UUID of the project', which provides basic meaning but omits guidance on how to obtain the ID (which was present in the schema's own description). The description adds minimal value beyond naming the parameter and its type.

  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 fetches technology stack preferences for a project, listing specific fields (frontend, backend, database, etc.) that distinguish it from sibling tools like sdlc_get_project_summary or sdlc_get_screens. The verb 'Fetch' and resource 'technology stack preferences' are specific and 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 implies usage when tech stack preferences are needed for a project, and the schema's parameter description references sdlc_list_projects as a prerequisite, providing clear context. However, it does not explicitly discuss alternatives or when not to use this tool, 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.

• sdlc_get_artifactA
  4.2/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds valuable behavior: it returns content as Markdown or JSON depending on artifact type, and errors if the artifact hasn't been generated. This goes beyond the structured 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 front-loaded with purpose, then provides structured Args and Returns sections. It is somewhat redundant with the schema's parameter descriptions, but each sentence serves a purpose and the overall length is justified.

  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, with two parameters and an output schema. The description covers all key aspects: purpose, artifact type selection, return format, and the error case for missing artifacts. It also references how to obtain project_id, making it self-contained.

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

  Parameters3/5

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

  The input schema already provides detailed descriptions for project_id and artifact_type, including valid enum values. The description repeats this information without adding new semantics. Since schema coverage is high, a 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 opens with 'Fetch the full content of a specific artifact from a project,' which is a specific verb+resource. It then enumerates distinct artifact types (PRD, Architecture Overview, etc.), clearly distinguishing this tool from sibling retrieval tools like sdlc_get_project_summary or sdlc_get_screens.

  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 clarifies that it retrieves artifacts and mentions project_id should come from sdlc_list_projects, providing a clear context. It lacks explicit exclusions or comparisons to alternatives, but the artifact-type list makes the tool's scope unambiguous.

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

• sdlc_list_projectsA
  4.4/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is well-established. The description adds behavioral context by stating it returns a Markdown-formatted list and includes which artifacts have been generated and how many UI screens exist, giving more detail than the annotations alone. 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.

  Conciseness5/5

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

  The description is well-structured with a concise summary, a clear usage sentence, and separate Args and Returns sections. It uses just enough detail to be informative without redundancy, and every sentence serves a purpose.

  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 read-only listing tool with one optional filter, the description covers the purpose, usage, parameter semantics, and return format. It does not mention pagination or potential large result sizes, but given the annotations and the simplicity of the operation, this is adequate. The presence of an output schema (though not shown) further reduces the need to detail return fields.

  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?

  Although schema description coverage is reported as 0%, the description compensates by explaining the single 'params' argument and its nested 'status_filter' property, including the valid status values ('DRAFT', 'ACTIVE', 'COMPLETED', 'ARCHIVED'). This adds meaning beyond the bare schema structure, even though the schema does contain a description for status_filter internally.

  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 all SDLC Assist projects with their status and artifact completion, and specifies it returns a summary of every project including generated artifacts and UI screen counts. This is a specific verb+resource combination that distinguishes it from sibling tools like sdlc_get_project_summary or sdlc_get_artifact, which focus on individual project details.

  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 'Use this to discover project IDs for other tools,' which provides a clear use case and context. While it doesn't explicitly mention alternatives or exclusions, this guidance is sufficient to understand when to invoke this tool versus sibling tools that target specific projects.

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

• sdlc_get_project_summaryA
  4.5/5.0
  Behavior4/5

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

  Annotations declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds context beyond annotations by specifying the markdown output format, the exact summary fields, and the exclusion of artifact content. No contradictions.

  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: purpose, return contents, exclusion, args, and returns. Every sentence provides value with no 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?

  For a single-parameter, read-only tool with an output schema, the description fully covers purpose, return format, and scope. It clearly states what is not returned and points to the alternative tool, 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.

  Parameters3/5

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

  Only one parameter, project_id, is described as a UUID. The description adds little beyond the schema's own parameter description, which already states where to get it (sdlc_list_projects). Since schema coverage is marked 0%, the description provides the essential meaning but no additional 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 tool retrieves a detailed summary of a single SDLC project, lists the specific fields returned (name, status, tech stack, artifacts, UI screens), and explicitly excludes artifact content, distinguishing it from sdlc_get_artifact.

  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 direction: use sdlc_get_artifact for artifact content (when-not-to-use), and the schema notes to obtain project_id from sdlc_list_projects, which implies this tool is for summaries after listing projects.

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