Skip to main content
Glama
Repo Test Architect

Repo Test Architect

Rank Project Test Candidates

rank_project_candidates
Read-onlyIdempotent

Ranks project candidates from an existing project-audits/v1 artifact or repo root, preserving project identity and returning the complete ranked result when the bounded review_repository output is insufficient.

Instructions

Rank candidates from an existing project-audits/v1 artifact while preserving project identity. review_repository returns a bounded version of this result; pass repoRoot here for the complete artifact.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "rank_project_candidates"
  }
}

Input Schema

NameRequiredDescriptionDefault
goTargetNo
repoRootNoRepository root to audit instead of passing projectAudits.
changedPathsNoOptional repository-relative source paths to limit target selection.
projectAuditsNoA project-audits/v1 artifact; or pass repoRoot instead.
excludeProjectRootsNoOptional project roots or subtree patterns such as examples/** to exclude before auditing.

Output Schema

NameRequiredDescriptionDefault
rootYes
summaryYes
candidatesYes
schemaVersionYes
failedProjectsNo
unsupportedProjectsYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed6 schema fields changedv1.2.0
    • addedInput schema / properties / changedPaths
      Added value: +{
      +  "description": "Optional repository-relative source paths to limit target selection.",
      +  "items": {
      +    "minLength": 1,
      +    "type": "string"
      +  },
      +  "type": "array"
      +}
    • addedInput schema / properties / excludeProjectRoots
      Added value: +{
      +  "description": "Optional project roots or subtree patterns such as examples/** to exclude before auditing.",
      +  "items": {
      +    "minLength": 1,
      +    "type": "string"
      +  },
      +  "type": "array"
      +}
    • addedInput schema / properties / goTarget
      Added value: +{
      +  "additionalProperties": false,
      +  "properties": {
      +    "goarch": {
      +      "description": "Explicit GOARCH for bounded Go build-constraint evaluation.",
      +      "minLength": 1,
      +      "type": "string"
      +    },
      +    "goos": {
      +      "description": "Explicit GOOS for bounded Go build-constraint evaluation.",
      +      "minLength": 1,
      +      "type": "string"
      +    },
      +    "tags": {
      +      "description": "Optional custom Go build tags passed to the target-aware verification command.",
      +      "items": {
      +        "minLength": 1,
      +        "type": "string"
      +      },
      +      "type": "array"
      +    }
      +  },
      +  "required": [
      +    "goos",
      +    "goarch"
      +  ],
      +  "type": "object"
      +}
    • changedInput schema / properties / projectAudits / description
      Previous value: -"A project-audits/v1 artifact."New value: +"A project-audits/v1 artifact; or pass repoRoot instead."
    • addedInput schema / properties / repoRoot
      Added value: +{
      +  "description": "Repository root to audit instead of passing projectAudits.",
      +  "type": "string"
      +}
    • changedInput schema / required
      Previous value: -[
      -  "projectAudits"
      -]New value: +[]
  2. Changed11 schema fields changedv1.1.0
    • removedOutput schema / $id
      Removed value: -"project-candidate-ranking-v1.schema.json"
    • removedOutput schema / $schema
      Removed value: -"https://json-schema.org/draft/2020-12/schema"
    • addedOutput schema / description
      Added value: +"Top-level shape of this artifact. The complete contract is schemas/project-candidate-ranking-v1.schema.json in the published package."
    • removedOutput schema / properties / candidates / items
      Removed value: -{
      -  "additionalProperties": false,
      -  "properties": {
      -    "adapterId": {
      -      "minLength": 1,
      -      "type": "string"
      -    },
      -    "category": {
      -      "enum": [
      -        "untested",
      -        "covered-but-risky"
      -      ]
      -    },
      -    "existingTestEvidence": {
      -      "items": {
      -        "additionalProperties": false,
      -        "properties": {
      -          "kind": {
      -            "type": "string"
      -          },
      -          "strength": {
      -            "enum": [
      -              "naming",
      -              "direct",
      -              "referenced",
      -              "indirect"
      -            ]
      -          },
      -          "testPath": {
      -            "type": "string"
      -          },
      -          "usage": {
      -            "enum": [
      -              "called",
      -              "asserted"
      -            ]
      -          },
      -          "viaUsage": {
      -            "enum": [
      -              "called",
      -              "asserted"
      -            ]
      -          }
      -        },
      -        "required": [
      -          "testPath",
      -          "kind",
      -          "strength"
      -        ],
      -        "type": "object"
      -      },
      -      "type": "array"
      -    },
      -    "existingTestPaths": {
      -      "items": {
      -        "type": "string"
      -      },
      -      "type": "array"
      -    },
      -    "kind": {
      -      "minLength": 1,
      -      "type": "string"
      -    },
      -    "maintenanceCost": {
      -      "maximum": 10,
      -      "minimum": 0,
      -      "type": "integer"
      -    },
      -    "path": {
      -      "minLength": 1,
      -      "type": "string"
      -    },
      -    "priority": {
      -      "type": "integer"
      -    },
      -    "projectId": {
      -      "minLength": 1,
      -      "type": "string"
      -    },
      -    "projectRoot": {
      -      "minLength": 1,
      -      "type": "string"
      -    },
      -    "projectTargetId": {
      -      "minLength": 1,
      -      "type": "string"
      -    },
      -    "rationale": {
      -      "items": {
      -        "type": "string"
      -      },
      -      "type": "array"
      -    },
      -    "riskReductionScore": {
      -      "maximum": 10,
      -      "minimum": 0,
      -      "type": "integer"
      -    },
      -    "signals": {
      -      "items": {
      -        "type": "string"
      -      },
      -      "type": "array"
      -    },
      -    "target": {
      -      "minLength": 1,
      -      "type": "string"
      -    },
      -    "targetId": {
      -      "minLength": 1,
      -      "type": "string"
      -    },
      -    "testLevel": {
      -      "enum": [
      -        "unit",
      -        "integration",
      -        "component",
      -        "ui",
      -        "none"
      -      ]
      -    }
      -  },
      -  "required": [
      -    "projectId",
      -    "projectRoot",
      -    "adapterId",
      -    "projectTargetId",
      -    "targetId",
      -    "target",
      -    "path",
      -    "category",
      -    "kind",
      -    "testLevel",
      -    "priority",
      -    "riskReductionScore",
      -    "maintenanceCost",
      -    "signals",
      -    "rationale",
      -    "existingTestPaths"
      -  ],
      -  "type": "object"
      -}
    • addedOutput schema / properties / failedProjects
      Added value: +{
      +  "type": "array"
      +}
    • removedOutput schema / properties / root / minLength
      Removed value: -1
    • removedOutput schema / properties / summary / additionalProperties
      Removed value: -false
    • removedOutput schema / properties / summary / properties
      Removed value: -{
      -  "auditCoverage": {
      -    "enum": [
      -      "complete",
      -      "partial",
      -      "none"
      -    ]
      -  },
      -  "auditedProjectCount": {
      -    "minimum": 0,
      -    "type": "integer"
      -  },
      -  "candidateCount": {
      -    "minimum": 0,
      -    "type": "integer"
      -  },
      -  "projectCount": {
      -    "minimum": 0,
      -    "type": "integer"
      -  },
      -  "unsupportedProjectCount": {
      -    "minimum": 0,
      -    "type": "integer"
      -  },
      -  "unsupportedReasons": {
      -    "items": {
      -      "minLength": 1,
      -      "type": "string"
      -    },
      -    "type": "array",
      -    "uniqueItems": true
      -  }
      -}
    • removedOutput schema / properties / summary / required
      Removed value: -[
      -  "projectCount",
      -  "auditedProjectCount",
      -  "unsupportedProjectCount",
      -  "auditCoverage",
      -  "unsupportedReasons",
      -  "candidateCount"
      -]
    • removedOutput schema / properties / unsupportedProjects / items
      Removed value: -{
      -  "additionalProperties": false,
      -  "properties": {
      -    "adapterMatches": {
      -      "items": {
      -        "additionalProperties": false,
      -        "properties": {
      -          "adapterId": {
      -            "minLength": 1,
      -            "type": "string"
      -          },
      -          "matchedEcosystems": {
      -            "items": {
      -              "minLength": 1,
      -              "type": "string"
      -            },
      -            "type": "array"
      -          },
      -          "matchedLanguages": {
      -            "items": {
      -              "minLength": 1,
      -              "type": "string"
      -            },
      -            "type": "array"
      -          },
      -          "maturity": {
      -            "enum": [
      -              "supported",
      -              "experimental",
      -              "planned"
      -            ]
      -          }
      -        },
      -        "required": [
      -          "adapterId",
      -          "maturity",
      -          "matchedEcosystems",
      -          "matchedLanguages"
      -        ],
      -        "type": "object"
      -      },
      -      "type": "array"
      -    },
      -    "ecosystems": {
      -      "items": {
      -        "minLength": 1,
      -        "type": "string"
      -      },
      -      "type": "array"
      -    },
      -    "languages": {
      -      "items": {
      -        "minLength": 1,
      -        "type": "string"
      -      },
      -      "type": "array"
      -    },
      -    "projectId": {
      -      "minLength": 1,
      -      "type": "string"
      -    },
      -    "projectRoot": {
      -      "minLength": 1,
      -      "type": "string"
      -    },
      -    "reason": {
      -      "minLength": 1,
      -      "type": "string"
      -    },
      -    "supportStatusReason": {
      -      "minLength": 1,
      -      "type": "string"
      -    }
      -  },
      -  "required": [
      -    "projectId",
      -    "projectRoot",
      -    "reason",
      -    "ecosystems",
      -    "languages",
      -    "adapterMatches",
      -    "supportStatusReason"
      -  ],
      -  "type": "object"
      -}
    • removedOutput schema / title
      Removed value: -"Project Candidate Ranking Artifact"
  3. Changed1 schema field changedv1.0.0
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
      +  "$id": "project-candidate-ranking-v1.schema.json",
      +  "$schema": "https://json-schema.org/draft/2020-12/schema",
      +  "additionalProperties": false,
      +  "properties": {
      +    "candidates": {
      +      "items": {
      +        "additionalProperties": false,
      +        "properties": {
      +          "adapterId": {
      +            "minLength": 1,
      +            "type": "string"
      +          },
      +          "category": {
      +            "enum": [
      +              "untested",
      +              "covered-but-risky"
      +            ]
      +          },
      +          "existingTestEvidence": {
      +            "items": {
      +              "additionalProperties": false,
      +              "properties": {
      +                "kind": {
      +                  "type": "string"
      +                },
      +                "strength": {
      +                  "enum": [
      +                    "naming",
      +                    "direct",
      +                    "referenced",
      +                    "indirect"
      +                  ]
      +                },
      +                "testPath": {
      +                  "type": "string"
      +                },
      +                "usage": {
      +                  "enum": [
      +                    "called",
      +                    "asserted"
      +                  ]
      +                },
      +                "viaUsage": {
      +                  "enum": [
      +                    "called",
      +                    "asserted"
      +                  ]
      +                }
      +              },
      +              "required": [
      +                "testPath",
      +                "kind",
      +                "strength"
      +              ],
      +              "type": "object"
      +            },
      +            "type": "array"
      +          },
      +          "existingTestPaths": {
      +            "items": {
      +              "type": "string"
      +            },
      +            "type": "array"
      +          },
      +          "kind": {
      +            "minLength": 1,
      +            "type": "string"
      +          },
      +          "maintenanceCost": {
      +            "maximum": 10,
      +            "minimum": 0,
      +            "type": "integer"
      +          },
      +          "path": {
      +            "minLength": 1,
      +            "type": "string"
      +          },
      +          "priority": {
      +            "type": "integer"
      +          },
      +          "projectId": {
      +            "minLength": 1,
      +            "type": "string"
      +          },
      +          "projectRoot": {
      +            "minLength": 1,
      +            "type": "string"
      +          },
      +          "projectTargetId": {
      +            "minLength": 1,
      +            "type": "string"
      +          },
      +          "rationale": {
      +            "items": {
      +              "type": "string"
      +            },
      +            "type": "array"
      +          },
      +          "riskReductionScore": {
      +            "maximum": 10,
      +            "minimum": 0,
      +            "type": "integer"
      +          },
      +          "signals": {
      +            "items": {
      +              "type": "string"
      +            },
      +            "type": "array"
      +          },
      +          "target": {
      +            "minLength": 1,
      +            "type": "string"
      +          },
      +          "targetId": {
      +            "minLength": 1,
      +            "type": "string"
      +          },
      +          "testLevel": {
      +            "enum": [
      +              "unit",
      +              "integration",
      +              "component",
      +              "ui",
      +              "none"
      +            ]
      +          }
      +        },
      +        "required": [
      +          "projectId",
      +          "projectRoot",
      +          "adapterId",
      +          "projectTargetId",
      +          "targetId",
      +          "target",
      +          "path",
      +          "category",
      +          "kind",
      +          "testLevel",
      +          "priority",
      +          "riskReductionScore",
      +          "maintenanceCost",
      +          "signals",
      +          "rationale",
      +          "existingTestPaths"
      +        ],
      +        "type": "object"
      +      },
      +      "type": "array"
      +    },
      +    "root": {
      +      "minLength": 1,
      +      "type": "string"
      +    },
      +    "schemaVersion": {
      +      "const": "project-candidate-ranking/v1"
      +    },
      +    "summary": {
      +      "additionalProperties": false,
      +      "properties": {
      +        "auditCoverage": {
      +          "enum": [
      +            "complete",
      +            "partial",
      +            "none"
      +          ]
      +        },
      +        "auditedProjectCount": {
      +          "minimum": 0,
      +          "type": "integer"
      +        },
      +        "candidateCount": {
      +          "minimum": 0,
      +          "type": "integer"
      +        },
      +        "projectCount": {
      +          "minimum": 0,
      +          "type": "integer"
      +        },
      +        "unsupportedProjectCount": {
      +          "minimum": 0,
      +          "type": "integer"
      +        },
      +        "unsupportedReasons": {
      +          "items": {
      +            "minLength": 1,
      +            "type": "string"
      +          },
      +          "type": "array",
      +          "uniqueItems": true
      +        }
      +      },
      +      "required": [
      +        "projectCount",
      +        "auditedProjectCount",
      +        "unsupportedProjectCount",
      +        "auditCoverage",
      +        "unsupportedReasons",
      +        "candidateCount"
      +      ],
      +      "type": "object"
      +    },
      +    "unsupportedProjects": {
      +      "items": {
      +        "additionalProperties": false,
      +        "properties": {
      +          "adapterMatches": {
      +            "items": {
      +              "additionalProperties": false,
      +              "properties": {
      +                "adapterId": {
      +                  "minLength": 1,
      +                  "type": "string"
      +                },
      +                "matchedEcosystems": {
      +                  "items": {
      +                    "minLength": 1,
      +                    "type": "string"
      +                  },
      +                  "type": "array"
      +                },
      +                "matchedLanguages": {
      +                  "items": {
      +                    "minLength": 1,
      +                    "type": "string"
      +                  },
      +                  "type": "array"
      +                },
      +                "maturity": {
      +                  "enum": [
      +                    "supported",
      +                    "experimental",
      +                    "planned"
      +                  ]
      +                }
      +              },
      +              "required": [
      +                "adapterId",
      +                "maturity",
      +                "matchedEcosystems",
      +                "matchedLanguages"
      +              ],
      +              "type": "object"
      +            },
      +            "type": "array"
      +          },
      +          "ecosystems": {
      +            "items": {
      +              "minLength": 1,
      +              "type": "string"
      +            },
      +            "type": "array"
      +          },
      +          "languages": {
      +            "items": {
      +              "minLength": 1,
      +              "type": "string"
      +            },
      +            "type": "array"
      +          },
      +          "projectId": {
      +            "minLength": 1,
      +            "type": "string"
      +          },
      +          "projectRoot": {
      +            "minLength": 1,
      +            "type": "string"
      +          },
      +          "reason": {
      +            "minLength": 1,
      +            "type": "string"
      +          },
      +          "supportStatusReason": {
      +            "minLength": 1,
      +            "type": "string"
      +          }
      +        },
      +        "required": [
      +          "projectId",
      +          "projectRoot",
      +          "reason",
      +          "ecosystems",
      +          "languages",
      +          "adapterMatches",
      +          "supportStatusReason"
      +        ],
      +        "type": "object"
      +      },
      +      "type": "array"
      +    }
      +  },
      +  "required": [
      +    "schemaVersion",
      +    "root",
      +    "summary",
      +    "unsupportedProjects",
      +    "candidates"
      +  ],
      +  "title": "Project Candidate Ranking Artifact",
      +  "type": "object"
      +}
  4. First observedv0.1.0

TDQS

A3.8/5.0
Behavior3/5

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds one genuinely useful behavioral fact—that results can be bounded versus complete depending on input path—but says nothing about what a "candidate" is, ranking criteria, or cost/latency.

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?

Two tight sentences with the primary action front-loaded and no redundancy. The phrase "while preserving project identity" is somewhat vague and does little work, a minor deduction.

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?

This is a five-parameter tool, but with no required parameters and 80% schema coverage, plus an output schema that carries return-value semantics. The description covers the one thing not derivable from structured fields: the bounded-vs-complete relationship with review_repository.

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 80%, so the schema largely documents parameters already. The description adds one piece of meaning beyond the schema: that repoRoot yields the complete artifact while projectAudits supplies an existing artifact, reinforcing the mutual-exclusion framing that the schema only states tersely.

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 gives a specific verb and resource ("Rank candidates from an existing project-audits/v1 artifact") and identifies the artifact format it consumes, which is the key distinguishing trait. It also contrasts itself with review_repository ("returns a bounded version of this result"), though it does not distinguish itself from the similarly named rank_test_candidates sibling.

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 states a clear usage condition and alternative: if you want the complete artifact result, pass repoRoot here rather than relying on review_repository's bounded output. It stops short of exclusions or guidance on when to prefer rank_test_candidates over this tool.

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