Skip to main content
Glama
Repo Test Architect

Repo Test Architect

Audit Projects

audit_projects
Read-onlyIdempotent

Returns raw per-project audit artifacts for supported roots and lists unsupported or failed adapters, so downstream specialist tools can consume project-audits/v1.

Instructions

Return raw per-project audit artifacts for all detected supported roots, report unsupported roots, and list roots whose adapter failed in failedProjects. Use when a downstream specialist tool needs project-audits/v1; for a general first-pass review, prefer review_repository. The result can be large; specialist tools also accept repoRoot directly, so the artifact rarely needs to be passed back.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "repoRoot": "<repoRoot>"
    },
    "name": "audit_projects"
  }
}

Input Schema

NameRequiredDescriptionDefault
goTargetNo
repoRootYesRepository root path.
changedPathsNoOptional repository-relative source paths to limit target selection.
excludeProjectRootsNoOptional project roots or subtree patterns such as examples/** to exclude before auditing detected projects.

Output Schema

NameRequiredDescriptionDefault
rootYes
auditsYes
summaryYes
schemaVersionYes
failedProjectsNo
skippedProjectsYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changedv1.2.0
    • changedInput schema / properties / changedPaths / description
      Previous value: -"Optional repository-relative source paths to limit target selection inside detected projects."New value: +"Optional repository-relative source paths to limit target selection."
    • changedInput schema / properties / excludeProjectRoots / description
      Previous value: -"Optional exact project roots or subtree patterns such as examples/** to exclude before auditing detected projects."New value: +"Optional project roots or subtree patterns such as examples/** to exclude before auditing detected projects."
  2. Changed11 schema fields changedv1.1.0
    • removedOutput schema / $id
      Removed value: -"project-audits-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-audits-v1.schema.json in the published package."
    • removedOutput schema / properties / audits / items
      Removed value: -{
      -  "additionalProperties": false,
      -  "properties": {
      -    "adapterId": {
      -      "minLength": 1,
      -      "type": "string"
      -    },
      -    "audit": {
      -      "additionalProperties": true,
      -      "properties": {
      -        "coveredButRisky": {
      -          "type": "array"
      -        },
      -        "profile": {
      -          "type": "object"
      -        },
      -        "risks": {
      -          "type": "array"
      -        },
      -        "schemaVersion": {
      -          "const": "audit/v1"
      -        },
      -        "skipped": {
      -          "type": "array"
      -        },
      -        "untestedCandidates": {
      -          "type": "array"
      -        }
      -      },
      -      "required": [
      -        "schemaVersion",
      -        "profile",
      -        "untestedCandidates",
      -        "coveredButRisky",
      -        "skipped",
      -        "risks"
      -      ],
      -      "type": "object"
      -    },
      -    "projectId": {
      -      "minLength": 1,
      -      "type": "string"
      -    },
      -    "projectRoot": {
      -      "minLength": 1,
      -      "type": "string"
      -    }
      -  },
      -  "required": [
      -    "projectId",
      -    "projectRoot",
      -    "adapterId",
      -    "audit"
      -  ],
      -  "type": "object"
      -}
    • addedOutput schema / properties / failedProjects
      Added value: +{
      +  "type": "array"
      +}
    • removedOutput schema / properties / root / minLength
      Removed value: -1
    • removedOutput schema / properties / skippedProjects / 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 / properties / summary / additionalProperties
      Removed value: -false
    • removedOutput schema / properties / summary / properties
      Removed value: -{
      -  "auditedProjectCount": {
      -    "minimum": 0,
      -    "type": "integer"
      -  },
      -  "projectCount": {
      -    "minimum": 0,
      -    "type": "integer"
      -  },
      -  "skippedProjectCount": {
      -    "minimum": 0,
      -    "type": "integer"
      -  }
      -}
    • removedOutput schema / properties / summary / required
      Removed value: -[
      -  "projectCount",
      -  "auditedProjectCount",
      -  "skippedProjectCount"
      -]
    • removedOutput schema / title
      Removed value: -"Project Audits Artifact"
  3. Changed1 schema field changedv1.0.0
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
      +  "$id": "project-audits-v1.schema.json",
      +  "$schema": "https://json-schema.org/draft/2020-12/schema",
      +  "additionalProperties": false,
      +  "properties": {
      +    "audits": {
      +      "items": {
      +        "additionalProperties": false,
      +        "properties": {
      +          "adapterId": {
      +            "minLength": 1,
      +            "type": "string"
      +          },
      +          "audit": {
      +            "additionalProperties": true,
      +            "properties": {
      +              "coveredButRisky": {
      +                "type": "array"
      +              },
      +              "profile": {
      +                "type": "object"
      +              },
      +              "risks": {
      +                "type": "array"
      +              },
      +              "schemaVersion": {
      +                "const": "audit/v1"
      +              },
      +              "skipped": {
      +                "type": "array"
      +              },
      +              "untestedCandidates": {
      +                "type": "array"
      +              }
      +            },
      +            "required": [
      +              "schemaVersion",
      +              "profile",
      +              "untestedCandidates",
      +              "coveredButRisky",
      +              "skipped",
      +              "risks"
      +            ],
      +            "type": "object"
      +          },
      +          "projectId": {
      +            "minLength": 1,
      +            "type": "string"
      +          },
      +          "projectRoot": {
      +            "minLength": 1,
      +            "type": "string"
      +          }
      +        },
      +        "required": [
      +          "projectId",
      +          "projectRoot",
      +          "adapterId",
      +          "audit"
      +        ],
      +        "type": "object"
      +      },
      +      "type": "array"
      +    },
      +    "root": {
      +      "minLength": 1,
      +      "type": "string"
      +    },
      +    "schemaVersion": {
      +      "const": "project-audits/v1"
      +    },
      +    "skippedProjects": {
      +      "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"
      +    },
      +    "summary": {
      +      "additionalProperties": false,
      +      "properties": {
      +        "auditedProjectCount": {
      +          "minimum": 0,
      +          "type": "integer"
      +        },
      +        "projectCount": {
      +          "minimum": 0,
      +          "type": "integer"
      +        },
      +        "skippedProjectCount": {
      +          "minimum": 0,
      +          "type": "integer"
      +        }
      +      },
      +      "required": [
      +        "projectCount",
      +        "auditedProjectCount",
      +        "skippedProjectCount"
      +      ],
      +      "type": "object"
      +    }
      +  },
      +  "required": [
      +    "schemaVersion",
      +    "root",
      +    "summary",
      +    "audits",
      +    "skippedProjects"
      +  ],
      +  "title": "Project Audits Artifact",
      +  "type": "object"
      +}
  4. First observedv0.1.0

TDQS

A4.3/5.0
Behavior4/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 safety is covered; the description adds real value beyond them by warning that "the result can be large", naming the failedProjects field for adapter failures, and noting unsupported roots are reported rather than silently dropped. It stops short of describing pagination or the full artifact shape, which is what keeps it at 4 rather than 5.

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 sentences, each doing a distinct job (what it returns, when to select it, and how to avoid re-passing the artifact), with the primary output statement front-loaded. The first sentence is dense with a nested "for all detected supported roots" clause but remains parseable; no filler sentences.

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 annotations covering the read-only profile, the description need not document return values, and it appropriately limits itself to the notable failure and size behaviors. The one gap is that a nested goTarget parameter for Go build-constraint evaluation goes unmentioned, which an agent might otherwise miss given the specialized tooling context.

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

Parameters3/5

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

None of the four parameters (repoRoot, goTarget, changedPaths, excludeProjectRoots) are explained in the description; the schema at 75% coverage already documents them, including the nested goos/goarch/tags fields. Baseline 3 applies: the schema carries the parameter burden and the description merely implies the tool operates over detected project roots.

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 ("Return raw per-project audit artifacts for all detected supported roots") and enumerates what the result contains: supported-root artifacts, unsupported roots, and failedProjects. It is clearly distinguishable from siblings like review_repository and summarize_project_audits, which imply a summarized or first-pass view rather than raw artifacts.

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 states the selecting condition explicitly ("Use when a downstream specialist tool needs project-audits/v1"), names the alternative for the other case ("for a general first-pass review, prefer review_repository"), and notes the workaround that specialist tools accept repoRoot directly so the artifact rarely needs passing back. That is when-to-use, when-not-to-use, and the preferred substitute in three sentences.

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