diff --git a/doc/api/cli.md b/doc/api/cli.md
index f41af658228d43..2f5d4223334263 100644
--- a/doc/api/cli.md
+++ b/doc/api/cli.md
@@ -154,8 +154,9 @@ the [Permission Model][].
 
 The valid arguments for the `--allow-fs-read` flag are:
 
-* `*` - To allow the `FileSystemRead` operations.
-* Paths delimited by comma (,) to manage `FileSystemRead` (reading) operations.
+* `*` - To allow all `FileSystemRead` operations.
+* Paths delimited by comma (`,`) to allow only matching `FileSystemRead`
+  operations.
 
 Examples can be found in the [File System Permissions][] documentation.
 
@@ -200,8 +201,9 @@ the [Permission Model][].
 
 The valid arguments for the `--allow-fs-write` flag are:
 
-* `*` - To allow the `FileSystemWrite` operations.
-* Paths delimited by comma (,) to manage `FileSystemWrite` (writing) operations.
+* `*` - To allow all `FileSystemWrite` operations.
+* Paths delimited by comma (`,`) to allow only matching `FileSystemWrite`
+  operations.
 
 Examples can be found in the [File System Permissions][] documentation.
 
diff --git a/doc/api/permissions.md b/doc/api/permissions.md
index ad41e4f290e625..0b48a682dc7413 100644
--- a/doc/api/permissions.md
+++ b/doc/api/permissions.md
@@ -520,8 +520,10 @@ Hello world!
 
 The valid arguments for both flags are:
 
-* `*` - To allow the all operations to given scope (read/write).
-* Paths delimited by comma (,) to manage reading/writing operations.
+* `*` - To allow all `FileSystemRead` or `FileSystemWrite` operations,
+  respectively.
+* Paths delimited by comma (`,`) to allow only matching `FileSystemRead` or
+  `FileSystemWrite` operations, respectively.
 
 Example: