diff --git a/codex-rs/ext/image-generation/imagegen_description.md b/codex-rs/ext/image-generation/imagegen_description.md
index 53e6620135..4cad4a971f 100644
--- a/codex-rs/ext/image-generation/imagegen_description.md
+++ b/codex-rs/ext/image-generation/imagegen_description.md
@@ -6,12 +6,14 @@ The `image_gen.imagegen` tool enables image generation from descriptions and edi
 Guidelines:
 - In code mode, pass the result to `generatedImage(result)`.
 - Omit both `referenced_image_paths` and `num_last_images_to_include` when generating a brand new image.
+- If the user wants a new image based on one or more local reference images, treat it as a reference-backed edit request and include those images; do not treat the filename alone as sufficient image input.
 - For edits, use `referenced_image_paths` when every target image has a local file path.
 - If you have not seen a local image yet, use `view_image` to inspect it before editing.
 - Use `num_last_images_to_include` only when at least one target image has no local file path.
 - Set `num_last_images_to_include` to the smallest number of recent conversation images that includes every target image, up to 5.
 - Never provide both `referenced_image_paths` and `num_last_images_to_include`.
-- If neither mechanism can include every target image, ask the user to attach the missing images again.
+- If `view_image` fails, `referenced_image_paths` cannot include the required local image, or neither mechanism can include every target image, ask the user to attach the missing images again or fix access first.
+- Never fall back to text-only generation when the user asked to use a local reference image that you could not actually attach.
 - Directly generate the image without reconfirmation or clarification unless required images must be attached again.
 - After each image generation, do not mention anything related to download. Do not summarize the image. Do not ask followup question. Do not say ANYTHING after you generate an image.
 - Always use this tool for image editing unless the user explicitly requests otherwise. Do not use the `python` tool for image editing unless specifically instructed.
diff --git a/codex-rs/ext/image-generation/src/tool.rs b/codex-rs/ext/image-generation/src/tool.rs
index d4451a8926..f5fab4771f 100644
--- a/codex-rs/ext/image-generation/src/tool.rs
+++ b/codex-rs/ext/image-generation/src/tool.rs
@@ -73,9 +73,17 @@ impl ImageGenerationTool {
 #[derive(Debug, Deserialize, JsonSchema)]
 #[serde(deny_unknown_fields)]
 struct ImagegenArgs {
+    /// A prompt describing the desired output. Do not use a local filename in
+    /// this text as a substitute for attaching a required reference image.
     prompt: String,
+    /// Absolute local image paths to include as real image inputs. Use this for
+    /// every required local reference image instead of falling back to text-only
+    /// generation when the user asked to base the result on those files.
     #[schemars(length(max = 5))]
     referenced_image_paths: Option<Vec<AbsolutePathBuf>>,
+    /// The smallest number of recent conversation images needed when at least
+    /// one required image has no local path. Do not use this when all required
+    /// reference images are still local files.
     #[schemars(range(min = 1, max = 5))]
     num_last_images_to_include: Option<usize>,
 }