diff --git a/docs/agents.md b/docs/agents.md
index b11a4dd68..f0bf5e662 100644
--- a/docs/agents.md
+++ b/docs/agents.md
@@ -10,7 +10,6 @@ The most common properties of an agent you'll configure are:
 -   `instructions`: also known as a developer message or system prompt.
 -   `model`: which LLM to use, and optional `model_settings` to configure model tuning parameters like temperature, top_p, etc.
 -   `tools`: Tools that the agent can use to achieve its tasks.
-
 ```python
 from agents import Agent, ModelSettings, function_tool
 
@@ -19,7 +18,9 @@ def get_weather(city: str) -> str:
     return f"The weather in {city} is sunny"
 
 agent = Agent(
+    # The 'name' is the agent's identity, used for context and tool calling.
     name="Haiku agent",
+    # The 'instructions' define the agent's core behavior and rules.
     instructions="Always respond in haiku form",
     model="o3-mini",
     tools=[get_weather],