OAS3 specs are full of things that need descriptions. Here are some tips for writing them. Always start with the action word. Use the action + object (+ how) pattern consistently for all your descriptions. (Example: "Retrieves a purchase order by ID.")