docs: correct MCP server and AI agent config framing in overview

[micheleRP]

What

Fixes inaccurate configuration framing in the ADP overview page (adp-overview.adoc) and aligns the pages it links to. A review flagged that "you define tools in YAML" was wrong for MCP servers, and the same YAML framing had leaked onto AI agents. A follow-up review flagged that the next-click page (agents-overview.adoc) still used the "prebuilt Redpanda Connect connectors" framing this PR removes, so the overview and its destination contradicted each other.

Changes

• MCP servers (adp-overview.adoc): Removed "You define tools in YAML." You pick a managed type from the marketplace and configure it, or register a self-managed server, and the server's tools are discovered automatically.
• AI agents (adp-overview.adoc): Removed "you define behaviors in YAML." Agents are configured declaratively (system prompt, model, tools), not authored in YAML. "Prebuilt connectors" → "prebuilt tools and integrations."
• Cross-page consistency (agents-overview.adoc): Dropped the "prebuilt Redpanda Connect connectors" agent-tool framing; tools are now sourced through MCP servers. Redpanda Connect stays named as the underlying data/streaming engine, and the bidirectional pipeline↔agent integration is unchanged.
• MCP server landing pages (mcp-servers.adoc, connect/index.adoc): "managed connector" → "managed type", matching the canonical taxonomy in mcp-overview.adoc.

No new Redpanda Connect references; the connect: xrefs are internal ADP module references and remain correct.

Preview pages

• Redpanda ADP Overview (updated)
• How Agents Work (updated)

🤖 Generated with Claude Code

[netlify]

✅ Deploy Preview for redpanda-agentic-data-plane ready!

Name	Link
🔨 Latest commit	88cb727
🔍 Latest deploy log	https://app.netlify.com/projects/redpanda-agentic-data-plane/deploys/6a26d1410aae29000811d244
😎 Deploy Preview	https://deploy-preview-66--redpanda-agentic-data-plane.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[Feediver1]

PR Review

Files reviewed: 1 .adoc file (modules/get-started/pages/adp-overview.adoc)
Overall assessment: Small, accurate correction. The new framing aligns with what the linked MCP overview page already says. One critical cross-page inconsistency to address, plus a minor terminology suggestion.

What this PR does

Replaces inaccurate "you define tools in YAML" / "you define behaviors in YAML" claims in the ADP overview page. The MCP servers section now describes the actual workflow (pick a managed type from the marketplace, or register a self-run server; tools discovered automatically). The AI agents section now describes declarative configuration (system prompt, model, tools). "Prebuilt connectors" → "prebuilt tools and integrations" to drop a residual Redpanda Connect reference.

Critical issues (must fix)

1. Cross-page inconsistency with modules/connect/pages/agents-overview.adoc — the page directly linked from the corrected AI agents section (xref:connect:agents-overview.adoc[]) still uses the framing this PR is removing:
   • L3 (description): "...declarative approach backed by a broad library of prebuilt connectors..."
   • L10 (intro): "...connecting tools drawn from a broad library of prebuilt Redpanda Connect connectors."
   • L20: "...Redpanda Connect provides the connectors and robust data processing capabilities..."
   • L39: "...access to Redpanda Connect's library of prebuilt connectors for data sources, APIs, and services."
   • Fix: Either expand this PR to update agents-overview.adoc consistently, or open a follow-up so the overview and its next-click destination stop contradicting each other.

Suggestions (should consider)

1. adp-overview.adoc:37 — Terminology alignment with mcp-overview.adoc. The deeper page uses the taxonomy "Managed" / "Self-managed" backends. The new sentence uses "a server you already run" — same idea, less consistent.

   • Current: "...or register a server you already run, and the server's tools are discovered automatically."
   • Suggested: "...or register a self-managed server, and its tools are discovered automatically."

2. adp-overview.adoc:37 — The new sentence runs 33 words with three clauses. Optional split for rhythm:

   • Current: "You pick a managed type from a marketplace and configure it with your credentials, or register a server you already run, and the server's tools are discovered automatically."
   • Suggested: "You pick a managed type from the marketplace and configure it with your credentials, or register a self-managed server. Either way, the server's tools are discovered automatically through tools/list."

Impact on other files

• modules/connect/pages/agents-overview.adoc — see Critical issue Initial setup: ADP documentation repository #1.
• modules/connect/pages/mcp-overview.adoc — no update needed; already accurate (matches the PR's new framing).
• No release-notes / What's New page exists in this repo; not applicable.
• No nav.adoc update needed (existing page).
• No broken xrefs introduced. All 7 xref targets in the file verified.
• Other YAML mentions in the repo (byoa-register.adoc, continue-admin.adoc) refer to real MCP server config files, not the inaccurate framing — out of scope.

What works well

• New MCP framing matches the canonical description in mcp-overview.adoc (managed type from marketplace; tools/list discovery aligns with "discovered automatically").
• New AI agents framing (system prompt + model + tools) matches the component list in agents-overview.adoc:22-28.
• "Prebuilt tools and integrations" is appropriately neutral and drops the Redpanda Connect reference per PR intent.
• Active voice, second person, present tense preserved throughout.
• Glossterm macros, page attributes, learning objectives, and personas unchanged.

---

🤖 Generated with Claude Code via /docs-team-standards:pr-review

[micheleRP]

Thanks for the review. Addressed both items in-PR (commit 88cb727) rather than deferring to a follow-up, and extended the sweep to the MCP server landing pages for consistency.

Critical — agents-overview.adoc cross-page inconsistency: Fixed. Dropped the "prebuilt Redpanda Connect connectors" agent-tool framing on lines 3, 10, 20, and 39. Agent tools are now described as sourced through MCP servers, matching the corrected overview. I kept Redpanda Connect named as the underlying data/streaming engine and left the bidirectional pipeline↔agent integration (line 31) intact, since that's accurate.

Suggestion 1 — taxonomy alignment on adp-overview.adoc: Done. "register a server you already run" → "register a self-managed server", and "a marketplace" → "the marketplace", matching the Managed / Self-managed taxonomy in mcp-overview.adoc.

Suggestion 2 — sentence split + tools/list: Took the split but dropped the tools/list clause (it read as too much mechanism for the overview). The sentence is now: "You pick a managed type from the marketplace and configure it with your credentials, or register a self-managed server."

Extra (consistency sweep): Normalized "managed connector" → "managed type" in mcp-servers.adoc and connect/index.adoc so the MCP server landing pages use the same vocabulary as mcp-overview.adoc. Left remote-mcp-clients.adoc untouched — those "connector" mentions refer to external chat-client custom connectors (Claude's own term), not MCP backends.