diff --git a/src/spec/chunks.ts b/src/spec/chunks.ts
index 768c44b..867d1c4 100644
--- a/src/spec/chunks.ts
+++ b/src/spec/chunks.ts
@@ -14,6 +14,13 @@ export const security = () => {
   return { security: [{ tokenHttpAuthentication: [] }] };
 };
 
+// Operation-level prose: `summary` is the short line Swagger UI shows next to the path,
+// `description` is the fuller explanation shown when the operation is expanded. Both are
+// lifted from the original pod documentation.
+export const operation = (summary: string, description: string) => {
+  return { summary, description };
+};
+
 export const jsonContent = (data: object = {}) => {
   return { content: { 'application/json': { ...data } } };
 };
@@ -69,7 +76,7 @@ export const buildingCommonMethods = (base: string) => {
   const buildingIdRequestBody = requestBodySchema({
     type: 'object',
     required: ['building_id'],
-    properties: { building_id: { type: 'integer' } },
+    properties: { building_id: { type: 'integer', description: 'The unique id of the building.' } },
   });
 
   const pendingBuildSchema = {
@@ -121,13 +128,29 @@ export const buildingCommonMethods = (base: string) => {
       post: {
         ...tags(base),
         ...security(),
+        ...operation(
+          'Queue this building for construction.',
+          "Adds this building to the planet's build queue at the given surface coordinates. Throws 1002, 1010, 1011, 1012, and 1013."
+        ),
         ...requestBodySchema({
           type: 'object',
           required: ['body_id', 'x', 'y'],
           properties: {
-            body_id: { type: 'integer' },
-            x: { type: 'integer', minimum: -5, maximum: 5 },
-            y: { type: 'integer', minimum: -5, maximum: 5 },
+            body_id: { type: 'integer', description: 'The id of the planet you wish to build on.' },
+            x: {
+              type: 'integer',
+              minimum: -5,
+              maximum: 5,
+              description:
+                'The x axis of the tile on the planet surface to place the building on. Valid values are between -5 and 5 inclusive.',
+            },
+            y: {
+              type: 'integer',
+              minimum: -5,
+              maximum: 5,
+              description:
+                'The y axis of the tile on the planet surface to place the building on. Valid values are between -5 and 5 inclusive.',
+            },
           },
         }),
         responses: queueResultSchema("Adds this building to the planet's build queue."),
@@ -138,6 +161,10 @@ export const buildingCommonMethods = (base: string) => {
       post: {
         ...tags(base),
         ...security(),
+        ...operation(
+          'Queue an upgrade for this building.',
+          'Adds the requested upgrade to the build queue. Throws 1002, 1010, 1011, 1012, and 1013.'
+        ),
         ...buildingIdRequestBody,
         responses: queueResultSchema('Adds the requested upgrade to the build queue.'),
       },
@@ -147,6 +174,10 @@ export const buildingCommonMethods = (base: string) => {
       post: {
         ...tags(base),
         ...security(),
+        ...operation(
+          'Downgrade this building by one level.',
+          "Downgrades a building by one level and then returns the building's view. Downgrading a level 1 building removes it, so the client must drop it from the display. Throws 1012."
+        ),
         ...buildingIdRequestBody,
         responses: buildingViewResultSchema(
           "Downgrades a building by one level and then returns the building's view."
@@ -158,6 +189,10 @@ export const buildingCommonMethods = (base: string) => {
       post: {
         ...tags(base),
         ...security(),
+        ...operation(
+          'Instantly destroy this building.',
+          'Instantly destroys a building. Throws 1012.'
+        ),
         ...buildingIdRequestBody,
         responses: {
           ...response200('Instantly destroys a building.', {
@@ -177,6 +212,10 @@ export const buildingCommonMethods = (base: string) => {
       post: {
         ...tags(base),
         ...security(),
+        ...operation(
+          'Repair this building to full efficiency.',
+          "Restores a building's efficiency to 100%, spending the resources listed in the view's repair_costs, then returns the building's view."
+        ),
         ...buildingIdRequestBody,
         responses: buildingViewResultSchema(
           "Restores a building's efficiency to 100%, then returns the building's view."
@@ -188,12 +227,25 @@ export const buildingCommonMethods = (base: string) => {
       post: {
         ...tags(base),
         ...security(),
+        ...operation(
+          "Project this building's stats at a given level.",
+          'Returns the projected stats of an existing building at a certain level. The building must already exist, because where it is and who owns it affects its stats. Intended for power users and script writers. Throws 1009.'
+        ),
         ...requestBodySchema({
           type: 'object',
           required: ['building_id', 'level'],
           properties: {
-            building_id: { type: 'integer' },
-            level: { type: 'integer', minimum: 1, maximum: 100 },
+            building_id: {
+              type: 'integer',
+              description: 'The unique id of the building you want to get the stats for.',
+            },
+            level: {
+              type: 'integer',
+              minimum: 1,
+              maximum: 100,
+              description:
+                'An integer between 1 and 100 representing the level you want to see the stats for.',
+            },
           },
         }),
         responses: {
@@ -257,10 +309,19 @@ export const buildingView = (
       post: {
         ...tags(base),
         ...security(),
+        ...operation(
+          "Retrieve this building's properties.",
+          'Retrieves the properties of the building: its production, capacity, efficiency, repair costs, upgrade and downgrade options, and any pending build or work state. Throws 1002 and 1010.'
+        ),
         ...requestBodySchema({
           type: 'object',
           required: ['building_id'],
-          properties: { building_id: { type: 'integer' } },
+          properties: {
+            building_id: {
+              type: 'integer',
+              description: 'The id of the building you wish to retrieve.',
+            },
+          },
         }),
         responses: {
           ...response200('Retrieves the properties of the building.', {
diff --git a/src/spec/components.ts b/src/spec/components.ts
index ece3179..031e4dc 100644
--- a/src/spec/components.ts
+++ b/src/spec/components.ts
@@ -11,21 +11,35 @@ export const components = {
   schemas: {
     body_status: {
       type: 'object',
+      description:
+        'Public information about a stellar body, returned in the `body` part of the status block and used to populate the Star Map.',
       properties: {
-        id: { type: 'integer' },
-        x: { type: 'number' },
-        y: { type: 'number' },
-        star_id: { type: 'integer' },
-        star_name: { type: 'string' },
-        zone: { type: 'string' },
-        orbit: { type: 'number' },
-        type: { type: 'string' }, // TODO: this can probably be an enum
-        name: { type: 'string' },
-        image: { type: 'string' },
-        size: { type: 'number' },
-        water: { type: 'number' },
+        id: { type: 'integer', description: 'The unique id of the body.' },
+        x: { type: 'number', description: 'The x coordinate of the body on the star map.' },
+        y: { type: 'number', description: 'The y coordinate of the body on the star map.' },
+        star_id: { type: 'integer', description: 'The id of the star this body orbits.' },
+        star_name: { type: 'string', description: 'The name of the star this body orbits.' },
+        zone: { type: 'string', description: 'The star map zone the body sits in, e.g. "0|0".' },
+        orbit: {
+          type: 'number',
+          description: 'Which orbit of the star the body occupies, where 1 is closest to the star.',
+        },
+        // TODO: this can probably be an enum
+        type: {
+          type: 'string',
+          description:
+            'The kind of body, e.g. "habitable planet", "gas giant", "asteroid", or "space station".',
+        },
+        name: { type: 'string', description: 'The name of the body.' },
+        image: { type: 'string', description: 'The image key used to render the body.' },
+        size: {
+          type: 'number',
+          description: 'The size of the body. On a planet this is the number of building plots.',
+        },
+        water: { type: 'number', description: 'The amount of water present on the body.' },
         ore: {
           type: 'object',
+          description: 'The ore concentrations present on the body, keyed by ore type.',
           properties: {
             anthracite: { type: 'integer' },
             bauxite: { type: 'integer' },
@@ -73,21 +87,32 @@ export const components = {
         },
         empire: {
           type: 'object',
+          description: 'The empire occupying this body. Only present when an empire occupies it.',
           properties: {
-            id: { type: 'integer' },
-            name: { type: 'string' },
-            alignment: { type: 'string', enum: ['ally', 'self', 'hostile'] },
-            is_isolationist: { type: 'integer', enum: [1, 0] },
+            id: { type: 'integer', description: 'The id of the occupying empire.' },
+            name: { type: 'string', description: 'The name of the occupying empire.' },
+            alignment: {
+              type: 'string',
+              enum: ['ally', 'self', 'hostile'],
+              description: "The occupying empire's alignment relative to you.",
+            },
+            is_isolationist: {
+              type: 'integer',
+              enum: [1, 0],
+              description: '1 if the occupying empire has not sent out any probes or colony ships.',
+            },
           },
           required: ['id', 'name', 'alignment', 'is_isolationist'],
         },
         station: {
           type: 'object',
+          description:
+            "The space station whose influence this body is under. Only present when the body is within a station's jurisdiction.",
           properties: {
-            id: { type: 'integer' },
-            x: { type: 'number' },
-            y: { type: 'number' },
-            name: { type: 'string' },
+            id: { type: 'integer', description: 'The id of the space station.' },
+            x: { type: 'number', description: 'The x coordinate of the space station.' },
+            y: { type: 'number', description: 'The y coordinate of the space station.' },
+            name: { type: 'string', description: 'The name of the space station.' },
           },
           required: ['id', 'x', 'y', 'name'],
         },
@@ -107,89 +132,164 @@ export const components = {
       ],
     },
 
-    // The comprehensive "own body" shape returned as the `planet` block on the
-    // Planetary Command / Station Command `view` — a body_status plus population, happiness,
-    // and per-resource stored/hour/capacity figures.
     planet_status: {
       type: 'object',
+      description:
+        'The comprehensive "own body" shape returned as the `planet` block on the Planetary Command / Station Command `view` — a body_status plus population, happiness, and per-resource stored/hour/capacity figures. Only returned for a body you own.',
       properties: {
-        id: { type: 'integer' },
-        x: { type: 'integer' },
-        y: { type: 'integer' },
-        star_id: { type: 'integer' },
-        star_name: { type: 'string' },
-        zone: { type: 'string' },
-        orbit: { type: 'integer' },
-        type: { type: 'string' },
-        name: { type: 'string' },
-        image: { type: 'string' },
-        size: { type: 'integer' },
-        water: { type: 'integer' },
-        ore: { type: 'object', additionalProperties: { type: 'integer' } },
-        notes: { type: 'string' },
-        neutral_entry: { type: 'string' },
+        id: { type: 'integer', description: 'The unique id of the body.' },
+        x: { type: 'integer', description: 'The x coordinate of the body on the star map.' },
+        y: { type: 'integer', description: 'The y coordinate of the body on the star map.' },
+        star_id: { type: 'integer', description: 'The id of the star this body orbits.' },
+        star_name: { type: 'string', description: 'The name of the star this body orbits.' },
+        zone: { type: 'string', description: 'The star map zone the body sits in, e.g. "0|0".' },
+        orbit: {
+          type: 'integer',
+          description: 'Which orbit of the star the body occupies, where 1 is closest to the star.',
+        },
+        type: {
+          type: 'string',
+          description:
+            'The kind of body, e.g. "habitable planet", "gas giant", "asteroid", or "space station".',
+        },
+        name: { type: 'string', description: 'The name of the body.' },
+        image: { type: 'string', description: 'The image key used to render the body.' },
+        size: {
+          type: 'integer',
+          description: 'The size of the body. On a planet this is the number of building plots.',
+        },
+        water: { type: 'integer', description: 'The amount of water stored on the body.' },
+        ore: {
+          type: 'object',
+          description: 'The ore concentrations present on the body, keyed by ore type.',
+          additionalProperties: { type: 'integer' },
+        },
+        notes: { type: 'string', description: 'The per-colony notes set for this body.' },
+        neutral_entry: {
+          type: 'string',
+          description: 'The earliest time the body may enter the neutral area.',
+        },
         empire: {
           type: 'object',
+          description: 'The empire occupying this body. Only present when an empire occupies it.',
           properties: {
-            id: { type: 'integer' },
-            name: { type: 'string' },
-            alignment: { type: 'string', enum: ['ally', 'self', 'hostile'] },
-            is_isolationist: { type: 'integer', enum: [1, 0] },
+            id: { type: 'integer', description: 'The id of the occupying empire.' },
+            name: { type: 'string', description: 'The name of the occupying empire.' },
+            alignment: {
+              type: 'string',
+              enum: ['ally', 'self', 'hostile'],
+              description: "The occupying empire's alignment relative to you.",
+            },
+            is_isolationist: {
+              type: 'integer',
+              enum: [1, 0],
+              description: '1 if the occupying empire has not sent out any probes or colony ships.',
+            },
           },
         },
-        building_count: { type: 'integer' },
-        population: { type: 'integer' },
-        happiness: { type: 'integer' },
-        happiness_hour: { type: 'integer' },
-        food_stored: { type: 'integer' },
-        food_capacity: { type: 'integer' },
-        food_hour: { type: 'integer' },
-        energy_stored: { type: 'integer' },
-        energy_capacity: { type: 'integer' },
-        energy_hour: { type: 'integer' },
-        ore_hour: { type: 'integer' },
-        ore_capacity: { type: 'integer' },
-        ore_stored: { type: 'integer' },
-        waste_hour: { type: 'integer' },
-        waste_stored: { type: 'integer' },
-        waste_capacity: { type: 'integer' },
-        water_stored: { type: 'integer' },
-        water_hour: { type: 'integer' },
-        water_capacity: { type: 'integer' },
-        num_incoming_own: { type: 'integer' },
-        num_incoming_ally: { type: 'integer' },
-        num_incoming_enemy: { type: 'integer' },
+        building_count: {
+          type: 'integer',
+          description: 'The number of buildings currently on the body.',
+        },
+        population: { type: 'integer', description: 'The current population of the body.' },
+        happiness: { type: 'integer', description: 'The current happiness stored on the body.' },
+        happiness_hour: {
+          type: 'integer',
+          description: 'The net happiness produced per hour on the body.',
+        },
+        food_stored: { type: 'integer', description: 'The amount of food currently in storage.' },
+        food_capacity: { type: 'integer', description: 'The total food storage capacity.' },
+        food_hour: { type: 'integer', description: 'The net food produced per hour.' },
+        energy_stored: {
+          type: 'integer',
+          description: 'The amount of energy currently in storage.',
+        },
+        energy_capacity: { type: 'integer', description: 'The total energy storage capacity.' },
+        energy_hour: { type: 'integer', description: 'The net energy produced per hour.' },
+        ore_hour: { type: 'integer', description: 'The net ore produced per hour.' },
+        ore_capacity: { type: 'integer', description: 'The total ore storage capacity.' },
+        ore_stored: { type: 'integer', description: 'The amount of ore currently in storage.' },
+        waste_hour: { type: 'integer', description: 'The net waste produced per hour.' },
+        waste_stored: { type: 'integer', description: 'The amount of waste currently in storage.' },
+        waste_capacity: { type: 'integer', description: 'The total waste storage capacity.' },
+        water_stored: { type: 'integer', description: 'The amount of water currently in storage.' },
+        water_hour: { type: 'integer', description: 'The net water produced per hour.' },
+        water_capacity: { type: 'integer', description: 'The total water storage capacity.' },
+        num_incoming_own: {
+          type: 'integer',
+          description: 'The number of incoming ships from your own colonies.',
+        },
+        num_incoming_ally: {
+          type: 'integer',
+          description: 'The number of incoming ships from within your alliance.',
+        },
+        num_incoming_enemy: {
+          type: 'integer',
+          description: 'The total number of incoming foreign ships.',
+        },
       },
     },
 
     empire_status: {
       type: 'object',
+      description:
+        'Information about the current state of the empire, returned in the `empire` part of the status block of every relevant request.',
       properties: {
-        essentia: { type: 'integer' },
-        // Keyed by body id (a stringified integer), value is the colony name.
-        colonies: { type: 'object', additionalProperties: { type: 'string' } },
-        rpc_count: { type: 'integer' },
-        is_isolationist: { type: 'integer' },
-        id: { type: 'integer' },
-        // Keyed by body id (a stringified integer), value is the planet name.
-        planets: { type: 'object', additionalProperties: { type: 'string' } },
-        has_new_messages: { type: 'integer' },
-        name: { type: 'string' },
-        home_planet_id: { type: 'integer' },
-        insurrect_value: { type: 'integer' },
-        status_message: { type: 'string' },
-        self_destruct_active: { type: 'integer' },
-        next_colony_srcs: { type: 'integer' },
-        // Keyed by space station id (a stringified integer), value is the station name.
-        stations: { type: 'object', additionalProperties: { type: 'string' } },
-        self_destruct_date: { type: 'string' },
-        next_colony_cost: { type: 'integer' },
-        latest_message_id: { type: 'integer' },
+        essentia: { type: 'integer', description: "The empire's current essentia balance." },
+        colonies: {
+          type: 'object',
+          description: 'Keyed by body id (a stringified integer), value is the colony name.',
+          additionalProperties: { type: 'string' },
+        },
+        rpc_count: {
+          type: 'integer',
+          description: 'The number of calls made to the server so far in the current RPC period.',
+        },
+        is_isolationist: {
+          type: 'integer',
+          description: "1 if the empire hasn't sent out any probes or colony ships.",
+        },
+        id: { type: 'integer', description: 'The unique id of the empire.' },
+        planets: {
+          type: 'object',
+          description: 'Keyed by body id (a stringified integer), value is the planet name.',
+          additionalProperties: { type: 'string' },
+        },
+        has_new_messages: {
+          type: 'integer',
+          description: 'The number of unread messages in the inbox.',
+        },
+        name: { type: 'string', description: 'The name of the empire.' },
+        home_planet_id: { type: 'integer', description: "The id of the empire's home planet." },
+        insurrect_value: { type: 'integer', description: 'The current insurrection value.' },
+        status_message: { type: 'string', description: "The empire's status message." },
+        self_destruct_active: {
+          type: 'integer',
+          description: '1 if the self destruct countdown is currently running.',
+        },
+        next_colony_srcs: { type: 'integer', description: 'The resource cost of the next colony.' },
+        stations: {
+          type: 'object',
+          description:
+            'Keyed by space station id (a stringified integer), value is the station name.',
+          additionalProperties: { type: 'string' },
+        },
+        self_destruct_date: {
+          type: 'string',
+          description: 'The date the empire will self destruct, when a countdown is active.',
+        },
+        next_colony_cost: {
+          type: 'integer',
+          description: 'The happiness cost of founding the next colony.',
+        },
+        latest_message_id: { type: 'integer', description: 'The id of the most recent message.' },
         bodies: {
           type: 'object',
+          description: 'The bodies known to the empire, grouped by relationship.',
           properties: {
             colonies: {
               type: 'array',
+              description: 'The colonies owned by the empire.',
               items: {
                 type: 'object',
                 properties: {
@@ -221,8 +321,14 @@ export const components = {
           },
           required: ['colonies'],
         },
-        next_station_cost: { type: 'integer' },
-        tech_level: { type: 'integer' },
+        next_station_cost: {
+          type: 'integer',
+          description: 'The resource cost of the next space station.',
+        },
+        tech_level: {
+          type: 'integer',
+          description: 'The highest level the University has reached.',
+        },
       },
       required: [
         'essentia',
@@ -250,22 +356,29 @@ export const components = {
 
     building_cost: {
       type: 'object',
+      description: 'The resource and time cost of a build or upgrade.',
       properties: {
-        food: { type: 'integer' },
-        water: { type: 'integer' },
-        energy: { type: 'integer' },
-        waste: { type: 'integer' },
-        ore: { type: 'integer' },
-        time: { type: 'integer' },
-        halls: { type: 'integer' },
+        food: { type: 'integer', description: 'Food spent from storage.' },
+        water: { type: 'integer', description: 'Water spent from storage.' },
+        energy: { type: 'integer', description: 'Energy spent from storage.' },
+        waste: {
+          type: 'integer',
+          description: 'Waste added to storage (not spent like the other resources).',
+        },
+        ore: { type: 'integer', description: 'Ore spent from storage.' },
+        time: { type: 'integer', description: 'Build time in seconds.' },
+        halls: {
+          type: 'integer',
+          description: 'Number of Halls of Vrbansk required, for buildings built from glyphs.',
+        },
       },
       required: ['time'],
     },
 
-    // The lightweight per-building shape returned by get_buildings/repair_list — not the full
-    // `building` schema, since this is a list/grid view, not a single-building detail view.
     buildings_list: {
       type: 'object',
+      description:
+        "The lightweight per-building shape returned by get_buildings / repair_list. Place these on the planet's 11x11 grid and fill the rest with blank ground tiles. Not the full `building` schema, since this is a list/grid view rather than a single-building detail view.",
       required: ['buildings'],
       properties: {
         buildings: {
@@ -275,18 +388,34 @@ export const components = {
             type: 'object',
             required: ['id', 'name', 'x', 'y', 'url', 'level', 'image', 'efficiency'],
             properties: {
-              // Same value as the map key, repeated for convenience.
-              id: { type: 'integer' },
-              name: { type: 'string' },
-              x: { type: 'integer', minimum: -5, maximum: 5 },
-              y: { type: 'integer', minimum: -5, maximum: 5 },
-              url: { type: 'string' },
-              level: { type: 'integer' },
-              image: { type: 'string' },
-              efficiency: { type: 'integer' },
-              // Only included when the building is being built/upgraded.
+              id: {
+                type: 'integer',
+                description:
+                  'The building id. Same value as the map key, repeated for convenience.',
+              },
+              name: { type: 'string', description: 'The building name.' },
+              x: {
+                type: 'integer',
+                minimum: -5,
+                maximum: 5,
+                description: 'The x coordinate of the building on the surface grid.',
+              },
+              y: {
+                type: 'integer',
+                minimum: -5,
+                maximum: 5,
+                description: 'The y coordinate of the building on the surface grid.',
+              },
+              url: { type: 'string', description: 'The building type\'s API URL, e.g. "/apple".' },
+              level: { type: 'integer', description: 'The current level of the building.' },
+              image: { type: 'string', description: 'The image key used to render the building.' },
+              efficiency: {
+                type: 'integer',
+                description: 'The current efficiency of the building, from 0 to 100.',
+              },
               pending_build: {
                 type: 'object',
+                description: 'Only included when the building is being built or upgraded.',
                 properties: {
                   seconds_remaining: { type: 'integer' },
                   start: { type: 'string' },
@@ -294,9 +423,10 @@ export const components = {
                 },
                 required: ['seconds_remaining', 'start', 'end'],
               },
-              // Only included when the building is working (Parks, Waste Recycling, etc).
               work: {
                 type: 'object',
+                description:
+                  'Only included when the building is working (Parks, Waste Recycling, etc).',
                 properties: {
                   seconds_remaining: { type: 'integer' },
                   start: { type: 'string' },
@@ -304,9 +434,9 @@ export const components = {
                 },
                 required: ['seconds_remaining', 'start', 'end'],
               },
-              // Only included when the building is damaged (efficiency < 100).
               repair_costs: {
                 type: 'object',
+                description: 'Only included when the building is damaged (efficiency below 100).',
                 properties: {
                   food: { type: 'integer' },
                   water: { type: 'integer' },
@@ -323,18 +453,19 @@ export const components = {
 
     building_production: {
       type: 'object',
+      description: "A building's hourly production and storage capacity for each resource.",
       properties: {
-        food_hour: { type: 'integer' },
-        food_capacity: { type: 'integer' },
-        energy_hour: { type: 'integer' },
-        energy_capacity: { type: 'integer' },
-        ore_hour: { type: 'integer' },
-        ore_capacity: { type: 'integer' },
-        water_hour: { type: 'integer' },
-        water_capacity: { type: 'integer' },
-        waste_hour: { type: 'integer' },
-        waste_capacity: { type: 'integer' },
-        happiness_hour: { type: 'integer' },
+        food_hour: { type: 'integer', description: 'Net food produced per hour.' },
+        food_capacity: { type: 'integer', description: 'Food storage capacity added.' },
+        energy_hour: { type: 'integer', description: 'Net energy produced per hour.' },
+        energy_capacity: { type: 'integer', description: 'Energy storage capacity added.' },
+        ore_hour: { type: 'integer', description: 'Net ore produced per hour.' },
+        ore_capacity: { type: 'integer', description: 'Ore storage capacity added.' },
+        water_hour: { type: 'integer', description: 'Net water produced per hour.' },
+        water_capacity: { type: 'integer', description: 'Water storage capacity added.' },
+        waste_hour: { type: 'integer', description: 'Net waste produced per hour.' },
+        waste_capacity: { type: 'integer', description: 'Waste storage capacity added.' },
+        happiness_hour: { type: 'integer', description: 'Net happiness produced per hour.' },
       },
       required: [
         'food_hour',
@@ -351,38 +482,38 @@ export const components = {
       ],
     },
 
-    // A single building's contribution to the planet economy, as returned by
-    // get_buildings_resources: the same aggregate figures as `building_production`
-    // plus a per-food-type and per-ore-type production breakdown.
-    //   - `food` is present only when the building produces food, `ore` only when
-    //     it produces ore (Perl omits an empty map entirely).
-    //   - `ore_hour` / `ore_capacity` / `ore` are ALL omitted for the Mining
-    //     Ministry, whose ore output is driven by its deployed mining platforms
-    //     rather than the building itself - hence they are not required here even
-    //     though `building_production` requires ore_hour / ore_capacity.
     building_resources: {
       type: 'object',
+      description:
+        "A single building's contribution to the planet economy, as returned by get_buildings_resources: the same aggregate figures as `building_production` plus a per-food-type and per-ore-type production breakdown. `ore_hour`, `ore_capacity` and `ore` are all omitted for the Mining Ministry, whose ore output is driven by its deployed mining platforms rather than the building itself.",
       properties: {
-        food_hour: { type: 'integer' },
-        food_capacity: { type: 'integer' },
-        energy_hour: { type: 'integer' },
-        energy_capacity: { type: 'integer' },
-        water_hour: { type: 'integer' },
-        water_capacity: { type: 'integer' },
-        waste_hour: { type: 'integer' },
-        waste_capacity: { type: 'integer' },
-        happiness_hour: { type: 'integer' },
-        // Omitted for the Mining Ministry (see above).
-        ore_hour: { type: 'integer' },
-        ore_capacity: { type: 'integer' },
+        food_hour: { type: 'integer', description: 'Net food produced per hour.' },
+        food_capacity: { type: 'integer', description: 'Food storage capacity added.' },
+        energy_hour: { type: 'integer', description: 'Net energy produced per hour.' },
+        energy_capacity: { type: 'integer', description: 'Energy storage capacity added.' },
+        water_hour: { type: 'integer', description: 'Net water produced per hour.' },
+        water_capacity: { type: 'integer', description: 'Water storage capacity added.' },
+        waste_hour: { type: 'integer', description: 'Net waste produced per hour.' },
+        waste_capacity: { type: 'integer', description: 'Waste storage capacity added.' },
+        happiness_hour: { type: 'integer', description: 'Net happiness produced per hour.' },
+        ore_hour: {
+          type: 'integer',
+          description: 'Net ore produced per hour. Omitted for the Mining Ministry.',
+        },
+        ore_capacity: {
+          type: 'integer',
+          description: 'Ore storage capacity added. Omitted for the Mining Ministry.',
+        },
         food: {
           type: 'object',
-          description: 'Hourly production keyed by food type.',
+          description:
+            'Hourly production keyed by food type. Only included when the building produces food.',
           additionalProperties: { type: 'integer' },
         },
         ore: {
           type: 'object',
-          description: 'Hourly production keyed by ore type.',
+          description:
+            'Hourly production keyed by ore type. Only included when the building produces ore.',
           additionalProperties: { type: 'integer' },
         },
       },
@@ -399,29 +530,42 @@ export const components = {
       ],
     },
 
-    // The per-building shape returned by get_buildings_resources — the lightweight
-    // grid shape (as in buildings_list) with a `resources` object added. Keyed by
-    // building id, one level deep (no extra `buildings` wrapper).
     buildings_resources_list: {
       type: 'object',
-      description: 'Keyed by building id (a stringified integer).',
+      description:
+        'The per-building shape returned by get_buildings_resources — the lightweight grid shape (as in buildings_list) with a `resources` object added. Keyed by building id (a stringified integer), one level deep (no extra `buildings` wrapper).',
       additionalProperties: {
         type: 'object',
         required: ['id', 'name', 'x', 'y', 'url', 'level', 'image', 'efficiency', 'resources'],
         properties: {
-          // Same value as the map key, repeated for convenience.
-          id: { type: 'integer' },
-          name: { type: 'string' },
-          x: { type: 'integer', minimum: -5, maximum: 5 },
-          y: { type: 'integer', minimum: -5, maximum: 5 },
-          url: { type: 'string' },
-          level: { type: 'integer' },
-          image: { type: 'string' },
-          efficiency: { type: 'integer' },
+          id: {
+            type: 'integer',
+            description: 'The building id. Same value as the map key, repeated for convenience.',
+          },
+          name: { type: 'string', description: 'The building name.' },
+          x: {
+            type: 'integer',
+            minimum: -5,
+            maximum: 5,
+            description: 'The x coordinate of the building on the surface grid.',
+          },
+          y: {
+            type: 'integer',
+            minimum: -5,
+            maximum: 5,
+            description: 'The y coordinate of the building on the surface grid.',
+          },
+          url: { type: 'string', description: 'The building type\'s API URL, e.g. "/apple".' },
+          level: { type: 'integer', description: 'The current level of the building.' },
+          image: { type: 'string', description: 'The image key used to render the building.' },
+          efficiency: {
+            type: 'integer',
+            description: 'The current efficiency of the building, from 0 to 100.',
+          },
           resources: { $ref: '#/components/schemas/building_resources' },
-          // Only included when the building is being built/upgraded.
           pending_build: {
             type: 'object',
+            description: 'Only included when the building is being built or upgraded.',
             properties: {
               seconds_remaining: { type: 'integer' },
               start: { type: 'string' },
@@ -429,9 +573,10 @@ export const components = {
             },
             required: ['seconds_remaining', 'start', 'end'],
           },
-          // Only included when the building is working (Parks, Waste Recycling, etc).
           work: {
             type: 'object',
+            description:
+              'Only included when the building is working (Parks, Waste Recycling, etc).',
             properties: {
               seconds_remaining: { type: 'integer' },
               start: { type: 'string' },
@@ -439,9 +584,9 @@ export const components = {
             },
             required: ['seconds_remaining', 'start', 'end'],
           },
-          // Only included when the building is damaged (efficiency < 100).
           repair_costs: {
             type: 'object',
+            description: 'Only included when the building is damaged (efficiency below 100).',
             properties: {
               food: { type: 'integer' },
               water: { type: 'integer' },
@@ -454,32 +599,47 @@ export const components = {
       },
     },
 
-    // The fields common to every building's `view` response. Building-type-specific endpoints
-    // (see src/spec/paths/buildings/*.ts) add extra sibling fields alongside this on `view`.
     building: {
       type: 'object',
+      description:
+        "The fields common to every building's `view` response. Building-type-specific endpoints (see src/spec/paths/buildings/*.ts) add extra sibling fields alongside this on `view`.",
       properties: {
-        id: { type: 'integer' },
-        name: { type: 'string' },
-        image: { type: 'string' },
-        url: { type: 'string' },
-        level: { type: 'integer' },
-        x: { type: 'integer', minimum: -5, maximum: 5 },
-        y: { type: 'integer', minimum: -5, maximum: 5 },
-        efficiency: { type: 'integer' },
-        food_hour: { type: 'integer' },
-        food_capacity: { type: 'integer' },
-        energy_hour: { type: 'integer' },
-        energy_capacity: { type: 'integer' },
-        ore_hour: { type: 'integer' },
-        ore_capacity: { type: 'integer' },
-        water_hour: { type: 'integer' },
-        water_capacity: { type: 'integer' },
-        waste_hour: { type: 'integer' },
-        waste_capacity: { type: 'integer' },
-        happiness_hour: { type: 'integer' },
+        id: { type: 'integer', description: 'The unique id of the building.' },
+        name: { type: 'string', description: 'The building name.' },
+        image: { type: 'string', description: 'The image key used to render the building.' },
+        url: { type: 'string', description: 'The building type\'s API URL, e.g. "/apple".' },
+        level: { type: 'integer', description: 'The current level of the building.' },
+        x: {
+          type: 'integer',
+          minimum: -5,
+          maximum: 5,
+          description: 'The x coordinate of the building on the surface grid.',
+        },
+        y: {
+          type: 'integer',
+          minimum: -5,
+          maximum: 5,
+          description: 'The y coordinate of the building on the surface grid.',
+        },
+        efficiency: {
+          type: 'integer',
+          description: 'The current efficiency of the building, from 0 to 100.',
+        },
+        food_hour: { type: 'integer', description: 'Net food produced per hour.' },
+        food_capacity: { type: 'integer', description: 'Food storage capacity added.' },
+        energy_hour: { type: 'integer', description: 'Net energy produced per hour.' },
+        energy_capacity: { type: 'integer', description: 'Energy storage capacity added.' },
+        ore_hour: { type: 'integer', description: 'Net ore produced per hour.' },
+        ore_capacity: { type: 'integer', description: 'Ore storage capacity added.' },
+        water_hour: { type: 'integer', description: 'Net water produced per hour.' },
+        water_capacity: { type: 'integer', description: 'Water storage capacity added.' },
+        waste_hour: { type: 'integer', description: 'Net waste produced per hour.' },
+        waste_capacity: { type: 'integer', description: 'Waste storage capacity added.' },
+        happiness_hour: { type: 'integer', description: 'Net happiness produced per hour.' },
         repair_costs: {
           type: 'object',
+          description:
+            'The resources it would cost to repair the building to full efficiency. See the repair method.',
           properties: {
             food: { type: 'integer' },
             water: { type: 'integer' },
@@ -488,9 +648,9 @@ export const components = {
           },
           required: ['food', 'water', 'energy', 'ore'],
         },
-        // Only present while the building is being built/upgraded.
         pending_build: {
           type: 'object',
+          description: 'Only present while the building is being built or upgraded.',
           properties: {
             seconds_remaining: { type: 'integer' },
             start: { type: 'string' },
@@ -498,37 +658,57 @@ export const components = {
           },
           required: ['seconds_remaining', 'start', 'end'],
         },
-        // Only present while the building is doing work (e.g. Parks, Waste Recycling).
         work: {
           type: 'object',
+          description:
+            'Only present while the building is doing work (e.g. Parks, Waste Recycling).',
           properties: {
             seconds_remaining: { type: 'integer' },
             start: { type: 'string' },
             end: { type: 'string' },
-            // Present for an Archaeology Ministry that is searching for a glyph.
-            searching: { type: 'string' },
+            searching: {
+              type: 'string',
+              description:
+                'Present for an Archaeology Ministry that is searching for a glyph — the ore being searched.',
+            },
           },
           required: ['seconds_remaining', 'start', 'end'],
         },
         downgrade: {
           type: 'object',
+          description: 'Whether the building can be downgraded, and why not.',
           properties: {
-            can: { type: 'integer', enum: [1, 0] },
-            // A [code, message] pair; [0, ""] when there is no reason.
-            reason: { type: 'array', items: {} },
-            image: { type: 'string' },
+            can: {
+              type: 'integer',
+              enum: [1, 0],
+              description: '1 if the building can be downgraded.',
+            },
+            reason: {
+              type: 'array',
+              items: {},
+              description: 'A [code, message] pair; [0, ""] when there is no reason.',
+            },
+            image: { type: 'string', description: 'The image key for the downgraded building.' },
           },
           required: ['can', 'reason', 'image'],
         },
         upgrade: {
           type: 'object',
+          description: 'Whether the building can be upgraded, its cost, and its projected stats.',
           properties: {
-            can: { type: 'integer', enum: [1, 0] },
-            // A [code, message] pair; [0, ""] when there is no reason.
-            reason: { type: 'array', items: {} },
+            can: {
+              type: 'integer',
+              enum: [1, 0],
+              description: '1 if the building can be upgraded.',
+            },
+            reason: {
+              type: 'array',
+              items: {},
+              description: 'A [code, message] pair; [0, ""] when there is no reason.',
+            },
             cost: { $ref: '#/components/schemas/building_cost' },
             production: { $ref: '#/components/schemas/building_production' },
-            image: { type: 'string' },
+            image: { type: 'string', description: 'The image key for the upgraded building.' },
           },
           required: ['can', 'reason', 'cost', 'production', 'image'],
         },
@@ -560,16 +740,20 @@ export const components = {
 
     rpc_error: {
       type: 'object',
+      description:
+        'A JSON-RPC error response. The game returns these with an HTTP 500 status code whenever a method throws.',
       required: ['id', 'jsonrpc', 'error'],
       properties: {
-        id: { type: 'number' },
-        jsonrpc: { type: 'string' },
+        id: { type: 'number', description: 'The id echoed back from the request.' },
+        jsonrpc: { type: 'string', description: 'The JSON-RPC version, always "2.0".' },
         error: {
           type: 'object',
           required: ['code', 'message'],
           properties: {
             code: {
               type: 'integer',
+              description:
+                'The error code. 1000-1018 are general game errors, 1100-1101 concern un-founded empires, and 1200 is game over. See ErrorCodes in the original documentation.',
               enum: [
                 1000, // Name not available.
                 1001, // Invalid password.
@@ -595,8 +779,12 @@ export const components = {
                 1200, // Game Over.
               ],
             },
-            message: { type: 'string' },
-            data: { type: 'object' },
+            message: { type: 'string', description: 'A human-readable description of the error.' },
+            data: {
+              type: 'object',
+              description:
+                'Extra context for the error, when available — e.g. a fresh captcha for 1014, or an empire id for 1100.',
+            },
           },
         },
       },
@@ -604,30 +792,41 @@ export const components = {
 
     server_status: {
       type: 'object',
+      description:
+        'Server-wide state, returned in the `server` part of the status block of every response.',
       properties: {
-        version: { type: 'number' },
-        time: { type: 'string' },
+        version: { type: 'number', description: 'The running server version.' },
+        time: {
+          type: 'string',
+          description: 'The current server time, e.g. "01 31 2010 13:09:05 +0600".',
+        },
         star_map_size: {
           type: 'object',
+          description: 'The inclusive [min, max] bounds of the star map on each axis.',
           properties: {
             y: { type: 'array', items: { type: 'integer' } },
             x: { type: 'array', items: { type: 'integer' } },
           },
           required: ['y', 'x'],
         },
-        rpc_limit: { type: 'integer' },
-        // 1 when a server announcement is active. Clients pop the announcement window on the
-        // 0 -> 1 transition.
-        announcement: { type: 'integer', enum: [1, 0] },
+        rpc_limit: {
+          type: 'integer',
+          description: 'The number of RPC calls allowed per 24 hour period.',
+        },
+        announcement: {
+          type: 'integer',
+          enum: [1, 0],
+          description:
+            '1 when a server announcement is active. Clients pop the announcement window on the 0 -> 1 transition.',
+        },
       },
       required: ['version', 'time', 'star_map_size', 'rpc_limit'],
     },
 
-    // The "General" tab of the in-game stats window is fed by a static `server_overview.json`
-    // snapshot on the server (not a JSON-RPC method), so it has no path in this spec. This
-    // schema documents that snapshot's shape.
     server_overview: {
       type: 'object',
+      description:
+        'The "General" tab of the in-game stats window is fed by a static `server_overview.json` snapshot on the server (not a JSON-RPC method), so it has no path in this spec. This schema documents that snapshot\'s shape.',
       properties: {
         bodies: {
           type: 'object',
diff --git a/src/spec/paths/alliance.ts b/src/spec/paths/alliance.ts
index 0b92aeb..555872f 100644
--- a/src/spec/paths/alliance.ts
+++ b/src/spec/paths/alliance.ts
@@ -1,4 +1,5 @@
 import {
+  operation,
   requestBodySchema,
   response200,
   response500,
@@ -15,11 +16,21 @@ export const alliance = {
     post: {
       ...tags('alliance'),
       ...security(),
+      ...operation(
+        "View an alliance's public profile.",
+        'Provides a list of the data that is publicly known about an alliance. Throws 1002.'
+      ),
 
       ...requestBodySchema({
         type: 'object',
         required: ['alliance_id'],
-        properties: { alliance_id: { type: 'integer' } },
+        properties: {
+          alliance_id: {
+            type: 'integer',
+            description:
+              "The id of the alliance for which you'd like to retrieve the public profile.",
+          },
+        },
       }),
 
       responses: {
@@ -81,11 +92,21 @@ export const alliance = {
     post: {
       ...tags('alliance'),
       ...security(),
+      ...operation(
+        'Find alliances by name.',
+        'Finds an alliance by name. Returns a hash reference containing alliance ids and alliance names.'
+      ),
 
       ...requestBodySchema({
         type: 'object',
         required: ['name'],
-        properties: { name: { type: 'string' } },
+        properties: {
+          name: {
+            type: 'string',
+            description:
+              "The name you're searching for. Case insensitive, and partial names work fine. Must be at least 3 characters.",
+          },
+        },
       }),
 
       responses: {
diff --git a/src/spec/paths/body.ts b/src/spec/paths/body.ts
index b1a48c1..41dcbba 100644
--- a/src/spec/paths/body.ts
+++ b/src/spec/paths/body.ts
@@ -1,4 +1,5 @@
 import {
+  operation,
   requestBodySchema,
   response200,
   response500,
@@ -12,11 +13,17 @@ export const body = {
     post: {
       ...tags('body'),
       ...security(),
+      ...operation(
+        'Get detailed status for a body.',
+        'Returns detailed statistics about a body owned or sat for by the current empire. You should probably never call this directly — the same data comes back in the status block of every relevant request.'
+      ),
 
       ...requestBodySchema({
         type: 'object',
         required: ['body_id'],
-        properties: { body_id: { type: 'integer' } },
+        properties: {
+          body_id: { type: 'integer', description: 'The id of the body you wish to retrieve.' },
+        },
       }),
 
       responses: {
@@ -41,11 +48,17 @@ export const body = {
     post: {
       ...tags('body'),
       ...security(),
+      ...operation(
+        'Get the public star-map status for a body.',
+        'Returns the public star-map view of any body. This endpoint is not part of the original API documentation.'
+      ),
 
       ...requestBodySchema({
         type: 'object',
         required: ['body_id'],
-        properties: { body_id: { type: 'integer' } },
+        properties: {
+          body_id: { type: 'integer', description: 'The id of the body you wish to retrieve.' },
+        },
       }),
 
       responses: {
@@ -66,11 +79,20 @@ export const body = {
     post: {
       ...tags('body'),
       ...security(),
+      ...operation(
+        'List the buildings on a body.',
+        'Retrieves the buildings on a body. The surface is an 11x11 tile grid running from -5 to 5 on both axes, with the Planetary Command Center always at 0,0; fill the remaining tiles with blank ground. Throws 1002 and 1010.'
+      ),
 
       ...requestBodySchema({
         type: 'object',
         required: ['body_id'],
-        properties: { body_id: { type: 'integer' } },
+        properties: {
+          body_id: {
+            type: 'integer',
+            description: 'The id of the body you wish to retrieve the buildings on.',
+          },
+        },
       }),
 
       responses: {
@@ -99,11 +121,20 @@ export const body = {
     post: {
       ...tags('body'),
       ...security(),
+      ...operation(
+        "List buildings on a body with each one's resource contribution.",
+        "Like get_buildings, but every building entry additionally carries a `resources` object describing that building's hourly production/consumption and storage capacity for each resource, plus per-food-type and per-ore-type breakdowns. Throws 1002 and 1010."
+      ),
 
       ...requestBodySchema({
         type: 'object',
         required: ['body_id'],
-        properties: { body_id: { type: 'integer' } },
+        properties: {
+          body_id: {
+            type: 'integer',
+            description: 'The id of the body you wish to retrieve the buildings on.',
+          },
+        },
       }),
 
       responses: {
@@ -133,12 +164,21 @@ export const body = {
       ...tags('body'),
       ...security(),
 
+      ...operation(
+        'Repair a list of buildings.',
+        'Repairs the given buildings, in the order their ids are supplied. Returns the same shape as get_buildings, but only for the repaired buildings.'
+      ),
+
       ...requestBodySchema({
         type: 'object',
         required: ['body_id', 'building_ids'],
         properties: {
-          body_id: { type: 'integer' },
-          building_ids: { type: 'array', items: { type: 'integer' } },
+          body_id: { type: 'integer', description: 'The id of the body the buildings are on.' },
+          building_ids: {
+            type: 'array',
+            items: { type: 'integer' },
+            description: 'The building ids to repair, in the order they should be repaired.',
+          },
         },
       }),
 
@@ -169,11 +209,19 @@ export const body = {
       ...tags('body'),
       ...security(),
 
+      ...operation(
+        'Move buildings to new coordinates.',
+        'Rearranges buildings to the coordinates supplied in the arrangement array. Throws 1002 and 1010.'
+      ),
+
       ...requestBodySchema({
         type: 'object',
         required: ['body_id', 'arrangement'],
         properties: {
-          body_id: { type: 'integer' },
+          body_id: {
+            type: 'integer',
+            description: 'The id of the body you wish to arrange buildings on.',
+          },
           arrangement: {
             type: 'array',
             description:
@@ -182,9 +230,19 @@ export const body = {
               type: 'object',
               required: ['id', 'x', 'y'],
               properties: {
-                id: { type: 'integer' },
-                x: { type: 'integer', minimum: -5, maximum: 5 },
-                y: { type: 'integer', minimum: -5, maximum: 5 },
+                id: { type: 'integer', description: 'The id of the building to move.' },
+                x: {
+                  type: 'integer',
+                  minimum: -5,
+                  maximum: 5,
+                  description: 'The new x coordinate for the building.',
+                },
+                y: {
+                  type: 'integer',
+                  minimum: -5,
+                  maximum: 5,
+                  description: 'The new y coordinate for the building.',
+                },
               },
             },
           },
@@ -227,16 +285,34 @@ export const body = {
       ...tags('body'),
       ...security(),
 
+      ...operation(
+        'List building types buildable on a tile.',
+        'Lists every building type that can be built on the given tile and matches the given tag. If several plans apply, returns the one with the highest extra_build_level. Throws 1002, 1010, 1011, 1012, and 1013.'
+      ),
+
       ...requestBodySchema({
         type: 'object',
         required: ['body_id', 'x', 'y', 'tag'],
         properties: {
-          body_id: { type: 'integer' },
-          x: { type: 'integer', minimum: -5, maximum: 5 },
-          y: { type: 'integer', minimum: -5, maximum: 5 },
+          body_id: { type: 'integer', description: 'The id of the body you wish to build on.' },
+          x: {
+            type: 'integer',
+            minimum: -5,
+            maximum: 5,
+            description:
+              'The x axis of the tile on the planet surface. Valid values are between -5 and 5 inclusive.',
+          },
+          y: {
+            type: 'integer',
+            minimum: -5,
+            maximum: 5,
+            description:
+              'The y axis of the tile on the planet surface. Valid values are between -5 and 5 inclusive.',
+          },
           tag: {
             type: 'string',
-            description: 'A tag to filter buildable types by. Cannot be Now, Soon, or Later.',
+            description:
+              'A tag that limits which building types are returned. Required. Cannot be Now, Soon, or Later; all other tags are allowed.',
           },
         },
       }),
@@ -309,11 +385,19 @@ export const body = {
       ...tags('body'),
       ...security(),
 
+      ...operation(
+        'List unoccupied buildable locations.',
+        'Tells you where buildings can be placed on the body. The order of the returned list is not guaranteed.'
+      ),
+
       ...requestBodySchema({
         type: 'object',
         required: ['body_id'],
         properties: {
-          body_id: { type: 'integer' },
+          body_id: {
+            type: 'integer',
+            description: 'The id of the body you wish to get the free locations of.',
+          },
           size: {
             type: 'integer',
             description:
@@ -347,10 +431,18 @@ export const body = {
       ...tags('body'),
       ...security(),
 
+      ...operation(
+        'Rename a body.',
+        'Renames a body owned by the empire attached to this session. Throws 1000, 1002, and 1010.'
+      ),
+
       ...requestBodySchema({
         type: 'object',
         required: ['body_id', 'name'],
-        properties: { body_id: { type: 'integer' }, name: { type: 'string' } },
+        properties: {
+          body_id: { type: 'integer', description: 'The id of the body you wish to rename.' },
+          name: { type: 'string', description: 'The new name for the body.' },
+        },
       }),
 
       responses: {
@@ -367,11 +459,21 @@ export const body = {
     post: {
       ...tags('body'),
       ...security(),
+      ...operation(
+        'Abandon a colony.',
+        'Abandons a colony, destroying everything on the planet. You cannot abandon your home planet.'
+      ),
 
       ...requestBodySchema({
         type: 'object',
         required: ['body_id'],
-        properties: { body_id: { type: 'integer' } },
+        properties: {
+          body_id: {
+            type: 'integer',
+            description:
+              'The unique id of the colony you wish to abandon. You cannot abandon your home planet.',
+          },
+        },
       }),
 
       responses: {
@@ -389,6 +491,11 @@ export const body = {
       ...tags('body'),
       ...security(),
 
+      ...operation(
+        'View the laws of a space station.',
+        'Returns the laws enacted by this space station. Pass the id of the station itself, not its Parliament building, since anyone may view the laws in a jurisdiction.'
+      ),
+
       ...requestBodySchema({
         type: 'object',
         required: ['body_id'],
@@ -431,15 +538,26 @@ export const body = {
       ...tags('body'),
       ...security(),
 
+      ...operation(
+        'Set the notes for a colony.',
+        'Sets the per-colony notes for an owned body (colony or station).'
+      ),
+
       ...requestBodySchema({
         type: 'object',
         required: ['body_id', 'options'],
         properties: {
-          body_id: { type: 'integer' },
+          body_id: {
+            type: 'integer',
+            description: 'The unique id of the body whose notes you want to update.',
+          },
           options: {
             type: 'object',
+            description: 'A hash of options. Currently the only valid key is `notes`.',
             required: ['notes'],
-            properties: { notes: { type: 'string' } },
+            properties: {
+              notes: { type: 'string', description: 'The notes to assign to the body.' },
+            },
           },
         },
       }),
diff --git a/src/spec/paths/buildings/archaeology.ts b/src/spec/paths/buildings/archaeology.ts
index efb2d66..45b933a 100644
--- a/src/spec/paths/buildings/archaeology.ts
+++ b/src/spec/paths/buildings/archaeology.ts
@@ -1,4 +1,5 @@
 import {
+  operation,
   buildingBase,
   buildingCommonMethods,
   buildingView,
@@ -38,7 +39,7 @@ const ORE_TYPES = [
 const buildingIdRequestBody = requestBodySchema({
   type: 'object',
   required: ['building_id'],
-  properties: { building_id: { type: 'integer' } },
+  properties: { building_id: { type: 'integer', description: 'The unique id of the building.' } },
 });
 
 export const archaeology = {
@@ -49,11 +50,15 @@ export const archaeology = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation(
+        'Search for glyph.',
+        'Searches ore for an ancient glyph. Returns the building view.'
+      ),
       ...requestBodySchema({
         type: 'object',
         required: ['building_id', 'ore_type'],
         properties: {
-          building_id: { type: 'integer' },
+          building_id: { type: 'integer', description: 'The unique id of the building.' },
           ore_type: {
             type: 'string',
             enum: ORE_TYPES,
@@ -79,6 +84,10 @@ export const archaeology = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation(
+        'Subsidize search.',
+        'Spends 2 essentia to complete the current glyph search immediately. Returns the building view.'
+      ),
       ...buildingIdRequestBody,
       responses: {
         ...response200(
@@ -101,6 +110,7 @@ export const archaeology = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation('Get glyph summary.', 'Returns the glyphs available for assembly.'),
       ...buildingIdRequestBody,
       responses: {
         ...response200('Returns the glyphs available for assembly.', {
@@ -132,11 +142,12 @@ export const archaeology = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation('Assemble glyphs.', 'Converts glyphs into a rare ancient item.'),
       ...requestBodySchema({
         type: 'object',
         required: ['building_id', 'glyphs'],
         properties: {
-          building_id: { type: 'integer' },
+          building_id: { type: 'integer', description: 'The unique id of the building.' },
           glyphs: {
             type: 'array',
             items: { type: 'string' },
@@ -162,6 +173,10 @@ export const archaeology = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation(
+        'Get ores available for processing.',
+        'Lists ore types with sufficient quantity in storage to search for a glyph.'
+      ),
       ...buildingIdRequestBody,
       responses: {
         ...response200(
@@ -188,6 +203,10 @@ export const archaeology = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation(
+        'View excavators.',
+        'Lists the active excavator sites controlled by this ministry.'
+      ),
       ...buildingIdRequestBody,
       responses: {
         ...response200('Lists the active excavator sites controlled by this ministry.', {
@@ -234,10 +253,14 @@ export const archaeology = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation('Abandon excavator.', 'Closes a single excavator site.'),
       ...requestBodySchema({
         type: 'object',
         required: ['building_id', 'site_id'],
-        properties: { building_id: { type: 'integer' }, site_id: { type: 'integer' } },
+        properties: {
+          building_id: { type: 'integer', description: 'The unique id of the building.' },
+          site_id: { type: 'integer', description: 'The unique id of the excavator site.' },
+        },
       }),
       responses: {
         ...response200('Closes a single excavator site.', {
@@ -254,6 +277,10 @@ export const archaeology = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation(
+        'Mass abandon excavator.',
+        'Destroys all excavators belonging to this ministry.'
+      ),
       ...buildingIdRequestBody,
       responses: {
         ...response200('Destroys all excavators belonging to this ministry.', {
diff --git a/src/spec/paths/buildings/blackholegenerator.ts b/src/spec/paths/buildings/blackholegenerator.ts
index a924172..0cf7745 100644
--- a/src/spec/paths/buildings/blackholegenerator.ts
+++ b/src/spec/paths/buildings/blackholegenerator.ts
@@ -2,6 +2,7 @@ import {
   buildingBase,
   buildingCommonMethods,
   buildingView,
+  operation,
   requestBodySchema,
   response200,
   response500,
@@ -56,7 +57,7 @@ const targetSchema = {
 const buildingIdRequestBody = requestBodySchema({
   type: 'object',
   required: ['building_id'],
-  properties: { building_id: { type: 'integer' } },
+  properties: { building_id: { type: 'integer', description: 'The unique id of the building.' } },
 });
 
 export const blackHoleGenerator = {
@@ -101,13 +102,17 @@ export const blackHoleGenerator = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation(
+        'Attempt a Black Hole Generator task.',
+        'Attempts a Black Hole Generator task against the target body, star, or zone. Returns the success, failure, and side-effect results; not every field is populated for every outcome. Failure rates increase with range, and side effects occur more often the harder the task. Throws 1002, 1009, 1010, and 1013.'
+      ),
       ...requestBodySchema({
         type: 'object',
         required: ['building_id', 'target', 'task_name'],
         properties: {
-          building_id: { type: 'integer' },
+          building_id: { type: 'integer', description: 'The unique id of the building.' },
           target: targetSchema,
-          task_name: { type: 'string', enum: TASK_NAMES },
+          task_name: { type: 'string', enum: TASK_NAMES, description: 'The task to perform.' },
           params: {
             type: 'object',
             description: "Only used for the 'Change Type' task.",
@@ -164,10 +169,17 @@ export const blackHoleGenerator = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation(
+        'Preview task odds and cost for a target.',
+        'Returns the task list with the success percentage and essentia cost for the given target. The essentia cost makes a task perfect (100% success); the lower the odds, the higher the cost, with a minimum of 2. A zero chance of success cannot be bought up.'
+      ),
       ...requestBodySchema({
         type: 'object',
         required: ['building_id', 'target'],
-        properties: { building_id: { type: 'integer' }, target: targetSchema },
+        properties: {
+          building_id: { type: 'integer', description: 'The unique id of the building.' },
+          target: targetSchema,
+        },
       }),
       responses: {
         ...response200(
@@ -229,6 +241,10 @@ export const blackHoleGenerator = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation(
+        'Subsidize the generator cooldown.',
+        'Spends 2 essentia to cool the generator down immediately, then returns the building view. Throws 1011.'
+      ),
       ...buildingIdRequestBody,
       responses: {
         ...response200(
diff --git a/src/spec/paths/buildings/capitol.ts b/src/spec/paths/buildings/capitol.ts
index 03f556a..fc68a9e 100644
--- a/src/spec/paths/buildings/capitol.ts
+++ b/src/spec/paths/buildings/capitol.ts
@@ -1,4 +1,5 @@
 import {
+  operation,
   buildingBase,
   buildingCommonMethods,
   buildingView,
@@ -14,16 +15,25 @@ const base = buildingBase('Capitol');
 
 export const capitol = {
   ...buildingCommonMethods(base),
-  ...buildingView(base, { rename_empire_cost: { type: 'integer' } }),
+  ...buildingView(base, {
+    rename_empire_cost: {
+      type: 'integer',
+      description: 'The essentia cost to rename the empire via rename_empire.',
+    },
+  }),
 
   [`${base}/rename_empire`]: {
     post: {
       ...tags(base),
       ...security(),
+      ...operation('Rename the empire.', 'Spends essentia to rename your empire.'),
       ...requestBodySchema({
         type: 'object',
         required: ['building_id', 'name'],
-        properties: { building_id: { type: 'integer' }, name: { type: 'string' } },
+        properties: {
+          building_id: { type: 'integer', description: 'The unique id of the building.' },
+          name: { type: 'string', description: 'The new name of your empire.' },
+        },
       }),
       responses: {
         ...response200(
diff --git a/src/spec/paths/buildings/development.ts b/src/spec/paths/buildings/development.ts
index 0041068..99bfd35 100644
--- a/src/spec/paths/buildings/development.ts
+++ b/src/spec/paths/buildings/development.ts
@@ -1,4 +1,5 @@
 import {
+  operation,
   buildingBase,
   buildingCommonMethods,
   buildingView,
@@ -15,7 +16,7 @@ const base = buildingBase('Development');
 const buildQueueItemSchema = {
   type: 'object',
   properties: {
-    building_id: { type: 'integer' },
+    building_id: { type: 'integer', description: 'The unique id of the building.' },
     name: { type: 'string' },
     to_level: { type: 'integer' },
     seconds_remaining: { type: 'integer' },
@@ -50,7 +51,7 @@ const developmentViewResultSchema = (description: string) => ({
 const buildingIdRequestBody = requestBodySchema({
   type: 'object',
   required: ['building_id'],
-  properties: { building_id: { type: 'integer' } },
+  properties: { building_id: { type: 'integer', description: 'The unique id of the building.' } },
 });
 
 export const development = {
@@ -71,6 +72,10 @@ export const development = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation(
+        'Subsidize build queue.',
+        'Instantly finishes all buildings in the build queue.'
+      ),
       ...buildingIdRequestBody,
       responses: {
         ...response200('Instantly finishes all buildings in the build queue.', {
@@ -87,11 +92,15 @@ export const development = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation(
+        'Subsidize one build.',
+        'Subsidizes the immediate build of one job on the build queue. Later jobs (if any) are brought forward by the (remaining) time of the subsidized build.'
+      ),
       ...requestBodySchema({
         type: 'object',
         required: ['building_id', 'scheduled_id'],
         properties: {
-          building_id: { type: 'integer' },
+          building_id: { type: 'integer', description: 'The unique id of the building.' },
           scheduled_id: {
             type: 'integer',
             description:
@@ -117,11 +126,15 @@ export const development = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation(
+        'Cancel build.',
+        'Cancels a build. All following builds in the build queue are brought forward. Resources or plans used when the build/upgrade was requested are not returned. Returns the same as the view method.'
+      ),
       ...requestBodySchema({
         type: 'object',
         required: ['building_id'],
         properties: {
-          building_id: { type: 'integer' },
+          building_id: { type: 'integer', description: 'The unique id of the building.' },
           scheduled_id: {
             oneOf: [{ type: 'integer' }, { type: 'array', items: { type: 'integer' } }],
             description:
diff --git a/src/spec/paths/buildings/distributioncenter.ts b/src/spec/paths/buildings/distributioncenter.ts
index 18edb1b..b2bdccb 100644
--- a/src/spec/paths/buildings/distributioncenter.ts
+++ b/src/spec/paths/buildings/distributioncenter.ts
@@ -1,4 +1,5 @@
 import {
+  operation,
   buildingBase,
   buildingCommonMethods,
   buildingView,
@@ -44,7 +45,7 @@ const reserveSchema = {
 const buildingIdRequestBody = requestBodySchema({
   type: 'object',
   required: ['building_id'],
-  properties: { building_id: { type: 'integer' } },
+  properties: { building_id: { type: 'integer', description: 'The unique id of the building.' } },
 });
 
 export const distributionCenter = {
@@ -55,17 +56,24 @@ export const distributionCenter = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation(
+        'Reserve resources.',
+        'Reserves resources so they are held until the timer expires or manually released. Returns the building view. Throws 1009, 1010, and 1011.'
+      ),
       ...requestBodySchema({
         type: 'object',
         required: ['building_id', 'resources'],
         properties: {
-          building_id: { type: 'integer' },
+          building_id: { type: 'integer', description: 'The unique id of the building.' },
           resources: {
             type: 'array',
             description: "Resources to reserve so they don't get automatically spent.",
             items: {
               type: 'object',
-              properties: { type: { type: 'string' }, quantity: { type: 'integer' } },
+              properties: {
+                type: { type: 'string' },
+                quantity: { type: 'integer', description: 'How many to process. Defaults to 1.' },
+              },
               required: ['type', 'quantity'],
             },
           },
@@ -93,6 +101,7 @@ export const distributionCenter = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation('Release reserve.', 'Returns the resources held in reserve back to the planet.'),
       ...buildingIdRequestBody,
       responses: {
         ...response200('Returns the resources held in reserve back to the planet.', {
@@ -109,6 +118,10 @@ export const distributionCenter = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation(
+        'Get stored resources.',
+        'Returns a list of the resources you have stored, to make it easier to identify what you want to store.'
+      ),
       ...buildingIdRequestBody,
       responses: {
         ...response200(
diff --git a/src/spec/paths/buildings/embassy.ts b/src/spec/paths/buildings/embassy.ts
index 6d85122..8898aa2 100644
--- a/src/spec/paths/buildings/embassy.ts
+++ b/src/spec/paths/buildings/embassy.ts
@@ -1,4 +1,5 @@
 import {
+  operation,
   buildingBase,
   buildingCommonMethods,
   buildingView,
@@ -15,7 +16,7 @@ const base = buildingBase('Embassy');
 const buildingIdRequestBody = requestBodySchema({
   type: 'object',
   required: ['building_id'],
-  properties: { building_id: { type: 'integer' } },
+  properties: { building_id: { type: 'integer', description: 'The unique id of the building.' } },
 });
 
 const optionalMessageRequestBody = (extraRequired: string[] = [], extraProperties: object = {}) =>
@@ -23,8 +24,11 @@ const optionalMessageRequestBody = (extraRequired: string[] = [], extraPropertie
     type: 'object',
     required: ['building_id', ...extraRequired],
     properties: {
-      building_id: { type: 'integer' },
-      message: { type: 'string' },
+      building_id: { type: 'integer', description: 'The unique id of the building.' },
+      message: {
+        type: 'string',
+        description: 'An optional personalised message included with the action.',
+      },
       ...extraProperties,
     },
   });
@@ -64,12 +68,19 @@ export const embassy = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation('Create alliance.', 'Creates a new alliance with this empire as leader.'),
       ...requestBodySchema({
         type: 'object',
         required: ['building_id', 'name'],
         properties: {
-          building_id: { type: 'integer' },
-          name: { type: 'string', minLength: 3, maxLength: 30 },
+          building_id: { type: 'integer', description: 'The unique id of the building.' },
+          name: {
+            type: 'string',
+            minLength: 3,
+            maxLength: 30,
+            description:
+              'A unique alliance name, 3-30 characters, no profanity or restricted characters.',
+          },
         },
       }),
       responses: {
@@ -87,6 +98,7 @@ export const embassy = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation('Get alliance status.', "Returns this empire's alliance data."),
       ...buildingIdRequestBody,
       responses: {
         ...response200("Returns this empire's alliance data.", {
@@ -103,6 +115,10 @@ export const embassy = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation(
+        'Dissolve alliance.',
+        'Leader-only. Disbands the alliance and converts its space stations to asteroids.'
+      ),
       ...buildingIdRequestBody,
       responses: {
         ...response200(
@@ -118,13 +134,16 @@ export const embassy = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation('Update alliance.', 'Leader-only. Updates alliance metadata.'),
       ...requestBodySchema({
         type: 'object',
         required: ['building_id', 'params'],
         properties: {
-          building_id: { type: 'integer' },
+          building_id: { type: 'integer', description: 'The unique id of the building.' },
           params: {
             type: 'object',
+            description:
+              'The alliance properties to update. Any or all of forum_uri, description, announcements.',
             properties: {
               forum_uri: { type: 'string' },
               description: { type: 'string' },
@@ -148,7 +167,10 @@ export const embassy = {
     post: {
       ...tags(base),
       ...security(),
-      ...optionalMessageRequestBody(['invitee_id'], { invitee_id: { type: 'integer' } }),
+      ...operation('Send invite.', 'Leader-only. Invites an empire to join the alliance.'),
+      ...optionalMessageRequestBody(['invitee_id'], {
+        invitee_id: { type: 'integer', description: 'The unique id of the empire to invite.' },
+      }),
       responses: {
         ...response200('Leader-only. Invites an empire to join the alliance.', {
           type: 'object',
@@ -164,7 +186,10 @@ export const embassy = {
     post: {
       ...tags(base),
       ...security(),
-      ...optionalMessageRequestBody(['invite_id'], { invite_id: { type: 'integer' } }),
+      ...operation('Withdraw invite.', 'Leader-only. Withdraws a pending invite.'),
+      ...optionalMessageRequestBody(['invite_id'], {
+        invite_id: { type: 'integer', description: 'The unique id of the invitation.' },
+      }),
       responses: {
         ...response200('Leader-only. Withdraws a pending invite.', {
           type: 'object',
@@ -180,6 +205,10 @@ export const embassy = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation(
+        'Get pending invites.',
+        'Leader-only. Lists outstanding invites sent by the alliance.'
+      ),
       ...buildingIdRequestBody,
       responses: {
         ...response200('Leader-only. Lists outstanding invites sent by the alliance.', {
@@ -209,7 +238,10 @@ export const embassy = {
     post: {
       ...tags(base),
       ...security(),
-      ...optionalMessageRequestBody(['invite_id'], { invite_id: { type: 'integer' } }),
+      ...operation('Accept invite.', 'Accepts an invite to join an alliance.'),
+      ...optionalMessageRequestBody(['invite_id'], {
+        invite_id: { type: 'integer', description: 'The unique id of the invitation.' },
+      }),
       responses: {
         ...response200('Accepts an invite to join an alliance.', {
           type: 'object',
@@ -225,7 +257,10 @@ export const embassy = {
     post: {
       ...tags(base),
       ...security(),
-      ...optionalMessageRequestBody(['invite_id'], { invite_id: { type: 'integer' } }),
+      ...operation('Reject invite.', 'Declines an invite to join an alliance.'),
+      ...optionalMessageRequestBody(['invite_id'], {
+        invite_id: { type: 'integer', description: 'The unique id of the invitation.' },
+      }),
       responses: {
         ...response200('Declines an invite to join an alliance.', {
           type: 'object',
@@ -241,6 +276,7 @@ export const embassy = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation('Get my invites.', 'Lists invites this empire has received.'),
       ...buildingIdRequestBody,
       responses: {
         ...response200('Lists invites this empire has received.', {
@@ -270,6 +306,7 @@ export const embassy = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation('Leave alliance.', 'Leaves the current alliance.'),
       ...optionalMessageRequestBody(),
       responses: {
         ...response200('Leaves the current alliance.', {
@@ -286,7 +323,10 @@ export const embassy = {
     post: {
       ...tags(base),
       ...security(),
-      ...optionalMessageRequestBody(['empire_id'], { empire_id: { type: 'integer' } }),
+      ...operation('Expel member.', 'Leader-only. Removes a member from the alliance.'),
+      ...optionalMessageRequestBody(['empire_id'], {
+        empire_id: { type: 'integer', description: 'The unique id of the member to remove.' },
+      }),
       responses: {
         ...response200('Leader-only. Removes a member from the alliance.', {
           type: 'object',
@@ -302,10 +342,21 @@ export const embassy = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation(
+        'Assign alliance leader.',
+        'Leader-only. Transfers alliance leadership to another current member.'
+      ),
       ...requestBodySchema({
         type: 'object',
         required: ['building_id', 'new_leader_id'],
-        properties: { building_id: { type: 'integer' }, new_leader_id: { type: 'integer' } },
+        properties: {
+          building_id: { type: 'integer', description: 'The unique id of the building.' },
+          new_leader_id: {
+            type: 'integer',
+            description:
+              'The unique id of the empire to make leader. Must already be a member of the alliance.',
+          },
+        },
       }),
       responses: {
         ...response200('Leader-only. Transfers alliance leadership to another current member.', {
@@ -322,6 +373,7 @@ export const embassy = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation('View stash.', "Returns the alliance stash's contents."),
       ...buildingIdRequestBody,
       responses: {
         ...response200("Returns the alliance stash's contents.", {
@@ -352,11 +404,12 @@ export const embassy = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation('Donate to stash.', 'Donates resources to the alliance stash.'),
       ...requestBodySchema({
         type: 'object',
         required: ['building_id', 'donation'],
         properties: {
-          building_id: { type: 'integer' },
+          building_id: { type: 'integer', description: 'The unique id of the building.' },
           donation: {
             type: 'object',
             description:
@@ -380,17 +433,23 @@ export const embassy = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation('Exchange with stash.', 'Exchanges resources with the alliance stash.'),
       ...requestBodySchema({
         type: 'object',
         required: ['building_id', 'donation', 'request'],
         properties: {
-          building_id: { type: 'integer' },
+          building_id: { type: 'integer', description: 'The unique id of the building.' },
           donation: {
             type: 'object',
             description: 'Must equal request in total value. Waste is not allowed.',
             additionalProperties: { type: 'integer' },
           },
-          request: { type: 'object', additionalProperties: { type: 'integer' } },
+          request: {
+            type: 'object',
+            description:
+              'Resource name to quantity to pull from the stash. Total value must equal the donation total.',
+            additionalProperties: { type: 'integer' },
+          },
         },
       }),
       responses: {
@@ -408,6 +467,7 @@ export const embassy = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation('View propositions.', 'Lists pending propositions the alliance is voting on.'),
       ...buildingIdRequestBody,
       responses: {
         ...response200('Lists pending propositions the alliance is voting on.', {
@@ -451,13 +511,21 @@ export const embassy = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation('Cast vote.', 'Casts a vote on a proposition. Throws 1018 if already voted.'),
       ...requestBodySchema({
         type: 'object',
         required: ['building_id', 'proposition_id', 'vote'],
         properties: {
-          building_id: { type: 'integer' },
-          proposition_id: { type: 'integer' },
-          vote: { type: 'integer', enum: [1, 0] },
+          building_id: { type: 'integer', description: 'The unique id of the building.' },
+          proposition_id: {
+            type: 'integer',
+            description: 'The id of the proposition being voted on. See view_propositions.',
+          },
+          vote: {
+            type: 'integer',
+            enum: [1, 0],
+            description: '1 for yes, 0 for no. Defaults to 0.',
+          },
         },
       }),
       responses: {
diff --git a/src/spec/paths/buildings/energyreserve.ts b/src/spec/paths/buildings/energyreserve.ts
index ad7a057..4a889e2 100644
--- a/src/spec/paths/buildings/energyreserve.ts
+++ b/src/spec/paths/buildings/energyreserve.ts
@@ -1,4 +1,5 @@
 import {
+  operation,
   buildingBase,
   buildingCommonMethods,
   buildingView,
@@ -20,11 +21,12 @@ export const energyReserve = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation('Dump energy as waste.', 'Converts energy into waste.'),
       ...requestBodySchema({
         type: 'object',
         required: ['building_id', 'amount'],
         properties: {
-          building_id: { type: 'integer' },
+          building_id: { type: 'integer', description: 'The unique id of the building.' },
           amount: { type: 'integer', description: 'The amount of energy to dump.' },
         },
       }),
diff --git a/src/spec/paths/buildings/entertainment.ts b/src/spec/paths/buildings/entertainment.ts
index 0f1fae6..7af5e89 100644
--- a/src/spec/paths/buildings/entertainment.ts
+++ b/src/spec/paths/buildings/entertainment.ts
@@ -1,4 +1,5 @@
 import {
+  operation,
   buildingBase,
   buildingCommonMethods,
   buildingView,
@@ -15,7 +16,7 @@ const base = buildingBase('Entertainment');
 const buildingIdRequestBody = requestBodySchema({
   type: 'object',
   required: ['building_id'],
-  properties: { building_id: { type: 'integer' } },
+  properties: { building_id: { type: 'integer', description: 'The unique id of the building.' } },
 });
 
 export const entertainment = {
@@ -26,6 +27,10 @@ export const entertainment = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation(
+        'Get lottery voting options.',
+        'Returns a list of sites the user can vote on. Voting once per site per day enters the empire into a daily lottery for 10 essentia; each vote is equal, but more votes increase the odds of winning. Each url is usable only once every 24 hours.'
+      ),
       ...buildingIdRequestBody,
       responses: {
         ...response200(
@@ -55,6 +60,10 @@ export const entertainment = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation(
+        'Duck quack.',
+        'Returns a fun string of quack text. Formatting (whitespace and carriage returns) must be preserved when displayed to the user.'
+      ),
       ...buildingIdRequestBody,
       responses: {
         ...response200(
diff --git a/src/spec/paths/buildings/essentiavein.ts b/src/spec/paths/buildings/essentiavein.ts
index 243f1ec..fa7d88b 100644
--- a/src/spec/paths/buildings/essentiavein.ts
+++ b/src/spec/paths/buildings/essentiavein.ts
@@ -1,4 +1,5 @@
 import {
+  operation,
   buildingBase,
   buildingCommonMethods,
   buildingView,
@@ -25,11 +26,15 @@ export const essentiaVein = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation(
+        'Drain essentia from the vein.',
+        'Instantly drains one or more 30-day periods of essentia from the vein.'
+      ),
       ...requestBodySchema({
         type: 'object',
         required: ['building_id'],
         properties: {
-          building_id: { type: 'integer' },
+          building_id: { type: 'integer', description: 'The unique id of the building.' },
           times: {
             type: 'integer',
             minimum: 1,
diff --git a/src/spec/paths/buildings/foodreserve.ts b/src/spec/paths/buildings/foodreserve.ts
index ad6e43f..44d1082 100644
--- a/src/spec/paths/buildings/foodreserve.ts
+++ b/src/spec/paths/buildings/foodreserve.ts
@@ -1,4 +1,5 @@
 import {
+  operation,
   buildingBase,
   buildingCommonMethods,
   buildingView,
@@ -26,16 +27,17 @@ export const foodReserve = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation('Dump food as waste.', 'Converts food into waste.'),
       ...requestBodySchema({
         type: 'object',
         required: ['building_id', 'type', 'amount'],
         properties: {
-          building_id: { type: 'integer' },
+          building_id: { type: 'integer', description: 'The unique id of the building.' },
           type: {
             type: 'string',
             description: 'Food type to convert into waste, e.g. apple, corn, burger.',
           },
-          amount: { type: 'integer' },
+          amount: { type: 'integer', description: 'The amount to convert into waste.' },
         },
       }),
       responses: {
diff --git a/src/spec/paths/buildings/geneticslab.ts b/src/spec/paths/buildings/geneticslab.ts
index 395c726..5cbe87e 100644
--- a/src/spec/paths/buildings/geneticslab.ts
+++ b/src/spec/paths/buildings/geneticslab.ts
@@ -1,4 +1,5 @@
 import {
+  operation,
   buildingBase,
   buildingCommonMethods,
   buildingView,
@@ -16,7 +17,7 @@ const base = buildingBase('GeneticsLab');
 const buildingIdRequestBody = requestBodySchema({
   type: 'object',
   required: ['building_id'],
-  properties: { building_id: { type: 'integer' } },
+  properties: { building_id: { type: 'integer', description: 'The unique id of the building.' } },
 });
 
 const experimentResultSchema = (
@@ -80,6 +81,10 @@ export const geneticsLab = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation(
+        'Prepare experiment.',
+        'Returns everything needed to set up a genetic graft experiment.'
+      ),
       ...buildingIdRequestBody,
       responses: experimentResultSchema(
         'Returns everything needed to set up a genetic graft experiment.'
@@ -91,12 +96,16 @@ export const geneticsLab = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation(
+        'Run experiment.',
+        'Experiments on a prisoner, attempting to graft one of their genetic traits onto the empire species. Returns the same shape as prepare_experiment plus an experiment result.'
+      ),
       ...requestBodySchema({
         type: 'object',
         required: ['building_id', 'spy_id', 'affinity'],
         properties: {
-          building_id: { type: 'integer' },
-          spy_id: { type: 'integer' },
+          building_id: { type: 'integer', description: 'The unique id of the building.' },
+          spy_id: { type: 'integer', description: 'The unique id of the spy.' },
           affinity: {
             type: 'string',
             description:
@@ -130,13 +139,18 @@ export const geneticsLab = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation(
+        'Rename species.',
+        "Updates the empire's species name and description. Can throw error codes 1000 (name not available) and 1005 (contains invalid characters), with the offending field in the error's data."
+      ),
       ...requestBodySchema({
         type: 'object',
         required: ['building_id', 'params'],
         properties: {
-          building_id: { type: 'integer' },
+          building_id: { type: 'integer', description: 'The unique id of the building.' },
           params: {
             type: 'object',
+            description: 'The species name and description to set.',
             required: ['name'],
             properties: {
               name: {
diff --git a/src/spec/paths/buildings/intelligence.ts b/src/spec/paths/buildings/intelligence.ts
index 3efa136..477986f 100644
--- a/src/spec/paths/buildings/intelligence.ts
+++ b/src/spec/paths/buildings/intelligence.ts
@@ -1,4 +1,5 @@
 import {
+  operation,
   buildingBase,
   buildingCommonMethods,
   buildingView,
@@ -15,7 +16,7 @@ const base = buildingBase('Intelligence');
 const buildingIdRequestBody = requestBodySchema({
   type: 'object',
   required: ['building_id'],
-  properties: { building_id: { type: 'integer' } },
+  properties: { building_id: { type: 'integer', description: 'The unique id of the building.' } },
 });
 
 const ASSIGNMENTS = [
@@ -129,11 +130,12 @@ export const intelligence = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation('Train spy.', 'Queues spies for training. Throws 1013, 1009.'),
       ...requestBodySchema({
         type: 'object',
         required: ['building_id'],
         properties: {
-          building_id: { type: 'integer' },
+          building_id: { type: 'integer', description: 'The unique id of the building.' },
           quantity: { type: 'integer', minimum: 1, maximum: 5, description: 'Defaults to 1.' },
         },
       }),
@@ -160,11 +162,12 @@ export const intelligence = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation('View spies.', 'Retrieves a paginated spy roster.'),
       ...requestBodySchema({
         type: 'object',
         required: ['building_id'],
         properties: {
-          building_id: { type: 'integer' },
+          building_id: { type: 'integer', description: 'The unique id of the building.' },
           page_number: { type: 'integer', description: 'Defaults to 1. 30 per page.' },
         },
       }),
@@ -187,6 +190,7 @@ export const intelligence = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation('View all spies.', 'Retrieves the complete (non-paginated) spy roster.'),
       ...buildingIdRequestBody,
       responses: {
         ...response200('Retrieves the complete (non-paginated) spy roster.', {
@@ -207,6 +211,10 @@ export const intelligence = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation(
+        'Subsidize training.',
+        'Completes all in-training spies immediately for 1 essentia per spy. Returns the building view. Throws 1011.'
+      ),
       ...buildingIdRequestBody,
       responses: {
         ...response200(
@@ -229,10 +237,14 @@ export const intelligence = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation('Burn spy.', 'Eliminates a spy from payroll. Throws 1002, 1010.'),
       ...requestBodySchema({
         type: 'object',
         required: ['building_id', 'spy_id'],
-        properties: { building_id: { type: 'integer' }, spy_id: { type: 'integer' } },
+        properties: {
+          building_id: { type: 'integer', description: 'The unique id of the building.' },
+          spy_id: { type: 'integer', description: 'The unique id of the spy.' },
+        },
       }),
       responses: {
         ...response200('Eliminates a spy from payroll. Throws 1002, 1010.', {
@@ -249,12 +261,13 @@ export const intelligence = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation('Name spy.', "Sets a spy's name. Throws 1002, 1005, 1013."),
       ...requestBodySchema({
         type: 'object',
         required: ['building_id', 'spy_id', 'name'],
         properties: {
-          building_id: { type: 'integer' },
-          spy_id: { type: 'integer' },
+          building_id: { type: 'integer', description: 'The unique id of the building.' },
+          spy_id: { type: 'integer', description: 'The unique id of the spy.' },
           name: { type: 'string', description: 'Cannot contain @, <, #, &, ; or profanity.' },
         },
       }),
@@ -273,13 +286,17 @@ export const intelligence = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation('Name spies.', 'Batch-names spies using the pattern "prefix ## suffix".'),
       ...requestBodySchema({
         type: 'object',
         required: ['building_id'],
         properties: {
-          building_id: { type: 'integer' },
-          prefix: { type: 'string' },
-          suffix: { type: 'string' },
+          building_id: { type: 'integer', description: 'The unique id of the building.' },
+          prefix: {
+            type: 'string',
+            description: 'Optional name prefix. New names look like "prefix ## suffix".',
+          },
+          suffix: { type: 'string', description: 'Optional name suffix.' },
           rename_null_only: {
             type: 'boolean',
             description: 'When true, only renames spies still named "Agent Null".',
@@ -306,12 +323,13 @@ export const intelligence = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation('Assign spy.', 'Assigns a spy to a new task.'),
       ...requestBodySchema({
         type: 'object',
         required: ['building_id', 'spy_id', 'assignment'],
         properties: {
-          building_id: { type: 'integer' },
-          spy_id: { type: 'integer' },
+          building_id: { type: 'integer', description: 'The unique id of the building.' },
+          spy_id: { type: 'integer', description: 'The unique id of the spy.' },
           assignment: {
             oneOf: [
               { type: 'string', enum: ASSIGNMENTS },
diff --git a/src/spec/paths/buildings/inteltraining.ts b/src/spec/paths/buildings/inteltraining.ts
index 4125dde..b610ff6 100644
--- a/src/spec/paths/buildings/inteltraining.ts
+++ b/src/spec/paths/buildings/inteltraining.ts
@@ -9,9 +9,12 @@ export const intelTraining = {
       type: 'object',
       description: 'Summary of spy training capacity for this facility.',
       properties: {
-        max_points: { type: 'integer' },
-        points_per: { type: 'integer' },
-        in_training: { type: 'integer' },
+        max_points: { type: 'integer', description: 'The maximum training points a spy can hold.' },
+        points_per: { type: 'integer', description: 'Training points added per training cycle.' },
+        in_training: {
+          type: 'integer',
+          description: 'The number of spies currently training here.',
+        },
       },
       required: ['max_points', 'points_per', 'in_training'],
     },
diff --git a/src/spec/paths/buildings/libraryofjith.ts b/src/spec/paths/buildings/libraryofjith.ts
index 879df00..a3d5455 100644
--- a/src/spec/paths/buildings/libraryofjith.ts
+++ b/src/spec/paths/buildings/libraryofjith.ts
@@ -1,4 +1,5 @@
 import {
+  operation,
   buildingBase,
   buildingCommonMethods,
   buildingView,
@@ -21,11 +22,12 @@ export const libraryOfJith = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation('Research species.', 'Returns species stats for any species in the game.'),
       ...requestBodySchema({
         type: 'object',
         required: ['building_id', 'empire_id'],
         properties: {
-          building_id: { type: 'integer' },
+          building_id: { type: 'integer', description: 'The unique id of the building.' },
           empire_id: {
             type: 'integer',
             description: "The unique id of an empire you'd like to know more about.",
diff --git a/src/spec/paths/buildings/mayhemtraining.ts b/src/spec/paths/buildings/mayhemtraining.ts
index f36bc5a..724ed95 100644
--- a/src/spec/paths/buildings/mayhemtraining.ts
+++ b/src/spec/paths/buildings/mayhemtraining.ts
@@ -7,10 +7,14 @@ export const mayhemTraining = {
   ...buildingView(base, {
     spies: {
       type: 'object',
+      description: 'Summary of spy training capacity for this facility.',
       properties: {
-        max_points: { type: 'integer' },
-        points_per: { type: 'integer' },
-        in_training: { type: 'integer' },
+        max_points: { type: 'integer', description: 'The maximum training points a spy can hold.' },
+        points_per: { type: 'integer', description: 'Training points added per training cycle.' },
+        in_training: {
+          type: 'integer',
+          description: 'The number of spies currently training here.',
+        },
       },
       required: ['max_points', 'points_per', 'in_training'],
     },
diff --git a/src/spec/paths/buildings/mercenariesguild.ts b/src/spec/paths/buildings/mercenariesguild.ts
index 3181fb0..01e5ab5 100644
--- a/src/spec/paths/buildings/mercenariesguild.ts
+++ b/src/spec/paths/buildings/mercenariesguild.ts
@@ -1,4 +1,5 @@
 import {
+  operation,
   buildingBase,
   buildingCommonMethods,
   buildingView,
@@ -15,7 +16,7 @@ const base = buildingBase('MercenariesGuild');
 const buildingIdRequestBody = requestBodySchema({
   type: 'object',
   required: ['building_id'],
-  properties: { building_id: { type: 'integer' } },
+  properties: { building_id: { type: 'integer', description: 'The unique id of the building.' } },
 });
 
 const tradeEntrySchema = {
@@ -50,11 +51,12 @@ export const mercenariesGuild = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation('Add to market.', 'Queues a trade of a spy for others to see.'),
       ...requestBodySchema({
         type: 'object',
         required: ['building_id', 'spy_id', 'ask'],
         properties: {
-          building_id: { type: 'integer' },
+          building_id: { type: 'integer', description: 'The unique id of the building.' },
           spy_id: { type: 'integer', description: 'See get_spies for a list of your spies.' },
           ask: {
             type: 'integer',
@@ -80,6 +82,10 @@ export const mercenariesGuild = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation(
+        'Get spies.',
+        'Returns a list of spies that may be traded. Used with add_to_market.'
+      ),
       ...buildingIdRequestBody,
       responses: {
         ...response200('Returns a list of spies that may be traded. Used with add_to_market.', {
@@ -110,10 +116,17 @@ export const mercenariesGuild = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation(
+        'Withdraw from market.',
+        'Removes a trade that you have offered and collects the items up for trade.'
+      ),
       ...requestBodySchema({
         type: 'object',
         required: ['building_id', 'trade_id'],
-        properties: { building_id: { type: 'integer' }, trade_id: { type: 'integer' } },
+        properties: {
+          building_id: { type: 'integer', description: 'The unique id of the building.' },
+          trade_id: { type: 'integer', description: 'The unique id of the trade.' },
+        },
       }),
       responses: {
         ...response200(
@@ -129,10 +142,17 @@ export const mercenariesGuild = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation(
+        'Accept from market.',
+        'Accepts a trade offer from the list of available trades. See view_market.'
+      ),
       ...requestBodySchema({
         type: 'object',
         required: ['building_id', 'trade_id'],
-        properties: { building_id: { type: 'integer' }, trade_id: { type: 'integer' } },
+        properties: {
+          building_id: { type: 'integer', description: 'The unique id of the building.' },
+          trade_id: { type: 'integer', description: 'The unique id of the trade.' },
+        },
       }),
       responses: {
         ...response200(
@@ -148,11 +168,12 @@ export const mercenariesGuild = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation('View market.', 'Displays a list of trades available at the present time.'),
       ...requestBodySchema({
         type: 'object',
         required: ['building_id'],
         properties: {
-          building_id: { type: 'integer' },
+          building_id: { type: 'integer', description: 'The unique id of the building.' },
           page_number: {
             type: 'integer',
             description: 'Optional. Defaults to 1. 25 trades per page.',
@@ -179,11 +200,12 @@ export const mercenariesGuild = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation('View my market.', 'Displays a list of trades the current user has posted.'),
       ...requestBodySchema({
         type: 'object',
         required: ['building_id'],
         properties: {
-          building_id: { type: 'integer' },
+          building_id: { type: 'integer', description: 'The unique id of the building.' },
           page_number: {
             type: 'integer',
             description: 'Optional. Defaults to 1. 25 trades per page.',
@@ -210,11 +232,15 @@ export const mercenariesGuild = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation(
+        'Get trade ships.',
+        'Returns a list of the ships that could be used to do a trade.'
+      ),
       ...requestBodySchema({
         type: 'object',
         required: ['building_id'],
         properties: {
-          building_id: { type: 'integer' },
+          building_id: { type: 'integer', description: 'The unique id of the building.' },
           target_body_id: {
             type: 'integer',
             description:
@@ -256,10 +282,17 @@ export const mercenariesGuild = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation(
+        'Report abuse.',
+        'Reports a trade that is suspected of abusing the trade system.'
+      ),
       ...requestBodySchema({
         type: 'object',
         required: ['building_id', 'trade_id'],
-        properties: { building_id: { type: 'integer' }, trade_id: { type: 'integer' } },
+        properties: {
+          building_id: { type: 'integer', description: 'The unique id of the building.' },
+          trade_id: { type: 'integer', description: 'The unique id of the trade.' },
+        },
       }),
       responses: {
         ...response200('Reports a trade that is suspected of abusing the trade system.', {
diff --git a/src/spec/paths/buildings/miningministry.ts b/src/spec/paths/buildings/miningministry.ts
index 15e2117..4e6f2a7 100644
--- a/src/spec/paths/buildings/miningministry.ts
+++ b/src/spec/paths/buildings/miningministry.ts
@@ -1,4 +1,5 @@
 import {
+  operation,
   buildingBase,
   buildingCommonMethods,
   buildingView,
@@ -42,7 +43,7 @@ const oreHourProperties = Object.fromEntries(
 const buildingIdRequestBody = requestBodySchema({
   type: 'object',
   required: ['building_id'],
-  properties: { building_id: { type: 'integer' } },
+  properties: { building_id: { type: 'integer', description: 'The unique id of the building.' } },
 });
 
 export const miningMinistry = {
@@ -53,6 +54,10 @@ export const miningMinistry = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation(
+        'View platforms.',
+        'Returns a list of the mining platforms currently controlled by this ministry.'
+      ),
       ...buildingIdRequestBody,
       responses: {
         ...response200(
@@ -102,6 +107,10 @@ export const miningMinistry = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation(
+        'View ships.',
+        'Shows the ships that are working in the mining fleet, and available to work in it.'
+      ),
       ...buildingIdRequestBody,
       responses: {
         ...response200(
@@ -137,10 +146,17 @@ export const miningMinistry = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation(
+        'Add cargo ship to fleet.',
+        'Takes a cargo ship from the space port and adds it to the mining fleet.'
+      ),
       ...requestBodySchema({
         type: 'object',
         required: ['building_id', 'ship_id'],
-        properties: { building_id: { type: 'integer' }, ship_id: { type: 'integer' } },
+        properties: {
+          building_id: { type: 'integer', description: 'The unique id of the building.' },
+          ship_id: { type: 'integer', description: 'The unique id of the ship.' },
+        },
       }),
       responses: {
         ...response200('Takes a cargo ship from the space port and adds it to the mining fleet.', {
@@ -157,10 +173,17 @@ export const miningMinistry = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation(
+        'Remove cargo ship from fleet.',
+        'Tells one of the cargo ships in the mining fleet to come home and park at the space port.'
+      ),
       ...requestBodySchema({
         type: 'object',
         required: ['building_id', 'ship_id'],
-        properties: { building_id: { type: 'integer' }, ship_id: { type: 'integer' } },
+        properties: {
+          building_id: { type: 'integer', description: 'The unique id of the building.' },
+          ship_id: { type: 'integer', description: 'The unique id of the ship.' },
+        },
       }),
       responses: {
         ...response200(
@@ -176,10 +199,14 @@ export const miningMinistry = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation('Abandon platform.', 'Closes down an existing mining platform.'),
       ...requestBodySchema({
         type: 'object',
         required: ['building_id', 'platform_id'],
-        properties: { building_id: { type: 'integer' }, platform_id: { type: 'integer' } },
+        properties: {
+          building_id: { type: 'integer', description: 'The unique id of the building.' },
+          platform_id: { type: 'integer', description: 'The unique id of the mining platform.' },
+        },
       }),
       responses: {
         ...response200('Closes down an existing mining platform.', {
@@ -196,6 +223,7 @@ export const miningMinistry = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation('Mass abandon platform.', 'Destroys all platforms controlled by this ministry.'),
       ...buildingIdRequestBody,
       responses: {
         ...response200('Destroys all platforms controlled by this ministry.', {
diff --git a/src/spec/paths/buildings/missioncommand.ts b/src/spec/paths/buildings/missioncommand.ts
index a727a4f..ba47cc2 100644
--- a/src/spec/paths/buildings/missioncommand.ts
+++ b/src/spec/paths/buildings/missioncommand.ts
@@ -1,4 +1,5 @@
 import {
+  operation,
   buildingBase,
   buildingCommonMethods,
   buildingView,
@@ -17,7 +18,7 @@ const missionIdRequestBody = (extraDescription: string) =>
     type: 'object',
     required: ['building_id', 'mission_id'],
     properties: {
-      building_id: { type: 'integer' },
+      building_id: { type: 'integer', description: 'The unique id of the building.' },
       mission_id: { type: 'integer', description: extraDescription },
     },
   });
@@ -30,10 +31,16 @@ export const missionCommand = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation(
+        'Get missions.',
+        "Returns a (non-exhaustive) list of missions eligible to be completed in this zone. Excludes missions already completed or above the empire's university level."
+      ),
       ...requestBodySchema({
         type: 'object',
         required: ['building_id'],
-        properties: { building_id: { type: 'integer' } },
+        properties: {
+          building_id: { type: 'integer', description: 'The unique id of the building.' },
+        },
       }),
       responses: {
         ...response200(
@@ -79,6 +86,10 @@ export const missionCommand = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation(
+        'Complete mission.',
+        'Completes a mission. Rejected if the objectives are not all met; otherwise the rewards are distributed.'
+      ),
       ...missionIdRequestBody('The unique id of the mission to complete.'),
       responses: {
         ...response200(
@@ -94,6 +105,7 @@ export const missionCommand = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation('Skip mission.', 'Skips a mission, hiding it from this list for 30 days.'),
       ...missionIdRequestBody(
         "The unique id of the mission to skip. Won't appear again for this empire for 30 days."
       ),
diff --git a/src/spec/paths/buildings/network19.ts b/src/spec/paths/buildings/network19.ts
index a2b0b54..7494a05 100644
--- a/src/spec/paths/buildings/network19.ts
+++ b/src/spec/paths/buildings/network19.ts
@@ -1,4 +1,5 @@
 import {
+  operation,
   buildingBase,
   buildingCommonMethods,
   buildingView,
@@ -27,11 +28,15 @@ export const network19 = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation(
+        'Restrict coverage.',
+        'Enacts or disbands a policy restricting what Network 19 covers about your planet.'
+      ),
       ...requestBodySchema({
         type: 'object',
         required: ['building_id', 'onoff'],
         properties: {
-          building_id: { type: 'integer' },
+          building_id: { type: 'integer', description: 'The unique id of the building.' },
           onoff: {
             type: 'integer',
             enum: [1, 0],
@@ -54,10 +59,16 @@ export const network19 = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation(
+        'View news.',
+        'Returns the top 100 headlines from this zone, and a list of RSS feeds usable outside the game to see the same news.'
+      ),
       ...requestBodySchema({
         type: 'object',
         required: ['building_id'],
-        properties: { building_id: { type: 'integer' } },
+        properties: {
+          building_id: { type: 'integer', description: 'The unique id of the building.' },
+        },
       }),
       responses: {
         ...response200(
diff --git a/src/spec/paths/buildings/observatory.ts b/src/spec/paths/buildings/observatory.ts
index c7d3bb8..d40d8f8 100644
--- a/src/spec/paths/buildings/observatory.ts
+++ b/src/spec/paths/buildings/observatory.ts
@@ -1,4 +1,5 @@
 import {
+  operation,
   buildingBase,
   buildingCommonMethods,
   buildingView,
@@ -15,7 +16,7 @@ const base = buildingBase('Observatory');
 const buildingIdRequestBody = requestBodySchema({
   type: 'object',
   required: ['building_id'],
-  properties: { building_id: { type: 'integer' } },
+  properties: { building_id: { type: 'integer', description: 'The unique id of the building.' } },
 });
 
 const starSchema = {
@@ -82,11 +83,15 @@ export const observatory = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation(
+        'Get probed stars.',
+        'Returns a list of the stars that have been probed by this planet.'
+      ),
       ...requestBodySchema({
         type: 'object',
         required: ['building_id'],
         properties: {
-          building_id: { type: 'integer' },
+          building_id: { type: 'integer', description: 'The unique id of the building.' },
           page_number: {
             type: 'integer',
             description:
@@ -115,11 +120,15 @@ export const observatory = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation(
+        'Abandon probe.',
+        'Deactivates a single probe, allowing it to burn up in the star.'
+      ),
       ...requestBodySchema({
         type: 'object',
         required: ['building_id', 'star_id'],
         properties: {
-          building_id: { type: 'integer' },
+          building_id: { type: 'integer', description: 'The unique id of the building.' },
           star_id: {
             type: 'integer',
             description: 'The unique id of the star the probe is attached to.',
@@ -141,6 +150,10 @@ export const observatory = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation(
+        'Abandon all probes.',
+        'Deactivates all probes controlled by this observatory, allowing them to burn up in the stars.'
+      ),
       ...buildingIdRequestBody,
       responses: {
         ...response200(
diff --git a/src/spec/paths/buildings/oracleofanid.ts b/src/spec/paths/buildings/oracleofanid.ts
index 85e1653..63aa911 100644
--- a/src/spec/paths/buildings/oracleofanid.ts
+++ b/src/spec/paths/buildings/oracleofanid.ts
@@ -1,4 +1,5 @@
 import {
+  operation,
   buildingBase,
   buildingCommonMethods,
   buildingView,
@@ -33,10 +34,17 @@ export const oracleOfAnid = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation(
+        'Get star.',
+        "Retrieves info on a single star, including its bodies, even without a probe there. The Oracle's range is 10 map units per level; requesting a star outside that range throws 1009. Use Map/search_stars to look up a star's id by name."
+      ),
       ...requestBodySchema({
         type: 'object',
         required: ['building_id', 'star_id'],
-        properties: { building_id: { type: 'integer' }, star_id: { type: 'integer' } },
+        properties: {
+          building_id: { type: 'integer', description: 'The unique id of the building.' },
+          star_id: { type: 'integer', description: 'The unique id of the star.' },
+        },
       }),
       responses: {
         ...response200(
@@ -56,11 +64,12 @@ export const oracleOfAnid = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation('Get probed stars.', 'Returns all stars within range of the Oracle.'),
       ...requestBodySchema({
         type: 'object',
         required: ['building_id'],
         properties: {
-          building_id: { type: 'integer' },
+          building_id: { type: 'integer', description: 'The unique id of the building.' },
           page_number: {
             type: 'integer',
             description: 'Optional. Defaults to 1. Each page contains page_size records.',
diff --git a/src/spec/paths/buildings/orestorage.ts b/src/spec/paths/buildings/orestorage.ts
index 0e8b17b..99422c3 100644
--- a/src/spec/paths/buildings/orestorage.ts
+++ b/src/spec/paths/buildings/orestorage.ts
@@ -1,4 +1,5 @@
 import {
+  operation,
   buildingBase,
   buildingCommonMethods,
   buildingView,
@@ -26,16 +27,17 @@ export const oreStorage = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation('Dump ore as waste.', 'Converts ore into waste.'),
       ...requestBodySchema({
         type: 'object',
         required: ['building_id', 'type', 'amount'],
         properties: {
-          building_id: { type: 'integer' },
+          building_id: { type: 'integer', description: 'The unique id of the building.' },
           type: {
             type: 'string',
             description: 'Ore type to convert into waste, e.g. gold, bauxite, galena.',
           },
-          amount: { type: 'integer' },
+          amount: { type: 'integer', description: 'The amount to convert into waste.' },
         },
       }),
       responses: {
diff --git a/src/spec/paths/buildings/park.ts b/src/spec/paths/buildings/park.ts
index 7f56173..3ed296d 100644
--- a/src/spec/paths/buildings/park.ts
+++ b/src/spec/paths/buildings/park.ts
@@ -1,4 +1,5 @@
 import {
+  operation,
   buildingBase,
   buildingCommonMethods,
   buildingView,
@@ -15,7 +16,7 @@ const base = buildingBase('Park');
 const buildingIdRequestBody = requestBodySchema({
   type: 'object',
   required: ['building_id'],
-  properties: { building_id: { type: 'integer' } },
+  properties: { building_id: { type: 'integer', description: 'The unique id of the building.' } },
 });
 
 const viewResultSchema = (description: string) => ({
@@ -57,6 +58,10 @@ export const park = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation(
+        'Throw a party.',
+        'Spends 10,000 food to throw a day-long party generating happiness. Returns the building view.'
+      ),
       ...buildingIdRequestBody,
       responses: viewResultSchema(
         'Spends 10,000 food to throw a day-long party generating happiness. Returns the building view.'
@@ -68,6 +73,10 @@ export const park = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation(
+        'Subsidize party.',
+        'Spends 2 essentia to complete the current party immediately. Returns the building view.'
+      ),
       ...buildingIdRequestBody,
       responses: viewResultSchema(
         'Spends 2 essentia to complete the current party immediately. Returns the building view.'
diff --git a/src/spec/paths/buildings/planetarycommand.ts b/src/spec/paths/buildings/planetarycommand.ts
index 2103b0b..5e9c28c 100644
--- a/src/spec/paths/buildings/planetarycommand.ts
+++ b/src/spec/paths/buildings/planetarycommand.ts
@@ -1,4 +1,5 @@
 import {
+  operation,
   buildingBase,
   buildingCommonMethods,
   buildingView,
@@ -15,7 +16,7 @@ const base = buildingBase('PlanetaryCommand');
 const buildingIdRequestBody = requestBodySchema({
   type: 'object',
   required: ['building_id'],
-  properties: { building_id: { type: 'integer' } },
+  properties: { building_id: { type: 'integer', description: 'The unique id of the building.' } },
 });
 
 export const planetaryCommand = {
@@ -43,6 +44,7 @@ export const planetaryCommand = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation('View plans.', 'Lists all building plans this empire has collected.'),
       ...buildingIdRequestBody,
       responses: {
         ...response200('Lists all building plans this empire has collected.', {
@@ -73,6 +75,10 @@ export const planetaryCommand = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation(
+        'View incoming supply chains.',
+        'Lists supply chains feeding resources into this planet.'
+      ),
       ...buildingIdRequestBody,
       responses: {
         ...response200('Lists supply chains feeding resources into this planet.', {
@@ -114,6 +120,10 @@ export const planetaryCommand = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation(
+        'Subsidize pod cooldown.',
+        'Spends 2 essentia to send a supply pod immediately. Returns the building view. Throws 1011.'
+      ),
       ...buildingIdRequestBody,
       responses: {
         ...response200(
diff --git a/src/spec/paths/buildings/politicstraining.ts b/src/spec/paths/buildings/politicstraining.ts
index b70a555..10448dd 100644
--- a/src/spec/paths/buildings/politicstraining.ts
+++ b/src/spec/paths/buildings/politicstraining.ts
@@ -7,10 +7,14 @@ export const politicsTraining = {
   ...buildingView(base, {
     spies: {
       type: 'object',
+      description: 'Summary of spy training capacity for this facility.',
       properties: {
-        max_points: { type: 'integer' },
-        points_per: { type: 'integer' },
-        in_training: { type: 'integer' },
+        max_points: { type: 'integer', description: 'The maximum training points a spy can hold.' },
+        points_per: { type: 'integer', description: 'Training points added per training cycle.' },
+        in_training: {
+          type: 'integer',
+          description: 'The number of spies currently training here.',
+        },
       },
       required: ['max_points', 'points_per', 'in_training'],
     },
diff --git a/src/spec/paths/buildings/security.ts b/src/spec/paths/buildings/security.ts
index b8435a8..c5c34d7 100644
--- a/src/spec/paths/buildings/security.ts
+++ b/src/spec/paths/buildings/security.ts
@@ -1,4 +1,5 @@
 import {
+  operation,
   buildingBase,
   buildingCommonMethods,
   buildingView,
@@ -15,13 +16,19 @@ const base = buildingBase('Security');
 const buildingIdRequestBody = requestBodySchema({
   type: 'object',
   required: ['building_id'],
-  properties: { building_id: { type: 'integer' } },
+  properties: { building_id: { type: 'integer', description: 'The unique id of the building.' } },
 });
 
 const prisonerIdRequestBody = requestBodySchema({
   type: 'object',
   required: ['building_id', 'prisoner_id'],
-  properties: { building_id: { type: 'integer' }, prisoner_id: { type: 'integer' } },
+  properties: {
+    building_id: { type: 'integer', description: 'The unique id of the building.' },
+    prisoner_id: {
+      type: 'integer',
+      description: 'The unique id of a captured prisoner. See view_prisoners.',
+    },
+  },
 });
 
 export const security_ = {
@@ -32,11 +39,12 @@ export const security_ = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation('View prisoners.', 'Displays a list of the spies that have been captured.'),
       ...requestBodySchema({
         type: 'object',
         required: ['building_id'],
         properties: {
-          building_id: { type: 'integer' },
+          building_id: { type: 'integer', description: 'The unique id of the building.' },
           page_number: {
             type: 'integer',
             description: 'Defaults to 1. Each page contains 25 spies.',
@@ -78,6 +86,10 @@ export const security_ = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation(
+        'Execute prisoner.',
+        "Executes a prisoner rather than letting them serve out their sentence. Costs 10,000 times the prisoner's level in happiness from your planet."
+      ),
       ...prisonerIdRequestBody,
       responses: {
         ...response200(
@@ -93,6 +105,7 @@ export const security_ = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation('Release prisoner.', 'Releases a captured prisoner.'),
       ...prisonerIdRequestBody,
       responses: {
         ...response200('Releases a captured prisoner.', {
@@ -109,11 +122,15 @@ export const security_ = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation(
+        'View foreign spies.',
+        'Displays a list of the spies that are on your planet and have a level lower than your security ministry.'
+      ),
       ...requestBodySchema({
         type: 'object',
         required: ['building_id'],
         properties: {
-          building_id: { type: 'integer' },
+          building_id: { type: 'integer', description: 'The unique id of the building.' },
           page_number: {
             type: 'integer',
             description: 'Defaults to 1. Each page contains 25 spies.',
diff --git a/src/spec/paths/buildings/shipyard.ts b/src/spec/paths/buildings/shipyard.ts
index 7ef6922..dc0b66e 100644
--- a/src/spec/paths/buildings/shipyard.ts
+++ b/src/spec/paths/buildings/shipyard.ts
@@ -1,4 +1,5 @@
 import {
+  operation,
   buildingBase,
   buildingCommonMethods,
   buildingView,
@@ -38,7 +39,7 @@ const shipsBuildingSchema = {
 const buildingIdRequestBody = requestBodySchema({
   type: 'object',
   required: ['building_id'],
-  properties: { building_id: { type: 'integer' } },
+  properties: { building_id: { type: 'integer', description: 'The unique id of the building.' } },
 });
 
 export const shipyard = {
@@ -49,11 +50,15 @@ export const shipyard = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation(
+        'View build queue.',
+        'Retrieves the ships currently being built at this shipyard.'
+      ),
       ...requestBodySchema({
         type: 'object',
         required: ['building_id'],
         properties: {
-          building_id: { type: 'integer' },
+          building_id: { type: 'integer', description: 'The unique id of the building.' },
           page_number: { type: 'integer', description: 'Defaults to 1. 25 items per page.' },
         },
       }),
@@ -71,6 +76,10 @@ export const shipyard = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation(
+        'Subsidize build queue.',
+        'Completes the entire build queue immediately for 1 essentia per ship. Throws 1011.'
+      ),
       ...buildingIdRequestBody,
       responses: {
         ...response200(
@@ -86,10 +95,17 @@ export const shipyard = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation(
+        'Subsidize ship.',
+        'Completes a single ship immediately for 1 essentia. Throws 1011.'
+      ),
       ...requestBodySchema({
         type: 'object',
         required: ['building_id', 'ship_id'],
-        properties: { building_id: { type: 'integer' }, ship_id: { type: 'integer' } },
+        properties: {
+          building_id: { type: 'integer', description: 'The unique id of the building.' },
+          ship_id: { type: 'integer', description: 'The unique id of the ship.' },
+        },
       }),
       responses: {
         ...response200(
@@ -105,14 +121,16 @@ export const shipyard = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation('Get buildable.', 'Lists buildable ship types with cost and availability.'),
       ...requestBodySchema({
         type: 'object',
         required: ['building_id'],
         properties: {
-          building_id: { type: 'integer' },
+          building_id: { type: 'integer', description: 'The unique id of the building.' },
           tag: {
             type: 'string',
             enum: ['Trade', 'Colonization', 'Intelligence', 'Exploration', 'War', 'Mining'],
+            description: 'Optional tag to limit which ship types are listed.',
           },
         },
       }),
@@ -175,13 +193,19 @@ export const shipyard = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation('Build ship.', 'Queues ships for construction at this shipyard.'),
       ...requestBodySchema({
         type: 'object',
         required: ['building_id', 'type'],
         properties: {
-          building_id: { type: 'integer' },
-          type: { type: 'string' },
-          quantity: { type: 'integer', minimum: 1, maximum: 600, description: 'Defaults to 1.' },
+          building_id: { type: 'integer', description: 'The unique id of the building.' },
+          type: { type: 'string', description: 'A ship type, from get_buildable.' },
+          quantity: {
+            type: 'integer',
+            minimum: 1,
+            maximum: 600,
+            description: 'Number of ships to build, up to 600. Defaults to 1.',
+          },
         },
       }),
       responses: {
@@ -195,15 +219,20 @@ export const shipyard = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation(
+        'Build ships.',
+        'Queues ships for construction across multiple shipyards at once.'
+      ),
       ...requestBodySchema({
         type: 'object',
         required: ['options'],
         properties: {
           options: {
             type: 'object',
+            description: 'Build options selecting ship type, quantity, and which shipyards to use.',
             required: ['type'],
             properties: {
-              type: { type: 'string' },
+              type: { type: 'string', description: 'A ship type, from get_buildable.' },
               quantity: {
                 type: 'integer',
                 minimum: 1,
@@ -215,7 +244,12 @@ export const shipyard = {
                 description: 'A single shipyard id, or an array of shipyard ids.',
                 oneOf: [{ type: 'integer' }, { type: 'array', items: { type: 'integer' } }],
               },
-              autoselect: { type: 'string', enum: ['all', 'higher', 'only'] },
+              autoselect: {
+                type: 'string',
+                enum: ['all', 'higher', 'only'],
+                description:
+                  'Shipyard autoselect mode. Defaults to using only the shipyard(s) in building_id.',
+              },
             },
           },
         },
diff --git a/src/spec/paths/buildings/spaceport.ts b/src/spec/paths/buildings/spaceport.ts
index 371b2a6..91e6f82 100644
--- a/src/spec/paths/buildings/spaceport.ts
+++ b/src/spec/paths/buildings/spaceport.ts
@@ -1,4 +1,5 @@
 import {
+  operation,
   buildingBase,
   buildingCommonMethods,
   buildingView,
@@ -15,7 +16,7 @@ const base = buildingBase('SpacePort');
 const buildingIdRequestBody = requestBodySchema({
   type: 'object',
   required: ['building_id'],
-  properties: { building_id: { type: 'integer' } },
+  properties: { building_id: { type: 'integer', description: 'The unique id of the building.' } },
 });
 
 // A star/body locator, as accepted by every method that needs to identify a target — exactly one
@@ -99,21 +100,29 @@ export const spacePort = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation('View all ships.', "Shows all of this empire's ships, whatever they are doing."),
       ...requestBodySchema({
         type: 'object',
         required: ['building_id'],
         properties: {
-          building_id: { type: 'integer' },
+          building_id: { type: 'integer', description: 'The unique id of the building.' },
           paging: {
             type: 'object',
+            description: 'Optional paging controls.',
             properties: {
               page_number: { type: 'integer', description: 'Defaults to 1.' },
               items_per_page: { type: 'integer', description: 'Defaults to 25.' },
-              no_paging: { type: 'integer', enum: [1, 0] },
+              no_paging: {
+                type: 'integer',
+                enum: [1, 0],
+                description:
+                  'If 1, all other paging options are ignored and every result is returned.',
+              },
             },
           },
           filter: {
             type: 'object',
+            description: 'Optional filters on task, type, and tag.',
             properties: {
               task: {
                 description:
@@ -157,11 +166,15 @@ export const spacePort = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation(
+        'View foreign ships.',
+        "Lists incoming foreign ships whose stealth this Space Port's level can detect (350 * level >= ship stealth). The `from` block is only included if 450 * level >= ship stealth."
+      ),
       ...requestBodySchema({
         type: 'object',
         required: ['building_id'],
         properties: {
-          building_id: { type: 'integer' },
+          building_id: { type: 'integer', description: 'The unique id of the building.' },
           page_number: { type: 'integer', description: 'Defaults to 1. 25 per page.' },
         },
       }),
@@ -187,10 +200,20 @@ export const spacePort = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation(
+        'Summarize a fleet available for a target.',
+        'Summarizes ships available to include in a fleet action, grouped by type/speed/stealth/combat.'
+      ),
       ...requestBodySchema({
         type: 'object',
         required: ['from_body_id', 'target'],
-        properties: { from_body_id: { type: 'integer' }, target: targetSchema },
+        properties: {
+          from_body_id: {
+            type: 'integer',
+            description: 'The unique id of the planet the ships are dispatched from.',
+          },
+          target: targetSchema,
+        },
       }),
       responses: {
         ...response200(
@@ -229,10 +252,20 @@ export const spacePort = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation(
+        'List ships available for a target.',
+        'Lists incoming ships and ships available to send to a target. Use with send_ship.'
+      ),
       ...requestBodySchema({
         type: 'object',
         required: ['from_body_id', 'target'],
-        properties: { from_body_id: { type: 'integer' }, target: targetSchema },
+        properties: {
+          from_body_id: {
+            type: 'integer',
+            description: 'The unique id of the planet the ships are dispatched from.',
+          },
+          target: targetSchema,
+        },
       }),
       responses: {
         ...response200(
@@ -286,10 +319,14 @@ export const spacePort = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation('Send ship.', 'Sends a single ship to a body or star. Use with get_ships_for.'),
       ...requestBodySchema({
         type: 'object',
         required: ['ship_id', 'target'],
-        properties: { ship_id: { type: 'integer' }, target: targetSchema },
+        properties: {
+          ship_id: { type: 'integer', description: 'The unique id of the ship.' },
+          target: targetSchema,
+        },
       }),
       responses: {
         ...response200('Sends a single ship to a body or star. Use with get_ships_for.', {
@@ -306,11 +343,18 @@ export const spacePort = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation(
+        'Send ship types.',
+        'Sends the given quantities of matching docked ships to a target. Returns the same shape as get_fleet_for, showing ships remaining to send. Throws 1002, 1009, 1010, 1019.'
+      ),
       ...requestBodySchema({
         type: 'object',
         required: ['from_body_id', 'target', 'types', 'arrival'],
         properties: {
-          from_body_id: { type: 'integer' },
+          from_body_id: {
+            type: 'integer',
+            description: 'The unique id of the planet the ships are dispatched from.',
+          },
           target: targetSchema,
           types: {
             type: 'array',
@@ -323,7 +367,7 @@ export const spacePort = {
                 speed: { type: 'integer' },
                 stealth: { type: 'integer' },
                 combat: { type: 'integer' },
-                quantity: { type: 'integer' },
+                quantity: { type: 'integer', description: 'How many to process. Defaults to 1.' },
               },
             },
           },
@@ -382,11 +426,19 @@ export const spacePort = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation(
+        'Send fleet.',
+        'Sends a fleet of ships to a body or star. Use with get_ships_for. Throws 1002, 1009, 1010, 1016.'
+      ),
       ...requestBodySchema({
         type: 'object',
         required: ['ship_ids', 'target'],
         properties: {
-          ship_ids: { type: 'array', items: { type: 'integer' } },
+          ship_ids: {
+            type: 'array',
+            items: { type: 'integer' },
+            description: 'An array of ship ids.',
+          },
           target: targetSchema,
           set_speed: {
             type: 'integer',
@@ -413,10 +465,17 @@ export const spacePort = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation(
+        'Recall ship.',
+        'Recalls an orbiting ship (task Defend or Orbiting) to its body of origin. Recalling an orbiting Spy Shuttle also fetches as many idle spies as will fit. Throws 1002, 1010, 1013.'
+      ),
       ...requestBodySchema({
         type: 'object',
         required: ['building_id', 'ship_id'],
-        properties: { building_id: { type: 'integer' }, ship_id: { type: 'integer' } },
+        properties: {
+          building_id: { type: 'integer', description: 'The unique id of the building.' },
+          ship_id: { type: 'integer', description: 'The unique id of the ship.' },
+        },
       }),
       responses: {
         ...response200(
@@ -436,6 +495,10 @@ export const spacePort = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation(
+        'Recall all.',
+        "Recalls all of this planet's orbiting ships (task Defend or Orbiting) to their Space Port of origin. Throws 1002, 1010."
+      ),
       ...buildingIdRequestBody,
       responses: {
         ...response200(
@@ -455,13 +518,19 @@ export const spacePort = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation('Name ship.', 'Renames a ship.'),
       ...requestBodySchema({
         type: 'object',
         required: ['building_id', 'ship_id', 'name'],
         properties: {
-          building_id: { type: 'integer' },
-          ship_id: { type: 'integer' },
-          name: { type: 'string', minLength: 1, maxLength: 30 },
+          building_id: { type: 'integer', description: 'The unique id of the building.' },
+          ship_id: { type: 'integer', description: 'The unique id of the ship.' },
+          name: {
+            type: 'string',
+            minLength: 1,
+            maxLength: 30,
+            description: 'The new ship name. 1-30 characters, no profanity or special characters.',
+          },
         },
       }),
       responses: {
@@ -479,10 +548,14 @@ export const spacePort = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation('Scuttle ship.', 'Destroys a docked ship.'),
       ...requestBodySchema({
         type: 'object',
         required: ['building_id', 'ship_id'],
-        properties: { building_id: { type: 'integer' }, ship_id: { type: 'integer' } },
+        properties: {
+          building_id: { type: 'integer', description: 'The unique id of the building.' },
+          ship_id: { type: 'integer', description: 'The unique id of the ship.' },
+        },
       }),
       responses: {
         ...response200('Destroys a docked ship.', {
@@ -499,12 +572,17 @@ export const spacePort = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation('Mass scuttle ship.', 'Destroys multiple docked ships.'),
       ...requestBodySchema({
         type: 'object',
         required: ['building_id', 'ship_ids'],
         properties: {
-          building_id: { type: 'integer' },
-          ship_ids: { type: 'array', items: { type: 'integer' } },
+          building_id: { type: 'integer', description: 'The unique id of the building.' },
+          ship_ids: {
+            type: 'array',
+            items: { type: 'integer' },
+            description: 'An array of ship ids.',
+          },
         },
       }),
       responses: {
@@ -522,11 +600,15 @@ export const spacePort = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation(
+        'View ships travelling.',
+        "Lists ships travelling to or from this planet, regardless of which Space Port they'll land at."
+      ),
       ...requestBodySchema({
         type: 'object',
         required: ['building_id'],
         properties: {
-          building_id: { type: 'integer' },
+          building_id: { type: 'integer', description: 'The unique id of the building.' },
           page_number: { type: 'integer', description: 'Defaults to 1. 25 per page.' },
         },
       }),
@@ -552,11 +634,15 @@ export const spacePort = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation(
+        'View ships orbiting.',
+        "Lists foreign ships orbiting this planet whose stealth this Space Port's level can detect (350 * level >= ship stealth). The `from` block is only included if 450 * level >= ship stealth."
+      ),
       ...requestBodySchema({
         type: 'object',
         required: ['building_id'],
         properties: {
-          building_id: { type: 'integer' },
+          building_id: { type: 'integer', description: 'The unique id of the building.' },
           page_number: { type: 'integer', description: 'Defaults to 1. 25 per page.' },
         },
       }),
@@ -582,10 +668,17 @@ export const spacePort = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation('Prepare send spies.', 'Gathers the ships and spies needed to call send_spies.'),
       ...requestBodySchema({
         type: 'object',
         required: ['on_body_id', 'to_body_id'],
-        properties: { on_body_id: { type: 'integer' }, to_body_id: { type: 'integer' } },
+        properties: {
+          on_body_id: {
+            type: 'integer',
+            description: 'The unique id of the planet the spies are on.',
+          },
+          to_body_id: { type: 'integer', description: 'The unique id of the destination planet.' },
+        },
       }),
       responses: {
         ...response200('Gathers the ships and spies needed to call send_spies.', {
@@ -625,14 +718,25 @@ export const spacePort = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation(
+        'Send spies.',
+        'Sends spies from on_body_id to to_body_id using the chosen ship. See prepare_send_spies.'
+      ),
       ...requestBodySchema({
         type: 'object',
         required: ['on_body_id', 'to_body_id', 'ship_id', 'spy_ids'],
         properties: {
-          on_body_id: { type: 'integer' },
-          to_body_id: { type: 'integer' },
-          ship_id: { type: 'integer' },
-          spy_ids: { type: 'array', items: { type: 'integer' } },
+          on_body_id: {
+            type: 'integer',
+            description: 'The unique id of the planet the spies are on.',
+          },
+          to_body_id: { type: 'integer', description: 'The unique id of the destination planet.' },
+          ship_id: { type: 'integer', description: 'The unique id of the ship.' },
+          spy_ids: {
+            type: 'array',
+            items: { type: 'integer' },
+            description: 'An array of spy ids.',
+          },
         },
       }),
       responses: {
@@ -663,6 +767,10 @@ export const spacePort = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation(
+        'Prepare fetch spies.',
+        'Gathers the ships and spies needed to call fetch_spies.'
+      ),
       ...requestBodySchema({
         type: 'object',
         required: ['on_body_id', 'to_body_id'],
@@ -708,6 +816,10 @@ export const spacePort = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation(
+        'Fetch spies.',
+        'Sends a ship to fetch spies from on_body_id and bring them to to_body_id. Spies not Idle on arrival are not picked up. See prepare_fetch_spies.'
+      ),
       ...requestBodySchema({
         type: 'object',
         required: ['on_body_id', 'to_body_id', 'ship_id', 'spy_ids'],
@@ -718,8 +830,12 @@ export const spacePort = {
             description:
               'The planet the spies should be brought to, and the ship will be dispatched from.',
           },
-          ship_id: { type: 'integer' },
-          spy_ids: { type: 'array', items: { type: 'integer' } },
+          ship_id: { type: 'integer', description: 'The unique id of the ship.' },
+          spy_ids: {
+            type: 'array',
+            items: { type: 'integer' },
+            description: 'An array of spy ids.',
+          },
         },
       }),
       responses: {
@@ -740,11 +856,15 @@ export const spacePort = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation(
+        'View battle logs.',
+        "Lists this empire's battle logs, most recent first. Cleared out every seven days."
+      ),
       ...requestBodySchema({
         type: 'object',
         required: ['building_id'],
         properties: {
-          building_id: { type: 'integer' },
+          building_id: { type: 'integer', description: 'The unique id of the building.' },
           page_number: { type: 'integer', description: 'Defaults to 1. 25 per page.' },
         },
       }),
diff --git a/src/spec/paths/buildings/spacestationlab.ts b/src/spec/paths/buildings/spacestationlab.ts
index 7d68ef0..a64b595 100644
--- a/src/spec/paths/buildings/spacestationlab.ts
+++ b/src/spec/paths/buildings/spacestationlab.ts
@@ -1,4 +1,5 @@
 import {
+  operation,
   buildingBase,
   buildingCommonMethods,
   buildingView,
@@ -17,7 +18,7 @@ const base = buildingBase('SpaceStationLab');
 const buildingIdRequestBody = requestBodySchema({
   type: 'object',
   required: ['building_id'],
-  properties: { building_id: { type: 'integer' } },
+  properties: { building_id: { type: 'integer', description: 'The unique id of the building.' } },
 });
 
 const makePlanSchema = {
@@ -63,13 +64,19 @@ export const spaceStationLab = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation('Make plan.', 'Starts the plan creation process. Returns the building view.'),
       ...requestBodySchema({
         type: 'object',
         required: ['building_id', 'type', 'level'],
         properties: {
-          building_id: { type: 'integer' },
+          building_id: { type: 'integer', description: 'The unique id of the building.' },
           type: { type: 'string', description: "Key from view's make_plan > types, e.g. 'ibs'." },
-          level: { type: 'integer', minimum: 1, maximum: 30 },
+          level: {
+            type: 'integer',
+            minimum: 1,
+            maximum: 30,
+            description: "The plan level (1-30), from view's make_plan > level_costs.",
+          },
         },
       }),
       responses: {
@@ -91,6 +98,10 @@ export const spaceStationLab = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation(
+        'Subsidize plan.',
+        "Spends essentia equal to view's subsidy_cost to complete the current plan immediately. Returns the building view. Throws 1011."
+      ),
       ...buildingIdRequestBody,
       responses: {
         ...response200(
diff --git a/src/spec/paths/buildings/subspacesupplydepot.ts b/src/spec/paths/buildings/subspacesupplydepot.ts
index b2c32ed..bda971f 100644
--- a/src/spec/paths/buildings/subspacesupplydepot.ts
+++ b/src/spec/paths/buildings/subspacesupplydepot.ts
@@ -1,4 +1,5 @@
 import {
+  operation,
   buildingBase,
   buildingCommonMethods,
   buildingView,
@@ -15,7 +16,7 @@ const base = buildingBase('SubspaceSupplyDepot');
 const buildingIdRequestBody = requestBodySchema({
   type: 'object',
   required: ['building_id'],
-  properties: { building_id: { type: 'integer' } },
+  properties: { building_id: { type: 'integer', description: 'The unique id of the building.' } },
 });
 
 // Shared response shape for the transmit_* methods and complete_build_queue — all convert seconds
@@ -53,6 +54,7 @@ export const subspaceSupplyDepot = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation('Transmit food.', 'Converts 3600 seconds into 3600 food.'),
       ...buildingIdRequestBody,
       responses: workResultSchema('Converts 3600 seconds into 3600 food.'),
     },
@@ -62,6 +64,7 @@ export const subspaceSupplyDepot = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation('Transmit energy.', 'Converts 3600 seconds into 3600 energy.'),
       ...buildingIdRequestBody,
       responses: workResultSchema('Converts 3600 seconds into 3600 energy.'),
     },
@@ -71,6 +74,7 @@ export const subspaceSupplyDepot = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation('Transmit ore.', 'Converts 3600 seconds into 3600 ore.'),
       ...buildingIdRequestBody,
       responses: workResultSchema('Converts 3600 seconds into 3600 ore.'),
     },
@@ -80,6 +84,7 @@ export const subspaceSupplyDepot = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation('Transmit water.', 'Converts 3600 seconds into 3600 water.'),
       ...buildingIdRequestBody,
       responses: workResultSchema('Converts 3600 seconds into 3600 water.'),
     },
@@ -89,6 +94,7 @@ export const subspaceSupplyDepot = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation('Complete build queue.', "Trades seconds for the planet's build queue time."),
       ...buildingIdRequestBody,
       responses: workResultSchema("Trades seconds for the planet's build queue time."),
     },
diff --git a/src/spec/paths/buildings/templeofthedrajilites.ts b/src/spec/paths/buildings/templeofthedrajilites.ts
index 450d35b..546a22f 100644
--- a/src/spec/paths/buildings/templeofthedrajilites.ts
+++ b/src/spec/paths/buildings/templeofthedrajilites.ts
@@ -1,4 +1,5 @@
 import {
+  operation,
   buildingBase,
   buildingCommonMethods,
   buildingView,
@@ -20,11 +21,12 @@ export const templeOfTheDrajilites = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation('List planets.', 'Lists the planets around a given star.'),
       ...requestBodySchema({
         type: 'object',
         required: ['building_id'],
         properties: {
-          building_id: { type: 'integer' },
+          building_id: { type: 'integer', description: 'The unique id of the building.' },
           star_id: { type: 'integer', description: 'Defaults to the star the Temple is built on.' },
         },
       }),
@@ -53,11 +55,15 @@ export const templeOfTheDrajilites = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation(
+        'View planet.',
+        'Returns a surface map identical in format to an Inbox attachment map.'
+      ),
       ...requestBodySchema({
         type: 'object',
         required: ['building_id', 'planet_id'],
         properties: {
-          building_id: { type: 'integer' },
+          building_id: { type: 'integer', description: 'The unique id of the building.' },
           planet_id: {
             type: 'integer',
             description:
diff --git a/src/spec/paths/buildings/thedillonforge.ts b/src/spec/paths/buildings/thedillonforge.ts
index 8de8ed6..491d168 100644
--- a/src/spec/paths/buildings/thedillonforge.ts
+++ b/src/spec/paths/buildings/thedillonforge.ts
@@ -1,4 +1,5 @@
 import {
+  operation,
   buildingBase,
   buildingCommonMethods,
   buildingView,
@@ -15,7 +16,7 @@ const base = buildingBase('TheDillonForge');
 const buildingIdRequestBody = requestBodySchema({
   type: 'object',
   required: ['building_id'],
-  properties: { building_id: { type: 'integer' } },
+  properties: { building_id: { type: 'integer', description: 'The unique id of the building.' } },
 });
 
 const tasksSchema = {
@@ -63,11 +64,12 @@ export const theDillonForge = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation('Make plan.', 'Starts making a plan. Returns the building view.'),
       ...requestBodySchema({
         type: 'object',
         required: ['building_id', 'plan_class', 'level'],
         properties: {
-          building_id: { type: 'integer' },
+          building_id: { type: 'integer', description: 'The unique id of the building.' },
           plan_class: {
             type: 'string',
             description: "The plan's class, as returned by view's tasks > make_plan.",
@@ -97,11 +99,15 @@ export const theDillonForge = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation(
+        'Split plan.',
+        'Splits a plan into its constituent glyphs. Returns the building view.'
+      ),
       ...requestBodySchema({
         type: 'object',
         required: ['building_id', 'plan_class', 'level', 'quantity'],
         properties: {
-          building_id: { type: 'integer' },
+          building_id: { type: 'integer', description: 'The unique id of the building.' },
           plan_class: {
             type: 'string',
             description: "The plan's class, as returned by view's tasks > split_plan.",
@@ -136,6 +142,10 @@ export const theDillonForge = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation(
+        'Subsidize the current forge task.',
+        'Spends essentia to complete the current task immediately (2e, unless splitting multiple plans). Returns the building view. Throws 1011.'
+      ),
       ...buildingIdRequestBody,
       responses: {
         ...response200(
diff --git a/src/spec/paths/buildings/thefttraining.ts b/src/spec/paths/buildings/thefttraining.ts
index f14b934..b405e2b 100644
--- a/src/spec/paths/buildings/thefttraining.ts
+++ b/src/spec/paths/buildings/thefttraining.ts
@@ -7,10 +7,14 @@ export const theftTraining = {
   ...buildingView(base, {
     spies: {
       type: 'object',
+      description: 'Spy training capacity for this facility.',
       properties: {
-        max_points: { type: 'integer' },
-        points_per: { type: 'integer' },
-        in_training: { type: 'integer' },
+        max_points: { type: 'integer', description: 'The maximum training points a spy can hold.' },
+        points_per: { type: 'integer', description: 'Training points added per training cycle.' },
+        in_training: {
+          type: 'integer',
+          description: 'The number of spies currently training here.',
+        },
       },
     },
   }),
diff --git a/src/spec/paths/buildings/themepark.ts b/src/spec/paths/buildings/themepark.ts
index 3d383f1..33dbb29 100644
--- a/src/spec/paths/buildings/themepark.ts
+++ b/src/spec/paths/buildings/themepark.ts
@@ -1,4 +1,5 @@
 import {
+  operation,
   buildingBase,
   buildingCommonMethods,
   buildingView,
@@ -29,10 +30,16 @@ export const themePark = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation(
+        'Start or extend Theme Park operation.',
+        'Starts (or extends) operation of the Theme Park. Requires at least 1,000 of each of 5 food types to start; while operating, subsequent calls must spend at least as much food as the last call. Happiness output scales with the number of food types used and the level of the Theme Park. Returns the building view. Throws 1002, 1006, 1010, 1011.'
+      ),
       ...requestBodySchema({
         type: 'object',
         required: ['building_id'],
-        properties: { building_id: { type: 'integer' } },
+        properties: {
+          building_id: { type: 'integer', description: 'The unique id of the building.' },
+        },
       }),
       responses: {
         ...response200(
diff --git a/src/spec/paths/buildings/trade.ts b/src/spec/paths/buildings/trade.ts
index 6dfff8d..982b4fd 100644
--- a/src/spec/paths/buildings/trade.ts
+++ b/src/spec/paths/buildings/trade.ts
@@ -1,4 +1,5 @@
 import {
+  operation,
   buildingBase,
   buildingCommonMethods,
   buildingView,
@@ -15,7 +16,7 @@ const base = buildingBase('Trade');
 const buildingIdRequestBody = requestBodySchema({
   type: 'object',
   required: ['building_id'],
-  properties: { building_id: { type: 'integer' } },
+  properties: { building_id: { type: 'integer', description: 'The unique id of the building.' } },
 });
 
 // A tradeable item, per the Trade docs — resources (quantity-based), glyphs, plans, prisoners, or ships.
@@ -63,19 +64,28 @@ export const trade = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation('Add to market.', 'Posts a trade offer for other players to accept.'),
       ...requestBodySchema({
         type: 'object',
         required: ['building_id', 'offer', 'ask'],
         properties: {
-          building_id: { type: 'integer' },
-          offer: { type: 'array', items: tradeableItemSchema },
+          building_id: { type: 'integer', description: 'The unique id of the building.' },
+          offer: {
+            type: 'array',
+            items: tradeableItemSchema,
+            description: 'The items to trade (resources, glyphs, plans, prisoners, or ships).',
+          },
           ask: {
             type: 'number',
             minimum: 0.1,
             maximum: 100,
             description: 'Essentia amount requested.',
           },
-          options: { type: 'object', properties: { ship_id: { type: 'integer' } } },
+          options: {
+            type: 'object',
+            description: 'Optional trade options.',
+            properties: { ship_id: { type: 'integer', description: 'The unique id of the ship.' } },
+          },
         },
       }),
       responses: {
@@ -93,15 +103,17 @@ export const trade = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation('View market.', "Lists other players' posted trades."),
       ...requestBodySchema({
         type: 'object',
         required: ['building_id'],
         properties: {
-          building_id: { type: 'integer' },
+          building_id: { type: 'integer', description: 'The unique id of the building.' },
           page_number: { type: 'integer', description: 'Defaults to 1. 25 items per page.' },
           filter: {
             type: 'string',
             enum: ['food', 'ore', 'water', 'waste', 'energy', 'glyph', 'prisoner', 'ship', 'plan'],
+            description: 'Optional. Narrows the list to trades offering one kind of object.',
           },
         },
       }),
@@ -127,11 +139,12 @@ export const trade = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation('View my market.', 'Lists trades posted by this empire.'),
       ...requestBodySchema({
         type: 'object',
         required: ['building_id'],
         properties: {
-          building_id: { type: 'integer' },
+          building_id: { type: 'integer', description: 'The unique id of the building.' },
           page_number: { type: 'integer', description: 'Defaults to 1.' },
         },
       }),
@@ -157,10 +170,17 @@ export const trade = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation(
+        'Accept from market.',
+        "Accepts another player's trade. Throws 1016 if the trade is no longer valid."
+      ),
       ...requestBodySchema({
         type: 'object',
         required: ['building_id', 'trade_id'],
-        properties: { building_id: { type: 'integer' }, trade_id: { type: 'integer' } },
+        properties: {
+          building_id: { type: 'integer', description: 'The unique id of the building.' },
+          trade_id: { type: 'integer', description: 'The unique id of the trade.' },
+        },
       }),
       responses: {
         ...response200(
@@ -176,10 +196,17 @@ export const trade = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation(
+        'Withdraw from market.',
+        'Cancels a trade this empire posted and retrieves the offered items.'
+      ),
       ...requestBodySchema({
         type: 'object',
         required: ['building_id', 'trade_id'],
-        properties: { building_id: { type: 'integer' }, trade_id: { type: 'integer' } },
+        properties: {
+          building_id: { type: 'integer', description: 'The unique id of the building.' },
+          trade_id: { type: 'integer', description: 'The unique id of the trade.' },
+        },
       }),
       responses: {
         ...response200('Cancels a trade this empire posted and retrieves the offered items.', {
@@ -196,20 +223,27 @@ export const trade = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation('Push items.', 'Transfers resources/items between planets this empire owns.'),
       ...requestBodySchema({
         type: 'object',
         required: ['building_id', 'target_id', 'items'],
         properties: {
-          building_id: { type: 'integer' },
+          building_id: { type: 'integer', description: 'The unique id of the building.' },
           target_id: {
             type: 'integer',
             description: 'The destination planet, which must be owned by this empire.',
           },
-          items: { type: 'array', items: tradeableItemSchema },
+          items: {
+            type: 'array',
+            items: tradeableItemSchema,
+            description:
+              'The items to ship to the target planet (resources, glyphs, plans, prisoners, or ships).',
+          },
           options: {
             type: 'object',
+            description: 'Optional push options.',
             properties: {
-              ship_id: { type: 'integer' },
+              ship_id: { type: 'integer', description: 'The unique id of the ship.' },
               stay: {
                 type: 'integer',
                 enum: [1, 0],
@@ -244,6 +278,10 @@ export const trade = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation(
+        'Get stored resources.',
+        'Lists resources available in storage, by type and quantity.'
+      ),
       ...buildingIdRequestBody,
       responses: {
         ...response200('Lists resources available in storage, by type and quantity.', {
@@ -263,10 +301,21 @@ export const trade = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation(
+        'Get trade ships.',
+        'Lists cargo vessels available for trading, with estimated travel time.'
+      ),
       ...requestBodySchema({
         type: 'object',
         required: ['building_id'],
-        properties: { building_id: { type: 'integer' }, target_body_id: { type: 'integer' } },
+        properties: {
+          building_id: { type: 'integer', description: 'The unique id of the building.' },
+          target_body_id: {
+            type: 'integer',
+            description:
+              'The unique id of the body being shipped to. If given, travel time is estimated.',
+          },
+        },
       }),
       responses: {
         ...response200('Lists cargo vessels available for trading, with estimated travel time.', {
@@ -299,6 +348,7 @@ export const trade = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation('Get ships.', 'Lists tradeable ships, with hold size and speed.'),
       ...buildingIdRequestBody,
       responses: {
         ...response200('Lists tradeable ships, with hold size and speed.', {
@@ -330,6 +380,7 @@ export const trade = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation('Get waste ships.', 'Lists scow vessels available for waste transport.'),
       ...buildingIdRequestBody,
       responses: {
         ...response200('Lists scow vessels available for waste transport.', {
@@ -361,6 +412,7 @@ export const trade = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation('Get supply ships.', 'Lists hulk vessels available for resource supply chains.'),
       ...buildingIdRequestBody,
       responses: {
         ...response200('Lists hulk vessels available for resource supply chains.', {
@@ -392,6 +444,7 @@ export const trade = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation('View supply chains.', "Lists this ministry's active resource supply chains."),
       ...buildingIdRequestBody,
       responses: {
         ...response200("Lists this ministry's active resource supply chains.", {
@@ -424,14 +477,28 @@ export const trade = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation(
+        'Create supply chain.',
+        'Establishes a new resource supply chain to a target planet.'
+      ),
       ...requestBodySchema({
         type: 'object',
         required: ['building_id', 'target_id', 'resource_type', 'resource_hour'],
         properties: {
-          building_id: { type: 'integer' },
-          target_id: { type: 'integer' },
-          resource_type: { type: 'string' },
-          resource_hour: { type: 'integer' },
+          building_id: { type: 'integer', description: 'The unique id of the building.' },
+          target_id: {
+            type: 'integer',
+            description: 'The unique id of a planet you control to send the items to.',
+          },
+          resource_type: {
+            type: 'string',
+            description: 'The resource to transfer, e.g. "water", "gold", "apple".',
+          },
+          resource_hour: {
+            type: 'integer',
+            description:
+              'The amount of the resource to transfer each hour. Set to 0 to suspend the chain.',
+          },
         },
       }),
       responses: {
@@ -449,13 +516,17 @@ export const trade = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation('Update supply chain.', 'Modifies an existing supply chain.'),
       ...requestBodySchema({
         type: 'object',
         required: ['building_id', 'supply_chain_id', 'resource_type', 'resource_hour'],
         properties: {
-          building_id: { type: 'integer' },
-          supply_chain_id: { type: 'integer' },
-          resource_type: { type: 'string' },
+          building_id: { type: 'integer', description: 'The unique id of the building.' },
+          supply_chain_id: { type: 'integer', description: 'The unique id of the supply chain.' },
+          resource_type: {
+            type: 'string',
+            description: 'The resource to transfer, e.g. "water", "gold", "apple".',
+          },
           resource_hour: { type: 'integer', description: 'Set to 0 to suspend the chain.' },
         },
       }),
@@ -474,10 +545,14 @@ export const trade = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation('Delete supply chain.', 'Removes a supply chain.'),
       ...requestBodySchema({
         type: 'object',
         required: ['building_id', 'supply_chain_id'],
-        properties: { building_id: { type: 'integer' }, supply_chain_id: { type: 'integer' } },
+        properties: {
+          building_id: { type: 'integer', description: 'The unique id of the building.' },
+          supply_chain_id: { type: 'integer', description: 'The unique id of the supply chain.' },
+        },
       }),
       responses: {
         ...response200('Removes a supply chain.', {
@@ -494,10 +569,17 @@ export const trade = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation(
+        'Add supply ship to fleet.',
+        'Assigns a hulk to supply chain service. Throws 1009 on failure.'
+      ),
       ...requestBodySchema({
         type: 'object',
         required: ['building_id', 'ship_id'],
-        properties: { building_id: { type: 'integer' }, ship_id: { type: 'integer' } },
+        properties: {
+          building_id: { type: 'integer', description: 'The unique id of the building.' },
+          ship_id: { type: 'integer', description: 'The unique id of the ship.' },
+        },
       }),
       responses: {
         ...response200('Assigns a hulk to supply chain service. Throws 1009 on failure.', {
@@ -514,10 +596,17 @@ export const trade = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation(
+        'Remove supply ship from fleet.',
+        'Returns a hulk to the spaceport from supply chain duty.'
+      ),
       ...requestBodySchema({
         type: 'object',
         required: ['building_id', 'ship_id'],
-        properties: { building_id: { type: 'integer' }, ship_id: { type: 'integer' } },
+        properties: {
+          building_id: { type: 'integer', description: 'The unique id of the building.' },
+          ship_id: { type: 'integer', description: 'The unique id of the ship.' },
+        },
       }),
       responses: {
         ...response200('Returns a hulk to the spaceport from supply chain duty.', {
@@ -534,6 +623,10 @@ export const trade = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation(
+        'View waste chains.',
+        'Lists waste chains (a default chain exists for the local star).'
+      ),
       ...buildingIdRequestBody,
       responses: {
         ...response200('Lists waste chains (a default chain exists for the local star).', {
@@ -563,13 +656,17 @@ export const trade = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation('Update waste chain.', 'Adjusts the transfer rate of a waste chain.'),
       ...requestBodySchema({
         type: 'object',
         required: ['building_id', 'waste_chain_id', 'waste_hour'],
         properties: {
-          building_id: { type: 'integer' },
-          waste_chain_id: { type: 'integer' },
-          waste_hour: { type: 'integer' },
+          building_id: { type: 'integer', description: 'The unique id of the building.' },
+          waste_chain_id: { type: 'integer', description: 'The unique id of the waste chain.' },
+          waste_hour: {
+            type: 'integer',
+            description: 'The amount of waste to transfer each hour. Set to 0 to stop.',
+          },
         },
       }),
       responses: {
@@ -587,10 +684,17 @@ export const trade = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation(
+        'Add waste ship to fleet.',
+        'Assigns a scow to waste transport duty. Throws 1009 on failure.'
+      ),
       ...requestBodySchema({
         type: 'object',
         required: ['building_id', 'ship_id'],
-        properties: { building_id: { type: 'integer' }, ship_id: { type: 'integer' } },
+        properties: {
+          building_id: { type: 'integer', description: 'The unique id of the building.' },
+          ship_id: { type: 'integer', description: 'The unique id of the ship.' },
+        },
       }),
       responses: {
         ...response200('Assigns a scow to waste transport duty. Throws 1009 on failure.', {
@@ -607,10 +711,17 @@ export const trade = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation(
+        'Remove waste ship from fleet.',
+        'Returns a scow to the spaceport from waste transport duty.'
+      ),
       ...requestBodySchema({
         type: 'object',
         required: ['building_id', 'ship_id'],
-        properties: { building_id: { type: 'integer' }, ship_id: { type: 'integer' } },
+        properties: {
+          building_id: { type: 'integer', description: 'The unique id of the building.' },
+          ship_id: { type: 'integer', description: 'The unique id of the ship.' },
+        },
       }),
       responses: {
         ...response200('Returns a scow to the spaceport from waste transport duty.', {
@@ -627,6 +738,7 @@ export const trade = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation('Get prisoners.', 'Lists tradeable spies, with level and sentence expiration.'),
       ...buildingIdRequestBody,
       responses: {
         ...response200('Lists tradeable spies, with level and sentence expiration.', {
@@ -657,6 +769,7 @@ export const trade = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation('Get plan summary.', 'Summarizes owned plans by type, level, and quantity.'),
       ...buildingIdRequestBody,
       responses: {
         ...response200('Summarizes owned plans by type, level, and quantity.', {
@@ -687,6 +800,7 @@ export const trade = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation('Get glyph summary.', 'Summarizes owned glyphs by type and quantity.'),
       ...buildingIdRequestBody,
       responses: {
         ...response200('Summarizes owned glyphs by type and quantity.', {
@@ -712,10 +826,14 @@ export const trade = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation('Report abuse.', 'Flags a suspicious trade for moderation review.'),
       ...requestBodySchema({
         type: 'object',
         required: ['building_id', 'trade_id'],
-        properties: { building_id: { type: 'integer' }, trade_id: { type: 'integer' } },
+        properties: {
+          building_id: { type: 'integer', description: 'The unique id of the building.' },
+          trade_id: { type: 'integer', description: 'The unique id of the trade.' },
+        },
       }),
       responses: {
         ...response200('Flags a suspicious trade for moderation review.', {
diff --git a/src/spec/paths/buildings/transporter.ts b/src/spec/paths/buildings/transporter.ts
index 628cbca..1324862 100644
--- a/src/spec/paths/buildings/transporter.ts
+++ b/src/spec/paths/buildings/transporter.ts
@@ -1,4 +1,5 @@
 import {
+  operation,
   buildingBase,
   buildingCommonMethods,
   buildingView,
@@ -15,7 +16,7 @@ const base = buildingBase('Transporter');
 const buildingIdRequestBody = requestBodySchema({
   type: 'object',
   required: ['building_id'],
-  properties: { building_id: { type: 'integer' } },
+  properties: { building_id: { type: 'integer', description: 'The unique id of the building.' } },
 });
 
 // A tradeable/pushable item — resources (name/quantity), glyphs, plans, prisoners, or ships.
@@ -78,11 +79,15 @@ export const transporter = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation(
+        'Add to market.',
+        'Queues a trade for other players to see. Costs 1 essentia in addition to whatever is offered.'
+      ),
       ...requestBodySchema({
         type: 'object',
         required: ['building_id', 'offer', 'ask'],
         properties: {
-          building_id: { type: 'integer' },
+          building_id: { type: 'integer', description: 'The unique id of the building.' },
           offer: {
             type: 'array',
             items: tradeableItemSchema,
@@ -114,6 +119,7 @@ export const transporter = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation('Get ships.', 'Lists ships that may be traded. Used with add_to_market.'),
       ...buildingIdRequestBody,
       responses: {
         ...response200('Lists ships that may be traded. Used with add_to_market.', {
@@ -146,6 +152,10 @@ export const transporter = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation(
+        'Get prisoners.',
+        'Lists prisoners that may be traded. Used with add_to_market.'
+      ),
       ...buildingIdRequestBody,
       responses: {
         ...response200('Lists prisoners that may be traded. Used with add_to_market.', {
@@ -177,6 +187,10 @@ export const transporter = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation(
+        'Get plan summary.',
+        'Lists plans that may be traded, in summary form. Used with add_to_market.'
+      ),
       ...buildingIdRequestBody,
       responses: {
         ...response200(
@@ -211,6 +225,10 @@ export const transporter = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation(
+        'Get glyph summary.',
+        'Summarizes glyphs that may be traded. Used with add_to_market.'
+      ),
       ...buildingIdRequestBody,
       responses: {
         ...response200('Summarizes glyphs that may be traded. Used with add_to_market.', {
@@ -237,10 +255,17 @@ export const transporter = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation(
+        'Withdraw from market.',
+        'Removes a trade this empire posted and retrieves the offered items.'
+      ),
       ...requestBodySchema({
         type: 'object',
         required: ['building_id', 'trade_id'],
-        properties: { building_id: { type: 'integer' }, trade_id: { type: 'integer' } },
+        properties: {
+          building_id: { type: 'integer', description: 'The unique id of the building.' },
+          trade_id: { type: 'integer', description: 'The unique id of the trade.' },
+        },
       }),
       responses: {
         ...response200('Removes a trade this empire posted and retrieves the offered items.', {
@@ -257,10 +282,17 @@ export const transporter = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation(
+        'Accept from market.',
+        'Accepts a trade offer from view_market. Costs the asking price plus 1 essentia. Throws 1016.'
+      ),
       ...requestBodySchema({
         type: 'object',
         required: ['building_id', 'trade_id'],
-        properties: { building_id: { type: 'integer' }, trade_id: { type: 'integer' } },
+        properties: {
+          building_id: { type: 'integer', description: 'The unique id of the building.' },
+          trade_id: { type: 'integer', description: 'The unique id of the trade.' },
+        },
       }),
       responses: {
         ...response200(
@@ -276,15 +308,17 @@ export const transporter = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation('View market.', 'Lists trades currently available to accept.'),
       ...requestBodySchema({
         type: 'object',
         required: ['building_id'],
         properties: {
-          building_id: { type: 'integer' },
+          building_id: { type: 'integer', description: 'The unique id of the building.' },
           page_number: { type: 'integer', description: 'Defaults to 1. 25 items per page.' },
           filter: {
             type: 'string',
             enum: ['food', 'ore', 'water', 'waste', 'energy', 'glyph', 'prisoner', 'ship', 'plan'],
+            description: 'Optional. Narrows the list to trades offering one kind of object.',
           },
         },
       }),
@@ -308,11 +342,12 @@ export const transporter = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation('View my market.', 'Lists trades this empire has posted.'),
       ...requestBodySchema({
         type: 'object',
         required: ['building_id'],
         properties: {
-          building_id: { type: 'integer' },
+          building_id: { type: 'integer', description: 'The unique id of the building.' },
           page_number: { type: 'integer', description: 'Defaults to 1. 25 items per page.' },
         },
       }),
@@ -336,6 +371,10 @@ export const transporter = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation(
+        'Get stored resources.',
+        'Lists resources in storage, to make it easier to decide what to trade.'
+      ),
       ...buildingIdRequestBody,
       responses: {
         ...response200('Lists resources in storage, to make it easier to decide what to trade.', {
@@ -356,11 +395,15 @@ export const transporter = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation(
+        'Push items.',
+        'Instantly sends resources/items to another planet this empire owns.'
+      ),
       ...requestBodySchema({
         type: 'object',
         required: ['building_id', 'target_id', 'items'],
         properties: {
-          building_id: { type: 'integer' },
+          building_id: { type: 'integer', description: 'The unique id of the building.' },
           target_id: { type: 'integer', description: 'A planet controlled by this empire.' },
           items: {
             type: 'array',
@@ -384,17 +427,21 @@ export const transporter = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation(
+        'Trade one for one.',
+        'Trades any resource for another one-for-one, in exchange for 3 essentia.'
+      ),
       ...requestBodySchema({
         type: 'object',
         required: ['building_id', 'have', 'want', 'quantity'],
         properties: {
-          building_id: { type: 'integer' },
+          building_id: { type: 'integer', description: 'The unique id of the building.' },
           have: {
             type: 'string',
             description: 'The resource type this empire has. See get_stored_resources.',
           },
           want: { type: 'string', description: 'The resource type this empire wants.' },
-          quantity: { type: 'integer' },
+          quantity: { type: 'integer', description: 'How many to process. Defaults to 1.' },
         },
       }),
       responses: {
@@ -412,10 +459,14 @@ export const transporter = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation('Report abuse.', 'Reports a trade suspected of abusing the trade system.'),
       ...requestBodySchema({
         type: 'object',
         required: ['building_id', 'trade_id'],
-        properties: { building_id: { type: 'integer' }, trade_id: { type: 'integer' } },
+        properties: {
+          building_id: { type: 'integer', description: 'The unique id of the building.' },
+          trade_id: { type: 'integer', description: 'The unique id of the trade.' },
+        },
       }),
       responses: {
         ...response200('Reports a trade suspected of abusing the trade system.', {
diff --git a/src/spec/paths/buildings/wasteexchanger.ts b/src/spec/paths/buildings/wasteexchanger.ts
index 906821f..a441b30 100644
--- a/src/spec/paths/buildings/wasteexchanger.ts
+++ b/src/spec/paths/buildings/wasteexchanger.ts
@@ -1,4 +1,5 @@
 import {
+  operation,
   buildingBase,
   buildingCommonMethods,
   buildingView,
@@ -62,11 +63,15 @@ export const wasteExchanger = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation(
+        'Recycle.',
+        "Converts waste into water, ore, and energy. The total requested must not exceed the waste in storage. Returns the building's view."
+      ),
       ...requestBodySchema({
         type: 'object',
         required: ['building_id', 'water', 'ore', 'energy'],
         properties: {
-          building_id: { type: 'integer' },
+          building_id: { type: 'integer', description: 'The unique id of the building.' },
           water: { type: 'integer', description: 'Amount of water to produce from waste.' },
           ore: { type: 'integer', description: 'Amount of ore to produce from waste.' },
           energy: { type: 'integer', description: 'Amount of energy to produce from waste.' },
@@ -88,10 +93,16 @@ export const wasteExchanger = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation(
+        'Subsidize recycling.',
+        "Spends 2 essentia to complete the current recycling job immediately. Returns the building's view."
+      ),
       ...requestBodySchema({
         type: 'object',
         required: ['building_id'],
-        properties: { building_id: { type: 'integer' } },
+        properties: {
+          building_id: { type: 'integer', description: 'The unique id of the building.' },
+        },
       }),
       responses: recycleResultSchema(
         "Spends 2 essentia to complete the current recycling job immediately. Returns the building's view."
diff --git a/src/spec/paths/buildings/wasterecycling.ts b/src/spec/paths/buildings/wasterecycling.ts
index 1339470..fc46117 100644
--- a/src/spec/paths/buildings/wasterecycling.ts
+++ b/src/spec/paths/buildings/wasterecycling.ts
@@ -1,4 +1,5 @@
 import {
+  operation,
   buildingBase,
   buildingCommonMethods,
   buildingView,
@@ -62,11 +63,15 @@ export const wasteRecycling = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation(
+        'Recycle.',
+        "Converts waste into water, ore, and energy. The total requested must not exceed the waste in storage. Returns the building's view."
+      ),
       ...requestBodySchema({
         type: 'object',
         required: ['building_id', 'water', 'ore', 'energy'],
         properties: {
-          building_id: { type: 'integer' },
+          building_id: { type: 'integer', description: 'The unique id of the building.' },
           water: { type: 'integer', description: 'Amount of water to produce from waste.' },
           ore: { type: 'integer', description: 'Amount of ore to produce from waste.' },
           energy: { type: 'integer', description: 'Amount of energy to produce from waste.' },
@@ -88,10 +93,16 @@ export const wasteRecycling = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation(
+        'Subsidize recycling.',
+        "Spends 2 essentia to complete the current recycling job immediately. Returns the building's view."
+      ),
       ...requestBodySchema({
         type: 'object',
         required: ['building_id'],
-        properties: { building_id: { type: 'integer' } },
+        properties: {
+          building_id: { type: 'integer', description: 'The unique id of the building.' },
+        },
       }),
       responses: recycleResultSchema(
         "Spends 2 essentia to complete the current recycling job immediately. Returns the building's view."
diff --git a/src/spec/paths/buildings/waterstorage.ts b/src/spec/paths/buildings/waterstorage.ts
index 8eafe05..b30dc09 100644
--- a/src/spec/paths/buildings/waterstorage.ts
+++ b/src/spec/paths/buildings/waterstorage.ts
@@ -1,4 +1,5 @@
 import {
+  operation,
   buildingBase,
   buildingCommonMethods,
   buildingView,
@@ -20,11 +21,12 @@ export const waterStorage = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation('Dump water as waste.', 'Converts water into waste.'),
       ...requestBodySchema({
         type: 'object',
         required: ['building_id', 'amount'],
         properties: {
-          building_id: { type: 'integer' },
+          building_id: { type: 'integer', description: 'The unique id of the building.' },
           amount: { type: 'integer', description: 'Amount of water to convert into waste.' },
         },
       }),
diff --git a/src/spec/paths/captcha.ts b/src/spec/paths/captcha.ts
index 6d5f0da..84f73d6 100644
--- a/src/spec/paths/captcha.ts
+++ b/src/spec/paths/captcha.ts
@@ -1,4 +1,11 @@
-import { requestBodySchema, response200, response500, security, tags } from '../chunks.ts';
+import {
+  operation,
+  requestBodySchema,
+  response200,
+  response500,
+  security,
+  tags,
+} from '../chunks.ts';
 
 // This is the standalone Captcha module (`/captcha`). Distinct from `/v2/empire/fetch_captcha`,
 // which is a separate, unauthenticated captcha flow used specifically for account creation.
@@ -7,6 +14,10 @@ export const captcha = {
     post: {
       ...tags('captcha'),
       ...security(),
+      ...operation(
+        'Fetch a captcha.',
+        "Retrieves a captcha that is required in order to call the solve method. Display the resulting captcha and then call solve with the user's response."
+      ),
 
       responses: {
         ...response200(
@@ -26,13 +37,23 @@ export const captcha = {
     post: {
       ...tags('captcha'),
       ...security(),
+      ...operation(
+        'Solve a captcha.',
+        "Validates the user's solution against the known solution for the given guid. On success the captcha stays valid for thirty minutes and this returns 1. A captcha cannot be used more than once; on a mismatch it throws 1014, with fresh captcha data in the error data that must be used for the next attempt."
+      ),
 
       ...requestBodySchema({
         type: 'object',
         required: ['guid', 'solution'],
         properties: {
-          guid: { type: 'string', description: 'Must match the guid from fetch.' },
-          solution: { type: 'string', description: "The user's typed solution." },
+          guid: {
+            type: 'string',
+            description: 'Must match the guid field returned by the fetch method.',
+          },
+          solution: {
+            type: 'string',
+            description: 'The text typed in by the user as the solution of the captcha.',
+          },
         },
       }),
 
diff --git a/src/spec/paths/empire.ts b/src/spec/paths/empire.ts
index e997665..9660669 100644
--- a/src/spec/paths/empire.ts
+++ b/src/spec/paths/empire.ts
@@ -1,4 +1,5 @@
 import {
+  operation,
   tags,
   requestBodySchema,
   response200,
@@ -45,6 +46,10 @@ export const empire = {
   '/v2/empire/is_name_available': {
     post: {
       ...tags('empire'),
+      ...operation(
+        'Check whether an empire name is available.',
+        'Returns 1 if the name is available, or throws an exception if it is not. Throws 1000.'
+      ),
       responses: {
         ...response200(
           'Returns a 1 if the name is available, or throws an exception if it is not. Throws 1000.',
@@ -67,6 +72,7 @@ export const empire = {
     post: {
       ...tags('empire'),
       ...security(),
+      ...operation('End the current session.', 'Ends a session. Returns 1. Throws 1006.'),
 
       responses: {
         ...response200('Ends a session. Returns 1. Throws 1006.', { type: 'integer', enum: [1] }),
@@ -78,6 +84,10 @@ export const empire = {
   '/v2/empire/login': {
     post: {
       ...tags('empire'),
+      ...operation(
+        'Log in to an empire and start a session.',
+        'Confirms the password matches the empire and returns a session id alongside the empire and server status. A session survives up to 2 hours of inactivity, so there is no need to log in again while an existing session is still valid. Throws 1004 and 1005.'
+      ),
       responses: {
         ...response200(
           'Confirms the password matches the empire and returns a session id alongside the empire and server status. A session survives up to 2 hours of inactivity, so there is no need to log in again while an existing session is still valid. Throws 1004 and 1005.',
@@ -118,6 +128,10 @@ export const empire = {
   '/v2/empire/fetch_captcha': {
     post: {
       ...tags('empire'),
+      ...operation(
+        'Fetch a captcha for empire creation.',
+        "Retrieves a captcha that is required in order to call the create method. Display the resulting captcha in your creation form and then call create with the user's response."
+      ),
       responses: {
         ...response200(
           "Retrieves a captcha that is required in order to call the create method. Display the resulting captcha in your creation form and then call create with the user's response.",
@@ -135,6 +149,10 @@ export const empire = {
   '/v2/empire/create': {
     post: {
       ...tags('empire'),
+      ...operation(
+        'Create a new empire.',
+        'Creates a new empire and returns its empire_id. The empire is not playable yet — either call update_species and then found, or skip the species step and call found directly. Throws 1000, 1001, 1002, and 1014. On a 1014 the error data carries fresh captcha information that must be used for the next attempt, since a captcha cannot be used more than once.'
+      ),
       responses: {
         ...response200(
           'Creates a new empire and returns its empire_id. The empire is not playable yet — either call update_species and then found, or skip the species step and call found directly. Throws 1000, 1001, 1002, and 1014. On a 1014 the error data carries fresh captcha information that must be used for the next attempt, since a captcha cannot be used more than once.',
@@ -194,6 +212,10 @@ export const empire = {
   '/v2/empire/found': {
     post: {
       ...tags('empire'),
+      ...operation(
+        'Found an empire on its home world.',
+        'Sets up an empire on its new home world. Once this method is called, the species can no longer be modified. The returned welcome_message_id identifies an inbox message that starts the tutorial, so the user can be prompted to read it right away.'
+      ),
       responses: {
         ...response200(
           'Sets up an empire on its new home world. Once this method is called, the species can no longer be modified. The returned welcome_message_id identifies an inbox message that starts the tutorial, so the user can be prompted to read it right away.',
@@ -233,6 +255,10 @@ export const empire = {
     post: {
       ...tags('empire'),
       ...security(),
+      ...operation(
+        'Get a referral URL for inviting friends.',
+        'Returns a URL that can be pasted into a blog, forum, or whatever to invite friends.'
+      ),
 
       responses: {
         ...response200(
@@ -252,6 +278,10 @@ export const empire = {
     post: {
       ...tags('empire'),
       ...security(),
+      ...operation(
+        'Email a friend an invitation code.',
+        'Sends an invitation code to a friend so that they can start in the same zone as your empire.'
+      ),
 
       responses: {
         ...response200(
@@ -299,6 +329,10 @@ export const empire = {
     post: {
       ...tags('empire'),
       ...security(),
+      ...operation(
+        'Get the current state of the empire.',
+        'Returns information about the current state of the empire. You should probably never call this directly — it is a wasted call, since the same data comes back in the status block of every relevant request. Throws 1002.'
+      ),
 
       responses: {
         ...response200(
@@ -321,6 +355,10 @@ export const empire = {
     post: {
       ...tags('empire'),
       ...security(),
+      ...operation(
+        'View the editable empire profile.',
+        "Provides a list of the editable properties of the current empire's profile. See also the edit_profile and view_public_profile methods."
+      ),
 
       responses: {
         ...response200(
@@ -395,6 +433,10 @@ export const empire = {
     post: {
       ...tags('empire'),
       ...security(),
+      ...operation(
+        'Edit the empire profile.',
+        'Edits properties of an empire. Returns the same payload as view_profile. Only the properties present in the request are updated. Throws 1005 and 1009.'
+      ),
 
       responses: {
         ...response200(
@@ -611,6 +653,10 @@ export const empire = {
     post: {
       ...tags('empire'),
       ...security(),
+      ...operation(
+        "View another empire's public profile.",
+        'Provides a list of the data that is publicly known about an empire. Throws 1002.'
+      ),
 
       responses: {
         ...response200(
@@ -772,6 +818,10 @@ export const empire = {
   '/v2/empire/send_password_reset_message': {
     post: {
       ...tags('empire'),
+      ...operation(
+        'Start a password recovery.',
+        'Starts a password recovery process by sending an email with a recovery key. Identify the empire by exactly one of empire_id, empire_name, or email.'
+      ),
       responses: {
         ...response200(
           'Starts a password recovery process by sending an email with a recovery key. Identify the empire by exactly one of empire_id, empire_name, or email.',
@@ -811,6 +861,10 @@ export const empire = {
   '/v2/empire/reset_password': {
     post: {
       ...tags('empire'),
+      ...operation(
+        'Reset a forgotten password.',
+        'Changes an empire password that has been forgotten, using the key emailed by send_password_reset_message. Returns the same response as login if successful.'
+      ),
       responses: {
         ...response200(
           'Change the empire password that has been forgotten. Returns the same response as `login` if successful.',
@@ -855,6 +909,7 @@ export const empire = {
     post: {
       ...tags('empire'),
       ...security(),
+      ...operation('Change the empire password.', 'Changes the empire password.'),
 
       responses: {
         ...response200('Change the empire password.', {
@@ -887,6 +942,10 @@ export const empire = {
     post: {
       ...tags('empire'),
       ...security(),
+      ...operation(
+        'Find empires by name.',
+        'Finds empires by name. Returns a hash reference containing empire ids and empire names.'
+      ),
 
       responses: {
         ...response200(
@@ -928,6 +987,10 @@ export const empire = {
     post: {
       ...tags('empire'),
       ...security(),
+      ...operation(
+        'Set the empire status message.',
+        'Sets the empire status message, similar to what you might put on your Facebook wall or in a tweet, but about your empire.'
+      ),
 
       responses: {
         ...response200(
@@ -955,6 +1018,10 @@ export const empire = {
     post: {
       ...tags('empire'),
       ...security(),
+      ...operation(
+        'View boost expiry dates.',
+        'Shows the dates at which boosts have expired or will expire. Boosts are subsidies applied to various resources using essentia.'
+      ),
 
       responses: {
         ...response200(
@@ -974,6 +1041,10 @@ export const empire = {
     post: {
       ...tags('empire'),
       ...security(),
+      ...operation(
+        'Boost storage on all planets for a week.',
+        'Spends 5 essentia and boosts storage (all 5 types) on all planets for 7 days. If a boost is already underway, calling again adds 7 more days. Throws 1011.'
+      ),
 
       responses: {
         ...response200(
@@ -1006,6 +1077,10 @@ export const empire = {
     post: {
       ...tags('empire'),
       ...security(),
+      ...operation(
+        'Boost food production on all planets for a week.',
+        'Spends 5 essentia and boosts food production on all planets for 7 days. If a boost is already underway, calling again adds 7 more days. Throws 1011.'
+      ),
 
       responses: {
         ...response200(
@@ -1038,6 +1113,10 @@ export const empire = {
     post: {
       ...tags('empire'),
       ...security(),
+      ...operation(
+        'Boost water production on all planets for a week.',
+        'Spends 5 essentia and boosts water production on all planets for 7 days. If a boost is already underway, calling again adds 7 more days. Throws 1011.'
+      ),
 
       responses: {
         ...response200(
@@ -1070,6 +1149,10 @@ export const empire = {
     post: {
       ...tags('empire'),
       ...security(),
+      ...operation(
+        'Boost energy production on all planets for a week.',
+        'Spends 5 essentia and boosts energy production on all planets for 7 days. If a boost is already underway, calling again adds 7 more days. Throws 1011.'
+      ),
 
       responses: {
         ...response200(
@@ -1102,6 +1185,10 @@ export const empire = {
     post: {
       ...tags('empire'),
       ...security(),
+      ...operation(
+        'Boost ore production on all planets for a week.',
+        'Spends 5 essentia and boosts ore production on all planets for 7 days. If a boost is already underway, calling again adds 7 more days. Throws 1011.'
+      ),
 
       responses: {
         ...response200(
@@ -1134,6 +1221,10 @@ export const empire = {
     post: {
       ...tags('empire'),
       ...security(),
+      ...operation(
+        'Boost happiness production on all planets for a week.',
+        'Spends 5 essentia and boosts happiness production on all planets for 7 days. If a boost is already underway, calling again adds 7 more days. Throws 1011.'
+      ),
 
       responses: {
         ...response200(
@@ -1166,6 +1257,10 @@ export const empire = {
     post: {
       ...tags('empire'),
       ...security(),
+      ...operation(
+        'Boost build queues on all planets for a week.',
+        'Spends 5 essentia and boosts build queues on all planets for 7 days. If a boost is already underway, calling again adds 7 more days. It does not speed up builds already under way, only new builds added to a queue. Throws 1011.'
+      ),
 
       responses: {
         ...response200(
@@ -1198,6 +1293,10 @@ export const empire = {
     post: {
       ...tags('empire'),
       ...security(),
+      ...operation(
+        'Boost spy training on all planets for a week.',
+        'Spends 5 essentia and boosts spy training speed on all planets by 50% for 7 days. If a boost is already underway, calling again adds 7 more days. Unlike the other boosts, this one also speeds up spies already in specialist training. Throws 1011.'
+      ),
 
       responses: {
         ...response200(
@@ -1230,6 +1329,10 @@ export const empire = {
     post: {
       ...tags('empire'),
       ...security(),
+      ...operation(
+        'Start the self destruct countdown.',
+        'Enables a destruction countdown of 24 hours. Sometime after the timer runs out, the empire will vaporize.'
+      ),
 
       responses: {
         ...response200(
@@ -1245,6 +1348,10 @@ export const empire = {
     post: {
       ...tags('empire'),
       ...security(),
+      ...operation(
+        'Cancel the self destruct countdown.',
+        'Disables the self destruction countdown.'
+      ),
 
       responses: {
         ...response200('Disables the self destruction countdown.', {
@@ -1261,6 +1368,10 @@ export const empire = {
     post: {
       ...tags('empire'),
       ...security(),
+      ...operation(
+        'Redeem an essentia code.',
+        "Redeems an essentia code and applies the essentia to the empire's balance."
+      ),
 
       responses: {
         ...response200(
@@ -1291,6 +1402,10 @@ export const empire = {
     post: {
       ...tags('empire'),
       ...security(),
+      ...operation(
+        'Update the species before founding.',
+        "Updates the empire's species and returns 1. Can only be called after create and before found; calling it outside that window throws an exception. Use redefine_species once the empire is founded. Throws 1000, 1002, 1005, 1007, 1008, 1009, and 1010; the error data carries the offending field name when the problem can be attributed to a single field."
+      ),
 
       responses: {
         ...response200(
@@ -1321,6 +1436,10 @@ export const empire = {
   '/v2/empire/redefine_species_limits': {
     post: {
       ...tags('empire'),
+      ...operation(
+        'View the limits on redefining a species.',
+        'Returns the extra limits placed on an empire that wants to redefine its species, including the essentia cost, the settable orbit range, the minimum growth affinity, and whether a redefinition is currently allowed.'
+      ),
       responses: {
         ...response200(
           'Returns the extra limits placed upon an empire that wants to redefine its species, including the essentia cost, the settable orbit range, the minimum growth affinity, and whether a redefinition is currently allowed at all.',
@@ -1347,6 +1466,10 @@ export const empire = {
     post: {
       ...tags('empire'),
       ...security(),
+      ...operation(
+        'Redefine the species after founding.',
+        "Spends essentia to redefine the empire's species affinities, name, and description. Only usable after the empire is founded; use update_species during creation. Once done it cannot be redone for one month, so prompt the user before submitting."
+      ),
 
       responses: {
         ...response200(
@@ -1374,6 +1497,10 @@ export const empire = {
     post: {
       ...tags('empire'),
       ...security(),
+      ...operation(
+        'View your species stats.',
+        "Returns the stats associated with the empire's species as it was originally created. An empire can only view its own species stats through this method."
+      ),
 
       responses: {
         ...response200(
@@ -1392,6 +1519,10 @@ export const empire = {
   '/v2/empire/get_species_templates': {
     post: {
       ...tags('empire'),
+      ...operation(
+        'List species templates.',
+        'Returns the list of species templates that can be used to help the user populate the form for update_species.'
+      ),
       responses: {
         ...response200(
           'Returns the list of species templates that can be used to help the user populate the form for update_species.',
@@ -1406,6 +1537,10 @@ export const empire = {
     post: {
       ...tags('empire'),
       ...security(),
+      ...operation(
+        'List authorized sitters.',
+        'Returns the empires currently authorized to sit for this account.'
+      ),
 
       responses: {
         ...response200('Lists the empires currently authorized to sit for this empire.', {
@@ -1436,6 +1571,10 @@ export const empire = {
     post: {
       ...tags('empire'),
       ...security(),
+      ...operation(
+        'Authorize sitters for this account.',
+        'Authorizes other empires to babysit this account. Each authorization is created if needed and granted for the full server-defined period. Returns the authorized sitters plus any rejected ids.'
+      ),
 
       responses: {
         ...response200(
@@ -1504,6 +1643,10 @@ export const empire = {
     post: {
       ...tags('empire'),
       ...security(),
+      ...operation(
+        'Remove authorized sitters.',
+        'Removes sitters from being permitted to sit this account.'
+      ),
 
       responses: {
         ...response200('Removes sitters from being permitted to sit this account.', {
diff --git a/src/spec/paths/inbox.ts b/src/spec/paths/inbox.ts
index c7d54ee..39ed308 100644
--- a/src/spec/paths/inbox.ts
+++ b/src/spec/paths/inbox.ts
@@ -1,4 +1,5 @@
 import {
+  operation,
   requestBodySchema,
   response200,
   response500,
@@ -59,10 +60,21 @@ const viewInboxRequestBody = requestBodySchema({
   properties: {
     options: {
       type: 'object',
+      description: 'Optional extra options.',
       properties: {
-        page_number: { type: 'integer' },
-        tags: { type: 'array', items: { type: 'string', enum: MESSAGE_TAGS } },
-        empire: { type: 'string' },
+        page_number: {
+          type: 'integer',
+          description: 'Which page of messages to view. 25 per page. Defaults to 1.',
+        },
+        tags: {
+          type: 'array',
+          items: { type: 'string', enum: MESSAGE_TAGS },
+          description: 'Only messages carrying at least one of these tags are returned.',
+        },
+        empire: {
+          type: 'string',
+          description: 'The name or id of a baby empire whose inbox to view.',
+        },
       },
     },
   },
@@ -86,6 +98,10 @@ export const inbox = {
     post: {
       ...tags('inbox'),
       ...security(),
+      ...operation(
+        'List inbox messages.',
+        "Displays a list of the messages in the empire's inbox, 25 per page, sorted newest to oldest. Throws 1002 and 1006."
+      ),
       ...viewInboxRequestBody,
       responses: viewInboxResponses(
         "Displays a list of the messages in the empire's inbox, 25 per page, newest to oldest."
@@ -97,6 +113,10 @@ export const inbox = {
     post: {
       ...tags('inbox'),
       ...security(),
+      ...operation(
+        'List archived messages.',
+        'Exactly the same as view_inbox, except it shows archived messages instead.'
+      ),
       ...viewInboxRequestBody,
       responses: viewInboxResponses('Same as view_inbox, but shows archived messages.'),
     },
@@ -106,6 +126,10 @@ export const inbox = {
     post: {
       ...tags('inbox'),
       ...security(),
+      ...operation(
+        'List trashed messages.',
+        'Exactly the same as view_inbox, except it shows trashed messages instead.'
+      ),
       ...viewInboxRequestBody,
       responses: viewInboxResponses('Same as view_inbox, but shows trashed messages.'),
     },
@@ -115,6 +139,10 @@ export const inbox = {
     post: {
       ...tags('inbox'),
       ...security(),
+      ...operation(
+        'List sent messages.',
+        'Exactly the same as view_inbox, except it shows sent messages instead.'
+      ),
       ...viewInboxRequestBody,
       responses: viewInboxResponses('Same as view_inbox, but shows sent messages.'),
     },
@@ -124,6 +152,10 @@ export const inbox = {
     post: {
       ...tags('inbox'),
       ...security(),
+      ...operation(
+        'List unread messages.',
+        'Exactly the same as view_inbox, except it shows only the unread messages in the inbox.'
+      ),
       ...viewInboxRequestBody,
       responses: viewInboxResponses('Same as view_inbox, but shows only unread messages.'),
     },
@@ -133,11 +165,20 @@ export const inbox = {
     post: {
       ...tags('inbox'),
       ...security(),
+      ...operation(
+        'Read a message.',
+        'Retrieves a message and marks it read if it was not already. Throws 1002, 1006, and 1010.'
+      ),
 
       ...requestBodySchema({
         type: 'object',
         required: ['message_id'],
-        properties: { message_id: { type: 'integer' } },
+        properties: {
+          message_id: {
+            type: 'integer',
+            description: 'A message id returned by view_inbox or one of the other view_ methods.',
+          },
+        },
       }),
 
       responses: {
@@ -178,13 +219,16 @@ export const inbox = {
                 has_archived: { type: 'integer', enum: [1, 0] },
                 has_trashed: { type: 'integer', enum: [1, 0] },
                 in_reply_to: { type: 'integer' },
-                // The complete list of empires who received the message. `to`/`to_id` above is
-                // just the empire that owns this particular copy of the message.
-                recipients: { type: 'array', items: { type: 'integer' } },
+                recipients: {
+                  type: 'array',
+                  items: { type: 'integer' },
+                  description:
+                    'The complete list of empires who received the message. `to`/`to_id` above is just the empire that owns this particular copy of the message.',
+                },
                 tags: { type: 'array', items: { type: 'string', enum: MESSAGE_TAGS } },
-                // No more than one of each attachment type per message.
                 attachments: {
                   type: 'object',
+                  description: 'At most one of each attachment type per message.',
                   properties: {
                     image: {
                       type: 'object',
@@ -237,10 +281,21 @@ export const inbox = {
       ...tags('inbox'),
       ...security(),
 
+      ...operation(
+        'Archive messages.',
+        'Archives a list of messages, marking them read in the process. Sent messages cannot be archived; a message that is already archived or otherwise un-archivable is returned in failure.'
+      ),
+
       ...requestBodySchema({
         type: 'object',
         required: ['message_ids'],
-        properties: { message_ids: { type: 'array', items: { type: 'integer' } } },
+        properties: {
+          message_ids: {
+            type: 'array',
+            items: { type: 'integer' },
+            description: 'The message ids to archive.',
+          },
+        },
       }),
 
       responses: {
@@ -266,10 +321,21 @@ export const inbox = {
       ...tags('inbox'),
       ...security(),
 
+      ...operation(
+        'Trash messages.',
+        'Trashes a list of messages, marking them read in the process. Only messages sent to you can be trashed.'
+      ),
+
       ...requestBodySchema({
         type: 'object',
         required: ['message_ids'],
-        properties: { message_ids: { type: 'array', items: { type: 'integer' } } },
+        properties: {
+          message_ids: {
+            type: 'array',
+            items: { type: 'integer' },
+            description: 'The message ids to trash.',
+          },
+        },
       }),
 
       responses: {
@@ -293,6 +359,10 @@ export const inbox = {
     post: {
       ...tags('inbox'),
       ...security(),
+      ...operation(
+        'Trash messages matching a spec.',
+        'Trashes every message that matches all keys of at least one spec entry, marking them read in the process. It is an error to supply an empty spec.'
+      ),
 
       ...requestBodySchema({
         type: 'object',
@@ -300,19 +370,35 @@ export const inbox = {
         properties: {
           spec: {
             type: 'array',
+            description:
+              'A list of match specifications. A message must match every key of an entry to be trashed; entries are OR-ed together. Use a subject of "%" to match all non-archived messages.',
             items: {
               type: 'object',
               properties: {
-                tags: { type: 'array', items: { type: 'string', enum: MESSAGE_TAGS } },
+                tags: {
+                  type: 'array',
+                  items: { type: 'string', enum: MESSAGE_TAGS },
+                  description:
+                    'A message carrying any of these tags is eligible. Defaults to all tags.',
+                },
                 subject: {
                   oneOf: [{ type: 'string' }, { type: 'array', items: { type: 'string' } }],
-                  description: 'Use % as a wildcard, e.g. "Pass:%".',
+                  description:
+                    'A subject to match. Use % as a wildcard, e.g. "Pass:%". An array is treated as a set of exact subjects, OR-ed together. Defaults to any subject.',
+                },
+                from: {
+                  type: 'array',
+                  items: { type: 'string' },
+                  description: 'Full empire names. A message from any of these is eligible.',
                 },
-                from: { type: 'array', items: { type: 'string' } },
               },
             },
           },
-          return_ids: { type: 'boolean' },
+          return_ids: {
+            type: 'boolean',
+            description:
+              'When true, the trashed message ids are gathered and returned in `deleted`. Off by default, since gathering them adds server work and response size; `deleted_count` is returned either way.',
+          },
         },
       }),
 
@@ -342,6 +428,10 @@ export const inbox = {
     post: {
       ...tags('inbox'),
       ...security(),
+      ...operation(
+        'Send a message to other players.',
+        'Sends a message to other players. Throws 1002, 1005, and 1006.'
+      ),
 
       ...requestBodySchema({
         type: 'object',
@@ -352,16 +442,30 @@ export const inbox = {
             description:
               'Comma separated empire names. "@ally" is a shortcut for all members of your alliance.',
           },
-          subject: { type: 'string', maxLength: 100 },
-          body: { type: 'string', maxLength: 200000 },
+          subject: {
+            type: 'string',
+            maxLength: 100,
+            description:
+              'A subject for the message. Fewer than 100 characters and cannot contain &, @, ;, <, or >.',
+          },
+          body: {
+            type: 'string',
+            maxLength: 200000,
+            description:
+              'The body of the message. Fewer than 200,000 characters and cannot contain < or >.',
+          },
           options: {
             type: 'object',
+            description: 'Optional extra options.',
             properties: {
-              in_reply_to: { type: 'integer' },
+              in_reply_to: {
+                type: 'integer',
+                description: 'The id of the message this one is in reply to, if any.',
+              },
               forward: {
                 type: 'integer',
                 description:
-                  'A message id whose attachments should be sent along with this message.',
+                  'A message id whose attachments should be sent along with this message. The original text is not forwarded; include it in the body yourself if you want it.',
               },
             },
           },
diff --git a/src/spec/paths/map.ts b/src/spec/paths/map.ts
index 3ed9770..3ee9bd7 100644
--- a/src/spec/paths/map.ts
+++ b/src/spec/paths/map.ts
@@ -1,4 +1,5 @@
 import {
+  operation,
   requestBodySchema,
   response200,
   response500,
@@ -41,10 +42,15 @@ const bodySnippetSchema = {
     type: { type: 'string' },
     image: { type: 'string' },
     size: { type: 'number' },
-    // Only present if the body is occupied by an empire.
-    empire: empireSnippetSchema,
-    // Only present on asteroids/bodies that have a fissure.
-    body_has_fissure: { type: 'integer', enum: [1, 0] },
+    empire: {
+      ...empireSnippetSchema,
+      description: 'Only present if the body is occupied by an empire.',
+    },
+    body_has_fissure: {
+      type: 'integer',
+      enum: [1, 0],
+      description: 'Only present on asteroids or bodies that have a fissure.',
+    },
   },
 };
 
@@ -59,10 +65,15 @@ const starDetailSchema = {
     zone: { type: 'string' },
     influence: { type: 'number' },
     id: { type: 'integer' },
-    // Only present if this star is under the influence of a space station.
-    station: stationSnippetSchema,
-    // Only present if a probe is present in the system.
-    bodies: { type: 'array', items: { $ref: '#/components/schemas/body_status' } },
+    station: {
+      ...stationSnippetSchema,
+      description: 'Only present if this star is under the influence of a space station.',
+    },
+    bodies: {
+      type: 'array',
+      items: { $ref: '#/components/schemas/body_status' },
+      description: 'Only present if a probe is present in the system.',
+    },
   },
 };
 
@@ -80,15 +91,19 @@ export const map = {
     post: {
       ...tags('map'),
       ...security(),
+      ...operation(
+        'Draw the star map (lite).',
+        'The preferred, lite way to get star data for drawing the star map — it returns just enough to render it, omitting most owned-planet detail such as ore and water and the station-influence block. The maximum area that can be returned is 1001 units (e.g. 50x20 or 1001x1).'
+      ),
 
       ...requestBodySchema({
         type: 'object',
         required: ['left', 'top', 'right', 'bottom'],
         properties: {
-          left: { type: 'number' },
-          top: { type: 'number' },
-          right: { type: 'number' },
-          bottom: { type: 'number' },
+          left: { type: 'number', description: 'The left edge of the bounding rectangle.' },
+          top: { type: 'number', description: 'The top edge of the bounding rectangle.' },
+          right: { type: 'number', description: 'The right edge of the bounding rectangle.' },
+          bottom: { type: 'number', description: 'The bottom edge of the bounding rectangle.' },
         },
       }),
 
@@ -115,9 +130,10 @@ export const map = {
                       type: 'number',
                       description: 'May be null when the star is outside any station jurisdiction.',
                     },
-                    // Only present if this star is under the influence of a space station.
                     station: {
                       type: 'object',
+                      description:
+                        'Only present if this star is under the influence of a space station.',
                       required: ['id', 'x', 'y', 'name', 'alliance'],
                       properties: {
                         id: { type: 'integer' },
@@ -151,15 +167,19 @@ export const map = {
     post: {
       ...tags('map'),
       ...security(),
+      ...operation(
+        'Get a chunk of the star map.',
+        'Retrieves a chunk of the map as an array of stars. Coordinates without a star are omitted. The requested area can be no larger than 900 spaces (30x30). Throws 1003 when the area is too large.'
+      ),
 
       ...requestBodySchema({
         type: 'object',
         required: ['x1', 'y1', 'x2', 'y2'],
         properties: {
-          x1: { type: 'number' },
-          y1: { type: 'number' },
-          x2: { type: 'number' },
-          y2: { type: 'number' },
+          x1: { type: 'number', description: 'The top left x coordinate.' },
+          y1: { type: 'number', description: 'The top left y coordinate.' },
+          x2: { type: 'number', description: 'The bottom right x coordinate.' },
+          y2: { type: 'number', description: 'The bottom right y coordinate.' },
         },
       }),
 
@@ -184,11 +204,15 @@ export const map = {
     post: {
       ...tags('map'),
       ...security(),
+      ...operation(
+        'Check for an inbound probe to a star.',
+        'If a star has a status of "unprobed", call this to find out whether a probe from this empire is on its way.'
+      ),
 
       ...requestBodySchema({
         type: 'object',
         required: ['star_id'],
-        properties: { star_id: { type: 'integer' } },
+        properties: { star_id: { type: 'integer', description: 'The unique id of the star.' } },
       }),
 
       responses: {
@@ -199,8 +223,11 @@ export const map = {
             required: ['status'],
             properties: {
               status: statusSchema(),
-              // Only present if a probe is inbound.
-              incoming_probe: { type: 'string' },
+              incoming_probe: {
+                type: 'string',
+                description:
+                  'The arrival date of the inbound probe. Only present if one is inbound.',
+              },
             },
           }
         ),
@@ -213,10 +240,11 @@ export const map = {
     post: {
       ...tags('map'),
       ...security(),
+      ...operation('Get one star by id.', 'Retrieves info on a single star.'),
       ...requestBodySchema({
         type: 'object',
         required: ['star_id'],
-        properties: { star_id: { type: 'integer' } },
+        properties: { star_id: { type: 'integer', description: 'The unique id of the star.' } },
       }),
       responses: starDetailResponses('Retrieves info on a single star.'),
     },
@@ -226,10 +254,16 @@ export const map = {
     post: {
       ...tags('map'),
       ...security(),
+      ...operation(
+        'Get one star by name.',
+        'Retrieves info on a single star by its exact, case insensitive name.'
+      ),
       ...requestBodySchema({
         type: 'object',
         required: ['name'],
-        properties: { name: { type: 'string' } },
+        properties: {
+          name: { type: 'string', description: 'The exact name of the star. Case insensitive.' },
+        },
       }),
       responses: starDetailResponses(
         'Retrieves info on a single star by its exact (case insensitive) name.'
@@ -241,10 +275,17 @@ export const map = {
     post: {
       ...tags('map'),
       ...security(),
+      ...operation(
+        'Get one star by coordinates.',
+        'Retrieves info on a single star by its coordinates.'
+      ),
       ...requestBodySchema({
         type: 'object',
         required: ['x', 'y'],
-        properties: { x: { type: 'number' }, y: { type: 'number' } },
+        properties: {
+          x: { type: 'number', description: 'The x coordinate of the star.' },
+          y: { type: 'number', description: 'The y coordinate of the star.' },
+        },
       }),
       responses: starDetailResponses('Retrieves info on a single star by coordinates.'),
     },
@@ -254,11 +295,21 @@ export const map = {
     post: {
       ...tags('map'),
       ...security(),
+      ...operation(
+        'Search stars by partial name.',
+        'Searches for stars by partial, case insensitive name. Returns up to 25 results, with no body data.'
+      ),
 
       ...requestBodySchema({
         type: 'object',
         required: ['name'],
-        properties: { name: { type: 'string' } },
+        properties: {
+          name: {
+            type: 'string',
+            description:
+              'A partial name of a star. Case insensitive. Must be at least 3 characters.',
+          },
+        },
       }),
 
       responses: {
@@ -294,6 +345,10 @@ export const map = {
     post: {
       ...tags('map'),
       ...security(),
+      ...operation(
+        'Summarize known fissures in a zone.',
+        "Returns a summary of every body with a fissure known to your own or your alliance's probes in the given zone. Returns an empty object when no fissures are known."
+      ),
 
       ...requestBodySchema({
         type: 'object',
@@ -329,11 +384,15 @@ export const map = {
     post: {
       ...tags('map'),
       ...security(),
+      ...operation(
+        'View the laws controlling a star.',
+        'Pass the id of a star and the laws enacted by the controlling space station are returned.'
+      ),
 
       ...requestBodySchema({
         type: 'object',
         required: ['star_id'],
-        properties: { star_id: { type: 'integer' } },
+        properties: { star_id: { type: 'integer', description: 'The unique id of the star.' } },
       }),
 
       responses: {
diff --git a/src/spec/paths/modules/artmuseum.ts b/src/spec/paths/modules/artmuseum.ts
index 510aa00..9a1af5f 100644
--- a/src/spec/paths/modules/artmuseum.ts
+++ b/src/spec/paths/modules/artmuseum.ts
@@ -1,4 +1,5 @@
 import {
+  operation,
   buildingBase,
   requestBodySchema,
   response200,
@@ -17,10 +18,16 @@ export const artMuseum = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation(
+        "Retrieve this module's properties.",
+        'Retrieves the properties of this module.'
+      ),
       ...requestBodySchema({
         type: 'object',
         required: ['building_id'],
-        properties: { building_id: { type: 'integer' } },
+        properties: {
+          building_id: { type: 'integer', description: 'The unique id of the building.' },
+        },
       }),
       responses: {
         ...response200('Retrieves the properties of this module.', {
diff --git a/src/spec/paths/modules/culinaryinstitute.ts b/src/spec/paths/modules/culinaryinstitute.ts
index 93bdf70..c6684ae 100644
--- a/src/spec/paths/modules/culinaryinstitute.ts
+++ b/src/spec/paths/modules/culinaryinstitute.ts
@@ -1,4 +1,5 @@
 import {
+  operation,
   buildingBase,
   requestBodySchema,
   response200,
@@ -17,10 +18,16 @@ export const culinaryInstitute = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation(
+        "Retrieve this module's properties.",
+        'Retrieves the properties of this module.'
+      ),
       ...requestBodySchema({
         type: 'object',
         required: ['building_id'],
-        properties: { building_id: { type: 'integer' } },
+        properties: {
+          building_id: { type: 'integer', description: 'The unique id of the building.' },
+        },
       }),
       responses: {
         ...response200('Retrieves the properties of this module.', {
diff --git a/src/spec/paths/modules/ibs.ts b/src/spec/paths/modules/ibs.ts
index ac2ac1c..0441b34 100644
--- a/src/spec/paths/modules/ibs.ts
+++ b/src/spec/paths/modules/ibs.ts
@@ -1,4 +1,5 @@
 import {
+  operation,
   buildingBase,
   requestBodySchema,
   response200,
@@ -17,10 +18,16 @@ export const ibs = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation(
+        "Retrieve this module's properties.",
+        'Retrieves the properties of this module.'
+      ),
       ...requestBodySchema({
         type: 'object',
         required: ['building_id'],
-        properties: { building_id: { type: 'integer' } },
+        properties: {
+          building_id: { type: 'integer', description: 'The unique id of the building.' },
+        },
       }),
       responses: {
         ...response200('Retrieves the properties of this module.', {
diff --git a/src/spec/paths/modules/operahouse.ts b/src/spec/paths/modules/operahouse.ts
index a4a16ae..668f131 100644
--- a/src/spec/paths/modules/operahouse.ts
+++ b/src/spec/paths/modules/operahouse.ts
@@ -1,4 +1,5 @@
 import {
+  operation,
   buildingBase,
   requestBodySchema,
   response200,
@@ -17,10 +18,16 @@ export const operaHouse = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation(
+        "Retrieve this module's properties.",
+        'Retrieves the properties of this module.'
+      ),
       ...requestBodySchema({
         type: 'object',
         required: ['building_id'],
-        properties: { building_id: { type: 'integer' } },
+        properties: {
+          building_id: { type: 'integer', description: 'The unique id of the building.' },
+        },
       }),
       responses: {
         ...response200('Retrieves the properties of this module.', {
diff --git a/src/spec/paths/modules/parliament.ts b/src/spec/paths/modules/parliament.ts
index cf8a280..71012b3 100644
--- a/src/spec/paths/modules/parliament.ts
+++ b/src/spec/paths/modules/parliament.ts
@@ -1,4 +1,5 @@
 import {
+  operation,
   buildingBase,
   requestBodySchema,
   response200,
@@ -13,7 +14,7 @@ const base = buildingBase('Parliament');
 const buildingIdRequestBody = requestBodySchema({
   type: 'object',
   required: ['building_id'],
-  properties: { building_id: { type: 'integer' } },
+  properties: { building_id: { type: 'integer', description: 'The unique id of the building.' } },
 });
 
 // Shared shape returned by view_propositions, cast_vote, and every propose_* method.
@@ -49,6 +50,20 @@ const propositionResponses = (description: string) => ({
   ...response500(),
 });
 
+// Turns e.g. "propose_broadcast_on_network19" into "Propose broadcast on Network 19."
+const proposeSummary = (name: string) => {
+  const words = name.replace(/_/g, ' ');
+  return (
+    words.charAt(0).toUpperCase() +
+    words
+      .slice(1)
+      .replace(/\bbhg\b/gi, 'BHG')
+      .replace(/\bbfg\b/gi, 'BFG')
+      .replace(/\bnetwork19\b/gi, 'Network 19') +
+    '.'
+  );
+};
+
 // Builds one `propose_*` (or the `allow_bhg_by_alliance`) endpoint. Every proposition method
 // takes `building_id` plus its own params, and returns the same {status, proposition} shape.
 const proposeMethod = (
@@ -61,10 +76,17 @@ const proposeMethod = (
     post: {
       ...tags(base),
       ...security(),
+      ...operation(proposeSummary(name), description),
       ...requestBodySchema({
         type: 'object',
         required: ['building_id', ...extraRequired],
-        properties: { building_id: { type: 'integer' }, ...extraProperties },
+        properties: {
+          building_id: {
+            type: 'integer',
+            description: 'The unique id of the Parliament building.',
+          },
+          ...extraProperties,
+        },
       }),
       responses: propositionResponses(description),
     },
@@ -80,6 +102,10 @@ export const parliament = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation(
+        "Retrieve this module's properties.",
+        'Retrieves the properties of this module.'
+      ),
       ...buildingIdRequestBody,
       responses: {
         ...response200('Retrieves the properties of this module.', {
@@ -111,6 +137,10 @@ export const parliament = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation(
+        'View laws.',
+        "Lists the laws currently in effect for this station's jurisdiction. Still usable, but superseded by the equivalent call on Body."
+      ),
       ...requestBodySchema({
         type: 'object',
         required: ['body_id'],
@@ -150,6 +180,7 @@ export const parliament = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation('View propositions.', 'Returns a list of the pending propositions.'),
       ...buildingIdRequestBody,
       responses: {
         ...response200('Returns a list of the pending propositions.', {
@@ -169,6 +200,10 @@ export const parliament = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation(
+        'View taxes collected.',
+        'Returns, for each empire that has paid taxes, their payments for today and the previous six days plus the seven-day total.'
+      ),
       ...buildingIdRequestBody,
       responses: {
         ...response200(
@@ -206,6 +241,10 @@ export const parliament = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation(
+        'Get stars in jurisdiction.',
+        'Returns a list of the stars in the jurisdiction of this space station.'
+      ),
       ...buildingIdRequestBody,
       responses: {
         ...response200('Returns a list of the stars in the jurisdiction of this space station.', {
@@ -248,11 +287,15 @@ export const parliament = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation(
+        'Get bodies for star in jurisdiction.',
+        'Returns a list of the bodies for a star in the jurisdiction of the space station.'
+      ),
       ...requestBodySchema({
         type: 'object',
         required: ['building_id', 'star_id'],
         properties: {
-          building_id: { type: 'integer' },
+          building_id: { type: 'integer', description: 'The unique id of the building.' },
           star_id: {
             type: 'integer',
             description: 'The unique id of a star in jurisdiction. See get_stars_in_jurisdiction.',
@@ -280,11 +323,15 @@ export const parliament = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation(
+        'Get mining platforms for asteroid in jurisdiction.',
+        'Returns a list of the mining platforms for an asteroid in the jurisdiction of the space station.'
+      ),
       ...requestBodySchema({
         type: 'object',
         required: ['building_id', 'asteroid_id'],
         properties: {
-          building_id: { type: 'integer' },
+          building_id: { type: 'integer', description: 'The unique id of the building.' },
           asteroid_id: {
             type: 'integer',
             description:
@@ -325,11 +372,15 @@ export const parliament = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation(
+        'Cast vote.',
+        'Casts a vote for or against a proposition. Cannot be voted on using a sitter password.'
+      ),
       ...requestBodySchema({
         type: 'object',
         required: ['building_id', 'proposition_id'],
         properties: {
-          building_id: { type: 'integer' },
+          building_id: { type: 'integer', description: 'The unique id of the building.' },
           proposition_id: {
             type: 'integer',
             description: 'The id of the proposition being voted on. See view_propositions.',
@@ -355,28 +406,43 @@ export const parliament = {
     'propose_writ',
     'Proposes an unenforceable law (writ). Requires Parliament level 4+.',
     ['title', 'description'],
-    { title: { type: 'string' }, description: { type: 'string' } }
+    {
+      title: { type: 'string', description: 'The name of the law.' },
+      description: {
+        type: 'string',
+        description:
+          'A detailed description of what the law intends to promote or prohibit. Same rules as an Inbox message body.',
+      },
+    }
   ),
 
   ...proposeMethod(
     'propose_repeal_law',
     'Proposes repealing an existing law. Requires Parliament level 5+.',
     ['law_id'],
-    { law_id: { type: 'integer' } }
+    { law_id: { type: 'integer', description: 'The id of the law to repeal.' } }
   ),
 
   ...proposeMethod(
     'propose_transfer_station_ownership',
     'Proposes transferring ownership of the station to another alliance member. Requires Parliament level 6+.',
     ['to_empire_id'],
-    { to_empire_id: { type: 'integer' } }
+    {
+      to_empire_id: {
+        type: 'integer',
+        description: 'The id of the alliance member to receive the station.',
+      },
+    }
   ),
 
   ...proposeMethod(
     'propose_rename_star',
     'Proposes renaming a star. Requires Parliament level 8+.',
     ['star_id', 'name'],
-    { star_id: { type: 'integer' }, name: { type: 'string' } }
+    {
+      star_id: { type: 'integer', description: 'The id of the star to rename.' },
+      name: { type: 'string', description: 'The new name of the star.' },
+    }
   ),
 
   ...proposeMethod(
@@ -397,7 +463,7 @@ export const parliament = {
     'Proposes inducting a new member into the alliance; if passed, an invitation is sent. Requires Parliament level 10+.',
     ['empire_id'],
     {
-      empire_id: { type: 'integer' },
+      empire_id: { type: 'integer', description: 'The id of the empire proposed for membership.' },
       message: {
         type: 'string',
         description: 'Optional personalized welcome message included in the invitation.',
@@ -410,7 +476,7 @@ export const parliament = {
     'Proposes expelling a member from the alliance. Requires Parliament level 10+.',
     ['empire_id'],
     {
-      empire_id: { type: 'integer' },
+      empire_id: { type: 'integer', description: 'The id of the empire proposed for removal.' },
       message: {
         type: 'string',
         description: 'Optional reason. Cannot contain restricted characters or profanity.',
@@ -422,14 +488,29 @@ export const parliament = {
     'propose_elect_new_leader',
     'Proposes electing a new alliance leader (who must already be a member). Requires Parliament level 11+.',
     ['to_empire_id'],
-    { to_empire_id: { type: 'integer' } }
+    {
+      to_empire_id: {
+        type: 'integer',
+        description: 'The id of the alliance member to elect as leader.',
+      },
+    }
   ),
 
   ...proposeMethod(
     'propose_rename_asteroid',
     'Proposes renaming an asteroid in the jurisdiction. Requires Parliament level 12+.',
     ['asteroid_id', 'name'],
-    { asteroid_id: { type: 'integer' }, name: { type: 'string', maxLength: 30 } }
+    {
+      asteroid_id: {
+        type: 'integer',
+        description: 'The id of the asteroid in the jurisdiction to rename.',
+      },
+      name: {
+        type: 'string',
+        maxLength: 30,
+        description: 'The new name (max 30 characters, no profanity or special characters).',
+      },
+    }
   ),
 
   ...proposeMethod(
@@ -461,7 +542,10 @@ export const parliament = {
     'Proposes sending a foreign aid supply pod to a planet in the jurisdiction. Costs double the resources sent (half covers the pod, half is the aid). Limited to one per day, like normal supply pods. Requires Parliament level 16+.',
     ['planet_id', 'resources'],
     {
-      planet_id: { type: 'integer' },
+      planet_id: {
+        type: 'integer',
+        description: 'The id of the planet to receive the foreign aid.',
+      },
       resources: {
         type: 'integer',
         description: 'The amount of resources to send to the receiving planet.',
@@ -473,7 +557,17 @@ export const parliament = {
     'propose_rename_uninhabited',
     'Proposes renaming an uninhabited planet in the jurisdiction. Requires Parliament level 17+.',
     ['planet_id', 'name'],
-    { planet_id: { type: 'integer' }, name: { type: 'string', maxLength: 30 } }
+    {
+      planet_id: {
+        type: 'integer',
+        description: 'The id of the uninhabited planet in the jurisdiction to rename.',
+      },
+      name: {
+        type: 'string',
+        maxLength: 30,
+        description: 'The new name (max 30 characters, no profanity or special characters).',
+      },
+    }
   ),
 
   ...proposeMethod(
@@ -501,8 +595,15 @@ export const parliament = {
     'Proposes firing the BFG equipped on all space stations at a planet within the jurisdiction. Requires Parliament level 25+.',
     ['body_id', 'reason'],
     {
-      body_id: { type: 'integer', description: 'See get_bodies_for_star_in_jurisdiction.' },
-      reason: { type: 'string' },
+      body_id: {
+        type: 'integer',
+        description: 'The planet to fire at. See get_bodies_for_star_in_jurisdiction.',
+      },
+      reason: {
+        type: 'string',
+        description:
+          'An explicit reason why the BFG should be fired. Same rules as an Inbox message body.',
+      },
     }
   ),
 
@@ -510,6 +611,11 @@ export const parliament = {
     'allow_bhg_by_alliance',
     'Proposes allowing another alliance to use Black Hole Generators in this jurisdiction, ignoring members-only colonization/stations restrictions. Requires Parliament level 28+.',
     ['alliance_id'],
-    { alliance_id: { type: 'integer' } }
+    {
+      alliance_id: {
+        type: 'integer',
+        description: 'The id of the alliance to be allowed to use their BHGs here.',
+      },
+    }
   ),
 };
diff --git a/src/spec/paths/modules/policestation.ts b/src/spec/paths/modules/policestation.ts
index 5002712..1fbce9a 100644
--- a/src/spec/paths/modules/policestation.ts
+++ b/src/spec/paths/modules/policestation.ts
@@ -1,4 +1,5 @@
 import {
+  operation,
   buildingBase,
   requestBodySchema,
   response200,
@@ -13,7 +14,7 @@ const base = buildingBase('PoliceStation');
 const buildingIdRequestBody = requestBodySchema({
   type: 'object',
   required: ['building_id'],
-  properties: { building_id: { type: 'integer' } },
+  properties: { building_id: { type: 'integer', description: 'The unique id of the building.' } },
 });
 
 const pagedRequestBody = (extraRequired: string[] = [], extraProperties: object = {}) =>
@@ -21,7 +22,7 @@ const pagedRequestBody = (extraRequired: string[] = [], extraProperties: object
     type: 'object',
     required: ['building_id', ...extraRequired],
     properties: {
-      building_id: { type: 'integer' },
+      building_id: { type: 'integer', description: 'The unique id of the building.' },
       page_number: {
         type: 'integer',
         description: 'Defaults to 1. Each page contains 25 results.',
@@ -63,6 +64,10 @@ export const policeStation = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation(
+        "Retrieve this module's properties.",
+        'Retrieves the properties of this module.'
+      ),
       ...buildingIdRequestBody,
       responses: {
         ...response200('Retrieves the properties of this module.', {
@@ -94,6 +99,7 @@ export const policeStation = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation('View prisoners.', 'Displays a list of the spies that have been captured.'),
       ...pagedRequestBody(),
       responses: {
         ...response200('Displays a list of the spies that have been captured.', {
@@ -129,10 +135,20 @@ export const policeStation = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation(
+        'Execute prisoner.',
+        'Executes a captured prisoner rather than letting them serve their sentence.'
+      ),
       ...requestBodySchema({
         type: 'object',
         required: ['building_id', 'prisoner_id'],
-        properties: { building_id: { type: 'integer' }, prisoner_id: { type: 'integer' } },
+        properties: {
+          building_id: { type: 'integer', description: 'The unique id of the building.' },
+          prisoner_id: {
+            type: 'integer',
+            description: 'The unique id of a captured prisoner. See view_prisoners.',
+          },
+        },
       }),
       responses: {
         ...response200(
@@ -148,10 +164,17 @@ export const policeStation = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation('Release prisoner.', 'Releases a captured prisoner.'),
       ...requestBodySchema({
         type: 'object',
         required: ['building_id', 'prisoner_id'],
-        properties: { building_id: { type: 'integer' }, prisoner_id: { type: 'integer' } },
+        properties: {
+          building_id: { type: 'integer', description: 'The unique id of the building.' },
+          prisoner_id: {
+            type: 'integer',
+            description: 'The unique id of a captured prisoner. See view_prisoners.',
+          },
+        },
       }),
       responses: {
         ...response200('Releases a captured prisoner.', {
@@ -168,6 +191,10 @@ export const policeStation = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation(
+        'View foreign spies.',
+        'Displays a list of the spies on your planet with a level lower than your Police Station.'
+      ),
       ...pagedRequestBody(),
       responses: {
         ...response200(
@@ -205,6 +232,10 @@ export const policeStation = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation(
+        'View foreign ships.',
+        "Shows incoming foreign ships filtered by the ship's stealth vs the Police Station's level (525 * level >= stealth to be visible at all; the `from` block requires 675 * level >= stealth)."
+      ),
       ...pagedRequestBody(),
       responses: {
         ...response200(
@@ -228,6 +259,10 @@ export const policeStation = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation(
+        'View ships travelling.',
+        'Returns a list of ships travelling to or from this planet, regardless of destination space port.'
+      ),
       ...pagedRequestBody(),
       responses: {
         ...response200(
@@ -278,6 +313,10 @@ export const policeStation = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation(
+        'View ships orbiting.',
+        "Shows foreign ships orbiting this planet, filtered by the ship's stealth vs the Police Station's level (525 * level >= stealth to be visible at all; the `from` block requires 675 * level >= stealth)."
+      ),
       ...pagedRequestBody(),
       responses: {
         ...response200(
diff --git a/src/spec/paths/modules/stationcommand.ts b/src/spec/paths/modules/stationcommand.ts
index f007510..9a6264c 100644
--- a/src/spec/paths/modules/stationcommand.ts
+++ b/src/spec/paths/modules/stationcommand.ts
@@ -1,4 +1,5 @@
 import {
+  operation,
   buildingBase,
   requestBodySchema,
   response200,
@@ -13,7 +14,7 @@ const base = buildingBase('StationCommand');
 const buildingIdRequestBody = requestBodySchema({
   type: 'object',
   required: ['building_id'],
-  properties: { building_id: { type: 'integer' } },
+  properties: { building_id: { type: 'integer', description: 'The unique id of the building.' } },
 });
 
 // StationCommand.pod's `planet` block on `view` documents the space station's own body/resource
@@ -27,6 +28,10 @@ export const stationCommand = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation(
+        "Retrieve this module's properties and planet data.",
+        "Retrieves the properties of this module, plus the station's own planet data."
+      ),
       ...buildingIdRequestBody,
       responses: {
         ...response200(
@@ -66,6 +71,7 @@ export const stationCommand = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation('View plans.', 'Returns a list of all the plans this empire has collected.'),
       ...buildingIdRequestBody,
       responses: {
         ...response200('Returns a list of all the plans this empire has collected.', {
@@ -100,6 +106,10 @@ export const stationCommand = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation(
+        'View incoming supply chains.',
+        'Returns a list of all incoming supply chains feeding this planet.'
+      ),
       ...buildingIdRequestBody,
       responses: {
         ...response200('Returns a list of all incoming supply chains feeding this planet.', {
diff --git a/src/spec/paths/modules/warehouse.ts b/src/spec/paths/modules/warehouse.ts
index 2bec01b..8e5b56c 100644
--- a/src/spec/paths/modules/warehouse.ts
+++ b/src/spec/paths/modules/warehouse.ts
@@ -1,4 +1,5 @@
 import {
+  operation,
   buildingBase,
   requestBodySchema,
   response200,
@@ -17,10 +18,16 @@ export const warehouse = {
     post: {
       ...tags(base),
       ...security(),
+      ...operation(
+        "Retrieve this module's properties.",
+        'Retrieves the properties of this module.'
+      ),
       ...requestBodySchema({
         type: 'object',
         required: ['building_id'],
-        properties: { building_id: { type: 'integer' } },
+        properties: {
+          building_id: { type: 'integer', description: 'The unique id of the building.' },
+        },
       }),
       responses: {
         ...response200('Retrieves the properties of this module.', {
diff --git a/src/spec/paths/stats.ts b/src/spec/paths/stats.ts
index a000f3f..711bde9 100644
--- a/src/spec/paths/stats.ts
+++ b/src/spec/paths/stats.ts
@@ -1,4 +1,5 @@
 import {
+  operation,
   requestBodySchema,
   response200,
   response500,
@@ -84,9 +85,14 @@ const empireRankEntrySchema = {
   properties: {
     empire_id: { type: 'integer' },
     empire_name: { type: 'string' },
-    // Always present, but null when the empire is not in an alliance.
-    alliance_id: { type: ['integer', 'null'] },
-    alliance_name: { type: ['string', 'null'] },
+    alliance_id: {
+      type: ['integer', 'null'],
+      description: 'Always present, but null when the empire is not in an alliance.',
+    },
+    alliance_name: {
+      type: ['string', 'null'],
+      description: 'Always present, but null when the empire is not in an alliance.',
+    },
     colony_count: { type: 'integer' },
     population: { type: 'integer' },
     empire_size: { type: 'integer' },
@@ -163,6 +169,10 @@ export const stats = {
     post: {
       ...tags('stats'),
       ...security(),
+      ...operation(
+        'Get the game credits.',
+        'Retrieves the list of game credits. Each entry names a single contribution category and the people who worked on it.'
+      ),
 
       responses: {
         ...response200(
@@ -185,6 +195,10 @@ export const stats = {
     post: {
       ...tags('stats'),
       ...security(),
+      ...operation(
+        'Rank alliances by statistic.',
+        'Returns a sorted list of alliances ranked according to various stats.'
+      ),
 
       ...requestBodySchema({
         type: 'object',
@@ -218,6 +232,10 @@ export const stats = {
     post: {
       ...tags('stats'),
       ...security(),
+      ...operation(
+        'Find an alliance in the rankings.',
+        'Searches for a particular alliance within the alliance rankings, returning the page of the alliance_rank listing each match appears on.'
+      ),
 
       ...requestBodySchema({
         type: 'object',
@@ -267,6 +285,10 @@ export const stats = {
     post: {
       ...tags('stats'),
       ...security(),
+      ...operation(
+        'Rank empires by statistic.',
+        'Returns a sorted list of empires ranked according to various stats.'
+      ),
 
       ...requestBodySchema({
         type: 'object',
@@ -300,6 +322,10 @@ export const stats = {
     post: {
       ...tags('stats'),
       ...security(),
+      ...operation(
+        'Find an empire in the rankings.',
+        'Searches for a particular empire within the empire rankings, returning the page of the empire_rank listing each match appears on.'
+      ),
 
       ...requestBodySchema({
         type: 'object',
@@ -349,6 +375,10 @@ export const stats = {
     post: {
       ...tags('stats'),
       ...security(),
+      ...operation(
+        'Rank colonies by statistic.',
+        'Returns a sorted list of planets ranked according to various stats.'
+      ),
 
       ...requestBodySchema({
         type: 'object',
@@ -379,6 +409,10 @@ export const stats = {
     post: {
       ...tags('stats'),
       ...security(),
+      ...operation(
+        'Rank the top spies by statistic.',
+        'Returns a sorted list of the top spies in the game ranked according to various stats.'
+      ),
 
       ...requestBodySchema({
         type: 'object',
@@ -409,6 +443,10 @@ export const stats = {
     post: {
       ...tags('stats'),
       ...security(),
+      ...operation(
+        "List this week's medal winners.",
+        "Returns the list of empires who won this week's weekly medals."
+      ),
 
       responses: {
         ...response200("Returns the list of empires who won this week's weekly medals.", {