Skip to main content
Glama

build-validate_brief

Validates a project's pre-construction brief files against the brief schema and reports whether each brief is ready for authoring; optionally checks one named area.

Instructions

Check the pre-construction brief(s) of this project, docs/briefs/.brief.yaml, against the brief schema (ADR-106) and say whether each is ready for authoring. Reads only the brief files, the project's pom.xml (and the app BOM poms it inherits from, read from the local Maven repository), the brief schema and, when present, target/classes/exeris-metadata; writes nothing, starts no process and uses no network, and is local only: the family needs the project root, so private product intent never reaches a hosted endpoint. The schema is the one inside the project's pinned eu.exeris:exeris-sdk-source-model jar in the local Maven repository (never downloaded), else the schema bundled with this bridge; skew.schemaSource says which. A project pinned below SDK 0.13.0 has no brief contract and gets a reason instead. A brief whose briefSchema is newer than the SDK of the schema used is returned valid:false, ready:false with the skew reported, and is not validated. valid means the schema passes. ready means valid and no blocking open question is still 'open'; an absent, empty or invalid brief is never ready. assumed lists the questions decided on credit with their owner. EARS criteria are checked by structure, never by text. Where the project has been built, each fulfilledBy reference is resolved against the emitted DomainMetadata (an entity by qualified class name; an action, rule or saga as #); unresolved names those that match nothing and does not change readiness, and without metadata every reference is unchecked. Optional area names one brief; without it every brief directly under docs/briefs is validated, up to 50.

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": "build-validate_brief"
  }
}

Input Schema

NameRequiredDescriptionDefault
areaNoOptional name of one bounded area (lowercase letters, digits and hyphens): validates docs/briefs/<area>.brief.yaml. A name, never a path.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.9.0

TDQS

A4.6/5.0
Behavior5/5

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

With no annotations, the description carries the full burden and does so: it declares the exact read set (briefs, pom.xml and inherited BOM poms, schema, optional target/classes/exeris-metadata), states 'writes nothing, starts no process and uses no network', and explains the local-only rationale. It also discloses semantics the agent could not otherwise know: valid vs ready, the SDK-skew short-circuit, assumed/unresolved/unchecked outcomes, and the 50-brief cap.

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?

Purpose is front-loaded in the first clause and every sentence carries operational information, but the body is one dense block with many parenthetical clauses and backtick identifiers that could be split into scannable lines. No sentence is pure filler, so it stays above a 3.

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 complex validation tool with no output schema, the description defines the return fields it matters for (valid, ready, assumed, unresolved, skew.schemaSource) and covers edge cases: absent/empty/invalid briefs are never ready, older SDK pins get a reason, and metadata absence degrades to 'unchecked'. Nothing an agent needs to invoke or interpret it is missing.

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 100%, so the baseline is 3, but the description adds meaning the schema does not: omitting `area` validates every brief directly under docs/briefs, and that enumeration is capped at 50. The 'a name, never a path' caveat is also reinforced in prose.

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 ('Check the pre-construction brief(s) ... against the brief schema (ADR-106)') plus the decision it returns ('whether each is ready for authoring'). The scope (docs/briefs/<area>.brief.yaml) and the ADR reference make it unmistakable against siblings like build-preview_generation or build-explain_artefacts.

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?

Implies the when clearly: validate briefs before authoring, with the optional `area` selecting one brief and the default validating all briefs under docs/briefs. It does not explicitly name a sibling as the alternative for a different task, so it stops 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.