diff --git a/src/caosdb/common/models.py b/src/caosdb/common/models.py
index 08fcd0206b9df22902e80277d0e57b5f67c76db5..be3c2fc18cb2ebea99dd4f00f48686a38e30f620 100644
--- a/src/caosdb/common/models.py
+++ b/src/caosdb/common/models.py
@@ -461,18 +461,30 @@ class Entity:
                      unit=None, importance=None, inheritance=None):  # @ReservedAssignment
         """Add a property to this entity.
 
-        The first parameter is meant to identify the property entity. So the method expects an instance of
-        Entity, an integer or a string here. The second parameter is the value of the new property. Any
-        other named parameter may be passed by means of the keywwords. Accepted keywords are:
-        id, name, description, importance, inheritance, datatype, and unit. Any other keyword will be
-        ignored right now. But that may change in the future.
+        The first parameter is meant to identify the property entity either via
+        its id or name, or by providing the corresponding ``Entity`` Python
+        object. The second parameter is the value of the new property. Any other
+        named parameter may be passed by means of the keywwords. Accepted
+        keywords are: id, name, description, importance, inheritance, datatype,
+        and unit.
+
+        Notes
+        -----
+        If you want to add a property to an already existing entity, the
+        property ``id`` of that property needs to be specified before you send
+        the updated entity to the server.
 
         Parameters
         ----------
-        property : int, str, Property, optional
-            An identifying parameter, by default None
-        value : int, str, Property, optional
-            The value of the new property, by default None
+        property : int, str, Entity, optional
+            An identifier for the property to be added, either its name, its id,
+            or the corresponding Entity Python object. If ``None``, either the
+            `name` or the `id` argument have to be specified explicitly. Default
+            is ``None``.
+        value : int, str, bool, datetime, Entity, or list of these types, optional
+            The value of the new property. In case of a reference to another
+            entity, this value may be the referenced entities id or the
+            ``Entity`` as a Python object. Default is None.
         id : int, optional
             Id of the property, by default None
         name : str, optional
@@ -491,17 +503,64 @@ class Entity:
         Returns
         -------
         Entity
+            This Entity object to which the new property has been added.
 
-        Raises
-        ------
+        Warns
+        -----
         UserWarning
             If the first parameter is None then id or name must be defined and not be None.
         UserWarning
             If the first parameter is an integer then it is interpreted as the id and id must be
             undefined or None.
         UserWarning
-             If the first parameter is not None and neither an instance of Entity nor an integer it is
+            If the first parameter is not None and neither an instance of Entity nor an integer it is
             interpreted as the name and name must be undefined or None.
+
+        Raises
+        ------
+        ValueError:
+            If you try to add an ``Entity`` object with File or Record role (or,
+            equivalently, a ``File`` or ``Record`` object) as a property, a
+            ``ValueError`` is raised.
+
+        Examples
+        --------
+        Add a simple integer property with the name ``TestProp`` and the value
+        27 to a Record:
+
+        >>> import caosdb as db
+        >>> rec = db.Record(name="TestRec").add_parent(name="TestType")
+        >>> rec.add_property("TestProp", value=27)  # specified by name, you could equally use the property's id if it is known
+
+        You can also use the Python object:
+
+        >>> prop = db.Property(name="TestProp", datatype=db.INTEGER)
+        >>> rec.add_property(prop, value=27)  # specified via the Python object
+
+        In case of updating an existing Record, the Property needs to be
+        specified by id:
+
+        >>> rec = db.Record(name="TestRec").retrieve()
+        >>> prop2 = db.Property(name="OtherTestProp").retrieve()
+        >>> rec.add_property(id=prop2.id, value="My new value")
+        >>> rec.update()
+
+        Let's look at the more advanced example of adding a list of integers as
+        value of the above integer ``TestProp``:
+
+        >>> rec.add_property("TestProp", value=[27,28,29], datatype=db.LIST(db.INTEGER))
+
+        Note that since `TestProp` is a scalar integer Property, the datatype
+        `LIST<INTEGER>` has to be specified explicitly.
+
+        Finally, we can also add reference properties, specified by the RecordType of the referenced entity.
+
+        >>> ref_rec = db.Record(name="ReferencedRecord").add_parent(name="OtherRT")
+        >>> rec.add_property(name="OtherRT", value=ref_rec)  # or value=ref_rec.id if ref_rec has one set by the server
+
+        See more on adding properties and inserting data in
+        https://docs.indiscale.com/caosdb-pylib/tutorials/Data-Insertion.html.
+
         """
 
         pid = id