If you think something is unreliable, that sounds like a bug report. Granted, “append” is probably not what you want for xtb when it comes to optimizations. OTOH, for “build this nanotube and add it to the current system” it makes more sense.

No. It reads the supplied format directly. There’s no “converting to CJSON.” (unless you’re supplying something that requires Open Babel conversion which would just slow things down)

1. append indicates that the contents of the file (i.e., atoms and/or bonds) should be added to the current system.
   readProperties was something you requested. It indicates to read properties, spectra, orbitals, etc. and add them to the current system - ignoring atoms and bonds.
2. See above
3. I’m not sure how these would apply to any other plugin type.
4. I don’t know why they would apply to the metadata. I can think of many, many scenarios in which you’d want to notify Avogadro only after running. I’m not really sure how it benefits Avogadro or the plugin if you want to declare append or readProperties ahead of time. Avogadro still needs to read the output JSON.
5. It makes sense to me, but I’m the one who wrote the code (and a bunch of plugins that use append)

I guess I want to know what you found confusing and/or unreliable. They work for my use cases certainly.