diff --git a/website/docs/reference/project-configs/query-comment.md b/website/docs/reference/project-configs/query-comment.md
index 7e654350306..f7f9472e947 100644
--- a/website/docs/reference/project-configs/query-comment.md
+++ b/website/docs/reference/project-configs/query-comment.md
@@ -30,7 +30,7 @@ query-comment:
 </File>
 
 ## Definition
-A string to inject as a comment in each query that dbt runs against your database. This comment can be used to attribute SQL statements to specific dbt resources like models and tests.
+A string to inject as a comment in each query that dbt runs against your database. This comment can attribute SQL statements to specific dbt resources like models and tests.
 
 The `query-comment` configuration can also call a macro that returns a string.
 
@@ -51,7 +51,7 @@ create view analytics.analytics.orders as (
 
 ## Using the dictionary syntax
 The dictionary syntax includes two keys:
-  * `comment` (optional, see above for default): The string to be injected to a query as a comment.
+  * `comment` (optional, for more information, refer to the [default](#default) section): The string to be injected into a query as a comment.
   * `append` (optional, default=`false`): Whether a comment should be appended (added to the bottom of a query) or not (i.e. added to the top of a query). By default, comments are added to the top of queries (i.e. `append: false`).
 
 This syntax is useful on databases like Snowflake which [remove leading SQL comments](https://docs.snowflake.com/en/release-notes/2017-04.html#queries-leading-comments-removed-during-execution).
@@ -275,4 +275,6 @@ The following context variables are available when generating a query comment:
 | var              | See [var](/reference/dbt-jinja-functions/var) |
 | target           | See [target](/reference/dbt-jinja-functions/target) |
 | connection_name  | A string representing the internal name for the connection. This string is generated by dbt. |
-| node             | A dictionary representation of the parsed node object. Use `node.unique_id`, `node.database`, `node.schema`, etc |
+| node             | A dictionary representation of the parsed node object. Use `node.unique_id`, `node.database`, `node.schema`, and so on. |
+
+Note: The `var()` function in `query-comment` macros only access variables passed through the `--vars` argument in the CLI. Variables defined in the vars block of your `dbt_project.yml` are not accessible when generating query comments.