diff --git a/hugr-core/src/envelope.rs b/hugr-core/src/envelope.rs
index c0c0663133..ccfe50661b 100644
--- a/hugr-core/src/envelope.rs
+++ b/hugr-core/src/envelope.rs
@@ -65,7 +65,9 @@ use crate::import::ImportError;
 use crate::{Extension, import::import_package};
 
 /// Key used to store the name of the generator that produced the envelope.
-pub const GENERATOR_KEY: &str = "__generator";
+pub const GENERATOR_KEY: &str = "core.generator";
+/// Key used to store the list of used extensions in the metadata of a HUGR.
+pub const USED_EXTENSIONS_KEY: &str = "core.used_extensions";
 
 /// Get the name of the generator from the metadata of the HUGR modules.
 /// If multiple modules have different generators, a comma-separated list is returned in
@@ -459,9 +461,6 @@ fn encode_model<'h>(
     Ok(())
 }
 
-/// Key used to store the list of used extensions in the metadata of a HUGR.
-pub const USED_EXTENSIONS_KEY: &str = "__used_extensions";
-
 #[derive(Debug, Clone, PartialEq, Eq, serde::Deserialize)]
 struct UsedExtension {
     name: String,
diff --git a/specification/hugr.md b/specification/hugr.md
index 032a221639..52b46653c0 100644
--- a/specification/hugr.md
+++ b/specification/hugr.md
@@ -770,11 +770,14 @@ existing metadata, given the node ID.
 `Ports` (for port metadata) or `History` (for use by the rewrite
 engine)?
 
+Reserved metadata keys used by the HUGR tooling are prefixed with `core.`.
+Use of this prefix by external tooling may cause issues. 
+
 #### Generator Metadata
 Tooling generating HUGR can specify some reserved metadata keys to be used for debugging
 purposes. 
 
-The key `__generator` when used on the module root node is
+The key `core.generator` when used on the module root node is
 used to specify the tooling used to generate the module.
 The associated value must be an object/dictionary containing the fields `name`
 and `version`, each with string values. Extra fields may be used to include
@@ -782,11 +785,11 @@ additional data about generating tooling that may be useful for debugging. Examp
 
 ```json
 {
-  "__generator": { "name": "my_compiler", "version": "1.0.0" }
+  "core.generator": { "name": "my_compiler", "version": "1.0.0" }
 }
 ```
 
-The key `__used_extensions` when used on the module root node is
+The key `core.used_extensions` when used on the module root node is
 used to specify the names and versions of all the extensions used in the module.
 Some of these may correspond to extensions packaged with the module, but they
 may also be extensions the consuming tooling has pre-loaded. They can be used by the
@@ -795,7 +798,7 @@ must be an array of objects/dictionaries containing the keys `name` and `version
 with string values. Example:
 ```json
 {
-  "__used_extensions": [{ "name": "my_ext", "version": "2.2.3" }]
+  "core.used_extensions": [{ "name": "my_ext", "version": "2.2.3" }]
 }
 ```