diff --git a/app/pdb/display-cmds.c b/app/pdb/display-cmds.c
index 21bc5c6aca..c98954e34e 100644
--- a/app/pdb/display-cmds.c
+++ b/app/pdb/display-cmds.c
@@ -245,7 +245,8 @@ register_display_procs (GimpPDB *pdb)
                                "gimp-display-id-is-valid");
   gimp_procedure_set_static_help (procedure,
                                   "Returns TRUE if the display ID is valid.",
-                                  "This procedure checks if the given display ID is valid and refers to an existing display.",
+                                  "This procedure checks if the given display ID is valid and refers to an existing display.\n"
+                                  "Note: in most use cases, you should not use this function. If you got a [class@Gimp.Display] from the API, you should trust it is valid. This function is mostly for internal usage.",
                                   NULL);
   gimp_procedure_set_static_attribution (procedure,
                                          "Sven Neumann <sven@gimp.org>",
diff --git a/app/pdb/item-cmds.c b/app/pdb/item-cmds.c
index 337e1e5a8f..7c3e209fcf 100644
--- a/app/pdb/item-cmds.c
+++ b/app/pdb/item-cmds.c
@@ -1068,8 +1068,9 @@ register_item_procs (GimpPDB *pdb)
   gimp_object_set_static_name (GIMP_OBJECT (procedure),
                                "gimp-item-id-is-valid");
   gimp_procedure_set_static_help (procedure,
-                                  "Returns TRUE if the item ID is valid.",
-                                  "This procedure checks if the given item ID is valid and refers to an existing item.",
+                                  "Returns %TRUE if the item ID is valid.",
+                                  "This procedure checks if the given item ID is valid and refers to an existing item.\n"
+                                  "Note: in most use cases, you should not use this function. If you got a [class@Gimp.Item] from the API, you should trust it is valid. This function is mostly for internal usage.",
                                   NULL);
   gimp_procedure_set_static_attribution (procedure,
                                          "Sven Neumann <sven@gimp.org>",
@@ -1098,7 +1099,8 @@ register_item_procs (GimpPDB *pdb)
                                "gimp-item-id-is-drawable");
   gimp_procedure_set_static_help (procedure,
                                   "Returns whether the item ID is a drawable.",
-                                  "This procedure returns TRUE if the specified item ID is a drawable.",
+                                  "This procedure returns %TRUE if the specified item ID is a drawable.\n"
+                                  "Note: in most use cases, you should not use this function. See [func.Item.id_is_layer] for a discussion on alternatives.",
                                   NULL);
   gimp_procedure_set_static_attribution (procedure,
                                          "Spencer Kimball & Peter Mattis",
@@ -1127,7 +1129,18 @@ register_item_procs (GimpPDB *pdb)
                                "gimp-item-id-is-layer");
   gimp_procedure_set_static_help (procedure,
                                   "Returns whether the item ID is a layer.",
-                                  "This procedure returns TRUE if the specified item ID is a layer.",
+                                  "This procedure returns %TRUE if the specified item ID is a layer.\n"
+                                  "Note: in most use cases, you should not use this function. If the goal is to verify the accurate type for a [class.Item], you should either use [method.Item.is_layer] or the specific type-checking methods for the used language.\n"
+                                  "For instance, in C:\n"
+                                  "```C\n"
+                                  "if (GIMP_IS_LAYER (item))\n"
+                                  "do_something ();\n"
+                                  "```\n"
+                                  "Or in the Python binding, you could run:\n"
+                                  "```py3\n"
+                                  "if isinstance(item, Gimp.Layer):\n"
+                                  "do_something()\n"
+                                  "```",
                                   NULL);
   gimp_procedure_set_static_attribution (procedure,
                                          "Spencer Kimball & Peter Mattis",
@@ -1156,7 +1169,8 @@ register_item_procs (GimpPDB *pdb)
                                "gimp-item-id-is-text-layer");
   gimp_procedure_set_static_help (procedure,
                                   "Returns whether the item ID is a text layer.",
-                                  "This procedure returns TRUE if the specified item ID is a text layer.",
+                                  "This procedure returns %TRUE if the specified item ID is a text layer.\n"
+                                  "Note: in most use cases, you should not use this function. See [func@Gimp.Item.id_is_layer] for a discussion on alternatives.",
                                   NULL);
   gimp_procedure_set_static_attribution (procedure,
                                          "Michael Natterer <mitch@gimp.org>",
@@ -1185,7 +1199,8 @@ register_item_procs (GimpPDB *pdb)
                                "gimp-item-id-is-group-layer");
   gimp_procedure_set_static_help (procedure,
                                   "Returns whether the item ID is a group layer.",
-                                  "This procedure returns TRUE if the specified item ID is a group layer.",
+                                  "This procedure returns %TRUE if the specified item ID is a group layer.\n"
+                                  "Note: in most use cases, you should not use this function. See [func@Gimp.Item.id_is_layer] for a discussion on alternatives.",
                                   NULL);
   gimp_procedure_set_static_attribution (procedure,
                                          "Jehan",
@@ -1214,7 +1229,8 @@ register_item_procs (GimpPDB *pdb)
                                "gimp-item-id-is-channel");
   gimp_procedure_set_static_help (procedure,
                                   "Returns whether the item ID is a channel.",
-                                  "This procedure returns TRUE if the specified item ID is a channel.",
+                                  "This procedure returns %TRUE if the specified item ID is a channel.\n"
+                                  "Note: in most use cases, you should not use this function. See [func.Item.id_is_layer] for a discussion on alternatives.",
                                   NULL);
   gimp_procedure_set_static_attribution (procedure,
                                          "Spencer Kimball & Peter Mattis",
@@ -1243,7 +1259,8 @@ register_item_procs (GimpPDB *pdb)
                                "gimp-item-id-is-layer-mask");
   gimp_procedure_set_static_help (procedure,
                                   "Returns whether the item ID is a layer mask.",
-                                  "This procedure returns TRUE if the specified item ID is a layer mask.",
+                                  "This procedure returns %TRUE if the specified item ID is a layer mask.\n"
+                                  "Note: in most use cases, you should not use this function. See [func.Item.id_is_layer] for a discussion on alternatives.",
                                   NULL);
   gimp_procedure_set_static_attribution (procedure,
                                          "Spencer Kimball & Peter Mattis",
@@ -1272,7 +1289,8 @@ register_item_procs (GimpPDB *pdb)
                                "gimp-item-id-is-path");
   gimp_procedure_set_static_help (procedure,
                                   "Returns whether the item ID is a path.",
-                                  "This procedure returns TRUE if the specified item ID is a path.",
+                                  "This procedure returns %TRUE if the specified item ID is a path.\n"
+                                  "Note: in most use cases, you should not use this function. See [func.Item.id_is_layer] for a discussion on alternatives.",
                                   NULL);
   gimp_procedure_set_static_attribution (procedure,
                                          "Spencer Kimball & Peter Mattis",
@@ -1301,7 +1319,8 @@ register_item_procs (GimpPDB *pdb)
                                "gimp-item-id-is-selection");
   gimp_procedure_set_static_help (procedure,
                                   "Returns whether the item ID is a selection.",
-                                  "This procedure returns TRUE if the specified item ID is a selection.",
+                                  "This procedure returns %TRUE if the specified item ID is a selection.\n"
+                                  "Note: in most use cases, you should not use this function. See [func.Item.id_is_layer] for a discussion on alternatives.",
                                   NULL);
   gimp_procedure_set_static_attribution (procedure,
                                          "Spencer Kimball & Peter Mattis",
@@ -1382,7 +1401,7 @@ register_item_procs (GimpPDB *pdb)
                                "gimp-item-is-group");
   gimp_procedure_set_static_help (procedure,
                                   "Returns whether the item is a group item.",
-                                  "This procedure returns TRUE if the specified item is a group item which can have children.",
+                                  "This procedure returns %TRUE if the specified item is a group item which can have children.",
                                   NULL);
   gimp_procedure_set_static_attribution (procedure,
                                          "Michael Natterer <mitch@gimp.org>",
@@ -1475,7 +1494,7 @@ register_item_procs (GimpPDB *pdb)
                                "gimp-item-get-expanded");
   gimp_procedure_set_static_help (procedure,
                                   "Returns whether the item is expanded.",
-                                  "This procedure returns TRUE if the specified item is expanded.",
+                                  "This procedure returns %TRUE if the specified item is expanded.",
                                   NULL);
   gimp_procedure_set_static_attribution (procedure,
                                          "Ell",
diff --git a/app/pdb/resource-cmds.c b/app/pdb/resource-cmds.c
index 69e764f924..3e8dff96bf 100644
--- a/app/pdb/resource-cmds.c
+++ b/app/pdb/resource-cmds.c
@@ -605,7 +605,8 @@ register_resource_procs (GimpPDB *pdb)
                                "gimp-resource-id-is-valid");
   gimp_procedure_set_static_help (procedure,
                                   "Returns TRUE if the resource ID is valid.",
-                                  "This procedure checks if the given resource ID is valid and refers to an existing resource.",
+                                  "This procedure checks if the given resource ID is valid and refers to an existing resource.\n"
+                                  "Note: in most use cases, you should not use this function. If you got a [class@Gimp.Resource] from the API, you should trust it is valid. This function is mostly for internal usage.",
                                   NULL);
   gimp_procedure_set_static_attribution (procedure,
                                          "Michael Natterer <mitch@gimp.org>",
diff --git a/libgimp/gimpdisplay.c b/libgimp/gimpdisplay.c
index 0bced4c78f..d7dce7aeac 100644
--- a/libgimp/gimpdisplay.c
+++ b/libgimp/gimpdisplay.c
@@ -132,6 +132,9 @@ gimp_display_get_property (GObject    *object,
  * gimp_display_get_id:
  * @display: The display.
  *
+ * Note: in most use cases, you should not need a display's ID which is
+ * mostly internal data and not reusable across sessions.
+ *
  * Returns: the display ID.
  *
  * Since: 3.0
@@ -148,6 +151,11 @@ gimp_display_get_id (GimpDisplay *display)
  *
  * Returns a #GimpDisplay representing @display_id.
  *
+ * Note: in most use cases, you should not need to retrieve a
+ * #GimpDisplay by its ID, which is mostly internal data and not
+ * reusable across sessions. Use the appropriate functions for your use
+ * case instead.
+ *
  * Returns: (nullable) (transfer none): a #GimpDisplay for @display_id or
  *          %NULL if @display_id does not represent a valid display.
  *          The object belongs to libgimp and you must not modify or
diff --git a/libgimp/gimpdisplay_pdb.c b/libgimp/gimpdisplay_pdb.c
index 33ab47a24a..399fc10988 100644
--- a/libgimp/gimpdisplay_pdb.c
+++ b/libgimp/gimpdisplay_pdb.c
@@ -44,6 +44,9 @@
  *
  * This procedure checks if the given display ID is valid and refers to
  * an existing display.
+ * Note: in most use cases, you should not use this function. If you
+ * got a [class@Gimp.Display] from the API, you should trust it is
+ * valid. This function is mostly for internal usage.
  *
  * Returns: Whether the display ID is valid.
  *
diff --git a/libgimp/gimpitem.c b/libgimp/gimpitem.c
index ca3a85d118..6f2ad0e9a3 100644
--- a/libgimp/gimpitem.c
+++ b/libgimp/gimpitem.c
@@ -134,6 +134,9 @@ gimp_item_get_property (GObject    *object,
  * gimp_item_get_id:
  * @item: The item.
  *
+ * Note: in most use cases, you should not need an item's ID which is
+ * mostly internal data and not reusable across sessions.
+ *
  * Returns: the item ID.
  *
  * Since: 3.0
@@ -161,6 +164,10 @@ gimp_item_get_id (GimpItem *item)
  * abstract class, the real object type will actually be the proper
  * subclass.
  *
+ * Note: in most use cases, you should not need to retrieve a #GimpItem
+ * by its ID, which is mostly internal data and not reusable across
+ * sessions. Use the appropriate functions for your use case instead.
+ *
  * Returns: (nullable) (transfer none): a #GimpItem for @item_id or
  *          %NULL if @item_id does not represent a valid item.
  *          The object belongs to libgimp and you must not modify
diff --git a/libgimp/gimpitem_pdb.c b/libgimp/gimpitem_pdb.c
index e4ffe43a04..baa51337d0 100644
--- a/libgimp/gimpitem_pdb.c
+++ b/libgimp/gimpitem_pdb.c
@@ -40,10 +40,13 @@
  * gimp_item_id_is_valid:
  * @item_id: The item ID to check.
  *
- * Returns TRUE if the item ID is valid.
+ * Returns %TRUE if the item ID is valid.
  *
  * This procedure checks if the given item ID is valid and refers to an
  * existing item.
+ * Note: in most use cases, you should not use this function. If you
+ * got a [class@Gimp.Item] from the API, you should trust it is valid.
+ * This function is mostly for internal usage.
  *
  * Returns: Whether the item ID is valid.
  *
@@ -79,7 +82,9 @@ gimp_item_id_is_valid (gint item_id)
  *
  * Returns whether the item ID is a drawable.
  *
- * This procedure returns TRUE if the specified item ID is a drawable.
+ * This procedure returns %TRUE if the specified item ID is a drawable.
+ * Note: in most use cases, you should not use this function. See
+ * [func.Item.id_is_layer] for a discussion on alternatives.
  *
  * Returns: TRUE if the item ID is a drawable, FALSE otherwise.
  *
@@ -115,7 +120,21 @@ gimp_item_id_is_drawable (gint item_id)
  *
  * Returns whether the item ID is a layer.
  *
- * This procedure returns TRUE if the specified item ID is a layer.
+ * This procedure returns %TRUE if the specified item ID is a layer.
+ * Note: in most use cases, you should not use this function. If the
+ * goal is to verify the accurate type for a [class.Item], you should
+ * either use [method.Item.is_layer] or the specific type-checking
+ * methods for the used language.
+ * For instance, in C:
+ * ```C
+ * if (GIMP_IS_LAYER (item))
+ * do_something ();
+ * ```
+ * Or in the Python binding, you could run:
+ * ```py3
+ * if isinstance(item, Gimp.Layer):
+ * do_something()
+ * ```
  *
  * Returns: TRUE if the item is a layer, FALSE otherwise.
  *
@@ -151,8 +170,10 @@ gimp_item_id_is_layer (gint item_id)
  *
  * Returns whether the item ID is a text layer.
  *
- * This procedure returns TRUE if the specified item ID is a text
+ * This procedure returns %TRUE if the specified item ID is a text
  * layer.
+ * Note: in most use cases, you should not use this function. See
+ * [func@Gimp.Item.id_is_layer] for a discussion on alternatives.
  *
  * Returns: TRUE if the item is a text layer, FALSE otherwise.
  *
@@ -188,8 +209,10 @@ gimp_item_id_is_text_layer (gint item_id)
  *
  * Returns whether the item ID is a group layer.
  *
- * This procedure returns TRUE if the specified item ID is a group
+ * This procedure returns %TRUE if the specified item ID is a group
  * layer.
+ * Note: in most use cases, you should not use this function. See
+ * [func@Gimp.Item.id_is_layer] for a discussion on alternatives.
  *
  * Returns: TRUE if the item is a group layer, FALSE otherwise.
  *
@@ -225,7 +248,9 @@ gimp_item_id_is_group_layer (gint item_id)
  *
  * Returns whether the item ID is a channel.
  *
- * This procedure returns TRUE if the specified item ID is a channel.
+ * This procedure returns %TRUE if the specified item ID is a channel.
+ * Note: in most use cases, you should not use this function. See
+ * [func.Item.id_is_layer] for a discussion on alternatives.
  *
  * Returns: TRUE if the item ID is a channel, FALSE otherwise.
  *
@@ -261,8 +286,10 @@ gimp_item_id_is_channel (gint item_id)
  *
  * Returns whether the item ID is a layer mask.
  *
- * This procedure returns TRUE if the specified item ID is a layer
+ * This procedure returns %TRUE if the specified item ID is a layer
  * mask.
+ * Note: in most use cases, you should not use this function. See
+ * [func.Item.id_is_layer] for a discussion on alternatives.
  *
  * Returns: TRUE if the item ID is a layer mask, FALSE otherwise.
  *
@@ -298,7 +325,9 @@ gimp_item_id_is_layer_mask (gint item_id)
  *
  * Returns whether the item ID is a path.
  *
- * This procedure returns TRUE if the specified item ID is a path.
+ * This procedure returns %TRUE if the specified item ID is a path.
+ * Note: in most use cases, you should not use this function. See
+ * [func.Item.id_is_layer] for a discussion on alternatives.
  *
  * Returns: TRUE if the item ID is a path, FALSE otherwise.
  *
@@ -334,7 +363,10 @@ gimp_item_id_is_path (gint item_id)
  *
  * Returns whether the item ID is a selection.
  *
- * This procedure returns TRUE if the specified item ID is a selection.
+ * This procedure returns %TRUE if the specified item ID is a
+ * selection.
+ * Note: in most use cases, you should not use this function. See
+ * [func.Item.id_is_layer] for a discussion on alternatives.
  *
  * Returns: TRUE if the item ID is a selection, FALSE otherwise.
  *
@@ -445,7 +477,7 @@ gimp_item_delete (GimpItem *item)
  *
  * Returns whether the item is a group item.
  *
- * This procedure returns TRUE if the specified item is a group item
+ * This procedure returns %TRUE if the specified item is a group item
  * which can have children.
  *
  * Returns: TRUE if the item is a group, FALSE otherwise.
@@ -564,7 +596,7 @@ gimp_item_get_children (GimpItem *item,
  *
  * Returns whether the item is expanded.
  *
- * This procedure returns TRUE if the specified item is expanded.
+ * This procedure returns %TRUE if the specified item is expanded.
  *
  * Returns: TRUE if the item is expanded, FALSE otherwise.
  *
diff --git a/libgimp/gimpresource.c b/libgimp/gimpresource.c
index 8ea6bdb5d1..060c5aca72 100644
--- a/libgimp/gimpresource.c
+++ b/libgimp/gimpresource.c
@@ -278,6 +278,9 @@ gimp_resource_deserialize_create (GType     type,
  * gimp_resource_get_id:
  * @resource: The resource.
  *
+ * Note: in most use cases, you should not need a resource's ID which is
+ * mostly internal data and not reusable across sessions.
+ *
  * Returns: the resource ID.
  *
  * Since: 3.0
@@ -305,6 +308,11 @@ gimp_resource_get_id (GimpResource *resource)
  * abstract class, the real object type will actually be the proper
  * subclass.
  *
+ * Note: in most use cases, you should not need to retrieve a
+ * #GimpResource by its ID, which is mostly internal data and not
+ * reusable across sessions. Use the appropriate functions for your use
+ * case instead.
+ *
  * Returns: (nullable) (transfer none): a #GimpResource for @resource_id or
  *          %NULL if @resource_id does not represent a valid resource.
  *          The object belongs to libgimp and you must not modify
diff --git a/libgimp/gimpresource_pdb.c b/libgimp/gimpresource_pdb.c
index 1904c9e1a0..c72690c7c4 100644
--- a/libgimp/gimpresource_pdb.c
+++ b/libgimp/gimpresource_pdb.c
@@ -133,6 +133,9 @@ _gimp_resource_get_by_identifiers (const gchar *type_name,
  *
  * This procedure checks if the given resource ID is valid and refers
  * to an existing resource.
+ * Note: in most use cases, you should not use this function. If you
+ * got a [class@Gimp.Resource] from the API, you should trust it is
+ * valid. This function is mostly for internal usage.
  *
  * Returns: Whether the resource ID is valid.
  *
diff --git a/pdb/groups/display.pdb b/pdb/groups/display.pdb
index 298e020867..55e01e0f68 100644
--- a/pdb/groups/display.pdb
+++ b/pdb/groups/display.pdb
@@ -22,6 +22,10 @@ sub display_id_is_valid {
     $help = <<'HELP';
 This procedure checks if the given display ID is valid and refers to an
 existing display.
+
+Note: in most use cases, you should not use this function. If you got a
+[class@Gimp.Display] from the API, you should trust it is valid. This
+function is mostly for internal usage.
 HELP
 
     &neo_pdb_misc('2007', '3.0');
diff --git a/pdb/groups/item.pdb b/pdb/groups/item.pdb
index 4dbb409454..6bb7f13237 100644
--- a/pdb/groups/item.pdb
+++ b/pdb/groups/item.pdb
@@ -17,11 +17,15 @@
 # "Perlized" from C source by Manish Singh <yosh@gimp.org>
 
 sub item_id_is_valid {
-    $blurb = 'Returns TRUE if the item ID is valid.';
+    $blurb = 'Returns %TRUE if the item ID is valid.';
 
     $help = <<'HELP';
 This procedure checks if the given item ID is valid and refers to an
 existing item.
+
+Note: in most use cases, you should not use this function. If you got a
+[class@Gimp.Item] from the API, you should trust it is valid. This
+function is mostly for internal usage.
 HELP
 
     &neo_pdb_misc('2007', '3.0');
@@ -52,7 +56,10 @@ sub item_id_is_drawable {
     $blurb = 'Returns whether the item ID is a drawable.';
 
     $help = <<HELP;
-This procedure returns TRUE if the specified item ID is a drawable.
+This procedure returns %TRUE if the specified item ID is a drawable.
+
+Note: in most use cases, you should not use this function. See
+[func@Gimp.Item.id_is_layer] for a discussion on alternatives.
 HELP
 
     &std_pdb_misc;
@@ -84,7 +91,33 @@ sub item_id_is_layer {
     $blurb = 'Returns whether the item ID is a layer.';
 
     $help = <<HELP;
-This procedure returns TRUE if the specified item ID is a layer.
+This procedure returns %TRUE if the specified item ID is a layer.
+
+Note: in most use cases, you should not use this function. If the goal
+is to verify the accurate type for a [class@Gimp.Item], you should
+either use [method@Gimp.Item.is_layer] or the specific type-checking
+methods for the used language.
+
+For instance, in C:
+
+```C
+
+if (GIMP_IS_LAYER (item))
+
+  do_something ();
+
+```
+
+Or in the Python binding, you could run:
+
+```py3
+
+if isinstance(item, Gimp.Layer):
+
+  do_something()
+
+```
+
 HELP
 
     &std_pdb_misc;
@@ -116,7 +149,10 @@ sub item_id_is_text_layer {
     $blurb = 'Returns whether the item ID is a text layer.';
 
     $help = <<'HELP';
-This procedure returns TRUE if the specified item ID is a text layer.
+This procedure returns %TRUE if the specified item ID is a text layer.
+
+Note: in most use cases, you should not use this function. See
+[func@Gimp.Item.id_is_layer] for a discussion on alternatives.
 HELP
 
     &mitch_pdb_misc('2010', '3.0');
@@ -148,7 +184,10 @@ sub item_id_is_group_layer {
     $blurb = 'Returns whether the item ID is a group layer.';
 
     $help = <<'HELP';
-This procedure returns TRUE if the specified item ID is a group layer.
+This procedure returns %TRUE if the specified item ID is a group layer.
+
+Note: in most use cases, you should not use this function. See
+[func@Gimp.Item.id_is_layer] for a discussion on alternatives.
 HELP
 
     &jehan_pdb_misc('2024', '3.0');
@@ -178,7 +217,10 @@ sub item_id_is_channel {
     $blurb = 'Returns whether the item ID is a channel.';
 
     $help = <<HELP;
-This procedure returns TRUE if the specified item ID is a channel.
+This procedure returns %TRUE if the specified item ID is a channel.
+
+Note: in most use cases, you should not use this function. See
+[func@Gimp.Item.id_is_layer] for a discussion on alternatives.
 HELP
 
     &std_pdb_misc;
@@ -210,7 +252,10 @@ sub item_id_is_layer_mask {
     $blurb = 'Returns whether the item ID is a layer mask.';
 
     $help = <<HELP;
-This procedure returns TRUE if the specified item ID is a layer mask.
+This procedure returns %TRUE if the specified item ID is a layer mask.
+
+Note: in most use cases, you should not use this function. See
+[func@Gimp.Item.id_is_layer] for a discussion on alternatives.
 HELP
 
     &std_pdb_misc;
@@ -242,7 +287,10 @@ sub item_id_is_selection {
     $blurb = 'Returns whether the item ID is a selection.';
 
     $help = <<HELP;
-This procedure returns TRUE if the specified item ID is a selection.
+This procedure returns %TRUE if the specified item ID is a selection.
+
+Note: in most use cases, you should not use this function. See
+[func@Gimp.Item.id_is_layer] for a discussion on alternatives.
 HELP
 
     &std_pdb_misc;
@@ -274,7 +322,10 @@ sub item_id_is_path {
     $blurb = 'Returns whether the item ID is a path.';
 
     $help = <<HELP;
-This procedure returns TRUE if the specified item ID is a path.
+This procedure returns %TRUE if the specified item ID is a path.
+
+Note: in most use cases, you should not use this function. See
+[func@Gimp.Item.id_is_layer] for a discussion on alternatives.
 HELP
 
     &std_pdb_misc;
@@ -367,7 +418,7 @@ sub item_is_group {
     $blurb = 'Returns whether the item is a group item.';
 
     $help = <<HELP;
-This procedure returns TRUE if the specified item is a group item which
+This procedure returns %TRUE if the specified item is a group item which
 can have children.
 HELP
 
@@ -478,7 +529,7 @@ sub item_get_expanded {
     $blurb = 'Returns whether the item is expanded.';
 
     $help = <<HELP;
-This procedure returns TRUE if the specified item is expanded.
+This procedure returns %TRUE if the specified item is expanded.
 HELP
 
     &ell_pdb_misc('2017', '2.10');
diff --git a/pdb/groups/resource.pdb b/pdb/groups/resource.pdb
index 1a2beb29c0..c3bb482ca0 100644
--- a/pdb/groups/resource.pdb
+++ b/pdb/groups/resource.pdb
@@ -107,6 +107,10 @@ sub resource_id_is_valid {
     $help = <<'HELP';
 This procedure checks if the given resource ID is valid and refers to an
 existing resource.
+
+Note: in most use cases, you should not use this function. If you got a
+[class@Gimp.Resource] from the API, you should trust it is valid. This
+function is mostly for internal usage.
 HELP
 
     &mitch_pdb_misc('2023', '3.0');