diff --git a/docs/deploy/decision-guide.md b/docs/deploy/decision-guide.md
new file mode 100644
index 000000000..f569d1d41
--- /dev/null
+++ b/docs/deploy/decision-guide.md
@@ -0,0 +1,61 @@
+# Deployment Strategy Guide
+
+Choosing the right deployment target for your ADK agents is critical for success. The ADK supports multiple deployment targets, ranging from fully managed serverless environments to custom containerized infrastructure.
+
+This guide helps you choose the right path based on your specific needs.
+
+## Decision Matrix
+
+Use this matrix to quickly identify the best deployment target for your project.
+
+| Feature | **Agent Engine** (Vertex AI) | **Cloud Run** (Serverless Container) | **GKE / Custom VM** |
+| :--- | :--- | :--- | :--- |
+| **Primary Use Case** | Pure agent logic, rapid prototyping, no-ops | Custom UIs, complex networking, specialized libraries | Enterprise compliance, existing K8s ecosystem |
+| **Management Overhead** | **Low** (Fully Managed) | **Medium** (Container configuration) | **High** (Cluster management) |
+| **State Management** | **Built-in** (Vertex AI Session Service) | **Ephemeral** (Requires external DB for persistence) | **External** (Requires external DB) |
+| **Scaling** | Auto-scaling (Managed) | Auto-scaling (0 to N instances) | Manual or Cluster Autoscaling |
+| **Networking** | Public API Endpoint | VPC connectivity, Custom Domains | Full VPC Control, Service Mesh |
+| **Cost Model** | Pay-per-use (Token/Request) | Compute-based (vCPU/Memory/Time) | Instance-based (Always on) |
+
+## Deployment Paths
+
+### Path A: Vertex AI Agent Engine (Recommended for most)
+**"I just want my agent to run."**
+
+This is the managed service path. You write code, and Google runs it. It supports both the "Accelerated" (Agent Starter Pack) and "Standard" deployment workflows described in the [Agent Engine documentation](./agent-engine.md).
+
+- **Pros**: No Dockerfile needed. No infrastructure config. Built-in conversation history via `VertexAiSessionService`.
+- **Cons**: Restricted runtime environment (cannot install system-level packages like `apt-get`).
+- **Command**: `adk deploy agent_engine`
+
+### Path B: Cloud Run (Native Deployment)
+**"I need a custom UI or specific libraries."**
+
+This acts like "Vercel for Agents". The ADK handles the containerization, but you get a standard Cloud Run service.
+- **Pros**: You can deploy a React frontend alongside your agent (`--with_ui`). You can install system dependencies (e.g., `poppler` for PDF parsing) by modifying the generated Dockerfile.
+- **Cons**: Session state is **ephemeral** by default (stored in memory). If the container restarts or scales down, conversation history is lost unless you configure an external database (Redis/SQL).
+- **Command**: `adk deploy cloud_run` (See [Cloud Run Guide](./cloud-run.md))
+
+### Path C: Container / GKE
+**"I have strict enterprise compliance requirements."**
+
+You package the agent as a Docker container yourself and deploy it to your existing infrastructure.
+- **Pros**: Complete control. Meets strict IT/Security policies.
+- **Cons**: You own the build pipeline, security patching, and orchestration.
+- **Guide**: See [GKE Guide](./gke.md)
+
+## Common Deployment Gotchas
+
+### Environment Variables
+- **Agent Engine**: The `adk deploy agent_engine` command reads your local `.env` file at **deployment time** to configure the service.
+    - *Tip*: If you exclude `.env` from version control (recommended), ensure you create one in your deployment environment (e.g., CI/CD pipeline) before running the deploy command.
+- **Cloud Run**: Variables can be passed during deployment or updated later on the service.
+    ```bash
+    adk deploy cloud_run --service_name my-agent
+    gcloud run services update my-agent --set-env-vars KEY=VALUE
+    ```
+
+### File Uploads
+If your agent processes files (PDFs, Images):
+- **Agent Engine**: Handles file storage automatically within the managed session context.
+- **Cloud Run**: You must implement a mechanism to accept file uploads (e.g., multipart/form-data) and store them (e.g., in Google Cloud Storage) before passing the URI to the agent, as the container's filesystem is ephemeral.
diff --git a/docs/tools-custom/best-practices.md b/docs/tools-custom/best-practices.md
new file mode 100644
index 000000000..6834c39d7
--- /dev/null
+++ b/docs/tools-custom/best-practices.md
@@ -0,0 +1,256 @@
+# Best Practices for Function Tools
+
+This guide provides best practices and common patterns for building robust and user-friendly function tools in ADK.
+
+## Handling File Uploads
+
+When building agents that process files, you often need to handle both:
+
+1. Files uploaded directly through the chat interface
+2. File paths provided as text by the user
+
+### Problem
+
+Without explicit handling, agents may:
+
+- Ask for file paths even when files are already uploaded
+- Fail to recognize uploaded files as attachments
+- Pass incorrect parameters to parsing tools
+
+### Solution: Flexible File Path Handling
+
+Design your tools to accept both display names (from uploaded files) and full file paths.
+
+???+ example "File Upload Tool Pattern"
+    === "Python"
+        ```python
+        import os
+
+        def parse_document(doc_path: str = "uploaded_document") -> str:
+          """Parses a document (uploaded file or file path).
+
+          Args:
+            doc_path: Display name of uploaded file or full file path.
+
+          Returns:
+            Success message with output path.
+          """
+          # Handle both uploaded file identifiers and full paths
+          if '/' in doc_path:
+            # Full path provided
+            run_id = os.path.basename(os.path.dirname(doc_path))
+          else:
+            # Uploaded file display name or simple identifier
+            run_id = doc_path.replace('.', '_')
+
+          output_path = f"output/{run_id}.xml"
+          os.makedirs(os.path.dirname(output_path), exist_ok=True)
+
+          # ... your parsing logic here
+
+          return f"Successfully parsed document to {output_path}"
+        ```
+
+### Agent Instructions
+
+Your agent instructions should explicitly guide the LLM on how to handle both upload methods:
+
+???+ example "Agent Instructions for File Handling"
+    === "Python"
+        ```python
+        from google.adk import Agent
+
+        agent = Agent(
+          name="DocumentParser",
+          model="gemini-2.0-flash",
+          instruction="""
+          You are a document parsing agent.
+
+          When the user provides files:
+          1. If files are uploaded directly in the chat:
+             - Acknowledge them by their display names
+             - Call parsing tools with their display names or identifiers
+             - You can identify uploaded files by their presence as attachments
+          2. If file paths are provided in text:
+             - Call parsing tools with the exact paths provided
+
+          Do not ask for file paths if files are already uploaded.
+          """,
+          tools=[parse_document]
+        )
+        ```
+
+### Why This Matters
+
+This pattern ensures your agent gracefully handles both upload methods, providing a better user experience.
+
+#### Example Usage
+
+**Uploaded File**:
+```
+User: [Uploads: report.pdf]
+      Parse this document
+
+Agent: [Calls parse_document("report.pdf")]
+```
+
+**File Path**:
+```
+User: Parse the document at /path/to/reports/quarterly_report.pdf
+
+Agent: [Calls parse_document("/path/to/reports/quarterly_report.pdf")]
+```
+
+## Type Annotations
+
+Always use explicit type annotations for function tool parameters to ensure proper schema generation.
+
+!!! warning "Use Explicit Types"
+    Bare `list` and `dict` types can cause schema validation errors. Always specify item types.
+
+???+ example "Proper Type Annotations"
+    === "❌ Invalid"
+        ```python
+        def process_items(items: list) -> str:
+            """This causes Gemini schema validation errors."""
+            pass
+        ```
+    === "✅ Valid"
+        ```python
+        from typing import List
+
+        def process_items(items: List[str]) -> str:
+            """Properly typed for Gemini schema generation."""
+            pass
+        ```
+
+## Tool Naming
+
+Use clear, descriptive names for your tools that indicate their purpose:
+
+- ✅ `get_weather_forecast`
+- ✅ `parse_pdf_document`
+- ✅ `calculate_tax_liability`
+- ❌ `tool1`
+- ❌ `process`
+- ❌ `do_thing`
+
+## Docstrings
+
+Provide comprehensive docstrings with `Args` and `Returns` sections. The LLM uses these to understand when and how to use your tool.
+
+???+ example "Well-Documented Tool"
+    === "Python"
+        ```python
+        def get_weather(city: str, unit: str = "celsius") -> dict:
+          """Retrieves current weather for a specified city.
+
+          This function fetches real-time weather data including temperature,
+          humidity, and conditions for the requested city.
+
+          Args:
+            city: The name of the city (e.g., "London", "New York").
+            unit: Temperature unit, either "celsius" or "fahrenheit".
+                  Defaults to "celsius".
+
+          Returns:
+            A dictionary containing:
+              - temperature: Current temperature as a float
+              - humidity: Humidity percentage as an integer
+              - conditions: Weather conditions as a string
+              - timestamp: UTC timestamp of the reading
+
+          Example:
+            >>> get_weather("Paris", "celsius")
+            {
+              "temperature": 18.5,
+              "humidity": 65,
+              "conditions": "Partly cloudy",
+              "timestamp": "2025-10-18T10:30:00Z"
+            }
+          """
+          # ... implementation
+        ```
+
+## Error Handling
+
+Return clear, actionable error messages that help the LLM understand what went wrong and how to fix it.
+
+???+ example "Error Handling"
+    === "❌ Poor Error Handling"
+        ```python
+        def validate_email(email: str) -> bool:
+            if "@" not in email:
+                raise ValueError("Invalid")
+            return True
+        ```
+    === "✅ Good Error Handling"
+        ```python
+        def validate_email(email: str) -> dict:
+            """Validates an email address format.
+
+            Args:
+              email: The email address to validate.
+
+            Returns:
+              A dictionary with 'valid' (bool) and 'message' (str) fields.
+            """
+            if "@" not in email:
+                return {
+                    "valid": False,
+                    "message": f"Email '{email}' is missing '@' symbol. "
+                               "Expected format: user@domain.com"
+                }
+
+            if "." not in email.split("@")[1]:
+                return {
+                    "valid": False,
+                    "message": f"Email '{email}' domain is missing a TLD. "
+                               "Expected format: user@domain.com"
+                }
+
+            return {
+                "valid": True,
+                "message": f"Email '{email}' is valid."
+            }
+        ```
+
+## Return Values
+
+Structure return values consistently and include enough context for the LLM to provide useful responses to the user.
+
+???+ tip "Structured Returns"
+    Return dictionaries with clear field names rather than plain strings or tuples when you have multiple pieces of information to convey.
+
+    === "❌ Unclear Return"
+        ```python
+        def search_products(query: str) -> str:
+            return "Found 3 items: item1, item2, item3"
+        ```
+    === "✅ Structured Return"
+        ```python
+        def search_products(query: str) -> dict:
+            """Searches for products matching the query.
+
+            Returns:
+              A dictionary containing:
+                - count: Number of products found
+                - products: List of product dictionaries
+                - query: The original search query
+            """
+            return {
+                "count": 3,
+                "products": [
+                    {"id": 1, "name": "item1", "price": 19.99},
+                    {"id": 2, "name": "item2", "price": 29.99},
+                    {"id": 3, "name": "item3", "price": 39.99}
+                ],
+                "query": query
+            }
+        ```
+
+## See Also
+
+- [Function Tools](function-tools.md) - Learn how to create function tools
+- [Long Running Tools](function-tools.md#long-run-tool) - Handle tools that take time to execute
+- [Tool Performance](performance.md) - Optimize tool execution
diff --git a/mkdocs.yml b/mkdocs.yml
index e7e84904d..aef6a3a2c 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -236,6 +236,7 @@ nav:
       - tools-custom/index.md
       - Function tools:
         - Overview: tools-custom/function-tools.md
+        - Best practices: tools-custom/best-practices.md
         - Tool performance: tools-custom/performance.md
         - Action confirmations: tools-custom/confirmation.md
       - MCP tools: tools-custom/mcp-tools.md
@@ -249,6 +250,7 @@ nav:
       - Resume Agents: runtime/resume.md
     - Deployment:
       - deploy/index.md
+      - Strategy Guide: deploy/decision-guide.md
       - Agent Engine: deploy/agent-engine.md
       - Cloud Run: deploy/cloud-run.md
       - GKE: deploy/gke.md
diff --git a/mkdocs.yml.backup b/mkdocs.yml.backup
new file mode 100644
index 000000000..620d6b476
--- /dev/null
+++ b/mkdocs.yml.backup
@@ -0,0 +1,394 @@
+# Project information
+site_name: Agent Development Kit
+site_url: https://google.github.io/adk-docs
+site_description: >-
+  Build powerful multi-agent systems with Agent Development Kit
+site_dir: site
+exclude_docs:
+  api-reference/java/legal/*
+
+# Repository
+repo_name: adk-docs
+repo_url: https://github.com/google/adk-docs
+edit_uri: edit/main/docs/
+
+# Copyright
+copyright: Copyright Google 2025&nbsp;&nbsp;|&nbsp;&nbsp;<a href="//policies.google.com/terms">Terms</a>&nbsp;&nbsp;|&nbsp;&nbsp;<a href="//policies.google.com/privacy">Privacy</a>&nbsp;&nbsp;|&nbsp;&nbsp;<a href="#__consent">Manage cookies</a>
+
+# Custom CSS
+extra_css:
+  - stylesheets/custom.css
+  - stylesheets/language-tags.css
+
+extra:
+  first_repo_url: https://github.com/google/adk-python
+  first_repo_name: adk-python
+  first_repo_icon: fontawesome/brands/github
+  second_repo_url: https://github.com/google/adk-go
+  second_repo_name: adk-go
+  second_repo_icon: fontawesome/brands/github
+  third_repo_url: https://github.com/google/adk-java
+  third_repo_name: adk-java
+  third_repo_icon: fontawesome/brands/github
+  analytics:
+    provider: google
+    property: G-DKHZS27PHP
+  consent:
+    title: Cookie consent
+    description: >-
+      We use cookies to recognize repeated visits and preferences,
+      as well as to measure the effectiveness of our documentation and
+      whether users find the information they need. With your consent,
+      you're helping us to make our documentation better.
+
+# Configuration
+theme:
+  name: material
+  font:
+    text: Google Sans
+    code: Roboto Mono
+  logo: assets/agent-development-kit.png
+  favicon: assets/agent-development-kit.png
+  icon:
+    repo: fontawesome/brands/github
+  custom_dir: overrides
+  palette:
+    - scheme: default
+      primary: white
+      accent: white
+      toggle:
+        icon: material/brightness-7
+        name: Switch to dark mode
+    - scheme: slate
+      primary: white
+      accent: white
+      toggle:
+        icon: material/brightness-4
+        name: Switch to light mode
+  features:
+    - content.action.edit
+    - content.action.view
+    - content.code.annotate
+    - content.code.copy
+    - content.code.select
+    - content.tabs.link
+    - content.tooltips
+    - navigation.footer
+    - navigation.indexes
+    - navigation.instant
+    - navigation.instant.progress
+    - navigation.path
+    - navigation.sections
+    - navigation.top
+    - navigation.tracking
+    - toc.follow
+
+# Extensions
+markdown_extensions:
+  - admonition
+  - attr_list
+  - md_in_html
+  - pymdownx.details
+  - pymdownx.emoji:
+      emoji_index: !!python/name:material.extensions.emoji.twemoji
+      emoji_generator: !!python/name:material.extensions.emoji.to_svg
+  - pymdownx.highlight:
+      anchor_linenums: true
+      line_spans: __span
+      pygments_lang_class: true
+  - pymdownx.inlinehilite
+  - pymdownx.snippets:
+      dedent_subsections: true
+  - pymdownx.superfences:
+      custom_fences:
+        - name: mermaid
+          class: mermaid
+          format: !!python/name:pymdownx.superfences.fence_code_format
+  - pymdownx.tabbed:
+      alternate_style: true
+      slugify: !!python/object/apply:pymdownx.slugs.slugify
+        kwds:
+          case: lower
+  - toc:
+      permalink: true
+
+
+# Plugins
+plugins:
+  - search
+  - redirects:
+      redirect_maps:
+        'get-started/local-testing.md': 'runtime/api-server.md'
+        'get-started/tutorial.md': 'tutorials/index.md'
+        'guides/responsible-agents.md': 'safety/index.md'
+        'tools/third-party-tools.md': 'tools/third-party/index.md'
+        'tools/third-party/openapi-tools.md': 'tools-custom/openapi-tools.md'
+        'tools/openapi-tools.md': 'tools-custom/openapi-tools.md'
+        'tutorials/ag-ui.md': 'tools/third-party/ag-ui.md'
+        'tools/third-party/langchain.md': 'tools/index.md'
+        'tools/third-party/crewai.md': 'tools/index.md'
+        'get-started/testing.md': 'runtime/api-server.md'
+        'tools/authentication.md': 'tools-custom/authentication.md'
+        'tools/function-tools.md': 'tools-custom/function-tools.md'
+        'tools/confirmation.md': 'tools-custom/confirmation.md'
+        'tools/performance.md': 'tools-custom/performance.md'
+        'tools/mcp-tools.md': 'tools-custom/mcp-tools.md'
+
+# Navigation
+nav:
+<<<<<<< HEAD
+  - Home:
+    - index.md
+  - Build Agents:
+    - Get Started:
+      - get-started/index.md
+      - Python: get-started/python.md
+      - Go: get-started/go.md
+      - Java: get-started/java.md
+    - Build your Agent:
+      - tutorials/index.md
+      - Multi-tool agent: get-started/quickstart.md
+      - Agent team: tutorials/agent-team.md
+      - Streaming agent:
+        - get-started/streaming/index.md
+        - Python: get-started/streaming/quickstart-streaming.md
+        - Java: get-started/streaming/quickstart-streaming-java.md
+      - Visual Builder: visual-builder/index.md
+      - Advanced setup: get-started/installation.md
+    - Agents:
+      - agents/index.md
+      - LLM agents: agents/llm-agents.md
+      - Workflow agents:
+        - agents/workflow-agents/index.md
+        - Sequential agents: agents/workflow-agents/sequential-agents.md
+        - Loop agents: agents/workflow-agents/loop-agents.md
+        - Parallel agents: agents/workflow-agents/parallel-agents.md
+      - Custom agents: agents/custom-agents.md
+      - Multi-agent systems: agents/multi-agents.md
+      - Agent Config: agents/config.md
+      - Models & Authentication: agents/models.md
+    - Tools for Agents:
+      - tools/index.md
+      - Built-in tools: tools/built-in-tools.md
+      - Gemini API tools:
+        -  Computer use: tools/gemini-api/computer-use.md
+      - Google Cloud tools:
+        - Overview: tools/google-cloud-tools.md
+        - MCP Toolbox for Databases: tools/google-cloud/mcp-toolbox-for-databases.md
+        - BigQuery Agent Analytics: tools/google-cloud/bigquery-agent-analytics.md
+        - Code Execution with Agent Engine: tools/google-cloud/code-exec-agent-engine.md
+      - Third-party tools:
+        - tools/third-party/index.md
+        - AgentQL: tools/third-party/agentql.md
+        - Bright Data: tools/third-party/bright-data.md
+        - Browserbase: tools/third-party/browserbase.md
+        - Exa: tools/third-party/exa.md
+        - Firecrawl: tools/third-party/firecrawl.md
+        - GitHub: tools/third-party/github.md
+        - Hugging Face: tools/third-party/hugging-face.md
+        - Notion: tools/third-party/notion.md
+        - Tavily: tools/third-party/tavily.md
+        - Agentic UI (AG-UI): tools/third-party/ag-ui.md
+    - Custom Tools:
+      - tools-custom/index.md
+      - Function tools:
+        - Overview: tools-custom/function-tools.md
+        - Tool performance: tools-custom/performance.md
+        - Action confirmations: tools-custom/confirmation.md
+      - MCP tools: tools-custom/mcp-tools.md
+      - OpenAPI tools: tools-custom/openapi-tools.md
+      - Authentication: tools-custom/authentication.md
+  - Run Agents:
+    - Agent Runtime:
+      - Agent Runtime: runtime/index.md
+      - Runtime Config: runtime/runconfig.md
+      - API Server: runtime/api-server.md
+      - Resume Agents: runtime/resume.md
+    - Deployment:
+      - deploy/index.md
+      - Agent Engine: deploy/agent-engine.md
+      - Cloud Run: deploy/cloud-run.md
+      - GKE: deploy/gke.md
+    - Observability:
+      - Logging: observability/logging.md
+      - Cloud Trace: observability/cloud-trace.md
+      - AgentOps: observability/agentops.md
+      - Arize AX: observability/arize-ax.md
+      - Freeplay: observability/freeplay.md
+      - Monocle: observability/monocle.md
+      - Phoenix: observability/phoenix.md
+      - W&B Weave: observability/weave.md
+    - Evaluation:
+      - evaluate/index.md
+      - Criteria: evaluate/criteria.md
+      - User Simulation: evaluate/user-sim.md
+    - Safety and Security:
+      - safety/index.md
+  - Components:
+    - Technical Overview: get-started/about.md
+    - Context:
+      - context/index.md
+      - Context caching: context/caching.md
+      - Context compression: context/compaction.md
+    - Sessions & Memory:
+      - sessions/index.md
+      - Session: sessions/session.md
+      - State: sessions/state.md
+      - Memory: sessions/memory.md
+      - Vertex AI Express Mode: sessions/express-mode.md
+    - Callbacks:
+      - callbacks/index.md
+      - Types of callbacks: callbacks/types-of-callbacks.md
+      - Callback patterns: callbacks/design-patterns-and-best-practices.md
+    - Artifacts:
+      - artifacts/index.md
+    - Events:
+      - events/index.md
+    - Apps:
+      - apps/index.md
+    - Plugins:
+      - plugins/index.md
+      - Reflect and retry: plugins/reflect-and-retry.md
+    - MCP:
+      - mcp/index.md
+    - A2A Protocol:
+      - a2a/index.md
+      - Introduction to A2A: a2a/intro.md
+      - A2A Quickstart (Exposing):
+        - Python: a2a/quickstart-exposing.md
+        - Go: a2a/quickstart-exposing-go.md
+      - A2A Quickstart (Consuming):
+        - Python: a2a/quickstart-consuming.md
+        - Go: a2a/quickstart-consuming-go.md
+    - Bidi-streaming (live):
+      - streaming/index.md
+      - Custom Audio Bidi-streaming app sample (WebSockets): streaming/custom-streaming-ws.md
+      - Bidi-streaming development guide series: streaming/dev-guide/part1.md
+      - Streaming Tools: streaming/streaming-tools.md
+      - Configurating Bidi-streaming behaviour: streaming/configuration.md
+    - Grounding:
+      - Understanding Google Search Grounding: grounding/google_search_grounding.md
+      - Understanding Vertex AI Search Grounding: grounding/vertex_ai_search_grounding.md
+  - Reference:
+    - API Reference:
+      - api-reference/index.md
+      - Python ADK: api-reference/python/index.html
+      - Go ADK: https://pkg.go.dev/google.golang.org/adk" target="_blank
+      - Java ADK: api-reference/java/index.html
+      - CLI Reference: api-reference/cli/index.html
+      - Agent Config reference: api-reference/agentconfig/index.html
+      - REST API: api-reference/rest/index.md
+    - Community Resources: community.md
+    - Contributing Guide: contributing-guide.md
+=======
+  - Home: index.md
+  - Get started:
+    - get-started/index.md
+    - Python: get-started/python.md
+    - Java: get-started/java.md
+  - Build your agent:
+    - tutorials/index.md
+    - Multi-tool agent: get-started/quickstart.md
+    - Agent team: tutorials/agent-team.md
+    - Streaming agent:
+      - get-started/streaming/index.md
+      - Python: get-started/streaming/quickstart-streaming.md
+      - Java: get-started/streaming/quickstart-streaming-java.md
+    - Testing: get-started/testing.md
+    - Code samples: https://github.com/google/adk-samples
+    - Advanced setup: get-started/installation.md
+  - Technical overview: get-started/about.md
+  - Agents:
+    - agents/index.md
+    - LLM agents: agents/llm-agents.md
+    - Workflow agents:
+      - agents/workflow-agents/index.md
+      - Sequential agents: agents/workflow-agents/sequential-agents.md
+      - Loop agents: agents/workflow-agents/loop-agents.md
+      - Parallel agents: agents/workflow-agents/parallel-agents.md
+    - Custom agents: agents/custom-agents.md
+    - Multi-agent systems: agents/multi-agents.md
+    - Agent Config: agents/config.md
+    - Models & Authentication: agents/models.md
+  - Tools for Agents:
+    - tools/index.md
+    - Built-in tools: tools/built-in-tools.md
+    - Google Cloud tools: tools/google-cloud-tools.md
+    - Third party tools: tools/third-party-tools.md
+    - OpenAPI tools: tools/openapi-tools.md
+  - Custom Tools:
+    - tools-custom/index.md
+    - Function tools:
+      - Overview: tools/function-tools.md
+      - Best practices: tools/best-practices.md
+      - Tool performance: tools/performance.md
+      - Action confirmations: tools/confirmation.md
+    - MCP tools: tools/mcp-tools.md
+    - Authentication: tools/authentication.md
+  - Running Agents:
+    - Agent Runtime: runtime/index.md
+    - Runtime Config: runtime/runconfig.md
+    - Resume Agents: runtime/resume.md
+  - Deploy:
+    - deploy/index.md
+    - Agent Engine: deploy/agent-engine.md
+    - Cloud Run: deploy/cloud-run.md
+    - GKE: deploy/gke.md
+  - Sessions & Memory:
+    - sessions/index.md
+    - Session: sessions/session.md
+    - State: sessions/state.md
+    - Memory: sessions/memory.md
+    - Vertex AI Express Mode: sessions/express-mode.md
+  - Callbacks:
+    - callbacks/index.md
+    - Types of callbacks: callbacks/types-of-callbacks.md
+    - Callback patterns: callbacks/design-patterns-and-best-practices.md
+  - Artifacts:
+    - artifacts/index.md
+  - Events:
+    - events/index.md
+  - Context:
+    - context/index.md
+  - Observability:
+    - Logging: observability/logging.md
+    - Cloud Trace: observability/cloud-trace.md
+    - AgentOps: observability/agentops.md
+    - Arize AX: observability/arize-ax.md
+    - Phoenix: observability/phoenix.md
+    - W&B Weave: observability/weave.md
+  - Evaluate:
+    - evaluate/index.md
+    - Criteria: evaluate/criteria.md
+  - MCP:
+    - mcp/index.md
+  - Plugins:
+    - plugins/index.md
+  - Bidi-streaming (live):
+    - streaming/index.md
+    - Custom Audio Bidi-streaming app sample (SSE): streaming/custom-streaming.md
+    - Custom Audio Bidi-streaming app sample (WebSockets): streaming/custom-streaming-ws.md
+    - Bidi-streaming development guide series: streaming/dev-guide/part1.md
+    - Streaming Tools: streaming/streaming-tools.md
+    - Configurating Bidi-streaming behaviour: streaming/configuration.md
+    - Google ADK + Vertex AI Live API (blog post): https://medium.com/google-cloud/google-adk-vertex-ai-live-api-125238982d5e
+  - Grounding:
+    - Understanding Google Search Grounding: grounding/google_search_grounding.md
+    - Understanding Vertex AI Search Grounding: grounding/vertex_ai_search_grounding.md
+  - Safety and Security: safety/index.md
+  - A2A Protocol:
+    - a2a/index.md
+    - Introduction to A2A: a2a/intro.md
+    - A2A Quickstart (Exposing): a2a/quickstart-exposing.md
+    - A2A Quickstart (Consuming): a2a/quickstart-consuming.md
+    - A2A Protocol Documentation: https://a2a-protocol.org
+  - Community Resources: community.md
+  - Contributing Guide: contributing-guide.md
+  - API Reference:
+    - api-reference/index.md
+    - Python ADK: api-reference/python/index.html
+    - Java ADK: api-reference/java/index.html
+    - CLI Reference: api-reference/cli/index.html
+    - Agent Config reference: api-reference/agentconfig/index.html
+    - REST API: api-reference/rest/index.md
+>>>>>>> 48a18a8 (docs: add best-practices.md to navigation)
diff --git a/mkdocs_fixed.yml b/mkdocs_fixed.yml
new file mode 100644
index 000000000..f96475ec7
--- /dev/null
+++ b/mkdocs_fixed.yml
@@ -0,0 +1,138 @@
+# Project information
+site_name: Agent Development Kit
+site_url: https://google.github.io/adk-docs
+site_description: >-
+  Build powerful multi-agent systems with Agent Development Kit
+site_dir: site
+exclude_docs:
+  api-reference/java/legal/*
+
+# Repository
+repo_name: adk-docs
+repo_url: https://github.com/google/adk-docs
+edit_uri: edit/main/docs/
+
+# Copyright
+copyright: Copyright Google 2025&nbsp;&nbsp;|&nbsp;&nbsp;<a href="//policies.google.com/terms">Terms</a>&nbsp;&nbsp;|&nbsp;&nbsp;<a href="//policies.google.com/privacy">Privacy</a>&nbsp;&nbsp;|&nbsp;&nbsp;<a href="#__consent">Manage cookies</a>
+
+# Custom CSS
+extra_css:
+  - stylesheets/custom.css
+  - stylesheets/language-tags.css
+
+extra:
+  first_repo_url: https://github.com/google/adk-python
+  first_repo_name: adk-python
+  first_repo_icon: fontawesome/brands/github
+  second_repo_url: https://github.com/google/adk-go
+  second_repo_name: adk-go
+  second_repo_icon: fontawesome/brands/github
+  third_repo_url: https://github.com/google/adk-java
+  third_repo_name: adk-java
+  third_repo_icon: fontawesome/brands/github
+  analytics:
+    provider: google
+    property: G-DKHZS27PHP
+  consent:
+    title: Cookie consent
+    description: >-
+      We use cookies to recognize repeated visits and preferences,
+      as well as to measure the effectiveness of our documentation and
+      whether users find the information they need. With your consent,
+      you're helping us to make our documentation better.
+
+# Configuration
+theme:
+  name: material
+  font:
+    text: Google Sans
+    code: Roboto Mono
+  logo: assets/agent-development-kit.png
+  favicon: assets/agent-development-kit.png
+  icon:
+    repo: fontawesome/brands/github
+  custom_dir: overrides
+  palette:
+    - scheme: default
+      primary: white
+      accent: white
+      toggle:
+        icon: material/brightness-7
+        name: Switch to dark mode
+    - scheme: slate
+      primary: white
+      accent: white
+      toggle:
+        icon: material/brightness-4
+        name: Switch to light mode
+  features:
+    - content.action.edit
+    - content.action.view
+    - content.code.annotate
+    - content.code.copy
+    - content.code.select
+    - content.tabs.link
+    - content.tooltips
+    - navigation.footer
+    - navigation.indexes
+    - navigation.instant
+    - navigation.instant.progress
+    - navigation.path
+    - navigation.sections
+    - navigation.top
+    - navigation.tracking
+    - toc.follow
+
+# Extensions
+markdown_extensions:
+  - admonition
+  - attr_list
+  - md_in_html
+  - pymdownx.details
+  - pymdownx.emoji:
+      emoji_index: !!python/name:material.extensions.emoji.twemoji
+      emoji_generator: !!python/name:material.extensions.emoji.to_svg
+  - pymdownx.highlight:
+      anchor_linenums: true
+      line_spans: __span
+      pygments_lang_class: true
+  - pymdownx.inlinehilite
+  - pymdownx.snippets:
+      dedent_subsections: true
+  - pymdownx.superfences:
+      custom_fences:
+        - name: mermaid
+          class: mermaid
+          format: !!python/name:pymdownx.superfences.fence_code_format
+  - pymdownx.tabbed:
+      alternate_style: true
+      slugify: !!python/object/apply:pymdownx.slugs.slugify
+        kwds:
+          case: lower
+  - toc:
+      permalink: true
+
+
+# Plugins
+plugins:
+  - search
+  - redirects:
+      redirect_maps:
+        'get-started/local-testing.md': 'runtime/api-server.md'
+        'get-started/tutorial.md': 'tutorials/index.md'
+        'guides/responsible-agents.md': 'safety/index.md'
+        'tools/third-party-tools.md': 'tools/third-party/index.md'
+        'tools/third-party/openapi-tools.md': 'tools-custom/openapi-tools.md'
+        'tools/openapi-tools.md': 'tools-custom/openapi-tools.md'
+        'tutorials/ag-ui.md': 'tools/third-party/ag-ui.md'
+        'tools/third-party/langchain.md': 'tools/index.md'
+        'tools/third-party/crewai.md': 'tools/index.md'
+        'get-started/testing.md': 'runtime/api-server.md'
+        'tools/authentication.md': 'tools-custom/authentication.md'
+        'tools/function-tools.md': 'tools-custom/function-tools.md'
+        'tools/confirmation.md': 'tools-custom/confirmation.md'
+        'tools/performance.md': 'tools-custom/performance.md'
+        'tools/mcp-tools.md': 'tools-custom/mcp-tools.md'
+
+# Navigation
+nav: