Address feedback

Author: JakeSCahill

modules/ai-agents/examples/agents/dispute-root-agent-prompt.txt

@@ -61,12 +61,12 @@ Never:
 **Clear, bank-appropriate language:**
 - Use "I've reviewed your account" not "I called the account-agent"
 - Use "this charge doesn't match your typical spending" not "fraud score is 95/100"
-- Use "I'm blocking this card" not "I recommend you freeze it"
+- Use "We're blocking this card" not "I recommend you freeze it"
 - Don't reveal merchant reputation scores or fraud report counts
 
 **Proactive protection:**
 For likely fraud (score 80+):
-- Block the card immediately: "I'm blocking your card ending in [XXXX] right now to prevent additional fraudulent charges"
+- Block the card immediately: "We're blocking your card ending in [XXXX] right now to prevent additional fraudulent charges"
 - Issue replacement: "We'll send you a replacement card with a new number"
 - Process the claim: "You'll see the credit for this charge within 10 business days"
 

modules/ai-agents/pages/agents/architecture-patterns.adoc

@@ -6,7 +6,7 @@
 :learning-objective-2: Choose appropriate LLM models based on task requirements
 :learning-objective-3: Apply agent boundary design principles for maintainability
 
-Design agent systems that are maintainable, discoverable, and reliable by choosing the right architecture pattern and applying clear boundary principles.
+This topic helps you design agent systems that are maintainable, discoverable, and reliable by choosing the right architecture pattern and applying clear boundary principles.
 
 After reading this page, you will be able to:
 
@@ -140,7 +140,7 @@ For implementation details on external A2A integration, see xref:ai-agents:agent
 
 == Common anti-patterns
 
-Avoid these architecture mistakes that lead to unmaintainable agent systems.
+Avoid these architecture mistakes that lead to unmaintainable agent systems. For examples of well-structured agents, see the xref:ai-agents:agents/tutorials/customer-support-agent.adoc[multi-tool orchestration tutorial] and xref:ai-agents:agents/tutorials/transaction-dispute-resolution.adoc[multi-agent architecture tutorial].
 
 === The monolithic prompt
 
@@ -212,7 +212,7 @@ For complex reasoning, choose premium models such as Claude Opus 4.5 or GPT-5.2.
 
 For real-time responses, choose smaller models. Use models optimized for speed, such as Mini or base tiers.
 
-For batch processing, optimize for accuracy over speed. Use larger models when users don't wait for results.
+For batch processing, optimize for accuracy over speed. Use larger models when users aren't waiting for results.
 
 === Optimize for cost and volume
 

modules/ai-agents/pages/agents/integration-overview.adoc

@@ -115,7 +115,7 @@ When integrating external applications with Redpanda Cloud agents, protect crede
 
 === Protect service account credentials
 
-Store the client ID and secret in secure credential stores, not in code. Use environment variables or secrets management systems. Rotate credentials if compromised and restrict access based on the principle of least privilege.
+Store the client ID and secret in secure credential stores, not in code. Use environment variables or xref:security:secrets.adoc[secrets management]. Rotate credentials if compromised and restrict access based on the principle of least privilege.
 
 === Protect access tokens
 

modules/ai-agents/pages/agents/monitor-agents.adoc

@@ -88,7 +88,7 @@ The *Inspector* tab provides real-time conversation testing. Use it to test agen
 
 === Testing best practices
 
-Test your agents systematically by exploring edge cases and potential failure scenarios. Begin with boundary testing. Requests at the edge of agent capabilities verify that scope enforcement works correctly. Error handling becomes clear when you request unavailable data and observe whether the agent degrades gracefully or fabricates information.
+Test your agents systematically by exploring edge cases and potential failure scenarios. Begin with boundary testing. Requests at the edge of agent capabilities verify that scope enforcement works correctly. Error handling becomes clear when you request unavailable data and observe whether the agent degrades gracefully. Even with proper system prompt constraints, testing confirms that your agent responds appropriately to edge cases.
 
 Monitor iteration counts during complex requests to ensure they complete within your configured limits. Ambiguous or vague queries reveal whether the agent asks clarifying questions or makes risky assumptions. Throughout testing, track token usage per request to estimate costs and identify which query patterns consume the most resources.
 

