docs: document make-before-break reconnection and shared-client retry behavior

[Pratham-Mishra04]

Summary

Briefly explain the purpose of this PR and the problem it solves.

Changes

• What was changed and why
• Any notable design decisions or trade-offs

Type of change

• Bug fix
• Feature
• Refactor
• Documentation
• Chore/CI

Affected areas

• Core (Go)
• Transports (HTTP)
• Providers/Integrations
• Plugins
• UI (React)
• Docs

How to test

Describe the steps to validate this change. Include commands and expected outcomes.

# Core/Transports
go version
go test ./...

# UI
cd ui
pnpm i || npm i
pnpm test || npm test
pnpm build || npm run build

If adding new configs or environment variables, document them here.

Screenshots/Recordings

If UI changes, add before/after screenshots or short clips.

Breaking changes

• Yes
• No

If yes, describe impact and migration instructions.

Related issues

Link related issues and discussions. Example: Closes #123

Security considerations

Note any security implications (auth, secrets, PII, sandboxing, etc.).

Checklist

• I read docs/contributing/README.md and followed the guidelines
• I added/updated tests where appropriate
• I updated documentation where needed
• I verified builds succeed (Go and UI)
• I verified the CI pipeline passes locally if applicable

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

[coderabbitai]

Note

GitHub couldn't provide a complete incremental comparison for this pull request, so CodeRabbit is performing a full review instead. This review may take a little longer.

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/mcp/tool-execution.mdx`:
- Around line 389-390: Update the shared-client retry documentation around the
“Shared clients” and “Safety opt-out” bullets to state that retries require an
explicit idempotency/retry-safety annotation. Include missing or unsafe
annotations among the conditions that prevent retries, while preserving the
background reconnect behavior and original-error semantics.

🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: cec7d011-a8eb-4849-8cee-1e5f7012ab74

📥 Commits

Reviewing files that changed from the base of the PR and between 5c06241 and eb95068.

📒 Files selected for processing (4)

• docs/mcp/auth/oauth.mdx
• docs/mcp/auth/overview.mdx
• docs/mcp/gateway.mdx
• docs/mcp/tool-execution.mdx

🚧 Files skipped from review as they are similar to previous changes (3)

• docs/mcp/auth/overview.mdx
• docs/mcp/gateway.mdx
• docs/mcp/auth/oauth.mdx

The base branch was changed.

[Pratham-Mishra04]

Merge activity

• Aug 8, 10:33 AM UTC: A user started a stack merge that includes this pull request via Graphite.
• Aug 8, 10:34 AM UTC: @Pratham-Mishra04 merged this pull request with Graphite.