Annotations trade flexibility for succinctness and readability. That's often a great reasonable tradeoff and a good place to start, but you might find yourself ripping them out later.

More abstractly, one of the characteristics of object-oriented design is the use of polymorphic objects. APIs which require you to define monomorphic annotated classes violate this and lose generality as a result. They are effectively class-oriented or method-oriented rather than true OO.

Why would you want an API that breaks the flexibility of code by forcing it to be glorified XML?

Why?

> You use annotations in place of java code, and while you can tweak java code you can't tweak what an annotation does or how it does it.

Why can't you tweak an annotation? Annotations are built into the language, the entire point of them is to allow code to detect their presence in the bytecode and thus react at runtime. e.g. wrap a method marked as @Transactional in a database transaction.

Edit: and they're hacky because they're magical--it's entirely not obvious what they're doing.