Skip to main content
Glama

build-explain_artefacts

Lists generated Exeris artefacts with their source generators and emission timing, so you can check what codegen already produced before hand-writing SQL, DTOs, or controllers.

Instructions

List the files Exeris codegen has generated into this project, each with the generator that produced it and when that generator emits — handlers, services, repositories, domain errors, event publishers, graph projections, sagas, Flyway migrations, OpenAPI specs, and the project-wide bootstrap. Ask this BEFORE hand-writing SQL, a DTO or a controller for an Exeris entity: the build usually already emits it. Optional entity narrows to one entity's artefacts. Reports what the pipeline actually emitted, read from its own output manifest and explained by the generator catalogue exeris-tooling publishes with its codegen jar. Each artefact carries candidates: every catalogue row that can have written the path, first match first. One candidate means generator names it; several mean the path shape is shared and generator is null rather than a guess; none means the path is unrecognised. A project that has not run codegen returns present:false.

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-explain_artefacts"
  }
}

Input Schema

NameRequiredDescriptionDefault
entityNoOptional Java simple name (e.g. 'Station'). Narrows to the artefacts whose filename carries that name; project-wide artefacts are always included.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.9.0

TDQS

A4.2/5.0
Behavior4/5

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

With no annotations present, the description carries the full burden and does substantial work: it discloses the data source (the pipeline's own output manifest plus the generator catalogue published with the codegen jar), the ambiguity policy (one candidate names the generator; several leave `generator` null rather than guessing; none means unrecognised path), and the empty-state behaviour (`present:false` when codegen has not run). It omits operational traits an agent might want, such as output volume on large projects or whether results are ordered/paginated, which keeps it from a 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?

The structure is well front-loaded: purpose first, then the imperative usage rule, then the return semantics. Most sentences earn their place, though the `candidates` explanation is dense and restates the one/many/none rule in a way that could be tightened into a single clause.

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?

There is no output schema, so the description must explain the return shape, and it does: each artefact carries `generator` and `candidates`, the null-generator case, and the `present` flag for projects without codegen. Combined with the single optional parameter and the manifest-based read model, an agent has everything needed to call it and interpret the response.

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 the `entity` parameter is already documented as a Java simple name that narrows by filename and keeps project-wide artefacts. The description's line "Optional `entity` narrows to one entity's artefacts" restates rather than extends the schema, adding no new format or matching semantics. Baseline 3 is appropriate where the schema does the heavy lifting.

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?

"List the files Exeris codegen has generated into this project, each with the generator that produced it and when that generator emits" is a precise verb+resource+payload statement, and the enumerated artefact types (handlers, services, repositories, sagas, Flyway migrations, OpenAPI specs, bootstrap) make the scope concrete. It is clearly distinguishable from sibling build-* tools, which deal with diagnostics, previews, metadata and domains rather than emitted 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?

It gives an explicit trigger with a strong temporal cue: "Ask this BEFORE hand-writing SQL, a DTO or a controller for an Exeris entity: the build usually already emits it." That is actionable when-to-use guidance tied to a real agent mistake (duplicating generated code). It stops short of naming which sibling to call instead when the question is about generation previews or domain metadata, so it is not a full when/when-not/alternatives statement.

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