diff --git a/docs/reference/pixi_manifest.md b/docs/reference/pixi_manifest.md
index 84230242eb..481ae0ff5a 100644
--- a/docs/reference/pixi_manifest.md
+++ b/docs/reference/pixi_manifest.md
@@ -639,6 +639,11 @@ There are two types of activation operations a user can modify in the manifest:
 
 These activation operations will be run before the `pixi run` and `pixi shell` commands.
 
+!!! note
+    The script specified in the `scripts` section are not directly sourced in the `pixi shell`, but rather they are called,
+    and the environment variables they set are then set in the `pixi shell`, so any defined function or other non-environment variable
+    modification to the environment will be ignored.
+
 !!! note
     The activation operations are run by the system shell interpreter as they run before an environment is available.
     This means that it runs as `cmd.exe` on windows and `bash` on linux and osx (Unix).