diff --git a/nexus/src/external_api/http_entrypoints.rs b/nexus/src/external_api/http_entrypoints.rs
index e709cecd99c..ba6e3c3617b 100644
--- a/nexus/src/external_api/http_entrypoints.rs
+++ b/nexus/src/external_api/http_entrypoints.rs
@@ -214,7 +214,10 @@ pub fn external_api() -> NexusApiDescription {
 // clients. Client generators use operationId to name API methods, so changing
 // a function name is a breaking change from a client perspective.
 
-/// List all organizations.
+/// List Organizations
+///
+/// Returns a list of all Organizations in the system. The Organizations are returned
+/// in sorted order by name alphabetically by default.
 #[endpoint {
     method = GET,
     path = "/organizations",
@@ -253,7 +256,9 @@ async fn organizations_get(
     apictx.external_latencies.instrument_dropshot_handler(&rqctx, handler).await
 }
 
-/// Create a new organization.
+/// Create an Organization
+///
+/// Creates a new Organization.
 #[endpoint {
     method = POST,
     path = "/organizations",
@@ -282,7 +287,10 @@ struct OrganizationPathParam {
     organization_name: Name,
 }
 
-/// Fetch a specific organization
+/// Get an Organization
+///
+/// Retrieves the details of an Organization with the given name. The same information
+/// is returned when creating or updating an Organization.
 #[endpoint {
     method = GET,
     path = "/organizations/{organization_name}",
@@ -305,7 +313,14 @@ async fn organizations_get_organization(
     apictx.external_latencies.instrument_dropshot_handler(&rqctx, handler).await
 }
 
-/// Delete a specific organization.
+/// Delete an Organization
+///
+/// Permanently deletes an Organization. It cannot be undone. This will not remove any
+/// Users or Groups since those are being synced from your identity provider via SCIM
+/// or via just-in-time SAML authentication.
+///
+/// A request to delete an Organization will fail if there are any active Projects
+/// in the Organization.
 #[endpoint {
     method = DELETE,
     path = "/organizations/{organization_name}",
@@ -327,12 +342,17 @@ async fn organizations_delete_organization(
     apictx.external_latencies.instrument_dropshot_handler(&rqctx, handler).await
 }
 
-/// Update a specific organization.
+/// Update an Organization
+///
+/// Updates the specified Organization by setting the values of the parameters passed.
+/// Any parameters not provided will be left unchanged.
 // TODO-correctness: Is it valid for PUT to accept application/json that's a
 // subset of what the resource actually represents?  If not, is that a problem?
 // (HTTP may require that this be idempotent.)  If so, can we get around that
 // having this be a slightly different content-type (e.g.,
 // "application/json-patch")?  We should see what other APIs do.
+// Other APIS work like the docs above, so it's fine. As any any parameters not passed are left
+// unchanged.
 #[endpoint {
     method = PUT,
     path = "/organizations/{organization_name}",
@@ -361,7 +381,10 @@ async fn organizations_put_organization(
     apictx.external_latencies.instrument_dropshot_handler(&rqctx, handler).await
 }
 
-/// List all projects.
+/// List Projects
+///
+/// Returns a list of all Projects in the Organization. The Projects are sorted
+/// by name alphabetically by default.
 #[endpoint {
     method = GET,
     path = "/organizations/{organization_name}/projects",
@@ -415,7 +438,9 @@ async fn organization_projects_get(
     apictx.external_latencies.instrument_dropshot_handler(&rqctx, handler).await
 }
 
-/// Create a new project.
+/// Create a Project
+///
+/// Creates a new Project in the specified Organization.
 #[endpoint {
     method = POST,
     path = "/organizations/{organization_name}/projects",
@@ -453,7 +478,9 @@ struct ProjectPathParam {
     project_name: Name,
 }
 
-/// Fetch a specific project
+/// Get a Project
+///
+/// Returns the Project with the specified name in the specified Organization.
 #[endpoint {
     method = GET,
     path = "/organizations/{organization_name}/projects/{project_name}",
@@ -478,7 +505,12 @@ async fn organization_projects_get_project(
     apictx.external_latencies.instrument_dropshot_handler(&rqctx, handler).await
 }
 
-/// Delete a specific project.
+/// Delete a Project
+///
+/// Permanently deletes the Project with the specified name in the specified Organization.
+/// It cannot be undone.
+// In the future we will want to also delete the project's data recursively, perhaps if the user
+// gives a flag or not, but see RFD4.
 #[endpoint {
     method = DELETE,
     path = "/organizations/{organization_name}/projects/{project_name}",
@@ -501,12 +533,10 @@ async fn organization_projects_delete_project(
     apictx.external_latencies.instrument_dropshot_handler(&rqctx, handler).await
 }
 
-/// Update a specific project.
-// TODO-correctness: Is it valid for PUT to accept application/json that's a
-// subset of what the resource actually represents?  If not, is that a problem?
-// (HTTP may require that this be idempotent.)  If so, can we get around that
-// having this be a slightly different content-type (e.g.,
-// "application/json-patch")?  We should see what other APIs do.
+/// Update a Project
+///
+/// Updates the specified Project in the specified Organization by setting the values
+/// of the parameters passed. Any parameters not provided are left unchanged.
 #[endpoint {
     method = PUT,
     path = "/organizations/{organization_name}/projects/{project_name}",
@@ -539,7 +569,10 @@ async fn organization_projects_put_project(
 
 // Disks
 
-/// List disks in a project.
+/// List Disks
+///
+/// Returns a list of disks in the specified Project. The Disks are returned sorted
+/// by name alphabetically by default.
 #[endpoint {
     method = GET,
     path = "/organizations/{organization_name}/projects/{project_name}/disks",
@@ -575,7 +608,9 @@ async fn project_disks_get(
     apictx.external_latencies.instrument_dropshot_handler(&rqctx, handler).await
 }
 
-/// Create a disk in a project.
+/// Create a Disk
+///
+/// Creates a new Disk in the specified Project.
 // TODO-correctness See note about instance create.  This should be async.
 #[endpoint {
     method = POST,
@@ -616,7 +651,9 @@ struct DiskPathParam {
     disk_name: Name,
 }
 
-/// Fetch a single disk in a project.
+/// Get a Disk
+///
+/// Retrieves the details of the Disk with the specified name in the specified Project.
 #[endpoint {
     method = GET,
     path = "/organizations/{organization_name}/projects/{project_name}/disks/{disk_name}",
@@ -642,7 +679,10 @@ async fn project_disks_get_disk(
     apictx.external_latencies.instrument_dropshot_handler(&rqctx, handler).await
 }
 
-/// Delete a disk from a project.
+/// Delete a Disk
+///
+/// Permanently deletes the Disk with the specified name in the specified Project.
+/// This cannot be undone.
 #[endpoint {
     method = DELETE,
     path = "/organizations/{organization_name}/projects/{project_name}/disks/{disk_name}",
@@ -675,7 +715,10 @@ async fn project_disks_delete_disk(
 
 // Instances
 
-/// List instances in a project.
+/// List Instances
+///
+/// Retrieves a list of Instances in the specified Project. The Instances are returned sorted
+/// by name alphabetically by default.
 #[endpoint {
     method = GET,
     path = "/organizations/{organization_name}/projects/{project_name}/instances",
@@ -711,7 +754,9 @@ async fn project_instances_get(
     apictx.external_latencies.instrument_dropshot_handler(&rqctx, handler).await
 }
 
-/// Create an instance in a project.
+/// Create an Instance
+///
+/// Creates a new Instance in the specified Project.
 // TODO-correctness This is supposed to be async.  Is that right?  We can create
 // the instance immediately -- it's just not booted yet.  Maybe the boot
 // operation is what's a separate operation_id.  What about the response code
@@ -758,7 +803,9 @@ struct InstancePathParam {
     instance_name: Name,
 }
 
-/// Get an instance in a project.
+/// Get an Instance
+///
+/// Retrieves the Instance with the specified name in the specified Project and Organization.
 #[endpoint {
     method = GET,
     path = "/organizations/{organization_name}/projects/{project_name}/instances/{instance_name}",
@@ -789,7 +836,17 @@ async fn project_instances_get_instance(
     apictx.external_latencies.instrument_dropshot_handler(&rqctx, handler).await
 }
 
-/// Delete an instance from a project.
+/// Delete an Instance
+///
+/// Permanently deletes the Instance with the specified name in the specified Project and
+/// Organization. This operation cannot be undone.
+///
+/// If the Instance is using a Disk, and the Disk settings are to delete upon
+/// Instance deletion, the Disk will be deleted.
+///
+/// Any ephemeral IP addresses associated with the Instance will be released.
+///
+/// Deleting an Instance requires that the Instance is stopped.
 #[endpoint {
     method = DELETE,
     path = "/organizations/{organization_name}/projects/{project_name}/instances/{instance_name}",
@@ -820,11 +877,13 @@ async fn project_instances_delete_instance(
     apictx.external_latencies.instrument_dropshot_handler(&rqctx, handler).await
 }
 
-/// Migrate an instance to a different propolis-server, possibly on a different sled.
+/// Migrate an Instance
+///
+/// Migrates an Instance to a different propolis server, possibly on a different Sled.
 #[endpoint {
     method = POST,
     path = "/organizations/{organization_name}/projects/{project_name}/instances/{instance_name}/migrate",
-    tags = ["instances"],
+    tags = ["hidden"],
 }]
 async fn project_instances_migrate_instance(
     rqctx: Arc<RequestContext<Arc<ServerContext>>>,
@@ -854,7 +913,14 @@ async fn project_instances_migrate_instance(
     apictx.external_latencies.instrument_dropshot_handler(&rqctx, handler).await
 }
 
-/// Reboot an instance.
+/// Reboot an Instance
+///
+/// Reboots the Instance with the specified name in the specified Project and Organization.
+///
+/// Any ephermal IP addresses associated with the Instance will be released and a new
+/// ephermal IP address will be assigned when the Instance starts back up. If you want the
+/// IP address to remain consistent, change it to a floating IP address before rebooting.
+// TODO: link to that API call above.
 #[endpoint {
     method = POST,
     path = "/organizations/{organization_name}/projects/{project_name}/instances/{instance_name}/reboot",
@@ -885,7 +951,9 @@ async fn project_instances_instance_reboot(
     apictx.external_latencies.instrument_dropshot_handler(&rqctx, handler).await
 }
 
-/// Boot an instance.
+/// Start an Instance
+///
+/// Starts the Instance with the specified name in the specified Project and Organization.
 #[endpoint {
     method = POST,
     path = "/organizations/{organization_name}/projects/{project_name}/instances/{instance_name}/start",
@@ -916,7 +984,13 @@ async fn project_instances_instance_start(
     apictx.external_latencies.instrument_dropshot_handler(&rqctx, handler).await
 }
 
-/// Halt an instance.
+/// Stop an Instance
+///
+/// Stop the Instance with the specified name in the specified Project and Organization.
+/// Any ephermal IP addresses associated with the Instance will be released and a new
+/// ephermal IP address will be assigned when the Instance starts back up. If you want the
+/// IP address to remain consistent, change it to a floating IP address before stopping.
+// TODO: link to that API call.
 #[endpoint {
     method = POST,
     path = "/organizations/{organization_name}/projects/{project_name}/instances/{instance_name}/stop",
@@ -948,7 +1022,10 @@ async fn project_instances_instance_stop(
     apictx.external_latencies.instrument_dropshot_handler(&rqctx, handler).await
 }
 
-/// List disks attached to this instance.
+/// List Disks attached
+///
+/// List the Disks attached to a specified instance. The Disks are listed in alphabetical
+/// order by name.
 // TODO-scalability needs to be paginated
 #[endpoint {
     method = GET,
@@ -987,6 +1064,11 @@ async fn instance_disks_get(
     apictx.external_latencies.instrument_dropshot_handler(&rqctx, handler).await
 }
 
+/// Attach a Disk
+///
+/// Attaches a Disk to a specified Instance. You must first create the Disk before
+/// you can attach it to an Instance. It is not possible to create and attach a
+/// Disk from one API call.
 #[endpoint {
     method = POST,
     path = "/organizations/{organization_name}/projects/{project_name}/instances/{instance_name}/disks/attach",
@@ -1019,6 +1101,10 @@ async fn instance_disks_attach(
     apictx.external_latencies.instrument_dropshot_handler(&rqctx, handler).await
 }
 
+/// Detach a Disk
+///
+/// Detaches a Disk from a specified Instance. The Disk is not deleted, but it is
+/// no longer attached to the Instance.
 #[endpoint {
     method = POST,
     path = "/organizations/{organization_name}/projects/{project_name}/instances/{instance_name}/disks/detach",
@@ -1051,7 +1137,10 @@ async fn instance_disks_detach(
     apictx.external_latencies.instrument_dropshot_handler(&rqctx, handler).await
 }
 
-/// List network interfaces attached to this instance.
+/// List Network Interfaces
+///
+/// List the Network Interfaces attached to a specified Instance. The Network Interfaces
+/// are listed in alphabetical order by name.
 #[endpoint {
     method = GET,
     path = "/organizations/{organization_name}/projects/{project_name}/instances/{instance_name}/network-interfaces",
@@ -1089,7 +1178,9 @@ async fn instance_network_interfaces_get(
     apictx.external_latencies.instrument_dropshot_handler(&rqctx, handler).await
 }
 
-/// Create a network interface for an instance.
+/// Create a Network Interface
+///
+/// Create a Network Interface for a specified Instance.
 #[endpoint {
     method = POST,
     path = "/organizations/{organization_name}/projects/{project_name}/instances/{instance_name}/network-interfaces",
@@ -1130,7 +1221,10 @@ pub struct NetworkInterfacePathParam {
     pub interface_name: Name,
 }
 
-/// Detach a network interface from an instance.
+/// Detach a Network Interface
+///
+/// Detaches a Network Interface from a specified Instance. The Network Interface is not deleted,
+/// but it is no longer attached to the Instance.
 #[endpoint {
     method = DELETE,
     path = "/organizations/{organization_name}/projects/{project_name}/instances/{instance_name}/network-interfaces/{interface_name}",
@@ -1163,7 +1257,9 @@ async fn instance_network_interfaces_delete_interface(
     apictx.external_latencies.instrument_dropshot_handler(&rqctx, handler).await
 }
 
-/// Get an interface attached to an instance.
+/// Get a Network Interface
+///
+/// Retrieve a specific Network Interface attached to a specified Instance.
 #[endpoint {
     method = GET,
     path = "/organizations/{organization_name}/projects/{project_name}/instances/{instance_name}/network-interfaces/{interface_name}",
@@ -1198,7 +1294,9 @@ async fn instance_network_interfaces_get_interface(
 
 // Snapshots
 
-/// List snapshots in a project.
+/// List Snapshots
+///
+/// List Snapshots in a project. Snapshots are sorted by alphabetically by name by default.
 #[endpoint {
     method = GET,
     path = "/organizations/{organization_name}/projects/{project_name}/snapshots",
@@ -1234,7 +1332,9 @@ async fn project_snapshots_get(
     apictx.external_latencies.instrument_dropshot_handler(&rqctx, handler).await
 }
 
-/// Create a snapshot of a disk.
+/// Create a Snapshot
+///
+/// Create a Snapshot of a Disk.
 #[endpoint {
     method = POST,
     path = "/organizations/{organization_name}/projects/{project_name}/snapshots",
@@ -1274,7 +1374,9 @@ struct SnapshotPathParam {
     snapshot_name: Name,
 }
 
-/// Get a snapshot in a project.
+/// Get a Snapshot
+///
+/// Retrieve details of a specific Snapshot in a Project.
 #[endpoint {
     method = GET,
     path = "/organizations/{organization_name}/projects/{project_name}/snapshots/{snapshot_name}",
@@ -1305,7 +1407,9 @@ async fn project_snapshots_get_snapshot(
     apictx.external_latencies.instrument_dropshot_handler(&rqctx, handler).await
 }
 
-/// Delete a snapshot from a project.
+/// Delete a Snapshot
+///
+/// Permanently delete a Snapshot from a Project. This operation cannot be undone.
 #[endpoint {
     method = DELETE,
     path = "/organizations/{organization_name}/projects/{project_name}/snapshots/{snapshot_name}",
@@ -1338,7 +1442,10 @@ async fn project_snapshots_delete_snapshot(
 
 // VPCs
 
-/// List VPCs in a project.
+/// List VPCs
+///
+/// Returns a list of VPCs in the specified Project. The VPCs are returned sorted
+/// by name alphabetically by default.
 #[endpoint {
     method = GET,
     path = "/organizations/{organization_name}/projects/{project_name}/vpcs",
@@ -1383,7 +1490,9 @@ struct VpcPathParam {
     vpc_name: Name,
 }
 
-/// Get a VPC in a project.
+/// Get a VPC
+///
+/// Retrieve details about a specific VPC in a Project.
 #[endpoint {
     method = GET,
     path = "/organizations/{organization_name}/projects/{project_name}/vpcs/{vpc_name}",
@@ -1409,7 +1518,9 @@ async fn project_vpcs_get_vpc(
     apictx.external_latencies.instrument_dropshot_handler(&rqctx, handler).await
 }
 
-/// Create a VPC in a project.
+/// Create a VPC
+///
+/// Create a new VPC in a Project.
 #[endpoint {
     method = POST,
     path = "/organizations/{organization_name}/projects/{project_name}/vpcs",
@@ -1441,7 +1552,10 @@ async fn project_vpcs_post(
     apictx.external_latencies.instrument_dropshot_handler(&rqctx, handler).await
 }
 
-/// Update a VPC.
+/// Update a VPC
+///
+/// Updates the specified VPC in a Project by setting the values of the parameters
+/// passed. Any parameters not provided will be left unchanged.
 #[endpoint {
     method = PUT,
     path = "/organizations/{organization_name}/projects/{project_name}/vpcs/{vpc_name}",
@@ -1471,7 +1585,9 @@ async fn project_vpcs_put_vpc(
     apictx.external_latencies.instrument_dropshot_handler(&rqctx, handler).await
 }
 
-/// Delete a vpc from a project.
+/// Delete a VPC
+///
+/// Permanently delete a VPC from a Project. This operation cannot be undone.
 #[endpoint {
     method = DELETE,
     path = "/organizations/{organization_name}/projects/{project_name}/vpcs/{vpc_name}",
@@ -1502,7 +1618,10 @@ async fn project_vpcs_delete_vpc(
     apictx.external_latencies.instrument_dropshot_handler(&rqctx, handler).await
 }
 
-/// List subnets in a VPC.
+/// List Subnets
+///
+/// Returns a list of all Subnets in a VPC. The Subnets are returned sorted by
+/// name alphabetically by default.
 #[endpoint {
     method = GET,
     path = "/organizations/{organization_name}/projects/{project_name}/vpcs/{vpc_name}/subnets",
@@ -1546,7 +1665,9 @@ struct VpcSubnetPathParam {
     subnet_name: Name,
 }
 
-/// Get subnet in a VPC.
+/// Get a Subnet
+///
+/// Returns the specified Subnet in a VPC.
 #[endpoint {
     method = GET,
     path = "/organizations/{organization_name}/projects/{project_name}/vpcs/{vpc_name}/subnets/{subnet_name}",
@@ -1575,7 +1696,9 @@ async fn vpc_subnets_get_subnet(
     apictx.external_latencies.instrument_dropshot_handler(&rqctx, handler).await
 }
 
-/// Create a subnet in a VPC.
+/// Create a Subnet
+///
+/// Creates a new Subnet in a VPC.
 #[endpoint {
     method = POST,
     path = "/organizations/{organization_name}/projects/{project_name}/vpcs/{vpc_name}/subnets",
@@ -1605,7 +1728,9 @@ async fn vpc_subnets_post(
     apictx.external_latencies.instrument_dropshot_handler(&rqctx, handler).await
 }
 
-/// Delete a subnet from a VPC.
+/// Delete a Subnet
+///
+/// Permanently deletes a Subnet from a VPC. This operation cannot be undone.
 #[endpoint {
     method = DELETE,
     path = "/organizations/{organization_name}/projects/{project_name}/vpcs/{vpc_name}/subnets/{subnet_name}",
@@ -1634,7 +1759,10 @@ async fn vpc_subnets_delete_subnet(
     apictx.external_latencies.instrument_dropshot_handler(&rqctx, handler).await
 }
 
-/// Update a VPC Subnet.
+/// Update a Subnet
+///
+/// Updates the specified Subnet in a VPC by setting the values of the parameters passed. Any
+/// parameters not provided are left unchanged.
 #[endpoint {
     method = PUT,
     path = "/organizations/{organization_name}/projects/{project_name}/vpcs/{vpc_name}/subnets/{subnet_name}",
@@ -1665,7 +1793,10 @@ async fn vpc_subnets_put_subnet(
     apictx.external_latencies.instrument_dropshot_handler(&rqctx, handler).await
 }
 
-/// List network interfaces in a VPC subnet.
+/// List Network Interfaces in a Subnet
+///
+/// Returns a list of Network Interfaces in a Subnet. The Network Interfaces are
+/// returned sorted alphabetically by name.
 #[endpoint {
     method = GET,
     path = "/organizations/{organization_name}/projects/{project_name}/vpcs/{vpc_name}/subnets/{subnet_name}/network-interfaces",
@@ -1703,7 +1834,10 @@ async fn subnet_network_interfaces_get(
 
 // VPC Firewalls
 
-/// List firewall rules for a VPC.
+/// List Firewall Rules
+///
+/// Returns a list of Firewall Rules in a VPC. The Firewall Rules are returned sorted
+/// by priority and then alphabetically by name.
 #[endpoint {
     method = GET,
     path = "/organizations/{organization_name}/projects/{project_name}/vpcs/{vpc_name}/firewall/rules",
@@ -1734,7 +1868,11 @@ async fn vpc_firewall_rules_get(
     apictx.external_latencies.instrument_dropshot_handler(&rqctx, handler).await
 }
 
-/// Replace the firewall rules for a VPC
+/// Replace the Firewall Rules
+///
+/// Replaces the Firewall Rules in a VPC with the specified rules. Any existing
+/// Firewall Rules are overwritten by the new rules.
+// TODO: write a bit about the semantics of this operation since it is finiky.
 #[endpoint {
     method = PUT,
     path = "/organizations/{organization_name}/projects/{project_name}/vpcs/{vpc_name}/firewall/rules",
@@ -1768,7 +1906,9 @@ async fn vpc_firewall_rules_put(
 
 // VPC Routers
 
-/// List VPC Custom and System Routers
+/// List Routers
+///
+/// Returns a list of Routers in a VPC. The Routers are returned sorted alphabetically by name.
 #[endpoint {
     method = GET,
     path = "/organizations/{organization_name}/projects/{project_name}/vpcs/{vpc_name}/routers",
@@ -1810,7 +1950,9 @@ struct VpcRouterPathParam {
     router_name: Name,
 }
 
-/// Get a VPC Router
+/// Get a Router
+///
+/// Returns details of the Router with the specified name.
 #[endpoint {
     method = GET,
     path = "/organizations/{organization_name}/projects/{project_name}/vpcs/{vpc_name}/routers/{router_name}",
@@ -1837,7 +1979,10 @@ async fn vpc_routers_get_router(
     apictx.external_latencies.instrument_dropshot_handler(&rqctx, handler).await
 }
 
-/// Create a VPC Router
+/// Create a Router
+///
+/// Creates a new custom Router in a VPC. There can only be one custom Router in a
+/// Subnet.
 #[endpoint {
     method = POST,
     path = "/organizations/{organization_name}/projects/{project_name}/vpcs/{vpc_name}/routers",
@@ -1866,7 +2011,9 @@ async fn vpc_routers_post(
     apictx.external_latencies.instrument_dropshot_handler(&rqctx, handler).await
 }
 
-/// Delete a router from its VPC
+/// Delete a Router
+///
+/// Deletes the custom Router with the specified name.
 #[endpoint {
     method = DELETE,
     path = "/organizations/{organization_name}/projects/{project_name}/vpcs/{vpc_name}/routers/{router_name}",
@@ -1893,7 +2040,10 @@ async fn vpc_routers_delete_router(
     apictx.external_latencies.instrument_dropshot_handler(&rqctx, handler).await
 }
 
-/// Update a VPC Router
+/// Update a Router
+///
+/// Updates the specified Router by setting the values of the parameters passed.
+/// Any parameters not specified are left unchanged.
 #[endpoint {
     method = PUT,
     path = "/organizations/{organization_name}/projects/{project_name}/vpcs/{vpc_name}/routers/{router_name}",
@@ -1924,7 +2074,10 @@ async fn vpc_routers_put_router(
 
 // Vpc Router Routes
 
-/// List a Router's routes
+/// List Routes
+///
+/// Returns a list of Routes for the specified router. The Routes are returned
+/// in alphabetical order by Route name.
 #[endpoint {
     method = GET,
     path = "/organizations/{organization_name}/projects/{project_name}/vpcs/{vpc_name}/routers/{router_name}/routes",
@@ -1968,7 +2121,9 @@ struct RouterRoutePathParam {
     route_name: Name,
 }
 
-/// Get a VPC Router route
+/// Get a Route
+///
+/// Returns details of the Route with the specified name in the specified Router.
 #[endpoint {
     method = GET,
     path = "/organizations/{organization_name}/projects/{project_name}/vpcs/{vpc_name}/routers/{router_name}/routes/{route_name}",
@@ -1996,7 +2151,9 @@ async fn routers_routes_get_route(
     apictx.external_latencies.instrument_dropshot_handler(&rqctx, handler).await
 }
 
-/// Create a VPC Router
+/// Create a Route
+///
+/// Creates a new Route in the specified custom Router.
 #[endpoint {
     method = POST,
     path = "/organizations/{organization_name}/projects/{project_name}/vpcs/{vpc_name}/routers/{router_name}/routes",
@@ -2026,7 +2183,9 @@ async fn routers_routes_post(
     apictx.external_latencies.instrument_dropshot_handler(&rqctx, handler).await
 }
 
-/// Delete a route from its router
+/// Delete a Route
+///
+/// Permanently deletes the specified Route from the specified custom Router.
 #[endpoint {
     method = DELETE,
     path = "/organizations/{organization_name}/projects/{project_name}/vpcs/{vpc_name}/routers/{router_name}/routes/{route_name}",
@@ -2054,7 +2213,10 @@ async fn routers_routes_delete_route(
     apictx.external_latencies.instrument_dropshot_handler(&rqctx, handler).await
 }
 
-/// Update a Router route
+/// Update a Route
+///
+/// Updates the specified Route in the specified custom Router by setting the values of the parameters
+/// passed. Any parameters not provided are left unchanged.
 #[endpoint {
     method = PUT,
     path = "/organizations/{organization_name}/projects/{project_name}/vpcs/{vpc_name}/routers/{router_name}/routes/{route_name}",
@@ -2086,7 +2248,9 @@ async fn routers_routes_put_route(
 
 // Racks
 
-/// List racks in the system.
+/// List Racks
+///
+/// Returns a list of Racks. The Racks are returned sorted by name alphabetically.
 #[endpoint {
     method = GET,
     path = "/hardware/racks",
@@ -2115,7 +2279,9 @@ struct RackPathParam {
     rack_id: Uuid,
 }
 
-/// Fetch information about a particular rack.
+/// Get a Rack
+///
+/// Returns details of the specified Rack.
 #[endpoint {
     method = GET,
     path = "/hardware/racks/{rack_id}",
@@ -2137,7 +2303,9 @@ async fn hardware_racks_get_rack(
 
 // Sleds
 
-/// List sleds in the system.
+/// List Sleds
+///
+/// Returns a list of Sleds. The Sleds are returned sorted by name alphabetically.
 #[endpoint {
     method = GET,
     path = "/hardware/sleds",
@@ -2169,7 +2337,9 @@ struct SledPathParam {
     sled_id: Uuid,
 }
 
-/// Fetch information about a sled in the system.
+/// Get a Sled
+///
+/// Returns details of the specified Sled.
 #[endpoint {
     method = GET,
     path = "/hardware/sleds/{sled_id}",
@@ -2192,10 +2362,13 @@ async fn hardware_sleds_get_sled(
 // Updates
 
 /// Refresh update metadata
+///
+/// Refreshes the update metadata. If there is a new software update, then the server
+/// will be aware of it and can optionally perform the update.
 #[endpoint {
      method = POST,
      path = "/updates/refresh",
-     tags = ["updates"],
+     tags = ["hidden"],
 }]
 async fn updates_refresh(
     rqctx: Arc<RequestContext<Arc<ServerContext>>>,
@@ -2211,11 +2384,14 @@ async fn updates_refresh(
 
 // Sagas
 
-/// List all sagas (for debugging)
+/// List sagas
+///
+/// Returns a list of sagas. The sagas are returned sorted by name alphabetically.
+/// This endpoint is only for debugging.
 #[endpoint {
     method = GET,
     path = "/sagas",
-    tags = ["sagas"],
+    tags = ["hidden"],
 }]
 async fn sagas_get(
     rqctx: Arc<RequestContext<Arc<ServerContext>>>,
@@ -2239,11 +2415,13 @@ struct SagaPathParam {
     saga_id: Uuid,
 }
 
-/// Fetch information about a single saga (for debugging)
+/// Get a saga
+///
+/// Returns details of the specified saga.
 #[endpoint {
     method = GET,
     path = "/sagas/{saga_id}",
-    tags = ["sagas"],
+    tags = ["hidden"],
 }]
 async fn sagas_get_saga(
     rqctx: Arc<RequestContext<Arc<ServerContext>>>,
@@ -2261,7 +2439,9 @@ async fn sagas_get_saga(
 
 // Built-in (system) users
 
-/// List the built-in system users
+/// List Users
+///
+/// Returns a list of Users. The Users are returned sorted by name alphabetically.
 #[endpoint {
     method = GET,
     path = "/users",
@@ -2296,7 +2476,11 @@ struct UserPathParam {
     user_name: Name,
 }
 
-/// Fetch a specific built-in system user
+/// Get a User
+///
+/// Returns details of the specified User.
+///
+/// To get details of the current authenticated User, use the `/session/me` endpoint.
 #[endpoint {
     method = GET,
     path = "/users/{user_name}",
@@ -2318,7 +2502,10 @@ async fn users_get_user(
     apictx.external_latencies.instrument_dropshot_handler(&rqctx, handler).await
 }
 
-/// List all timeseries schema
+/// List timeseries schema
+///
+/// Returns a list of all timeseries schemas. The schemas are returned sorted by
+/// name alphabetically.
 #[endpoint {
     method = GET,
     path = "/timeseries/schema",
@@ -2348,7 +2535,10 @@ struct RolePage {
     last_seen: String,
 }
 
-/// List the built-in roles
+/// List Roles
+///
+/// Returns a list of Roles. The Roles are returned sorted by name alphabetically.
+/// For now, these are only the built-in Roles.
 #[endpoint {
     method = GET,
     path = "/roles",
@@ -2402,7 +2592,9 @@ struct RolePathParam {
     role_name: String,
 }
 
-/// Fetch a specific built-in role
+/// Get a Role
+///
+/// Returns details of the specified Role.
 #[endpoint {
     method = GET,
     path = "/roles/{role_name}",
diff --git a/nexus/tests/output/nexus_tags.txt b/nexus/tests/output/nexus_tags.txt
index 2ddef25a4c7..92b409596f0 100644
--- a/nexus/tests/output/nexus_tags.txt
+++ b/nexus/tests/output/nexus_tags.txt
@@ -13,8 +13,12 @@ vpc_firewall_rules_put                   /organizations/{organization_name}/proj
 API operations found with tag "hidden"
 OPERATION ID                             URL PATH
 logout                                   /logout
+project_instances_migrate_instance       /organizations/{organization_name}/projects/{project_name}/instances/{instance_name}/migrate
+sagas_get                                /sagas
+sagas_get_saga                           /sagas/{saga_id}
 session_me                               /session/me
 spoof_login                              /login
+updates_refresh                          /updates/refresh
 
 API operations found with tag "instances"
 OPERATION ID                             URL PATH
@@ -31,7 +35,6 @@ project_instances_get_instance           /organizations/{organization_name}/proj
 project_instances_instance_reboot        /organizations/{organization_name}/projects/{project_name}/instances/{instance_name}/reboot
 project_instances_instance_start         /organizations/{organization_name}/projects/{project_name}/instances/{instance_name}/start
 project_instances_instance_stop          /organizations/{organization_name}/projects/{project_name}/instances/{instance_name}/stop
-project_instances_migrate_instance       /organizations/{organization_name}/projects/{project_name}/instances/{instance_name}/migrate
 project_instances_post                   /organizations/{organization_name}/projects/{project_name}/instances
 
 API operations found with tag "metrics"
@@ -80,11 +83,6 @@ routers_routes_get_route                 /organizations/{organization_name}/proj
 routers_routes_post                      /organizations/{organization_name}/projects/{project_name}/vpcs/{vpc_name}/routers/{router_name}/routes
 routers_routes_put_route                 /organizations/{organization_name}/projects/{project_name}/vpcs/{vpc_name}/routers/{router_name}/routes/{route_name}
 
-API operations found with tag "sagas"
-OPERATION ID                             URL PATH
-sagas_get                                /sagas
-sagas_get_saga                           /sagas/{saga_id}
-
 API operations found with tag "sleds"
 OPERATION ID                             URL PATH
 hardware_sleds_get                       /hardware/sleds
@@ -106,10 +104,6 @@ vpc_subnets_get_subnet                   /organizations/{organization_name}/proj
 vpc_subnets_post                         /organizations/{organization_name}/projects/{project_name}/vpcs/{vpc_name}/subnets
 vpc_subnets_put_subnet                   /organizations/{organization_name}/projects/{project_name}/vpcs/{vpc_name}/subnets/{subnet_name}
 
-API operations found with tag "updates"
-OPERATION ID                             URL PATH
-updates_refresh                          /updates/refresh
-
 API operations found with tag "users"
 OPERATION ID                             URL PATH
 users_get                                /users
diff --git a/openapi/nexus.json b/openapi/nexus.json
index 35f9c5f5f51..f0a7bee1f39 100644
--- a/openapi/nexus.json
+++ b/openapi/nexus.json
@@ -15,7 +15,8 @@
         "tags": [
           "racks"
         ],
-        "summary": "List racks in the system.",
+        "summary": "List Racks",
+        "description": "Returns a list of Racks. The Racks are returned sorted by name alphabetically.",
         "operationId": "hardware_racks_get",
         "parameters": [
           {
@@ -75,7 +76,8 @@
         "tags": [
           "racks"
         ],
-        "summary": "Fetch information about a particular rack.",
+        "summary": "Get a Rack",
+        "description": "Returns details of the specified Rack.",
         "operationId": "hardware_racks_get_rack",
         "parameters": [
           {
@@ -115,7 +117,8 @@
         "tags": [
           "sleds"
         ],
-        "summary": "List sleds in the system.",
+        "summary": "List Sleds",
+        "description": "Returns a list of Sleds. The Sleds are returned sorted by name alphabetically.",
         "operationId": "hardware_sleds_get",
         "parameters": [
           {
@@ -175,7 +178,8 @@
         "tags": [
           "sleds"
         ],
-        "summary": "Fetch information about a sled in the system.",
+        "summary": "Get a Sled",
+        "description": "Returns details of the specified Sled.",
         "operationId": "hardware_sleds_get_sled",
         "parameters": [
           {
@@ -251,7 +255,8 @@
         "tags": [
           "organizations"
         ],
-        "summary": "List all organizations.",
+        "summary": "List Organizations",
+        "description": "Returns a list of all Organizations in the system. The Organizations are returned in sorted order by name alphabetically by default.",
         "operationId": "organizations_get",
         "parameters": [
           {
@@ -309,7 +314,8 @@
         "tags": [
           "organizations"
         ],
-        "summary": "Create a new organization.",
+        "summary": "Create an Organization",
+        "description": "Creates a new Organization.",
         "operationId": "organizations_post",
         "requestBody": {
           "content": {
@@ -346,7 +352,8 @@
         "tags": [
           "organizations"
         ],
-        "summary": "Fetch a specific organization",
+        "summary": "Get an Organization",
+        "description": "Retrieves the details of an Organization with the given name. The same information is returned when creating or updating an Organization.",
         "operationId": "organizations_get_organization",
         "parameters": [
           {
@@ -383,7 +390,8 @@
         "tags": [
           "organizations"
         ],
-        "summary": "Update a specific organization.",
+        "summary": "Update an Organization",
+        "description": "Updates the specified Organization by setting the values of the parameters passed. Any parameters not provided will be left unchanged.",
         "operationId": "organizations_put_organization",
         "parameters": [
           {
@@ -430,7 +438,8 @@
         "tags": [
           "organizations"
         ],
-        "summary": "Delete a specific organization.",
+        "summary": "Delete an Organization",
+        "description": "Permanently deletes an Organization. It cannot be undone. This will not remove any Users or Groups since those are being synced from your identity provider via SCIM or via just-in-time SAML authentication.\nA request to delete an Organization will fail if there are any active Projects in the Organization.",
         "operationId": "organizations_delete_organization",
         "parameters": [
           {
@@ -462,7 +471,8 @@
         "tags": [
           "projects"
         ],
-        "summary": "List all projects.",
+        "summary": "List Projects",
+        "description": "Returns a list of all Projects in the Organization. The Projects are sorted by name alphabetically by default.",
         "operationId": "organization_projects_get",
         "parameters": [
           {
@@ -530,7 +540,8 @@
         "tags": [
           "projects"
         ],
-        "summary": "Create a new project.",
+        "summary": "Create a Project",
+        "description": "Creates a new Project in the specified Organization.",
         "operationId": "organization_projects_post",
         "parameters": [
           {
@@ -579,7 +590,8 @@
         "tags": [
           "projects"
         ],
-        "summary": "Fetch a specific project",
+        "summary": "Get a Project",
+        "description": "Returns the Project with the specified name in the specified Organization.",
         "operationId": "organization_projects_get_project",
         "parameters": [
           {
@@ -626,7 +638,8 @@
         "tags": [
           "projects"
         ],
-        "summary": "Update a specific project.",
+        "summary": "Update a Project",
+        "description": "Updates the specified Project in the specified Organization by setting the values of the parameters passed. Any parameters not provided are left unchanged.",
         "operationId": "organization_projects_put_project",
         "parameters": [
           {
@@ -683,7 +696,8 @@
         "tags": [
           "projects"
         ],
-        "summary": "Delete a specific project.",
+        "summary": "Delete a Project",
+        "description": "Permanently deletes the Project with the specified name in the specified Organization. It cannot be undone.",
         "operationId": "organization_projects_delete_project",
         "parameters": [
           {
@@ -725,7 +739,8 @@
         "tags": [
           "disks"
         ],
-        "summary": "List disks in a project.",
+        "summary": "List Disks",
+        "description": "Returns a list of disks in the specified Project. The Disks are returned sorted by name alphabetically by default.",
         "operationId": "project_disks_get",
         "parameters": [
           {
@@ -803,7 +818,8 @@
         "tags": [
           "disks"
         ],
-        "summary": "Create a disk in a project.",
+        "summary": "Create a Disk",
+        "description": "Creates a new Disk in the specified Project.",
         "operationId": "project_disks_post",
         "parameters": [
           {
@@ -862,7 +878,8 @@
         "tags": [
           "disks"
         ],
-        "summary": "Fetch a single disk in a project.",
+        "summary": "Get a Disk",
+        "description": "Retrieves the details of the Disk with the specified name in the specified Project.",
         "operationId": "project_disks_get_disk",
         "parameters": [
           {
@@ -916,7 +933,8 @@
         "tags": [
           "disks"
         ],
-        "summary": "Delete a disk from a project.",
+        "summary": "Delete a Disk",
+        "description": "Permanently deletes the Disk with the specified name in the specified Project. This cannot be undone.",
         "operationId": "project_disks_delete_disk",
         "parameters": [
           {
@@ -965,7 +983,8 @@
         "tags": [
           "instances"
         ],
-        "summary": "List instances in a project.",
+        "summary": "List Instances",
+        "description": "Retrieves a list of Instances in the specified Project. The Instances are returned sorted by name alphabetically by default.",
         "operationId": "project_instances_get",
         "parameters": [
           {
@@ -1043,7 +1062,8 @@
         "tags": [
           "instances"
         ],
-        "summary": "Create an instance in a project.",
+        "summary": "Create an Instance",
+        "description": "Creates a new Instance in the specified Project.",
         "operationId": "project_instances_post",
         "parameters": [
           {
@@ -1102,7 +1122,8 @@
         "tags": [
           "instances"
         ],
-        "summary": "Get an instance in a project.",
+        "summary": "Get an Instance",
+        "description": "Retrieves the Instance with the specified name in the specified Project and Organization.",
         "operationId": "project_instances_get_instance",
         "parameters": [
           {
@@ -1156,7 +1177,8 @@
         "tags": [
           "instances"
         ],
-        "summary": "Delete an instance from a project.",
+        "summary": "Delete an Instance",
+        "description": "Permanently deletes the Instance with the specified name in the specified Project and Organization. This operation cannot be undone.\nIf the Instance is using a Disk, and the Disk settings are to delete upon Instance deletion, the Disk will be deleted.\nAny ephemeral IP addresses associated with the Instance will be released.\nDeleting an Instance requires that the Instance is stopped.",
         "operationId": "project_instances_delete_instance",
         "parameters": [
           {
@@ -1205,7 +1227,8 @@
         "tags": [
           "instances"
         ],
-        "summary": "List disks attached to this instance.",
+        "summary": "List Disks attached",
+        "description": "List the Disks attached to a specified instance. The Disks are listed in alphabetical order by name.",
         "operationId": "instance_disks_get",
         "parameters": [
           {
@@ -1292,6 +1315,8 @@
         "tags": [
           "instances"
         ],
+        "summary": "Attach a Disk",
+        "description": "Attaches a Disk to a specified Instance. You must first create the Disk before you can attach it to an Instance. It is not possible to create and attach a Disk from one API call.",
         "operationId": "instance_disks_attach",
         "parameters": [
           {
@@ -1357,6 +1382,8 @@
         "tags": [
           "instances"
         ],
+        "summary": "Detach a Disk",
+        "description": "Detaches a Disk from a specified Instance. The Disk is not deleted, but it is no longer attached to the Instance.",
         "operationId": "instance_disks_detach",
         "parameters": [
           {
@@ -1420,9 +1447,10 @@
     "/organizations/{organization_name}/projects/{project_name}/instances/{instance_name}/migrate": {
       "post": {
         "tags": [
-          "instances"
+          "hidden"
         ],
-        "summary": "Migrate an instance to a different propolis-server, possibly on a different sled.",
+        "summary": "Migrate an Instance",
+        "description": "Migrates an Instance to a different propolis server, possibly on a different Sled.",
         "operationId": "project_instances_migrate_instance",
         "parameters": [
           {
@@ -1488,7 +1516,8 @@
         "tags": [
           "instances"
         ],
-        "summary": "List network interfaces attached to this instance.",
+        "summary": "List Network Interfaces",
+        "description": "List the Network Interfaces attached to a specified Instance. The Network Interfaces are listed in alphabetical order by name.",
         "operationId": "instance_network_interfaces_get",
         "parameters": [
           {
@@ -1573,7 +1602,8 @@
         "tags": [
           "instances"
         ],
-        "summary": "Create a network interface for an instance.",
+        "summary": "Create a Network Interface",
+        "description": "Create a Network Interface for a specified Instance.",
         "operationId": "instance_network_interfaces_post",
         "parameters": [
           {
@@ -1639,7 +1669,8 @@
         "tags": [
           "instances"
         ],
-        "summary": "Get an interface attached to an instance.",
+        "summary": "Get a Network Interface",
+        "description": "Retrieve a specific Network Interface attached to a specified Instance.",
         "operationId": "instance_network_interfaces_get_interface",
         "parameters": [
           {
@@ -1702,7 +1733,8 @@
         "tags": [
           "instances"
         ],
-        "summary": "Detach a network interface from an instance.",
+        "summary": "Detach a Network Interface",
+        "description": "Detaches a Network Interface from a specified Instance. The Network Interface is not deleted, but it is no longer attached to the Instance.",
         "operationId": "instance_network_interfaces_delete_interface",
         "parameters": [
           {
@@ -1760,7 +1792,8 @@
         "tags": [
           "instances"
         ],
-        "summary": "Reboot an instance.",
+        "summary": "Reboot an Instance",
+        "description": "Reboots the Instance with the specified name in the specified Project and Organization.\nAny ephermal IP addresses associated with the Instance will be released and a new ephermal IP address will be assigned when the Instance starts back up. If you want the IP address to remain consistent, change it to a floating IP address before rebooting.",
         "operationId": "project_instances_instance_reboot",
         "parameters": [
           {
@@ -1816,7 +1849,8 @@
         "tags": [
           "instances"
         ],
-        "summary": "Boot an instance.",
+        "summary": "Start an Instance",
+        "description": "Starts the Instance with the specified name in the specified Project and Organization.",
         "operationId": "project_instances_instance_start",
         "parameters": [
           {
@@ -1872,7 +1906,8 @@
         "tags": [
           "instances"
         ],
-        "summary": "Halt an instance.",
+        "summary": "Stop an Instance",
+        "description": "Stop the Instance with the specified name in the specified Project and Organization. Any ephermal IP addresses associated with the Instance will be released and a new ephermal IP address will be assigned when the Instance starts back up. If you want the IP address to remain consistent, change it to a floating IP address before stopping.",
         "operationId": "project_instances_instance_stop",
         "parameters": [
           {
@@ -1928,7 +1963,8 @@
         "tags": [
           "snapshots"
         ],
-        "summary": "List snapshots in a project.",
+        "summary": "List Snapshots",
+        "description": "List Snapshots in a project. Snapshots are sorted by alphabetically by name by default.",
         "operationId": "project_snapshots_get",
         "parameters": [
           {
@@ -2006,7 +2042,8 @@
         "tags": [
           "snapshots"
         ],
-        "summary": "Create a snapshot of a disk.",
+        "summary": "Create a Snapshot",
+        "description": "Create a Snapshot of a Disk.",
         "operationId": "project_snapshots_post",
         "parameters": [
           {
@@ -2065,7 +2102,8 @@
         "tags": [
           "snapshots"
         ],
-        "summary": "Get a snapshot in a project.",
+        "summary": "Get a Snapshot",
+        "description": "Retrieve details of a specific Snapshot in a Project.",
         "operationId": "project_snapshots_get_snapshot",
         "parameters": [
           {
@@ -2119,7 +2157,8 @@
         "tags": [
           "snapshots"
         ],
-        "summary": "Delete a snapshot from a project.",
+        "summary": "Delete a Snapshot",
+        "description": "Permanently delete a Snapshot from a Project. This operation cannot be undone.",
         "operationId": "project_snapshots_delete_snapshot",
         "parameters": [
           {
@@ -2168,7 +2207,8 @@
         "tags": [
           "vpcs"
         ],
-        "summary": "List VPCs in a project.",
+        "summary": "List VPCs",
+        "description": "Returns a list of VPCs in the specified Project. The VPCs are returned sorted by name alphabetically by default.",
         "operationId": "project_vpcs_get",
         "parameters": [
           {
@@ -2246,7 +2286,8 @@
         "tags": [
           "vpcs"
         ],
-        "summary": "Create a VPC in a project.",
+        "summary": "Create a VPC",
+        "description": "Create a new VPC in a Project.",
         "operationId": "project_vpcs_post",
         "parameters": [
           {
@@ -2305,7 +2346,8 @@
         "tags": [
           "vpcs"
         ],
-        "summary": "Get a VPC in a project.",
+        "summary": "Get a VPC",
+        "description": "Retrieve details about a specific VPC in a Project.",
         "operationId": "project_vpcs_get_vpc",
         "parameters": [
           {
@@ -2359,7 +2401,8 @@
         "tags": [
           "vpcs"
         ],
-        "summary": "Update a VPC.",
+        "summary": "Update a VPC",
+        "description": "Updates the specified VPC in a Project by setting the values of the parameters passed. Any parameters not provided will be left unchanged.",
         "operationId": "project_vpcs_put_vpc",
         "parameters": [
           {
@@ -2423,7 +2466,8 @@
         "tags": [
           "vpcs"
         ],
-        "summary": "Delete a vpc from a project.",
+        "summary": "Delete a VPC",
+        "description": "Permanently delete a VPC from a Project. This operation cannot be undone.",
         "operationId": "project_vpcs_delete_vpc",
         "parameters": [
           {
@@ -2472,7 +2516,8 @@
         "tags": [
           "firewall"
         ],
-        "summary": "List firewall rules for a VPC.",
+        "summary": "List Firewall Rules",
+        "description": "Returns a list of Firewall Rules in a VPC. The Firewall Rules are returned sorted by priority and then alphabetically by name.",
         "operationId": "vpc_firewall_rules_get",
         "parameters": [
           {
@@ -2526,7 +2571,8 @@
         "tags": [
           "firewall"
         ],
-        "summary": "Replace the firewall rules for a VPC",
+        "summary": "Replace the Firewall Rules",
+        "description": "Replaces the Firewall Rules in a VPC with the specified rules. Any existing Firewall Rules are overwritten by the new rules.",
         "operationId": "vpc_firewall_rules_put",
         "parameters": [
           {
@@ -2592,7 +2638,8 @@
         "tags": [
           "routers"
         ],
-        "summary": "List VPC Custom and System Routers",
+        "summary": "List Routers",
+        "description": "Returns a list of Routers in a VPC. The Routers are returned sorted alphabetically by name.",
         "operationId": "vpc_routers_get",
         "parameters": [
           {
@@ -2677,7 +2724,8 @@
         "tags": [
           "routers"
         ],
-        "summary": "Create a VPC Router",
+        "summary": "Create a Router",
+        "description": "Creates a new custom Router in a VPC. There can only be one custom Router in a Subnet.",
         "operationId": "vpc_routers_post",
         "parameters": [
           {
@@ -2743,7 +2791,8 @@
         "tags": [
           "routers"
         ],
-        "summary": "Get a VPC Router",
+        "summary": "Get a Router",
+        "description": "Returns details of the Router with the specified name.",
         "operationId": "vpc_routers_get_router",
         "parameters": [
           {
@@ -2806,7 +2855,8 @@
         "tags": [
           "routers"
         ],
-        "summary": "Update a VPC Router",
+        "summary": "Update a Router",
+        "description": "Updates the specified Router by setting the values of the parameters passed. Any parameters not specified are left unchanged.",
         "operationId": "vpc_routers_put_router",
         "parameters": [
           {
@@ -2872,7 +2922,8 @@
         "tags": [
           "routers"
         ],
-        "summary": "Delete a router from its VPC",
+        "summary": "Delete a Router",
+        "description": "Deletes the custom Router with the specified name.",
         "operationId": "vpc_routers_delete_router",
         "parameters": [
           {
@@ -2930,7 +2981,8 @@
         "tags": [
           "routes"
         ],
-        "summary": "List a Router's routes",
+        "summary": "List Routes",
+        "description": "Returns a list of Routes for the specified router. The Routes are returned in alphabetical order by Route name.",
         "operationId": "routers_routes_get",
         "parameters": [
           {
@@ -3024,7 +3076,8 @@
         "tags": [
           "routes"
         ],
-        "summary": "Create a VPC Router",
+        "summary": "Create a Route",
+        "description": "Creates a new Route in the specified custom Router.",
         "operationId": "routers_routes_post",
         "parameters": [
           {
@@ -3099,7 +3152,8 @@
         "tags": [
           "routes"
         ],
-        "summary": "Get a VPC Router route",
+        "summary": "Get a Route",
+        "description": "Returns details of the Route with the specified name in the specified Router.",
         "operationId": "routers_routes_get_route",
         "parameters": [
           {
@@ -3171,7 +3225,8 @@
         "tags": [
           "routes"
         ],
-        "summary": "Update a Router route",
+        "summary": "Update a Route",
+        "description": "Updates the specified Route in the specified custom Router by setting the values of the parameters passed. Any parameters not provided are left unchanged.",
         "operationId": "routers_routes_put_route",
         "parameters": [
           {
@@ -3246,7 +3301,8 @@
         "tags": [
           "routes"
         ],
-        "summary": "Delete a route from its router",
+        "summary": "Delete a Route",
+        "description": "Permanently deletes the specified Route from the specified custom Router.",
         "operationId": "routers_routes_delete_route",
         "parameters": [
           {
@@ -3313,7 +3369,8 @@
         "tags": [
           "subnets"
         ],
-        "summary": "List subnets in a VPC.",
+        "summary": "List Subnets",
+        "description": "Returns a list of all Subnets in a VPC. The Subnets are returned sorted by name alphabetically by default.",
         "operationId": "vpc_subnets_get",
         "parameters": [
           {
@@ -3398,7 +3455,8 @@
         "tags": [
           "subnets"
         ],
-        "summary": "Create a subnet in a VPC.",
+        "summary": "Create a Subnet",
+        "description": "Creates a new Subnet in a VPC.",
         "operationId": "vpc_subnets_post",
         "parameters": [
           {
@@ -3464,7 +3522,8 @@
         "tags": [
           "subnets"
         ],
-        "summary": "Get subnet in a VPC.",
+        "summary": "Get a Subnet",
+        "description": "Returns the specified Subnet in a VPC.",
         "operationId": "vpc_subnets_get_subnet",
         "parameters": [
           {
@@ -3527,7 +3586,8 @@
         "tags": [
           "subnets"
         ],
-        "summary": "Update a VPC Subnet.",
+        "summary": "Update a Subnet",
+        "description": "Updates the specified Subnet in a VPC by setting the values of the parameters passed. Any parameters not provided are left unchanged.",
         "operationId": "vpc_subnets_put_subnet",
         "parameters": [
           {
@@ -3600,7 +3660,8 @@
         "tags": [
           "subnets"
         ],
-        "summary": "Delete a subnet from a VPC.",
+        "summary": "Delete a Subnet",
+        "description": "Permanently deletes a Subnet from a VPC. This operation cannot be undone.",
         "operationId": "vpc_subnets_delete_subnet",
         "parameters": [
           {
@@ -3658,7 +3719,8 @@
         "tags": [
           "subnets"
         ],
-        "summary": "List network interfaces in a VPC subnet.",
+        "summary": "List Network Interfaces in a Subnet",
+        "description": "Returns a list of Network Interfaces in a Subnet. The Network Interfaces are returned sorted alphabetically by name.",
         "operationId": "subnet_network_interfaces_get",
         "parameters": [
           {
@@ -3754,7 +3816,8 @@
         "tags": [
           "roles"
         ],
-        "summary": "List the built-in roles",
+        "summary": "List Roles",
+        "description": "Returns a list of Roles. The Roles are returned sorted by name alphabetically. For now, these are only the built-in Roles.",
         "operationId": "roles_get",
         "parameters": [
           {
@@ -3806,7 +3869,8 @@
         "tags": [
           "roles"
         ],
-        "summary": "Fetch a specific built-in role",
+        "summary": "Get a Role",
+        "description": "Returns details of the specified Role.",
         "operationId": "roles_get_role",
         "parameters": [
           {
@@ -3843,9 +3907,10 @@
     "/sagas": {
       "get": {
         "tags": [
-          "sagas"
+          "hidden"
         ],
-        "summary": "List all sagas (for debugging)",
+        "summary": "List sagas",
+        "description": "Returns a list of sagas. The sagas are returned sorted by name alphabetically. This endpoint is only for debugging.",
         "operationId": "sagas_get",
         "parameters": [
           {
@@ -3903,9 +3968,10 @@
     "/sagas/{saga_id}": {
       "get": {
         "tags": [
-          "sagas"
+          "hidden"
         ],
-        "summary": "Fetch information about a single saga (for debugging)",
+        "summary": "Get a saga",
+        "description": "Returns details of the specified saga.",
         "operationId": "sagas_get_saga",
         "parameters": [
           {
@@ -3971,7 +4037,8 @@
         "tags": [
           "metrics"
         ],
-        "summary": "List all timeseries schema",
+        "summary": "List timeseries schema",
+        "description": "Returns a list of all timeseries schemas. The schemas are returned sorted by name alphabetically.",
         "operationId": "timeseries_schema_get",
         "parameters": [
           {
@@ -4021,9 +4088,10 @@
     "/updates/refresh": {
       "post": {
         "tags": [
-          "updates"
+          "hidden"
         ],
         "summary": "Refresh update metadata",
+        "description": "Refreshes the update metadata. If there is a new software update, then the server will be aware of it and can optionally perform the update.",
         "operationId": "updates_refresh",
         "responses": {
           "204": {
@@ -4043,7 +4111,8 @@
         "tags": [
           "users"
         ],
-        "summary": "List the built-in system users",
+        "summary": "List Users",
+        "description": "Returns a list of Users. The Users are returned sorted by name alphabetically.",
         "operationId": "users_get",
         "parameters": [
           {
@@ -4103,7 +4172,8 @@
         "tags": [
           "users"
         ],
-        "summary": "Fetch a specific built-in system user",
+        "summary": "Get a User",
+        "description": "Returns details of the specified User.\nTo get details of the current authenticated User, use the `/session/me` endpoint.",
         "operationId": "users_get_user",
         "parameters": [
           {