Dynamically discover functionality.

Descriptions form one half of RESTdesc.
The other half is discovery: exposing those descriptions for automated use.

Agents can learn about their options.

The HTTP specification mentions an OPTIONS method representing "a request for information about the communication options available on the request/response chain identified". Although currently unspecified, the response body provides provides an interesting opportunity to present descriptions.

Therefore, RESTdesc descriptions can be given in response to an OPTIONS request.

$ curl -i -X OPTIONS http://example.org/photos

An example response to the above request could be:

HTTP/1.1 200 OK
Allow: GET,HEAD,POST,OPTIONS
Content-Type: text/n3

@prefix : <http://example.org/image#>.
@prefix http: <http://www.w3.org/2011/http#>.
@prefix dbpedia: <http://dbpedia.org/resource/>.
@prefix dbpedia-owl: <http://dbpedia.org/ontology/>.
{
  ?image :smallThumbnail ?thumbnail.
}
=>
{
  _:request http:methodName "GET";
            http:requestURI ?thumbnail;
            http:resp [ http:body ?thumbnail ].
  ?image dbpedia-owl:thumbnail ?thumbnail.
  ?thumbnail a dbpedia:Image;
             dbpedia-owl:height 80.0.
}.

This description is the RESTdesc thumbnail example introduced previously.

Resources provide their own manual.

The core idea is that the descriptions of how to use and manipulate resources should be easily retrievable from the resources themselves.
The HTTP OPTIONS method is a great match for this.