This looks really great for discoverability that works within the web platform already, without the need for inventing a new format [0].

However, I'm not sure if this goes far enough. There exist some formats for describing what APIs can do in natural language, though I'm not convinced that they're really that useful [1][2].

[0] http://apisjson.org [1] http://alps.io [2] http://restdesc.org