diff --git a/lib/puppet/face/catalog.rb b/lib/puppet/face/catalog.rb
index 59356d43f..da03af0fd 100644
--- a/lib/puppet/face/catalog.rb
+++ b/lib/puppet/face/catalog.rb
@@ -1,49 +1,55 @@
 require 'puppet/face/indirector'
 
 Puppet::Face::Indirector.define(:catalog, '0.0.1') do
   summary "Compile, save, view, and convert catalogs."
 
-  @longdocs = "This face primarily interacts with the compiling subsystem.
-  By default, it compiles a catalog using the default manifest and the
-  hostname from 'certname', but you can choose to retrieve a catalog from
-  the server by specifying '--from rest'.  You can also choose to print any
-  catalog in 'dot' format (for easy graph viewing with OmniGraffle or Graphviz)
-  with '--format dot'."
+  description <<-EOT
+This face primarily interacts with the compiling subsystem.
+By default, it compiles a catalog using the default manifest and the
+hostname from 'certname', but you can choose to retrieve a catalog from
+the server by specifying '--from rest'.  You can also choose to print any
+catalog in 'dot' format (for easy graph viewing with OmniGraffle or Graphviz)
+with '--format dot'.
+  EOT
 
   action(:apply) do
+    summary "apply a Puppet::Resource::Catalog object"
+
     when_invoked do |catalog, options|
       report = Puppet::Transaction::Report.new("apply")
       report.configuration_version = catalog.version
 
       Puppet::Util::Log.newdestination(report)
 
       begin
         benchmark(:notice, "Finished catalog run") do
           catalog.apply(:report => report)
         end
       rescue => detail
         puts detail.backtrace if Puppet[:trace]
         Puppet.err "Failed to apply catalog: #{detail}"
       end
 
       report.finalize_report
       report
     end
   end
 
   action(:download) do
+    summary "download the catalog given the certname and facts"
+
     when_invoked do |certname, facts, options|
       Puppet::Resource::Catalog.indirection.terminus_class = :rest
       facts_to_upload = {:facts_format => :b64_zlib_yaml, :facts => CGI.escape(facts.render(:b64_zlib_yaml))}
       catalog = nil
       retrieval_duration = thinmark do
         catalog = Puppet::Face[:catalog, '0.0.1'].find(certname, facts_to_upload)
       end
       catalog = catalog.to_ral
       catalog.finalize
       catalog.retrieval_duration = retrieval_duration
       catalog.write_class_file
       catalog
     end
   end
 end
diff --git a/lib/puppet/face/facts.rb b/lib/puppet/face/facts.rb
index a5a279ddf..abcb3369a 100644
--- a/lib/puppet/face/facts.rb
+++ b/lib/puppet/face/facts.rb
@@ -1,20 +1,21 @@
 require 'puppet/face/indirector'
 require 'puppet/node/facts'
 
 Puppet::Face::Indirector.define(:facts, '0.0.1') do
   summary "Retrieve, store, and view facts."
 
-  # Upload our facts to the server
   action(:upload) do
+    summary "upload our facts to the server."
+
     render_as :yaml
 
     when_invoked do |options|
       Puppet::Node::Facts.indirection.terminus_class = :facter
       facts = Puppet::Node::Facts.indirection.find(Puppet[:certname])
       Puppet::Node::Facts.indirection.terminus_class = :rest
       Puppet::Node::Facts.indirection.save(facts)
       Puppet.notice "Uploaded facts for '#{Puppet[:certname]}'"
       nil
     end
   end
 end
diff --git a/lib/puppet/face/key.rb b/lib/puppet/face/key.rb
index c85345167..0988ebea2 100644
--- a/lib/puppet/face/key.rb
+++ b/lib/puppet/face/key.rb
@@ -1,8 +1,11 @@
 require 'puppet/face/indirector'
 
 Puppet::Face::Indirector.define(:key, '0.0.1') do
   summary "Create, save, and remove certificate keys."
 
-  @longdocs = "Keys are created for you automatically when certificate
-  requests are generated with 'puppet certificate generate'."
+  description <<-EOT
+Keys are created for you automatically when certificate
+requests are generated with 'puppet certificate generate'.
+  EOT
+
 end
diff --git a/lib/puppet/face/node.rb b/lib/puppet/face/node.rb
index 7032debc3..7cb6ae469 100644
--- a/lib/puppet/face/node.rb
+++ b/lib/puppet/face/node.rb
@@ -1,7 +1,8 @@
 require 'puppet/face/indirector'
 Puppet::Face::Indirector.define(:node, '0.0.1') do
   summary "View and manage nodes"
 
-  @longdocs = "It defaults to using whatever your node
-  terminus is set as."
+  description <<-EOT
+It defaults to using whatever your node terminus is set as.
+  EOT
 end
diff --git a/lib/puppet/face/secret_agent.rb b/lib/puppet/face/secret_agent.rb
index af7ffb7b7..90841b9e0 100644
--- a/lib/puppet/face/secret_agent.rb
+++ b/lib/puppet/face/secret_agent.rb
@@ -1,19 +1,21 @@
 require 'puppet/face'
 
 Puppet::Face.define(:secret_agent, '0.0.1') do
   summary "Provides agent-like behavior, with no plugin downloading or reporting."
 
   action(:synchronize) do
+    summary "run the secret agent, which makes the catalog and system match..."
+
     when_invoked do |certname, options|
       Puppet::Face[:plugin, '0.0.1'].download
 
       facts   = Puppet::Face[:facts, '0.0.1'].find(certname)
       catalog = Puppet::Face[:catalog, '0.0.1'].download(certname, facts)
       report  = Puppet::Face[:catalog, '0.0.1'].apply(catalog)
 
       Puppet::Face[:report, '0.0.1'].submit(report)
 
       return report
     end
   end
 end