We need to rethink APIs for agents rather than humans.

@insforge has been experimenting with a better agent API.

Key changes:

- Status states

- Detailed context on error (and success too)

- Clear next steps