diff --git a/src/libinput.h b/src/libinput.h
index 828cf6b4..3413eeb7 100644
--- a/src/libinput.h
+++ b/src/libinput.h
@@ -85,7 +85,8 @@ struct libinput_seat;
  * Tablet events generated by such a device are bound to a specific tool
  * rather than coming from the device directly. Depending on the hardware it
  * is possible to track the same physical tool across multiple
- * struct libinput_device devices, see @ref tablet-serial-numbers.
+ * struct libinput_device devices.
+ * See libinput_tablet_tool_get_serial() for more details.
  *
  * This struct is refcounted, use libinput_tablet_tool_ref() and
  * libinput_tablet_tool_unref().
@@ -2255,8 +2256,8 @@ libinput_event_tablet_tool_get_y_transformed(struct libinput_event_tablet_tool *
  * whenever the tools enters proximity again.
   *
  * @note Physical tool tracking requires hardware support. If unavailable,
- * libinput creates one tool per type per tablet. See @ref
- * tablet-serial-numbers for more details.
+ * libinput creates one tool per type per tablet. See
+ * libinput_tablet_tool_get_serial() for more details.
  *
  * @param event The libinput tablet tool event
  * @return The new tool triggering this event
@@ -2271,7 +2272,19 @@ libinput_event_tablet_tool_get_tool(struct libinput_event_tablet_tool *event);
  * Used to check whether or not a tool came in or out of proximity during an
  * event of type @ref LIBINPUT_EVENT_TABLET_TOOL_PROXIMITY.
  *
- * See @ref tablet-fake-proximity for recommendations on proximity handling.
+ * The proximity state represents the logical proximity state which does not
+ * necessarily match when a tool comes into sensor range or leaves the
+ * sensor range. On some tools this range does not represent the physical
+ * range but a reduced tool-specific logical range. If the range is reduced,
+ * this is done transparent to the caller.
+ *
+ * For example, the Wacom mouse and lens cursor tools are usually
+ * used in relative mode, lying flat on the tablet. Movement typically follows
+ * the interaction normal mouse movements have, i.e. slightly lift the tool and
+ * place it in a separate location. The proximity detection on Wacom
+ * tablets however extends further than the user may lift the mouse, i.e. the
+ * tool may not be lifted out of physical proximity. For such tools, libinput
+ * provides software-emulated proximity.
  *
  * @param event The libinput tablet tool event
  * @return The new proximity state of the tool from the event.
@@ -2365,8 +2378,18 @@ libinput_event_tablet_tool_get_time_usec(struct libinput_event_tablet_tool *even
 /**
  * @ingroup event_tablet
  *
- * Return the tool type for a tool object, see @ref
- * tablet-tool-types for details.
+ * Return the high-level tool type for a tool object.
+ *
+ * The high level tool describes general interaction expected with the tool.
+ * For example, a user would expect a tool of type @ref
+ * LIBINPUT_TABLET_TOOL_TYPE_PEN to interact with a graphics application
+ * taking pressure and tilt into account. The default virtual tool assigned
+ * should be a drawing tool, e.g. a virtual pen or brush.
+ * A tool of type @ref LIBINPUT_TABLET_TOOL_TYPE_ERASER would normally be
+ * mapped to an eraser-like virtual tool.
+ *
+ * If supported by the hardware, a more specific tool id is always
+ * available, see * libinput_tablet_tool_get_tool_id().
  *
  * @param tool The libinput tool
  * @return The tool type for this tool object
@@ -2381,11 +2404,12 @@ libinput_tablet_tool_get_type(struct libinput_tablet_tool *tool);
  *
  * Return the tool ID for a tool object. If nonzero, this number identifies
  * the specific type of the tool with more precision than the type returned in
- * libinput_tablet_tool_get_type(), see @ref tablet-tool-types. Not all
- * tablets support a tool ID.
+ * libinput_tablet_tool_get_type(). Not all tablets support a tool ID.
  *
  * Tablets known to support tool IDs include the Wacom Intuos 3, 4, 5, Wacom
- * Cintiq and Wacom Intuos Pro series.
+ * Cintiq and Wacom Intuos Pro series. The tool ID can be used to
+ * distinguish between e.g. a Wacom Classic Pen or a Wacom Pro Pen.  It is
+ * the caller's responsibility to interpret the tool ID.
  *
  * @param tool The libinput tool
  * @return The tool ID for this tool object or 0 if none is provided
@@ -2512,7 +2536,7 @@ libinput_tablet_tool_has_button(struct libinput_tablet_tool *tool,
  * libinput, or nonzero otherwise. If a tool can be uniquely identified,
  * keeping a reference to the tool allows tracking the tool across
  * proximity out sequences and across compatible tablets.
- * See @ref tablet-serial-numbers for more details.
+ * See libinput_tablet_tool_get_serial() for more details.
  *
  * @param tool A tablet tool
  * @return 1 if the tool can be uniquely identified, 0 otherwise.
@@ -2526,8 +2550,30 @@ libinput_tablet_tool_is_unique(struct libinput_tablet_tool *tool);
  * @ingroup event_tablet
  *
  * Return the serial number of a tool. If the tool does not report a serial
- * number, this function returns zero. See @ref tablet-serial-numbers for
- * details.
+ * number, this function returns zero.
+ *
+ * Some tools provide hardware information that enables libinput to uniquely
+ * identify the physical device. For example, tools compatible with the
+ * Wacom Intuos 4, Intuos 5, Intuos Pro and Cintiq series are uniquely
+ * identifiable through a serial number. libinput does not specify how a
+ * tool can be identified uniquely, a caller should use
+ * libinput_tablet_tool_is_unique() to check if the tool is unique.
+ *
+ * libinput creates a struct @ref libinput_tablet_tool on the first
+ * proximity in of this tool. By default, this struct is destroyed on
+ * proximity out and re-initialized on the next proximity in. If a caller
+ * keeps a reference to the tool by using libinput_tablet_tool_ref()
+ * libinput re-uses this struct whenever that same physical tool comes into
+ * proximity on any tablet
+ * recognized by libinput. It is possible to attach tool-specific virtual
+ * state to the tool. For example, a graphics program such as the GIMP may
+ * assign a specific color to each tool, allowing the artist to use the
+ * tools like physical pens of different color. In multi-tablet setups it is
+ * also possible to track the tool across devices.
+ *
+ * If the tool does not have a unique identifier, libinput creates a single
+ * struct @ref libinput_tablet_tool per tool type on each tablet the tool is
+ * used on.
  *
  * @param tool The libinput tool
  * @return The tool serial number