add initial tool documentation and match the semantics in the build script and main