modules/ai-agents/pages/agents/tutorials/customer-support-agent.adoc

@@ -16,7 +16,7 @@ After completing this tutorial, you will be able to:
 * [ ] {learning-objective-2}
 * [ ] {learning-objective-3}
 
-== What you'll learn
+== Why multi-tool orchestration matters
 
 Agents become powerful when they coordinate multiple tools to solve complex problems. A single-tool agent can retrieve order status. A multi-tool agent can check order status, fetch tracking information, look up customer history, and decide which tools to invoke based on conversation context.
 

modules/ai-agents/pages/agents/tutorials/transaction-dispute-resolution.adoc

@@ -613,7 +613,7 @@ The pipeline uses a two-stage filter:
 - Only processes transactions with `amount > 500` or `preliminary_flag == true`
 - Only sends transactions to the agent if `preliminary_risk_score >= 40`
 
-Transactions that pass the first filter but not the second (e.g., a $600 domestic transaction with low risk) will appear in the output with:
+Transactions that pass the first filter but not the second (for example, a $600 domestic transaction with low risk) will appear in the output with:
 
 * `final_decision: "low_risk_no_investigation"`
 * `alert_level: "low"`

modules/ai-agents/pages/observability/concepts.adoc

@@ -110,15 +110,15 @@ MCP server traces contain these span types:
 | Internal service processing span that appears at multiple levels in the hierarchy. Represents Redpanda Connect service operations including routing, processing, and component execution.
 | Track internal processing overhead and identify where time is spent in the service layer.
 
-| Tool name (e.g., `get_order_status`, `get_customer_history`)
+| Tool name (for example, `get_order_status`, `get_customer_history`)
 | The specific MCP tool being invoked. This span name matches the tool name defined in the MCP server configuration.
 | Identify which tool was called and measure tool-specific execution time.
 
 | `processors`
 | Processor pipeline execution span showing the collection of processors that process the tool's data. Appears as a child of the tool invocation span.
 | Measure total processor pipeline execution time.
 
-| Processor name (e.g., `mapping`, `http`, `branch`)
+| Processor name (for example, `mapping`, `http`, `branch`)
 | Individual processor execution span representing a single Redpanda Connect processor. The span name matches the processor type.
 | Identify slow processors and debug processing logic.
 |===

modules/ai-agents/partials/transcripts-ui-guide.adoc

@@ -34,7 +34,7 @@
 === Navigate the transcripts view
 
 // Navigation is identical for both contexts
-. In the left navigation panel, click *Transcripts*.
+. Click *Transcripts*.
 ifeval::["{context}" == "agent"]
 . Select a recent transcript from your agent executions.
 endif::[]
@@ -44,14 +44,14 @@ endif::[]
 
 The transcripts view displays:
 
-* *Timeline* (top): Visual history of recent executions with success/error indicators
-* *Trace list* (middle): Hierarchical view of traces and spans
-* *Summary panel* (right): Detailed metrics when you select a transcript
+* *Timeline*: Visual history of recent executions with success/error indicators
+* *Trace list*: Hierarchical view of traces and spans
+* *Summary panel*: Detailed metrics when you select a transcript
 
 // UI component descriptions
 ==== Timeline visualization
 
-The timeline at the top shows execution patterns over time:
+The timeline shows execution patterns over time:
 
 * Green bars: Successful executions
 * Red bars: Failed executions with errors
@@ -74,7 +74,7 @@ endif::[]
 
 ==== Summary panel
 
-When you select a transcript, the right panel shows:
+When you select a transcript, the summary panel shows:
 
 * Duration: Total execution time for this request
 * Total Spans: Number of operations in the trace