Relay / fictional worked example
Complementary tool pipeline
On this page
The tool pipeline supports the architecture and delivery loop. It is not a separate product tier or a reason to require a particular engine, IDE or orchestration platform.
What should be tools?
Good candidates are tasks with known inputs, predictable outputs and repeatable validation. For Relay’s intake slice:
| Operation | Deterministic mechanism | Why not re-prompt an agent each time? |
|---|---|---|
| Validate request fixture | tools/validate_fixture.py | Avoid guessing required keys and formats |
| Exercise contract behaviour | python -m unittest discover -s tests -v | Record repeatable evidence for replay/conflict cases |
| Check package syntax | python -m compileall -q relay tools tests | Catch parse errors mechanically |
| Inspect changed files | Git diff/status in the actual project | See what was changed, not just what was described |
| Generate future adapters | A versioned project tool with explicit schema inputs | Reduce inconsistent hand-built scaffolding |
The fixture validator is included as executable code. Git-based inspection is intended for the host repository into which the example may be placed; the ZIP itself does not contain a Git repository.
Tool contract
Even a small helper benefits from a clear interface:
- Input: one JSON fixture file for a request record.
- Output: success with a meaningful message, or non-zero exit and actionable error.
- Rule: validate shape and basic invariants against documented expectations; do not modify the fixture.
- Limit: the standard-library validator covers the example’s schema subset, not every feature of the JSON Schema specification.
Tool or AI?
Use deterministic tools for known mechanics and checks. Use AI where interpretation, design exploration, exception analysis or generating new capabilities is useful. Once a high-frequency operation becomes stable, consider moving it from repeated prompting into a tested tool.
A tool can be incorrect too. It needs its own tests, clear ownership and a versioned interface. Repeatability is not a guarantee of correctness.
See executable example.