diff --git a/src/models/team/team.graphql b/src/models/team/team.graphql
index d74cb38e4b5ef5e704d4613dade16ab22e92f6d1..9f72bf98801d767e350c6327cebdf7ff493abbea 100644
--- a/src/models/team/team.graphql
+++ b/src/models/team/team.graphql
@@ -1,10 +1,17 @@
 type Team {
+  "The team id"
   id: ID!
+  "The team role (eg. 'editor')"
   role: String!
+  "The team display name"
   displayName: String!
+  "The related object id (only if not global)"
   objectId: ID
+  "The related object type (only if not global)"
   objectType: String
+  "The members of the team"
   members(currentUserOnly: Boolean): [TeamMember!]
+  "Whether the team is global or not"
   global: Boolean!
 }
 
diff --git a/src/models/teamMember/teamMember.graphql b/src/models/teamMember/teamMember.graphql
index c15d913f4f9d0209c3b9f43a2e11d3a1fa5cd241..6500513e0deafb5b3979fa25b1c0d6c4642abeb5 100644
--- a/src/models/teamMember/teamMember.graphql
+++ b/src/models/teamMember/teamMember.graphql
@@ -1,6 +1,9 @@
 type TeamMember {
-  id: ID
-  user: User
+  "The team member id"
+  id: ID!
+  "The user related to this team member. Members are separate entities from users."
+  user: User!
+  "The status of the team member"
   status: String
 }