diff --git a/src/agentCore.jl b/src/agentCore.jl
index 9c196fc..1853b9d 100644
--- a/src/agentCore.jl
+++ b/src/agentCore.jl
@@ -19,15 +19,32 @@ mutable struct yiemAgent <: agent             # High-level agent wrapper
   
   # user sends prompt message to agent. if agent is idle, it process user message right away. 
   # if agent is running, it process user message after  the current tool call finished.
-  # Expect each message in OpenAI chat format
+  # Expect each message in OpenAI chat format:
+  #   Dict("role" => "user", "content" => [
+  #     Dict("type" => "text", "text" => "Your question here"),
+  #     Dict("type" => "image_url", "image_url" => Dict("url" => "data:image/png;base64,<base64-string>"))
+  #   ])
+  # To embed an image, read it as bytes and encode to base64:
+  #   img = read("path/to/image.png")
+  #   b64 = base64encode(img)
+  #   data_uri = "data:image/png;base64,$b64"
+  #   message = Dict("role" => "user", "content" => [
+  #     Dict("type" => "text", "text" => "Do you have this wine?"),
+  #     Dict("type" => "image_url", "image_url" => Dict("url" => data_uri))
+  #   ])
+  # Multiple images can be included alongside text in the content array.
   inputChannel::Channel                        
                                               
-  # Buffers messages the user sends while the agent is busy. Processed after all inputChannel 
-  # messages are handled and the agent is idle (not using a tool call).
+  # Buffers follow-up messages the user sends while the agent is busy. Uses the same
+  # OpenAI chat format as inputChannel. Processed after all inputChannel messages are
+  # handled and the agent is idle (not in the middle of a tool call).
   followUpChannel::Channel                    
 
-  # agent sends response message to user after processing all user messages in inputChannel 
-  # and all followUp messages.
+  # agent sends response message to user after processing all user messages in inputChannel
+  # and all followUp messages. Response is in OpenAI message format:
+  #   Dict("role" => "assistant", "content" => [
+  #     Dict("type" => "text", "text" => "Response text here")
+  #   ])
   outputChannel::Channel                     
                                               
   _agentLoop::Union{Task, Nothing}                 # agent loop running in the background
@@ -116,7 +133,7 @@ function yiemAgent(
   outputChannel   = Channel(16)
 
   if mcpServer === nothing
-    """ please implement the following MCP server interface
+    error(""" please implement the following MCP server interface
     struct mcpServer
       natsConn::NATS.Connection
       topic::String
@@ -134,7 +151,7 @@ function yiemAgent(
       sessionId::String)::AbstractDict{String, <:Any}
       error("please implement MCP server interface")
     end
-    """
+    """)
   end
 
   tools = OrderedDict{String, agentTool}()