diff --git a/pkgs/native_assets_cli/lib/src/api/build.dart b/pkgs/native_assets_cli/lib/src/api/build.dart
index 5534773ec..c033a8c58 100644
--- a/pkgs/native_assets_cli/lib/src/api/build.dart
+++ b/pkgs/native_assets_cli/lib/src/api/build.dart
@@ -11,6 +11,8 @@ import '../validation.dart';
 
 /// Runs a native assets build.
 ///
+/// Meant to be used in build hooks (`hook/build.dart`).
+///
 /// Can build native assets which are not already available, or expose existing
 /// files. Each individual asset is assigned a unique asset ID.
 ///
@@ -87,6 +89,11 @@ import '../validation.dart';
 ///   });
 /// }
 /// ```
+///
+/// If the [builder] fails, it must `throw`. Build hooks are guaranteed to be
+/// invoked with a process invocation and should return a non-zero exit code on
+/// failure. Throwing will lead to an uncaught exception, causing a non-zero
+/// exit code.
 Future<void> build(
   List<String> arguments,
   Future<void> Function(BuildConfig config, BuildOutputBuilder output) builder,
diff --git a/pkgs/native_assets_cli/lib/src/api/link.dart b/pkgs/native_assets_cli/lib/src/api/link.dart
index 975ec280b..fe3d445bf 100644
--- a/pkgs/native_assets_cli/lib/src/api/link.dart
+++ b/pkgs/native_assets_cli/lib/src/api/link.dart
@@ -11,6 +11,8 @@ import '../validation.dart';
 
 /// Runs a native assets link.
 ///
+/// Meant to be used in link hooks (`hook/link.dart`).
+///
 /// Can link native assets which are not already available, or expose existing
 /// files. Each individual asset is assigned a unique asset ID.
 ///
@@ -30,6 +32,10 @@ import '../validation.dart';
 ///   });
 /// }
 /// ```
+/// If the [linker] fails, it must `throw`. Link hooks are guaranteed to be
+/// invoked with a process invocation and should return a non-zero exit code on
+/// failure. Throwing will lead to an uncaught exception, causing a non-zero
+/// exit code.
 Future<void> link(
   List<String> arguments,
   Future<void> Function(LinkConfig config, LinkOutputBuilder output) linker,