diff --git a/docs/user/FlowVariables.md b/docs/user/FlowVariables.md
index 32051e5c09..178f0f2b0a 100644
--- a/docs/user/FlowVariables.md
+++ b/docs/user/FlowVariables.md
@@ -270,7 +270,7 @@ configuration file.
 | <a name="VERILOG_DEFINES"></a>VERILOG_DEFINES| Preprocessor defines passed to the language frontend. Example: `-D HPDCACHE_ASSERT_OFF`| |
 | <a name="VERILOG_FILES"></a>VERILOG_FILES| The path to the design Verilog/SystemVerilog files providing a description of modules.| |
 | <a name="VERILOG_INCLUDE_DIRS"></a>VERILOG_INCLUDE_DIRS| Specifies the include directories for the Verilog input files.| |
-| <a name="VERILOG_TOP_PARAMS"></a>VERILOG_TOP_PARAMS| Apply toplevel params (if exist).| |
+| <a name="VERILOG_TOP_PARAMS"></a>VERILOG_TOP_PARAMS| Apply toplevel params (if exist). Passed in as a list of key value pairs in tcl syntax; separated by spaces: PARAM1 VALUE1 PARAM2 VALUE2 stages: - synth| |
 | <a name="YOSYS_FLAGS"></a>YOSYS_FLAGS| Flags to pass to yosys.| -v 3|
 ## synth variables
 
@@ -306,7 +306,6 @@ configuration file.
 - [VERILOG_DEFINES](#VERILOG_DEFINES)
 - [VERILOG_FILES](#VERILOG_FILES)
 - [VERILOG_INCLUDE_DIRS](#VERILOG_INCLUDE_DIRS)
-- [VERILOG_TOP_PARAMS](#VERILOG_TOP_PARAMS)
 - [YOSYS_FLAGS](#YOSYS_FLAGS)
 
 ## floorplan variables
@@ -541,4 +540,5 @@ configuration file.
 - [TAP_CELL_NAME](#TAP_CELL_NAME)
 - [TECH_LEF](#TECH_LEF)
 - [USE_FILL](#USE_FILL)
+- [VERILOG_TOP_PARAMS](#VERILOG_TOP_PARAMS)
 
diff --git a/flow/scripts/variables.yaml b/flow/scripts/variables.yaml
index 56b77c37c0..fe50e320f2 100644
--- a/flow/scripts/variables.yaml
+++ b/flow/scripts/variables.yaml
@@ -873,8 +873,9 @@ SYNTH_OPT_HIER:
     - synth
 VERILOG_TOP_PARAMS:
   description: |
-    Apply toplevel params (if exist).
-  stages:
+    Apply toplevel params (if exist). Passed in as a list of key value pairs
+    in tcl syntax; separated by spaces: PARAM1 VALUE1 PARAM2 VALUE2
+    stages:
     - synth
 CORE_ASPECT_RATIO:
   description: >