Address PR feedback

Author: greenie-msft

samples-v2/openai_agents/docs/getting-started.md

@@ -126,7 +126,7 @@ def main():
     return result.final_output
 ```
 
-**Durable Transformation**: The `@durable_openai_agent_orchestrator` decorator in `function_app.py` wraps this agent execution within a Durable Functions orchestrator, providing agent state persisted at each LLM and tool interaction.
+**Durable Transformation**: The `@app.durable_openai_agent_orchestrator` decorator in `function_app.py` wraps this agent execution within a Durable Functions orchestrator, providing agent state persisted at each LLM and tool interaction.
 
 ## Execution and Monitoring
 

samples-v2/openai_agents/docs/reference.md

@@ -4,15 +4,15 @@ Complete reference for Durable OpenAI Agents integration.
 
 ## Durable Orchestration
 
-### @durable_openai_agent_orchestrator
+### @app.durable_openai_agent_orchestrator
 
 Primary decorator enabling durable execution for agent invocations.
 
 ```python
 from azure.durable_functions.openai_agents import durable_openai_agent_orchestrator
 
 @app.orchestration_trigger(context_name="context")
-@durable_openai_agent_orchestrator
+@app.durable_openai_agent_orchestrator
 def my_agent_orchestrator(context):
     # Agent implementation
     pass
@@ -31,11 +31,11 @@ def my_agent_orchestrator(context):
 
 ### @app.orchestration_trigger
 
-Azure Functions orchestration trigger decorator. Required with `@durable_openai_agent_orchestrator`.
+Azure Functions orchestration trigger decorator. Required with `@app.durable_openai_agent_orchestrator`.
 
 ```python
 @app.orchestration_trigger(context_name="context")
-@durable_openai_agent_orchestrator
+@app.durable_openai_agent_orchestrator
 def my_orchestrator(context):
     # ...
 ```
@@ -63,30 +63,9 @@ def my_orchestrator(context):
 
 ## Tools
 
-### Open AI Function Tools
-
-Simple, deterministic tools that execute within the orchestration context.
-
-```python
-from agents import function_tool
-
-@function_tool
-def calculate(expression: str) -> str:
-    """Calculate mathematical expressions."""
-    return str(eval(expression))
-```
-
-**Requirements**:
-- Must be deterministic (same input → same output)
-- Should be fast-executing
-- No external API calls (use activity tools instead)
-- Input/output must be JSON serializable
-
-**Best For**: Calculations, data transformations, validation logic, quick lookups
-
 ### Durable Functions Activity Tools
 
-Durable Function Activities that execute as durable tool invocations for complex operations.
+Durable Function Activities that execute as durable tool invocations. **This is the recommended approach for most use cases** as it provides the strongest correctness guarantees. - **When in doubt - this is the safe choice**
 
 ```python
 # 1. Define activity function
@@ -97,7 +76,7 @@ async def my_activity(input_param):
 
 # 2. Use in orchestrator
 @app.orchestration_trigger(context_name="context")
-@durable_openai_agent_orchestrator
+@app.durable_openai_agent_orchestrator
 def my_orchestrator(context):
     agent = Agent(
         tools=[context.create_activity_tool(my_activity)]
@@ -111,18 +90,26 @@ def my_orchestrator(context):
 
 **Best For**: External API calls, database operations, file I/O, expensive computations, non-deterministic operations
 
-### Tool Selection Guide
+### Open AI Function Tools
+
+Simple, deterministic tools that execute within the orchestration context. **Recommended only as a performance optimization when you're certain the tool meets all deterministic requirements.**
+
+```python
+from agents import function_tool
+
+@function_tool
+def calculate(expression: str) -> str:
+    """Calculate mathematical expressions."""
+    return str(eval(expression))
+```
 
-**Use Function Tools when**:
-- Operations are deterministic and fast
-- No external dependencies required
-- Simple calculations or data transformations
+**Requirements**:
+- Must be deterministic (same input → same output)
+- Should be fast-executing
+- No external API calls (use activity tools instead)
+- Input/output must be JSON serializable
 
-**Use Activity Tools when**:
-- Making external API calls or database queries
-- Operations may fail and need retry logic
-- Long-running or expensive computations
-- Non-deterministic operations
+**Best For**: Calculations, data transformations, validation logic, quick lookups
 
 ### Current Limitations