Merge remote-tracking branch 'origin/dev' into fix/block-search-camelcase

Reverts the %s-style lazy formatting back to f-strings in both
hybrid_search.py and content_handlers.py, as requested in review
thread #27 — the prior commit went in the wrong direction.

autogpt_platform/backend/backend/api/features/store/content_handlers.py

@@ -5,16 +5,26 @@ Pluggable system for different content sources (store agents, blocks, docs).
 Each handler knows how to fetch and process its content type for embedding.
 """
 
+from __future__ import annotations
+
+import asyncio
+import functools
+import itertools
 import logging
 from abc import ABC, abstractmethod
 from dataclasses import dataclass
 from pathlib import Path
-from typing import Any, get_args, get_origin
+from typing import TYPE_CHECKING, Any, get_args, get_origin
 
 from prisma.enums import ContentType
 
+from backend.blocks import get_blocks
 from backend.blocks.llm import LlmModel
 from backend.data.db import query_raw_with_schema
+from backend.util.text import split_camelcase
+
+if TYPE_CHECKING:
+    from backend.blocks._base import AnyBlockSchema
 
 logger = logging.getLogger(__name__)
 
@@ -154,6 +164,28 @@ class StoreAgentHandler(ContentHandler):
         }
 
 
+@functools.lru_cache(maxsize=1)
+def _get_enabled_blocks() -> dict[str, AnyBlockSchema]:
+    """Return ``{block_id: block_instance}`` for all enabled, instantiable blocks.
+
+    Disabled blocks and blocks that fail to instantiate are silently skipped
+    (with a warning log), so callers never need their own try/except loop.
+
+    Results are cached for the process lifetime via ``lru_cache`` because
+    blocks are registered at import time and never change while running.
+    """
+    enabled: dict[str, AnyBlockSchema] = {}
+    for block_id, block_cls in get_blocks().items():
+        try:
+            instance = block_cls()
+        except Exception as e:
+            logger.warning(f"Skipping block {block_id}: init failed: {e}")
+            continue
+        if not instance.disabled:
+            enabled[block_id] = instance
+    return enabled
+
+
 class BlockHandler(ContentHandler):
     """Handler for block definitions (Python classes)."""
 
@@ -163,16 +195,14 @@ class BlockHandler(ContentHandler):
 
     async def get_missing_items(self, batch_size: int) -> list[ContentItem]:
         """Fetch blocks without embeddings."""
-        from backend.blocks import get_blocks
-
-        # Get all available blocks
-        all_blocks = get_blocks()
-
-        # Check which ones have embeddings
-        if not all_blocks:
+        # to_thread keeps the first (heavy) call off the event loop.  On
+        # subsequent calls the lru_cache makes this a dict lookup, so the
+        # thread-pool overhead is negligible compared to the DB queries below.
+        enabled = await asyncio.to_thread(_get_enabled_blocks)
+        if not enabled:
             return []
 
-        block_ids = list(all_blocks.keys())
+        block_ids = list(enabled.keys())
 
         # Query for existing embeddings
         placeholders = ",".join([f"${i+1}" for i in range(len(block_ids))])
@@ -187,52 +217,42 @@ class BlockHandler(ContentHandler):
         )
 
         existing_ids = {row["contentId"] for row in existing_result}
-        missing_blocks = [
-            (block_id, block_cls)
-            for block_id, block_cls in all_blocks.items()
-            if block_id not in existing_ids
-        ]
 
-        # Convert to ContentItem
+        # Convert to ContentItem — disabled filtering already done by
+        # _get_enabled_blocks so batch_size won't be exhausted by disabled blocks.
+        missing = ((bid, b) for bid, b in enabled.items() if bid not in existing_ids)
         items = []
-        for block_id, block_cls in missing_blocks[:batch_size]:
+        for block_id, block in itertools.islice(missing, batch_size):
             try:
-                block_instance = block_cls()
-
-                if block_instance.disabled:
-                    continue
-
                 # Build searchable text from block metadata
-                parts = []
-                if block_instance.name:
-                    parts.append(block_instance.name)
-                if block_instance.description:
-                    parts.append(block_instance.description)
-                if block_instance.categories:
-                    parts.append(
-                        " ".join(str(cat.value) for cat in block_instance.categories)
+                if not block.name:
+                    logger.warning(
+                        f"Block {block_id} has no name — using block_id as fallback"
                     )
+                display_name = split_camelcase(block.name) if block.name else ""
+                parts = []
+                if display_name:
+                    parts.append(display_name)
+                if block.description:
+                    parts.append(block.description)
+                if block.categories:
+                    parts.append(" ".join(str(cat.value) for cat in block.categories))
 
                 # Add input schema field descriptions
-                block_input_fields = block_instance.input_schema.model_fields
                 parts += [
                     f"{field_name}: {field_info.description}"
-                    for field_name, field_info in block_input_fields.items()
+                    for field_name, field_info in block.input_schema.model_fields.items()
                     if field_info.description
                 ]
 
                 searchable_text = " ".join(parts)
 
                 categories_list = (
-                    [cat.value for cat in block_instance.categories]
-                    if block_instance.categories
-                    else []
+                    [cat.value for cat in block.categories] if block.categories else []
                 )
 
                 # Extract provider names from credentials fields
-                credentials_info = (
-                    block_instance.input_schema.get_credentials_fields_info()
-                )
+                credentials_info = block.input_schema.get_credentials_fields_info()
                 is_integration = len(credentials_info) > 0
                 provider_names = [
                     provider.value.lower()
@@ -243,7 +263,7 @@ class BlockHandler(ContentHandler):
                 # Check if block has LlmModel field in input schema
                 has_llm_model_field = any(
                     _contains_type(field.annotation, LlmModel)
-                    for field in block_instance.input_schema.model_fields.values()
+                    for field in block.input_schema.model_fields.values()
                 )
 
                 items.append(
@@ -252,13 +272,13 @@ class BlockHandler(ContentHandler):
                         content_type=ContentType.BLOCK,
                         searchable_text=searchable_text,
                         metadata={
-                            "name": block_instance.name,
+                            "name": display_name or block.name or block_id,
                             "categories": categories_list,
                             "providers": provider_names,
                             "has_llm_model_field": has_llm_model_field,
                             "is_integration": is_integration,
                         },
-                        user_id=None,  # Blocks are public
+                        user_id=None,
                     )
                 )
             except Exception as e:
@@ -269,22 +289,13 @@ class BlockHandler(ContentHandler):
 
     async def get_stats(self) -> dict[str, int]:
         """Get statistics about block embedding coverage."""
-        from backend.blocks import get_blocks
-
-        all_blocks = get_blocks()
-
-        # Filter out disabled blocks - they're not indexed
-        enabled_block_ids = [
-            block_id
-            for block_id, block_cls in all_blocks.items()
-            if not block_cls().disabled
-        ]
-        total_blocks = len(enabled_block_ids)
+        enabled = await asyncio.to_thread(_get_enabled_blocks)
+        total_blocks = len(enabled)
 
         if total_blocks == 0:
             return {"total": 0, "with_embeddings": 0, "without_embeddings": 0}
 
-        block_ids = enabled_block_ids
+        block_ids = list(enabled.keys())
         placeholders = ",".join([f"${i+1}" for i in range(len(block_ids))])
 
         embedded_result = await query_raw_with_schema(

autogpt_platform/backend/backend/api/features/store/content_handlers_test.py

@@ -1,7 +1,5 @@
 """
-E2E tests for content handlers (blocks, store agents, documentation).
-
-Tests the full flow: discovering content → generating embeddings → storing.
+Tests for content handlers (blocks, store agents, documentation).
 """
 
 from pathlib import Path
@@ -15,15 +13,103 @@ from backend.api.features.store.content_handlers import (
     BlockHandler,
     DocumentationHandler,
     StoreAgentHandler,
+    _get_enabled_blocks,
 )
 
 
+@pytest.fixture(autouse=True)
+def _clear_block_cache():
+    """Clear the lru_cache on _get_enabled_blocks before each test."""
+    _get_enabled_blocks.cache_clear()
+    yield
+    _get_enabled_blocks.cache_clear()
+
+
+# ---------------------------------------------------------------------------
+# Helper to build a mock block class that returns a pre-configured instance
+# ---------------------------------------------------------------------------
+
+
+def _make_block_class(
+    *,
+    name: str = "Block",
+    description: str = "",
+    disabled: bool = False,
+    categories: list[MagicMock] | None = None,
+    fields: dict[str, str] | None = None,
+    raise_on_init: Exception | None = None,
+) -> MagicMock:
+    cls = MagicMock()
+    if raise_on_init is not None:
+        cls.side_effect = raise_on_init
+        return cls
+    inst = MagicMock()
+    inst.name = name
+    inst.disabled = disabled
+    inst.description = description
+    inst.categories = categories or []
+    field_mocks = {
+        fname: MagicMock(description=fdesc) for fname, fdesc in (fields or {}).items()
+    }
+    inst.input_schema.model_fields = field_mocks
+    inst.input_schema.get_credentials_fields_info.return_value = {}
+    cls.return_value = inst
+    return cls
+
+
+# ---------------------------------------------------------------------------
+# _get_enabled_blocks
+# ---------------------------------------------------------------------------
+
+
+def test_get_enabled_blocks_filters_disabled():
+    """Disabled blocks are excluded."""
+    blocks = {
+        "enabled": _make_block_class(name="E", disabled=False),
+        "disabled": _make_block_class(name="D", disabled=True),
+    }
+    with patch(
+        "backend.api.features.store.content_handlers.get_blocks", return_value=blocks
+    ):
+        result = _get_enabled_blocks()
+    assert list(result.keys()) == ["enabled"]
+
+
+def test_get_enabled_blocks_skips_broken():
+    """Blocks that raise on init are skipped without crashing."""
+    blocks = {
+        "good": _make_block_class(name="Good"),
+        "bad": _make_block_class(raise_on_init=RuntimeError("boom")),
+    }
+    with patch(
+        "backend.api.features.store.content_handlers.get_blocks", return_value=blocks
+    ):
+        result = _get_enabled_blocks()
+    assert list(result.keys()) == ["good"]
+
+
+def test_get_enabled_blocks_cached():
+    """_get_enabled_blocks() calls get_blocks() only once across multiple calls."""
+    blocks = {"b1": _make_block_class(name="B1")}
+    with patch(
+        "backend.api.features.store.content_handlers.get_blocks", return_value=blocks
+    ) as mock_get_blocks:
+        result1 = _get_enabled_blocks()
+        result2 = _get_enabled_blocks()
+    assert result1 is result2
+    mock_get_blocks.assert_called_once()
+
+
+# ---------------------------------------------------------------------------
+# StoreAgentHandler
+# ---------------------------------------------------------------------------
+
+
 @pytest.mark.asyncio(loop_scope="session")
 async def test_store_agent_handler_get_missing_items(mocker):
     """Test StoreAgentHandler fetches approved agents without embeddings."""
     handler = StoreAgentHandler()
 
-    # Mock database query
     mock_missing = [
         {
             "id": "agent-1",
@@ -54,9 +140,7 @@ async def test_store_agent_handler_get_stats(mocker):
     """Test StoreAgentHandler returns correct stats."""
     handler = StoreAgentHandler()
 
-    # Mock approved count query
     mock_approved = [{"count": 50}]
-    # Mock embedded count query
     mock_embedded = [{"count": 30}]
 
     with patch(
@@ -70,74 +154,130 @@ async def test_store_agent_handler_get_stats(mocker):
         assert stats["without_embeddings"] == 20
 
 
+# ---------------------------------------------------------------------------
+# BlockHandler
+# ---------------------------------------------------------------------------
+
+
 @pytest.mark.asyncio(loop_scope="session")
-async def test_block_handler_get_missing_items(mocker):
+async def test_block_handler_get_missing_items():
     """Test BlockHandler discovers blocks without embeddings."""
     handler = BlockHandler()
 
-    # Mock get_blocks to return test blocks
-    mock_block_class = MagicMock()
-    mock_block_instance = MagicMock()
-    mock_block_instance.name = "Calculator Block"
-    mock_block_instance.description = "Performs calculations"
-    mock_block_instance.categories = [MagicMock(value="MATH")]
-    mock_block_instance.disabled = False
-    mock_field = MagicMock()
-    mock_field.description = "Math expression to evaluate"
-    mock_block_instance.input_schema.model_fields = {"expression": mock_field}
-    mock_block_instance.input_schema.get_credentials_fields_info.return_value = {}
-    mock_block_class.return_value = mock_block_instance
-
-    mock_blocks = {"block-uuid-1": mock_block_class}
-
-    # Mock existing embeddings query (no embeddings exist)
-    mock_existing = []
+    blocks = {
+        "block-uuid-1": _make_block_class(
+            name="CalculatorBlock",
+            description="Performs calculations",
+            categories=[MagicMock(value="MATH")],
+            fields={"expression": "Math expression to evaluate"},
+        ),
+    }
 
     with patch(
-        "backend.blocks.get_blocks",
-        return_value=mock_blocks,
+        "backend.api.features.store.content_handlers.get_blocks", return_value=blocks
     ):
         with patch(
             "backend.api.features.store.content_handlers.query_raw_with_schema",
-            return_value=mock_existing,
+            return_value=[],
         ):
             items = await handler.get_missing_items(batch_size=10)
 
             assert len(items) == 1
             assert items[0].content_id == "block-uuid-1"
             assert items[0].content_type == ContentType.BLOCK
+            # CamelCase should be split in searchable text and metadata name
             assert "Calculator Block" in items[0].searchable_text
             assert "Performs calculations" in items[0].searchable_text
             assert "MATH" in items[0].searchable_text
             assert "expression: Math expression" in items[0].searchable_text
+            assert items[0].metadata["name"] == "Calculator Block"
             assert items[0].user_id is None
 
 
 @pytest.mark.asyncio(loop_scope="session")
-async def test_block_handler_get_stats(mocker):
+async def test_block_handler_get_missing_items_splits_camelcase():
+    """CamelCase block names are split for better search indexing."""
+    handler = BlockHandler()
+
+    blocks = {
+        "ai-block": _make_block_class(name="AITextGeneratorBlock"),
+    }
+
+    with patch(
+        "backend.api.features.store.content_handlers.get_blocks", return_value=blocks
+    ):
+        with patch(
+            "backend.api.features.store.content_handlers.query_raw_with_schema",
+            return_value=[],
+        ):
+            items = await handler.get_missing_items(batch_size=10)
+
+            assert len(items) == 1
+            assert "AI Text Generator Block" in items[0].searchable_text
+
+
+@pytest.mark.asyncio(loop_scope="session")
+async def test_block_handler_get_missing_items_batch_size_zero():
+    """batch_size=0 returns an empty list; the DB is still queried to find missing IDs."""
+    handler = BlockHandler()
+
+    blocks = {"b1": _make_block_class(name="B1")}
+
+    with patch(
+        "backend.api.features.store.content_handlers.get_blocks", return_value=blocks
+    ):
+        with patch(
+            "backend.api.features.store.content_handlers.query_raw_with_schema",
+            return_value=[],
+        ) as mock_query:
+            items = await handler.get_missing_items(batch_size=0)
+            assert items == []
+            # DB query is still issued to learn which blocks lack embeddings;
+            # the empty result comes from itertools.islice limiting to 0 items.
+            mock_query.assert_called_once()
+
+
+@pytest.mark.asyncio(loop_scope="session")
+async def test_block_handler_disabled_dont_exhaust_batch():
+    """Disabled blocks don't consume batch budget, so enabled blocks get indexed."""
+    handler = BlockHandler()
+
+    # 5 disabled + 3 enabled, batch_size=2
+    blocks = {
+        **{
+            f"dis-{i}": _make_block_class(name=f"D{i}", disabled=True) for i in range(5)
+        },
+        **{f"en-{i}": _make_block_class(name=f"E{i}") for i in range(3)},
+    }
+
+    with patch(
+        "backend.api.features.store.content_handlers.get_blocks", return_value=blocks
+    ):
+        with patch(
+            "backend.api.features.store.content_handlers.query_raw_with_schema",
+            return_value=[],
+        ):
+            items = await handler.get_missing_items(batch_size=2)
+
+            assert len(items) == 2
+            assert all(item.content_id.startswith("en-") for item in items)
+
+
+@pytest.mark.asyncio(loop_scope="session")
+async def test_block_handler_get_stats():
     """Test BlockHandler returns correct stats."""
     handler = BlockHandler()
 
-    # Mock get_blocks - each block class returns an instance with disabled=False
-    def make_mock_block_class():
-        mock_class = MagicMock()
-        mock_instance = MagicMock()
-        mock_instance.disabled = False
-        mock_class.return_value = mock_instance
-        return mock_class
-
-    mock_blocks = {
-        "block-1": make_mock_block_class(),
-        "block-2": make_mock_block_class(),
-        "block-3": make_mock_block_class(),
+    blocks = {
+        "block-1": _make_block_class(name="B1"),
+        "block-2": _make_block_class(name="B2"),
+        "block-3": _make_block_class(name="B3"),
     }
 
-    # Mock embedded count query (2 blocks have embeddings)
     mock_embedded = [{"count": 2}]
 
     with patch(
-        "backend.blocks.get_blocks",
-        return_value=mock_blocks,
+        "backend.api.features.store.content_handlers.get_blocks", return_value=blocks
     ):
         with patch(
             "backend.api.features.store.content_handlers.query_raw_with_schema",
@@ -150,21 +290,123 @@ async def test_block_handler_get_stats(mocker):
             assert stats["without_embeddings"] == 1
 
 
+@pytest.mark.asyncio(loop_scope="session")
+async def test_block_handler_get_stats_skips_broken():
+    """get_stats skips broken blocks instead of crashing."""
+    handler = BlockHandler()
+
+    blocks = {
+        "good": _make_block_class(name="Good"),
+        "bad": _make_block_class(raise_on_init=RuntimeError("boom")),
+    }
+
+    mock_embedded = [{"count": 1}]
+
+    with patch(
+        "backend.api.features.store.content_handlers.get_blocks", return_value=blocks
+    ):
+        with patch(
+            "backend.api.features.store.content_handlers.query_raw_with_schema",
+            return_value=mock_embedded,
+        ):
+            stats = await handler.get_stats()
+
+            assert stats["total"] == 1  # only the good block
+            assert stats["with_embeddings"] == 1
+
+
+@pytest.mark.asyncio(loop_scope="session")
+async def test_block_handler_handles_none_name():
+    """When block.name is None the fallback display name logic is used."""
+    handler = BlockHandler()
+
+    blocks = {
+        "none-name-block": _make_block_class(
+            name="placeholder",  # will be overridden to None below
+            description="A block with no name",
+        ),
+    }
+    # Override the name to None after construction so _make_block_class
+    # doesn't interfere with the mock wiring.
+    blocks["none-name-block"].return_value.name = None
+
+    with patch(
+        "backend.api.features.store.content_handlers.get_blocks", return_value=blocks
+    ):
+        with patch(
+            "backend.api.features.store.content_handlers.query_raw_with_schema",
+            return_value=[],
+        ):
+            items = await handler.get_missing_items(batch_size=10)
+
+            assert len(items) == 1
+            # display_name should be "" because block.name is None
+            # searchable_text should still contain the description
+            assert "A block with no name" in items[0].searchable_text
+            # metadata["name"] falls back to block_id when both display_name
+            # and block.name are falsy, ensuring it is always a non-empty string.
+            assert items[0].metadata["name"] == "none-name-block"
+
+
+@pytest.mark.asyncio(loop_scope="session")
+async def test_block_handler_handles_empty_attributes():
+    """Test BlockHandler handles blocks with empty/falsy attribute values."""
+    handler = BlockHandler()
+
+    blocks = {"block-minimal": _make_block_class(name="Minimal Block")}
+
+    with patch(
+        "backend.api.features.store.content_handlers.get_blocks", return_value=blocks
+    ):
+        with patch(
+            "backend.api.features.store.content_handlers.query_raw_with_schema",
+            return_value=[],
+        ):
+            items = await handler.get_missing_items(batch_size=10)
+
+            assert len(items) == 1
+            assert items[0].searchable_text == "Minimal Block"
+
+
+@pytest.mark.asyncio(loop_scope="session")
+async def test_block_handler_skips_failed_blocks():
+    """Test BlockHandler skips blocks that fail to instantiate."""
+    handler = BlockHandler()
+
+    blocks = {
+        "good-block": _make_block_class(name="Good Block", description="Works fine"),
+        "bad-block": _make_block_class(raise_on_init=Exception("Instantiation failed")),
+    }
+
+    with patch(
+        "backend.api.features.store.content_handlers.get_blocks", return_value=blocks
+    ):
+        with patch(
+            "backend.api.features.store.content_handlers.query_raw_with_schema",
+            return_value=[],
+        ):
+            items = await handler.get_missing_items(batch_size=10)
+
+            assert len(items) == 1
+            assert items[0].content_id == "good-block"
+
+
+# ---------------------------------------------------------------------------
+# DocumentationHandler
+# ---------------------------------------------------------------------------
+
+
 @pytest.mark.asyncio(loop_scope="session")
 async def test_documentation_handler_get_missing_items(tmp_path, mocker):
     """Test DocumentationHandler discovers docs without embeddings."""
     handler = DocumentationHandler()
 
-    # Create temporary docs directory with test files
     docs_root = tmp_path / "docs"
     docs_root.mkdir()
-
     (docs_root / "guide.md").write_text("# Getting Started\n\nThis is a guide.")
     (docs_root / "api.mdx").write_text("# API Reference\n\nAPI documentation.")
 
-    # Mock _get_docs_root to return temp dir
     with patch.object(handler, "_get_docs_root", return_value=docs_root):
-        # Mock existing embeddings query (no embeddings exist)
         with patch(
             "backend.api.features.store.content_handlers.query_raw_with_schema",
             return_value=[],
@@ -173,7 +415,6 @@ async def test_documentation_handler_get_missing_items(tmp_path, mocker):
 
             assert len(items) == 2
 
-            # Check guide.md (content_id format: doc_path::section_index)
             guide_item = next(
                 (item for item in items if item.content_id == "guide.md::0"), None
             )
@@ -184,7 +425,6 @@ async def test_documentation_handler_get_missing_items(tmp_path, mocker):
             assert guide_item.metadata["doc_title"] == "Getting Started"
             assert guide_item.user_id is None
 
-            # Check api.mdx (content_id format: doc_path::section_index)
             api_item = next(
                 (item for item in items if item.content_id == "api.mdx::0"), None
             )
@@ -197,14 +437,12 @@ async def test_documentation_handler_get_stats(tmp_path, mocker):
     """Test DocumentationHandler returns correct stats."""
     handler = DocumentationHandler()
 
-    # Create temporary docs directory
     docs_root = tmp_path / "docs"
     docs_root.mkdir()
     (docs_root / "doc1.md").write_text("# Doc 1")
     (docs_root / "doc2.md").write_text("# Doc 2")
     (docs_root / "doc3.mdx").write_text("# Doc 3")
 
-    # Mock embedded count query (1 doc has embedding)
     mock_embedded = [{"count": 1}]
 
     with patch.object(handler, "_get_docs_root", return_value=docs_root):
@@ -224,13 +462,11 @@ async def test_documentation_handler_title_extraction(tmp_path):
     """Test DocumentationHandler extracts title from markdown heading."""
     handler = DocumentationHandler()
 
-    # Test with heading
     doc_with_heading = tmp_path / "with_heading.md"
     doc_with_heading.write_text("# My Title\n\nContent here")
     title = handler._extract_doc_title(doc_with_heading)
     assert title == "My Title"
 
-    # Test without heading
     doc_without_heading = tmp_path / "no-heading.md"
     doc_without_heading.write_text("Just content, no heading")
     title = handler._extract_doc_title(doc_without_heading)
@@ -242,7 +478,6 @@ async def test_documentation_handler_markdown_chunking(tmp_path):
     """Test DocumentationHandler chunks markdown by headings."""
     handler = DocumentationHandler()
 
-    # Test document with multiple sections
     doc_with_sections = tmp_path / "sections.md"
     doc_with_sections.write_text(
         "# Document Title\n\n"
@@ -254,7 +489,6 @@ async def test_documentation_handler_markdown_chunking(tmp_path):
     )
     sections = handler._chunk_markdown_by_headings(doc_with_sections)
 
-    # Should have 3 sections: intro (with doc title), section one, section two
     assert len(sections) == 3
     assert sections[0].title == "Document Title"
     assert sections[0].index == 0
@@ -268,7 +502,6 @@ async def test_documentation_handler_markdown_chunking(tmp_path):
     assert sections[2].index == 2
     assert "Content for section two" in sections[2].content
 
-    # Test document without headings
     doc_no_sections = tmp_path / "no-sections.md"
     doc_no_sections.write_text("Just plain content without any headings.")
     sections = handler._chunk_markdown_by_headings(doc_no_sections)
@@ -282,21 +515,39 @@ async def test_documentation_handler_section_content_ids():
     """Test DocumentationHandler creates and parses section content IDs."""
     handler = DocumentationHandler()
 
-    # Test making content ID
     content_id = handler._make_section_content_id("docs/guide.md", 2)
     assert content_id == "docs/guide.md::2"
 
-    # Test parsing content ID
     doc_path, section_index = handler._parse_section_content_id("docs/guide.md::2")
     assert doc_path == "docs/guide.md"
     assert section_index == 2
 
-    # Test parsing legacy format (no section index)
     doc_path, section_index = handler._parse_section_content_id("docs/old-format.md")
     assert doc_path == "docs/old-format.md"
     assert section_index == 0
 
 
+@pytest.mark.asyncio(loop_scope="session")
+async def test_documentation_handler_missing_docs_directory():
+    """Test DocumentationHandler handles missing docs directory gracefully."""
+    handler = DocumentationHandler()
+
+    fake_path = Path("/nonexistent/docs")
+    with patch.object(handler, "_get_docs_root", return_value=fake_path):
+        items = await handler.get_missing_items(batch_size=10)
+        assert items == []
+
+        stats = await handler.get_stats()
+        assert stats["total"] == 0
+        assert stats["with_embeddings"] == 0
+        assert stats["without_embeddings"] == 0
+
+
+# ---------------------------------------------------------------------------
+# Registry
+# ---------------------------------------------------------------------------
+
+
 @pytest.mark.asyncio(loop_scope="session")
 async def test_content_handlers_registry():
     """Test all content types are registered."""
@@ -307,88 +558,3 @@ async def test_content_handlers_registry():
     assert isinstance(CONTENT_HANDLERS[ContentType.STORE_AGENT], StoreAgentHandler)
     assert isinstance(CONTENT_HANDLERS[ContentType.BLOCK], BlockHandler)
     assert isinstance(CONTENT_HANDLERS[ContentType.DOCUMENTATION], DocumentationHandler)
-
-
-@pytest.mark.asyncio(loop_scope="session")
-async def test_block_handler_handles_empty_attributes():
-    """Test BlockHandler handles blocks with empty/falsy attribute values."""
-    handler = BlockHandler()
-
-    # Mock block with empty values (all attributes exist but are falsy)
-    mock_block_class = MagicMock()
-    mock_block_instance = MagicMock()
-    mock_block_instance.name = "Minimal Block"
-    mock_block_instance.disabled = False
-    mock_block_instance.description = ""
-    mock_block_instance.categories = set()
-    mock_block_instance.input_schema.model_fields = {}
-    mock_block_instance.input_schema.get_credentials_fields_info.return_value = {}
-    mock_block_class.return_value = mock_block_instance
-
-    mock_blocks = {"block-minimal": mock_block_class}
-
-    with patch(
-        "backend.blocks.get_blocks",
-        return_value=mock_blocks,
-    ):
-        with patch(
-            "backend.api.features.store.content_handlers.query_raw_with_schema",
-            return_value=[],
-        ):
-            items = await handler.get_missing_items(batch_size=10)
-
-            assert len(items) == 1
-            assert items[0].searchable_text == "Minimal Block"
-
-
-@pytest.mark.asyncio(loop_scope="session")
-async def test_block_handler_skips_failed_blocks():
-    """Test BlockHandler skips blocks that fail to instantiate."""
-    handler = BlockHandler()
-
-    # Mock one good block and one bad block
-    good_block = MagicMock()
-    good_instance = MagicMock()
-    good_instance.name = "Good Block"
-    good_instance.description = "Works fine"
-    good_instance.categories = []
-    good_instance.disabled = False
-    good_instance.input_schema.model_fields = {}
-    good_instance.input_schema.get_credentials_fields_info.return_value = {}
-    good_block.return_value = good_instance
-
-    bad_block = MagicMock()
-    bad_block.side_effect = Exception("Instantiation failed")
-
-    mock_blocks = {"good-block": good_block, "bad-block": bad_block}
-
-    with patch(
-        "backend.blocks.get_blocks",
-        return_value=mock_blocks,
-    ):
-        with patch(
-            "backend.api.features.store.content_handlers.query_raw_with_schema",
-            return_value=[],
-        ):
-            items = await handler.get_missing_items(batch_size=10)
-
-            # Should only get the good block
-            assert len(items) == 1
-            assert items[0].content_id == "good-block"
-
-
-@pytest.mark.asyncio(loop_scope="session")
-async def test_documentation_handler_missing_docs_directory():
-    """Test DocumentationHandler handles missing docs directory gracefully."""
-    handler = DocumentationHandler()
-
-    # Mock _get_docs_root to return non-existent path
-    fake_path = Path("/nonexistent/docs")
-    with patch.object(handler, "_get_docs_root", return_value=fake_path):
-        items = await handler.get_missing_items(batch_size=10)
-        assert items == []
-
-        stats = await handler.get_stats()
-        assert stats["total"] == 0
-        assert stats["with_embeddings"] == 0
-        assert stats["without_embeddings"] == 0

autogpt_platform/backend/backend/api/features/store/embeddings.py

@@ -15,6 +15,7 @@ from prisma.enums import ContentType
 from tiktoken import encoding_for_model
 
 from backend.api.features.store.content_handlers import CONTENT_HANDLERS
+from backend.blocks import get_blocks
 from backend.data.db import execute_raw_with_schema, query_raw_with_schema
 from backend.util.clients import get_openai_client
 from backend.util.json import dumps
@@ -662,8 +663,6 @@ async def cleanup_orphaned_embeddings() -> dict[str, Any]:
                 )
                 current_ids = {row["id"] for row in valid_agents}
             elif content_type == ContentType.BLOCK:
-                from backend.blocks import get_blocks
-
                 current_ids = set(get_blocks().keys())
             elif content_type == ContentType.DOCUMENTATION:
                 # Use DocumentationHandler to get section-based content IDs

autogpt_platform/backend/backend/api/features/store/hybrid_search.py

@@ -31,12 +31,10 @@ logger = logging.getLogger(__name__)
 
 
 def tokenize(text: str) -> list[str]:
-    """Simple tokenizer for BM25 - lowercase and split on non-alphanumeric."""
+    """Tokenize text for BM25."""
     if not text:
         return []
-    # Lowercase and split on non-alphanumeric characters
-    tokens = re.findall(r"\b\w+\b", text.lower())
-    return tokens
+    return re.findall(r"\b\w+\b", text.lower())
 
 
 def bm25_rerank(

autogpt_platform/backend/backend/api/features/store/hybrid_search_test.py

@@ -14,9 +14,27 @@ from backend.api.features.store.hybrid_search import (
     HybridSearchWeights,
     UnifiedSearchWeights,
     hybrid_search,
+    tokenize,
     unified_hybrid_search,
 )
 
+# ---------------------------------------------------------------------------
+# tokenize (BM25)
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.parametrize(
+    "input_text, expected",
+    [
+        ("AITextGeneratorBlock", ["aitextgeneratorblock"]),
+        ("hello world", ["hello", "world"]),
+        ("", []),
+        ("HTTPRequest", ["httprequest"]),
+    ],
+)
+def test_tokenize(input_text: str, expected: list[str]):
+    assert tokenize(input_text) == expected
+
 
 @pytest.mark.asyncio(loop_scope="session")
 @pytest.mark.integration

autogpt_platform/backend/backend/api/features/store/text_utils.py

@@ -0,0 +1,5 @@
+"""Backward-compatibility shim — ``split_camelcase`` now lives in backend.util.text."""
+
+from backend.util.text import split_camelcase  # noqa: F401
+
+__all__ = ["split_camelcase"]

autogpt_platform/backend/backend/api/features/store/text_utils_test.py

@@ -0,0 +1,49 @@
+"""Tests for split_camelcase (now in backend.util.text)."""
+
+import pytest
+
+from backend.util.text import split_camelcase
+
+# ---------------------------------------------------------------------------
+# split_camelcase
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.parametrize(
+    "input_text, expected",
+    [
+        ("AITextGeneratorBlock", "AI Text Generator Block"),
+        ("HTTPRequestBlock", "HTTP Request Block"),
+        ("simpleWord", "simple Word"),
+        ("already spaced", "already spaced"),
+        ("XMLParser", "XML Parser"),
+        ("getHTTPResponse", "get HTTP Response"),
+        ("Block", "Block"),
+        ("", ""),
+        ("OAuth2Block", "OAuth2 Block"),
+        ("IOError", "IO Error"),
+        ("getHTTPSResponse", "get HTTPS Response"),
+        # Known limitation: single-letter uppercase prefixes are NOT split.
+        # "ABlock" stays "ABlock" because the algorithm requires the left
+        # part of an uppercase run to retain at least 2 uppercase chars.
+        ("ABlock", "ABlock"),
+        # Digit-to-uppercase transitions
+        ("Base64Encoder", "Base64 Encoder"),
+        ("UTF8Decoder", "UTF8 Decoder"),
+        # Pure digits — no camelCase boundaries to split
+        ("123", "123"),
+        # Known limitation: single-letter uppercase segments after digits
+        # are not split from the following word.  "3D" is only 1 uppercase
+        # char so the uppercase-run rule cannot fire, producing "3 DRenderer"
+        # rather than the ideal "3D Renderer".
+        ("3DRenderer", "3 DRenderer"),
+        # Exception list — compound terms that should stay together
+        ("YouTubeBlock", "YouTube Block"),
+        ("OpenAIBlock", "OpenAI Block"),
+        ("AutoGPTAgent", "AutoGPT Agent"),
+        ("GitHubIntegration", "GitHub Integration"),
+        ("LinkedInBlock", "LinkedIn Block"),
+    ],
+)
+def test_split_camelcase(input_text: str, expected: str):
+    assert split_camelcase(input_text) == expected

autogpt_platform/backend/backend/copilot/prompting.py

@@ -11,18 +11,34 @@ from backend.copilot.tools import TOOL_REGISTRY
 # Shared technical notes that apply to both SDK and baseline modes
 _SHARED_TOOL_NOTES = """\
 
-### Sharing files
-After `write_workspace_file`, embed the `download_url` in Markdown:
-- File: `[report.csv](workspace://file_id#text/csv)`
-- Image: `![chart](workspace://file_id#image/png)`
-- Video: `![recording](workspace://file_id#video/mp4)`
+### Sharing files with the user
+After saving a file to the persistent workspace with `write_workspace_file`,
+share it with the user by embedding the `download_url` from the response in
+your message as a Markdown link or image:
 
-### File references — @@agptfile:
-Pass large file content to tools by reference: `@@agptfile:<uri>[<start>-<end>]`
-- `workspace://<file_id>` or `workspace:///<path>` — workspace files
-- `/absolute/path` — local/sandbox files
-- `[start-end]` — optional 1-indexed line range
-- Multiple refs per argument supported. Only `workspace://` and absolute paths are expanded.
+- **Any file** — shows as a clickable download link:
+  `[report.csv](workspace://file_id#text/csv)`
+- **Image** — renders inline in chat:
+  `![chart](workspace://file_id#image/png)`
+- **Video** — renders inline in chat with player controls:
+  `![recording](workspace://file_id#video/mp4)`
+
+The `download_url` field in the `write_workspace_file` response is already
+in the correct format — paste it directly after the `(` in the Markdown.
+
+### Passing file content to tools — @@agptfile: references
+Instead of copying large file contents into a tool argument, pass a file
+reference and the platform will load the content for you.
+
+Syntax: `@@agptfile:<uri>[<start>-<end>]`
+
+- `<uri>` **must** start with `workspace://` or `/` (absolute path):
+  - `workspace://<file_id>` — workspace file by ID
+  - `workspace:///<path>` — workspace file by virtual path
+  - `/absolute/local/path` — ephemeral or sdk_cwd file
+  - E2B sandbox absolute path (e.g. `/home/user/script.py`)
+- `[<start>-<end>]` is an optional 1-indexed inclusive line range.
+- URIs that do not start with `workspace://` or `/` are **not** expanded.
 
 Examples:
 ```
@@ -33,16 +49,50 @@ Examples:
 @@agptfile:/home/user/script.py
 ```
 
-**Structured data**: When the entire argument is a single file reference, the platform auto-parses by extension/MIME. Supported: JSON, JSONL, CSV, TSV, YAML, TOML, Parquet, Excel (.xlsx only). Unrecognised formats return plain string.
+You can embed a reference inside any string argument, or use it as the entire
+value.  Multiple references in one argument are all expanded.
 
-**Type coercion**: The platform auto-coerces expanded string values to match block input types (e.g. JSON string → `list[list[str]]`).
+**Structured data**: When the **entire** argument value is a single file
+reference (no surrounding text), the platform automatically parses the file
+content based on its extension or MIME type.  Supported formats: JSON, JSONL,
+CSV, TSV, YAML, TOML, Parquet, and Excel (.xlsx — first sheet only).
+For example, pass `@@agptfile:workspace://<id>` where the file is a `.csv` and
+the rows will be parsed into `list[list[str]]` automatically.  If the format is
+unrecognised or parsing fails, the content is returned as a plain string.
+Legacy `.xls` files are **not** supported — only the modern `.xlsx` format.
+
+**Type coercion**: The platform also coerces expanded values to match the
+block's expected input types.  For example, if a block expects `list[list[str]]`
+and the expanded value is a JSON string, it will be parsed into the correct type.
 
 ### Media file inputs (format: "file")
-Inputs with `"format": "file"` accept `workspace://<file_id>` or `data:<mime>;base64,<payload>`.
-Pass the `workspace://` URI directly (do NOT wrap in `@@agptfile:`). This avoids large payloads and preserves binary content.
+Some block inputs accept media files — their schema shows `"format": "file"`.
+These fields accept:
+- **`workspace://<file_id>`** or **`workspace://<file_id>#<mime>`** — preferred
+  for large files (images, videos, PDFs). The platform passes the reference
+  directly to the block without reading the content into memory.
+- **`data:<mime>;base64,<payload>`** — inline base64 data URI, suitable for
+  small files only.
+
+When a block input has `format: "file"`, **pass the `workspace://` URI
+directly as the value** (do NOT wrap it in `@@agptfile:`). This avoids large
+payloads in tool arguments and preserves binary content (images, videos)
+that would be corrupted by text encoding.
+
+Example — committing an image file to GitHub:
+```json
+{
+  "files": [{
+    "path": "docs/hero.png",
+    "content": "workspace://abc123#image/png",
+    "operation": "upsert"
+  }]
+}
+```
 
 ### Sub-agent tasks
-- Task tool: NEVER set `run_in_background` to true.
+- When using the Task tool, NEVER set `run_in_background` to true.
+  All tasks must run in the foreground.
 """
 
 
@@ -78,18 +128,30 @@ def _build_storage_supplement(
 
 ## Tool notes
 
-### Shell & filesystem
-- Use `bash_exec` for shell commands ({sandbox_type}). Working dir: `{working_dir}`
-- All file tools share the same filesystem. Use relative or absolute paths under this dir.
+### Shell commands
+- The SDK built-in Bash tool is NOT available.  Use the `bash_exec` MCP tool
+  for shell commands — it runs {sandbox_type}.
+
+### Working directory
+- Your working directory is: `{working_dir}`
+- All SDK file tools AND `bash_exec` operate on the same filesystem
+- Use relative paths or absolute paths under `{working_dir}` for all file operations
+
+### Two storage systems — CRITICAL to understand
 
-### Storage — important
 1. **{storage_system_1_name}** (`{working_dir}`):
 {characteristics}
 {persistence}
-2. **Persistent workspace** (cloud) — survives across sessions.
-   - {file_move_name_1_to_2}: use `write_workspace_file`
-   - {file_move_name_2_to_1}: use `read_workspace_file` with save_to_path
-   - Save important files to workspace for persistence.
+
+2. **Persistent workspace** (cloud storage):
+   - Files here **survive across sessions indefinitely**
+
+### Moving files between storages
+- **{file_move_name_1_to_2}**: Copy to persistent workspace
+- **{file_move_name_2_to_1}**: Download for processing
+
+### File persistence
+Important files (code, configs, outputs) should be saved to workspace to ensure they persist.
 {_SHARED_TOOL_NOTES}"""
 
 

autogpt_platform/backend/backend/copilot/tools/add_understanding.py

@@ -22,11 +22,13 @@ class AddUnderstandingTool(BaseTool):
 
     @property
     def description(self) -> str:
-        return (
-            "Store user's business context, workflows, pain points, and automation goals. "
-            "Call whenever the user shares business info. Each call incrementally merges "
-            "with existing data — provide only the fields you have."
-        )
+        return """Capture and store information about the user's business context,
+workflows, pain points, and automation goals. Call this tool whenever the user
+shares information about their business. Each call incrementally adds to the
+existing understanding - you don't need to provide all fields at once.
+
+Use this to build a comprehensive profile that helps recommend better agents
+and automations for the user's specific needs."""
 
     @property
     def parameters(self) -> dict[str, Any]:

autogpt_platform/backend/backend/copilot/tools/agent_browser.py

@@ -408,11 +408,18 @@ class BrowserNavigateTool(BaseTool):
     @property
     def description(self) -> str:
         return (
-            "Navigate to a URL in a real browser. Returns accessibility tree with @ref IDs "
-            "for browser_act. Session persists (cookies/auth carry over). "
-            "For static pages, prefer web_fetch. "
-            "For SPAs, elements may load late — use browser_act with wait + browser_screenshot to verify. "
-            "For auth: navigate to login, fill creds with browser_act, then navigate to target."
+            "Navigate to a URL using a real browser. Returns an accessibility "
+            "tree snapshot listing the page's interactive elements with @ref IDs "
+            "(e.g. @e3) that can be used with browser_act. "
+            "Session persists — cookies and login state carry over between calls. "
+            "Use this (with browser_act) for multi-step interaction: login flows, "
+            "form filling, button clicks, or anything requiring page interaction. "
+            "For plain static pages, prefer web_fetch — no browser overhead. "
+            "For authenticated pages: navigate to the login page first, use browser_act "
+            "to fill credentials and submit, then navigate to the target page. "
+            "Note: for slow SPAs, the returned snapshot may reflect a partially-loaded "
+            "state. If elements seem missing, use browser_act with action='wait' and a "
+            "CSS selector or millisecond delay, then take a browser_screenshot to verify."
         )
 
     @property
@@ -422,13 +429,13 @@ class BrowserNavigateTool(BaseTool):
             "properties": {
                 "url": {
                     "type": "string",
-                    "description": "HTTP/HTTPS URL to navigate to.",
+                    "description": "The HTTP/HTTPS URL to navigate to.",
                 },
                 "wait_for": {
                     "type": "string",
                     "enum": ["networkidle", "load", "domcontentloaded"],
                     "default": "networkidle",
-                    "description": "Navigation completion strategy (default: networkidle).",
+                    "description": "When to consider navigation complete. Use 'networkidle' for SPAs (default).",
                 },
             },
             "required": ["url"],
@@ -547,12 +554,14 @@ class BrowserActTool(BaseTool):
     @property
     def description(self) -> str:
         return (
-            "Interact with the current browser page using @ref IDs from the snapshot. "
-            "Actions: click, dblclick, fill, type, scroll, hover, press, "
+            "Interact with the current browser page. Use @ref IDs from the "
+            "snapshot (e.g. '@e3') to target elements. Returns an updated snapshot. "
+            "Supported actions: click, dblclick, fill, type, scroll, hover, press, "
             "check, uncheck, select, wait, back, forward, reload. "
-            "fill clears field first; type appends. "
-            "wait accepts CSS selector or milliseconds (e.g. '1000'). "
-            "Returns updated snapshot."
+            "fill clears the field before typing; type appends without clearing. "
+            "wait accepts a CSS selector (waits for element) or milliseconds string (e.g. '1000'). "
+            "Example login flow: fill @e1 with email → fill @e2 with password → "
+            "click @e3 (submit) → browser_navigate to the target page."
         )
 
     @property
@@ -578,21 +587,30 @@ class BrowserActTool(BaseTool):
                         "forward",
                         "reload",
                     ],
-                    "description": "Action to perform.",
+                    "description": "The action to perform.",
                 },
                 "target": {
                     "type": "string",
-                    "description": "@ref ID (e.g. '@e3'), CSS selector, or text description.",
+                    "description": (
+                        "Element to target. Use @ref from snapshot (e.g. '@e3'), "
+                        "a CSS selector, or a text description. "
+                        "Required for: click, dblclick, fill, type, hover, check, uncheck, select. "
+                        "For wait: a CSS selector to wait for, or milliseconds as a string (e.g. '1000')."
+                    ),
                 },
                 "value": {
                     "type": "string",
-                    "description": "Text for fill/type, key for press (e.g. 'Enter'), option for select.",
+                    "description": (
+                        "For fill/type: the text to enter. "
+                        "For press: key name (e.g. 'Enter', 'Tab', 'Control+a'). "
+                        "For select: the option value to select."
+                    ),
                 },
                 "direction": {
                     "type": "string",
                     "enum": ["up", "down", "left", "right"],
                     "default": "down",
-                    "description": "Scroll direction (default: down).",
+                    "description": "For scroll: direction to scroll.",
                 },
             },
             "required": ["action"],
@@ -739,10 +757,12 @@ class BrowserScreenshotTool(BaseTool):
     @property
     def description(self) -> str:
         return (
-            "Screenshot the current browser page and save to workspace. "
-            "annotate=true overlays @ref labels on elements. "
-            "IMPORTANT: After calling, you MUST immediately call read_workspace_file with the "
-            "returned file_id to display the image inline."
+            "Take a screenshot of the current browser page and save it to the workspace. "
+            "IMPORTANT: After calling this tool, immediately call read_workspace_file "
+            "with the returned file_id to display the image inline to the user — "
+            "the screenshot is not visible until you do this. "
+            "With annotate=true (default), @ref labels are overlaid on interactive "
+            "elements, making it easy to see which @ref ID maps to which element on screen."
         )
 
     @property
@@ -753,12 +773,12 @@ class BrowserScreenshotTool(BaseTool):
                 "annotate": {
                     "type": "boolean",
                     "default": True,
-                    "description": "Overlay @ref labels (default: true).",
+                    "description": "Overlay @ref labels on interactive elements (default: true).",
                 },
                 "filename": {
                     "type": "string",
                     "default": "screenshot.png",
-                    "description": "Workspace filename (default: screenshot.png).",
+                    "description": "Filename to save in the workspace.",
                 },
             },
         }

autogpt_platform/backend/backend/copilot/tools/agent_output.py

@@ -108,12 +108,22 @@ class AgentOutputTool(BaseTool):
 
     @property
     def description(self) -> str:
-        return (
-            "Retrieve execution outputs from a library agent. "
-            "Identify by agent_name, library_agent_id, or store_slug. "
-            "Filter by execution_id or run_time. "
-            "Optionally wait for running executions."
-        )
+        return """Retrieve execution outputs from agents in the user's library.
+
+        Identify the agent using one of:
+        - agent_name: Fuzzy search in user's library
+        - library_agent_id: Exact library agent ID
+        - store_slug: Marketplace format 'username/agent-name'
+
+        Select which run to retrieve using:
+        - execution_id: Specific execution ID
+        - run_time: 'latest' (default), 'yesterday', 'last week', or ISO date 'YYYY-MM-DD'
+
+        Wait for completion (optional):
+        - wait_if_running: Max seconds to wait if execution is still running (0-300).
+          If the execution is running/queued, waits up to this many seconds for completion.
+          Returns current status on timeout. If already finished, returns immediately.
+        """
 
     @property
     def parameters(self) -> dict[str, Any]:
@@ -122,27 +132,32 @@ class AgentOutputTool(BaseTool):
             "properties": {
                 "agent_name": {
                     "type": "string",
-                    "description": "Agent name (fuzzy match).",
+                    "description": "Agent name to search for in user's library (fuzzy match)",
                 },
                 "library_agent_id": {
                     "type": "string",
-                    "description": "Library agent ID.",
+                    "description": "Exact library agent ID",
                 },
                 "store_slug": {
                     "type": "string",
-                    "description": "Marketplace 'username/agent-slug'.",
+                    "description": "Marketplace identifier: 'username/agent-slug'",
                 },
                 "execution_id": {
                     "type": "string",
-                    "description": "Specific execution ID.",
+                    "description": "Specific execution ID to retrieve",
                 },
                 "run_time": {
                     "type": "string",
-                    "description": "Time filter: 'latest', today/yesterday/last week/last 7 days/last month/last 30 days, 'YYYY-MM-DD', or ISO datetime.",
+                    "description": (
+                        "Time filter: 'latest', 'yesterday', 'last week', or 'YYYY-MM-DD'"
+                    ),
                 },
                 "wait_if_running": {
                     "type": "integer",
-                    "description": "Max seconds to wait if still running (0-300). Returns current state on timeout.",
+                    "description": (
+                        "Max seconds to wait if execution is still running (0-300). "
+                        "If running, waits for completion. Returns current state on timeout."
+                    ),
                 },
             },
             "required": [],

autogpt_platform/backend/backend/copilot/tools/bash_exec.py

@@ -41,9 +41,15 @@ class BashExecTool(BaseTool):
     @property
     def description(self) -> str:
         return (
-            "Execute a Bash command or script. Shares filesystem with SDK file tools. "
-            "Useful for scripts, data processing, and package installation. "
-            "Killed after timeout (default 30s, max 120s)."
+            "Execute a Bash command or script. "
+            "Full Bash scripting is supported (loops, conditionals, pipes, "
+            "functions, etc.). "
+            "The working directory is shared with the SDK Read/Write/Edit/Glob/Grep "
+            "tools — files created by either are immediately visible to both. "
+            "Execution is killed after the timeout (default 30s, max 120s). "
+            "Returns stdout and stderr. "
+            "Useful for file manipulation, data processing, running scripts, "
+            "and installing packages."
         )
 
     @property
@@ -53,11 +59,13 @@ class BashExecTool(BaseTool):
             "properties": {
                 "command": {
                     "type": "string",
-                    "description": "Bash command or script.",
+                    "description": "Bash command or script to execute.",
                 },
                 "timeout": {
                     "type": "integer",
-                    "description": "Max seconds (default 30, max 120).",
+                    "description": (
+                        "Max execution time in seconds (default 30, max 120)."
+                    ),
                     "default": 30,
                 },
             },

autogpt_platform/backend/backend/copilot/tools/continue_run_block.py

@@ -30,7 +30,12 @@ class ContinueRunBlockTool(BaseTool):
 
     @property
     def description(self) -> str:
-        return "Resume block execution after human review approval. Pass the review_id."
+        return (
+            "Continue executing a block after human review approval. "
+            "Use this after a run_block call returned review_required. "
+            "Pass the review_id from the review_required response. "
+            "The block will execute with the original pre-approved input data."
+        )
 
     @property
     def parameters(self) -> dict[str, Any]:
@@ -39,7 +44,10 @@ class ContinueRunBlockTool(BaseTool):
             "properties": {
                 "review_id": {
                     "type": "string",
-                    "description": "review_id from the review_required response.",
+                    "description": (
+                        "The review_id from a previous review_required response. "
+                        "This resumes execution with the pre-approved input data."
+                    ),
                 },
             },
             "required": ["review_id"],

autogpt_platform/backend/backend/copilot/tools/create_agent.py

@@ -23,8 +23,12 @@ class CreateAgentTool(BaseTool):
     @property
     def description(self) -> str:
         return (
-            "Create a new agent from JSON (nodes + links). Validates, auto-fixes, and saves. "
-            "Before calling, search for existing agents with find_library_agent."
+            "Create a new agent workflow. Pass `agent_json` with the complete "
+            "agent graph JSON you generated using block schemas from find_block. "
+            "The tool validates, auto-fixes, and saves.\n\n"
+            "IMPORTANT: Before calling this tool, search for relevant existing agents "
+            "using find_library_agent that could be used as building blocks. "
+            "Pass their IDs in the library_agent_ids parameter."
         )
 
     @property
@@ -38,21 +42,34 @@ class CreateAgentTool(BaseTool):
             "properties": {
                 "agent_json": {
                     "type": "object",
-                    "description": "Agent graph with 'nodes' and 'links' arrays.",
+                    "description": (
+                        "The agent JSON to validate and save. "
+                        "Must contain 'nodes' and 'links' arrays, and optionally "
+                        "'name' and 'description'."
+                    ),
                 },
                 "library_agent_ids": {
                     "type": "array",
                     "items": {"type": "string"},
-                    "description": "Library agent IDs as building blocks.",
+                    "description": (
+                        "List of library agent IDs to use as building blocks."
+                    ),
                 },
                 "save": {
                     "type": "boolean",
-                    "description": "Save the agent (default: true). False for preview.",
+                    "description": (
+                        "Whether to save the agent. Default is true. "
+                        "Set to false for preview only."
+                    ),
                     "default": True,
                 },
                 "folder_id": {
                     "type": "string",
-                    "description": "Folder ID to save into (default: root).",
+                    "description": (
+                        "Optional folder ID to save the agent into. "
+                        "If not provided, the agent is saved at root level. "
+                        "Use list_folders to find available folders."
+                    ),
                 },
             },
             "required": ["agent_json"],

autogpt_platform/backend/backend/copilot/tools/customize_agent.py

@@ -23,7 +23,9 @@ class CustomizeAgentTool(BaseTool):
     @property
     def description(self) -> str:
         return (
-            "Customize a marketplace/template agent. Validates, auto-fixes, and saves."
+            "Customize a marketplace or template agent. Pass `agent_json` "
+            "with the complete customized agent JSON. The tool validates, "
+            "auto-fixes, and saves."
         )
 
     @property
@@ -37,21 +39,32 @@ class CustomizeAgentTool(BaseTool):
             "properties": {
                 "agent_json": {
                     "type": "object",
-                    "description": "Customized agent JSON with nodes and links.",
+                    "description": (
+                        "Complete customized agent JSON to validate and save. "
+                        "Optionally include 'name' and 'description'."
+                    ),
                 },
                 "library_agent_ids": {
                     "type": "array",
                     "items": {"type": "string"},
-                    "description": "Library agent IDs as building blocks.",
+                    "description": (
+                        "List of library agent IDs to use as building blocks."
+                    ),
                 },
                 "save": {
                     "type": "boolean",
-                    "description": "Save the agent (default: true). False for preview.",
+                    "description": (
+                        "Whether to save the customized agent. Default is true."
+                    ),
                     "default": True,
                 },
                 "folder_id": {
                     "type": "string",
-                    "description": "Folder ID to save into (default: root).",
+                    "description": (
+                        "Optional folder ID to save the agent into. "
+                        "If not provided, the agent is saved at root level. "
+                        "Use list_folders to find available folders."
+                    ),
                 },
             },
             "required": ["agent_json"],

autogpt_platform/backend/backend/copilot/tools/edit_agent.py

@@ -23,8 +23,12 @@ class EditAgentTool(BaseTool):
     @property
     def description(self) -> str:
         return (
-            "Edit an existing agent. Validates, auto-fixes, and saves. "
-            "Before calling, search for existing agents with find_library_agent."
+            "Edit an existing agent. Pass `agent_json` with the complete "
+            "updated agent JSON you generated. The tool validates, auto-fixes, "
+            "and saves.\n\n"
+            "IMPORTANT: Before calling this tool, if the changes involve adding new "
+            "functionality, search for relevant existing agents using find_library_agent "
+            "that could be used as building blocks."
         )
 
     @property
@@ -38,20 +42,33 @@ class EditAgentTool(BaseTool):
             "properties": {
                 "agent_id": {
                     "type": "string",
-                    "description": "Graph ID or library agent ID to edit.",
+                    "description": (
+                        "The ID of the agent to edit. "
+                        "Can be a graph ID or library agent ID."
+                    ),
                 },
                 "agent_json": {
                     "type": "object",
-                    "description": "Updated agent JSON with nodes and links.",
+                    "description": (
+                        "Complete updated agent JSON to validate and save. "
+                        "Must contain 'nodes' and 'links'. "
+                        "Include 'name' and/or 'description' if they need "
+                        "to be updated."
+                    ),
                 },
                 "library_agent_ids": {
                     "type": "array",
                     "items": {"type": "string"},
-                    "description": "Library agent IDs as building blocks.",
+                    "description": (
+                        "List of library agent IDs to use as building blocks for the changes."
+                    ),
                 },
                 "save": {
                     "type": "boolean",
-                    "description": "Save changes (default: true). False for preview.",
+                    "description": (
+                        "Whether to save the changes. "
+                        "Default is true. Set to false for preview only."
+                    ),
                     "default": True,
                 },
             },

autogpt_platform/backend/backend/copilot/tools/feature_requests.py

@@ -134,7 +134,11 @@ class SearchFeatureRequestsTool(BaseTool):
 
     @property
     def description(self) -> str:
-        return "Search existing feature requests. Check before creating a new one."
+        return (
+            "Search existing feature requests to check if a similar request "
+            "already exists before creating a new one. Returns matching feature "
+            "requests with their ID, title, and description."
+        )
 
     @property
     def parameters(self) -> dict[str, Any]:
@@ -230,9 +234,14 @@ class CreateFeatureRequestTool(BaseTool):
     @property
     def description(self) -> str:
         return (
-            "Create a feature request or add need to existing one. "
-            "Search first to avoid duplicates. Pass existing_issue_id to add to existing. "
-            "Never include PII (names, emails, phone numbers, company names) in title/description."
+            "Create a new feature request or add a customer need to an existing one. "
+            "Always search first with search_feature_requests to avoid duplicates. "
+            "If a matching request exists, pass its ID as existing_issue_id to add "
+            "the user's need to it instead of creating a duplicate. "
+            "IMPORTANT: Never include personally identifiable information (PII) in "
+            "the title or description — no names, emails, phone numbers, company "
+            "names, or other identifying details. Write titles and descriptions in "
+            "generic, feature-focused language."
         )
 
     @property
@@ -242,15 +251,28 @@ class CreateFeatureRequestTool(BaseTool):
             "properties": {
                 "title": {
                     "type": "string",
-                    "description": "Feature request title. No PII.",
+                    "description": (
+                        "Title for the feature request. Must be generic and "
+                        "feature-focused — do not include any user names, emails, "
+                        "company names, or other PII."
+                    ),
                 },
                 "description": {
                     "type": "string",
-                    "description": "What the user wants and why. No PII.",
+                    "description": (
+                        "Detailed description of what the user wants and why. "
+                        "Must not contain any personally identifiable information "
+                        "(PII) — describe the feature need generically without "
+                        "referencing specific users, companies, or contact details."
+                    ),
                 },
                 "existing_issue_id": {
                     "type": "string",
-                    "description": "Linear issue ID to add need to (from search results).",
+                    "description": (
+                        "If adding a need to an existing feature request, "
+                        "provide its Linear issue ID (from search results). "
+                        "Omit to create a new feature request."
+                    ),
                 },
             },
             "required": ["title", "description"],

autogpt_platform/backend/backend/copilot/tools/find_agent.py

@@ -18,7 +18,9 @@ class FindAgentTool(BaseTool):
 
     @property
     def description(self) -> str:
-        return "Search marketplace agents by capability."
+        return (
+            "Discover agents from the marketplace based on capabilities and user needs."
+        )
 
     @property
     def parameters(self) -> dict[str, Any]:
@@ -27,7 +29,7 @@ class FindAgentTool(BaseTool):
             "properties": {
                 "query": {
                     "type": "string",
-                    "description": "Search keywords (single keywords work best).",
+                    "description": "Search query describing what the user wants to accomplish. Use single keywords for best results.",
                 },
             },
             "required": ["query"],

autogpt_platform/backend/backend/copilot/tools/find_block.py

@@ -51,7 +51,14 @@ class FindBlockTool(BaseTool):
 
     @property
     def description(self) -> str:
-        return "Search blocks by name or description. Returns block IDs for run_block. Always call this FIRST to get block IDs before using run_block."
+        return (
+            "Search for available blocks by name or description. "
+            "Blocks are reusable components that perform specific tasks like "
+            "sending emails, making API calls, processing text, etc. "
+            "IMPORTANT: Use this tool FIRST to get the block's 'id' before calling run_block. "
+            "The response includes each block's id, name, and description. "
+            "Call run_block with the block's id **with no inputs** to see detailed inputs/outputs and execute it."
+        )
 
     @property
     def parameters(self) -> dict[str, Any]:
@@ -60,11 +67,18 @@ class FindBlockTool(BaseTool):
             "properties": {
                 "query": {
                     "type": "string",
-                    "description": "Search keywords (e.g. 'email', 'http', 'ai').",
+                    "description": (
+                        "Search query to find blocks by name or description. "
+                        "Use keywords like 'email', 'http', 'text', 'ai', etc."
+                    ),
                 },
                 "include_schemas": {
                     "type": "boolean",
-                    "description": "Include full input/output schemas (for agent JSON generation).",
+                    "description": (
+                        "If true, include full input_schema and output_schema "
+                        "for each block. Use when generating agent JSON that "
+                        "needs block schemas. Default is false."
+                    ),
                     "default": False,
                 },
             },

autogpt_platform/backend/backend/copilot/tools/find_library_agent.py

@@ -19,8 +19,13 @@ class FindLibraryAgentTool(BaseTool):
     @property
     def description(self) -> str:
         return (
-            "Search user's library agents. Returns graph_id, schemas for sub-agent composition. "
-            "Omit query to list all."
+            "Search for or list agents in the user's library. Use this to find "
+            "agents the user has already added to their library, including agents "
+            "they created or added from the marketplace. "
+            "When creating agents with sub-agent composition, use this to get "
+            "the agent's graph_id, graph_version, input_schema, and output_schema "
+            "needed for AgentExecutorBlock nodes. "
+            "Omit the query to list all agents."
         )
 
     @property
@@ -30,7 +35,10 @@ class FindLibraryAgentTool(BaseTool):
             "properties": {
                 "query": {
                     "type": "string",
-                    "description": "Search by name/description. Omit to list all.",
+                    "description": (
+                        "Search query to find agents by name or description. "
+                        "Omit to list all agents in the library."
+                    ),
                 },
             },
             "required": [],

autogpt_platform/backend/backend/copilot/tools/fix_agent.py

@@ -22,8 +22,20 @@ class FixAgentGraphTool(BaseTool):
     @property
     def description(self) -> str:
         return (
-            "Auto-fix common agent JSON issues (UUIDs, types, credentials, spacing, etc.). "
-            "Returns fixed JSON and list of fixes applied."
+            "Auto-fix common issues in an agent JSON graph. Applies fixes for:\n"
+            "- Missing or invalid UUIDs on nodes and links\n"
+            "- StoreValueBlock prerequisites for ConditionBlock\n"
+            "- Double curly brace escaping in prompt templates\n"
+            "- AddToList/AddToDictionary prerequisite blocks\n"
+            "- CodeExecutionBlock output field naming\n"
+            "- Missing credentials configuration\n"
+            "- Node X coordinate spacing (800+ units apart)\n"
+            "- AI model default parameters\n"
+            "- Link static properties based on input schema\n"
+            "- Type mismatches (inserts conversion blocks)\n\n"
+            "Returns the fixed agent JSON plus a list of fixes applied. "
+            "After fixing, the agent is re-validated. If still invalid, "
+            "the remaining errors are included in the response."
         )
 
     @property

autogpt_platform/backend/backend/copilot/tools/get_agent_building_guide.py

@@ -42,7 +42,12 @@ class GetAgentBuildingGuideTool(BaseTool):
 
     @property
     def description(self) -> str:
-        return "Get the agent JSON building guide (nodes, links, AgentExecutorBlock, MCPToolBlock usage). Call before generating agent JSON."
+        return (
+            "Returns the complete guide for building agent JSON graphs, including "
+            "block IDs, link structure, AgentInputBlock, AgentOutputBlock, "
+            "AgentExecutorBlock (for sub-agent composition), and MCPToolBlock usage. "
+            "Call this before generating agent JSON to ensure correct structure."
+        )
 
     @property
     def parameters(self) -> dict[str, Any]:

autogpt_platform/backend/backend/copilot/tools/get_doc_page.py

@@ -25,7 +25,8 @@ class GetDocPageTool(BaseTool):
     @property
     def description(self) -> str:
         return (
-            "Read full documentation page content by path (from search_docs results)."
+            "Get the full content of a documentation page by its path. "
+            "Use this after search_docs to read the complete content of a relevant page."
         )
 
     @property
@@ -35,7 +36,10 @@ class GetDocPageTool(BaseTool):
             "properties": {
                 "path": {
                     "type": "string",
-                    "description": "Doc file path (e.g. 'platform/block-sdk-guide.md').",
+                    "description": (
+                        "The path to the documentation file, as returned by search_docs. "
+                        "Example: 'platform/block-sdk-guide.md'"
+                    ),
                 },
             },
             "required": ["path"],

autogpt_platform/backend/backend/copilot/tools/get_mcp_guide.py

@@ -38,7 +38,11 @@ class GetMCPGuideTool(BaseTool):
 
     @property
     def description(self) -> str:
-        return "Get MCP server URLs and auth guide."
+        return (
+            "Returns the MCP tool guide: known hosted server URLs (Notion, Linear, "
+            "Stripe, Intercom, Cloudflare, Atlassian) and authentication workflow. "
+            "Call before using run_mcp_tool if you need a server URL or auth info."
+        )
 
     @property
     def parameters(self) -> dict[str, Any]:

autogpt_platform/backend/backend/copilot/tools/manage_folders.py

@@ -88,7 +88,10 @@ class CreateFolderTool(BaseTool):
 
     @property
     def description(self) -> str:
-        return "Create a library folder. Use parent_id to nest inside another folder."
+        return (
+            "Create a new folder in the user's library to organize agents. "
+            "Optionally nest it inside an existing folder using parent_id."
+        )
 
     @property
     def requires_auth(self) -> bool:
@@ -101,19 +104,22 @@ class CreateFolderTool(BaseTool):
             "properties": {
                 "name": {
                     "type": "string",
-                    "description": "Folder name (max 100 chars).",
+                    "description": "Name for the new folder (max 100 chars).",
                 },
                 "parent_id": {
                     "type": "string",
-                    "description": "Parent folder ID (omit for root).",
+                    "description": (
+                        "ID of the parent folder to nest inside. "
+                        "Omit to create at root level."
+                    ),
                 },
                 "icon": {
                     "type": "string",
-                    "description": "Icon identifier.",
+                    "description": "Optional icon identifier for the folder.",
                 },
                 "color": {
                     "type": "string",
-                    "description": "Hex color (#RRGGBB).",
+                    "description": "Optional hex color code (#RRGGBB).",
                 },
             },
             "required": ["name"],
@@ -169,8 +175,13 @@ class ListFoldersTool(BaseTool):
     @property
     def description(self) -> str:
         return (
-            "List library folders. Omit parent_id for full tree. "
-            "Set include_agents=true when user asks about agents in folders."
+            "List the user's library folders. "
+            "Omit parent_id to get the full folder tree. "
+            "Provide parent_id to list only direct children of that folder. "
+            "Set include_agents=true to also return the agents inside each folder "
+            "and root-level agents not in any folder. Always set include_agents=true "
+            "when the user asks about agents, wants to see what's in their folders, "
+            "or mentions agents alongside folders."
         )
 
     @property
@@ -184,11 +195,17 @@ class ListFoldersTool(BaseTool):
             "properties": {
                 "parent_id": {
                     "type": "string",
-                    "description": "List children of this folder (omit for full tree).",
+                    "description": (
+                        "List children of this folder. "
+                        "Omit to get the full folder tree."
+                    ),
                 },
                 "include_agents": {
                     "type": "boolean",
-                    "description": "Include agents in each folder (default: false).",
+                    "description": (
+                        "Whether to include the list of agents inside each folder. "
+                        "Defaults to false."
+                    ),
                 },
             },
             "required": [],
@@ -340,7 +357,10 @@ class MoveFolderTool(BaseTool):
 
     @property
     def description(self) -> str:
-        return "Move a folder. Set target_parent_id to null for root."
+        return (
+            "Move a folder to a different parent folder. "
+            "Set target_parent_id to null to move to root level."
+        )
 
     @property
     def requires_auth(self) -> bool:
@@ -353,11 +373,14 @@ class MoveFolderTool(BaseTool):
             "properties": {
                 "folder_id": {
                     "type": "string",
-                    "description": "Folder ID.",
+                    "description": "ID of the folder to move.",
                 },
                 "target_parent_id": {
                     "type": ["string", "null"],
-                    "description": "New parent folder ID (null for root).",
+                    "description": (
+                        "ID of the new parent folder. "
+                        "Use null to move to root level."
+                    ),
                 },
             },
             "required": ["folder_id"],
@@ -410,7 +433,10 @@ class DeleteFolderTool(BaseTool):
 
     @property
     def description(self) -> str:
-        return "Delete a folder. Agents inside move to root (not deleted)."
+        return (
+            "Delete a folder from the user's library. "
+            "Agents inside the folder are moved to root level (not deleted)."
+        )
 
     @property
     def requires_auth(self) -> bool:
@@ -473,7 +499,10 @@ class MoveAgentsToFolderTool(BaseTool):
 
     @property
     def description(self) -> str:
-        return "Move agents to a folder. Set folder_id to null for root."
+        return (
+            "Move one or more agents to a folder. "
+            "Set folder_id to null to move agents to root level."
+        )
 
     @property
     def requires_auth(self) -> bool:
@@ -487,11 +516,13 @@ class MoveAgentsToFolderTool(BaseTool):
                 "agent_ids": {
                     "type": "array",
                     "items": {"type": "string"},
-                    "description": "Library agent IDs to move.",
+                    "description": "List of library agent IDs to move.",
                 },
                 "folder_id": {
                     "type": ["string", "null"],
-                    "description": "Target folder ID (null for root).",
+                    "description": (
+                        "Target folder ID. Use null to move to root level."
+                    ),
                 },
             },
             "required": ["agent_ids"],

autogpt_platform/backend/backend/copilot/tools/run_agent.py

@@ -104,11 +104,19 @@ class RunAgentTool(BaseTool):
 
     @property
     def description(self) -> str:
-        return (
-            "Run or schedule an agent. Automatically checks inputs and credentials. "
-            "Identify by username_agent_slug ('user/agent') or library_agent_id. "
-            "For scheduling, provide schedule_name + cron."
-        )
+        return """Run or schedule an agent from the marketplace or user's library.
+
+        The tool automatically handles the setup flow:
+        - Returns missing inputs if required fields are not provided
+        - Returns missing credentials if user needs to configure them
+        - Executes immediately if all requirements are met
+        - Schedules execution if cron expression is provided
+
+        Identify the agent using either:
+        - username_agent_slug: Marketplace format 'username/agent-name'
+        - library_agent_id: ID of an agent in the user's library
+
+        For scheduled execution, provide: schedule_name, cron, and optionally timezone."""
 
     @property
     def parameters(self) -> dict[str, Any]:
@@ -117,36 +125,40 @@ class RunAgentTool(BaseTool):
             "properties": {
                 "username_agent_slug": {
                     "type": "string",
-                    "description": "Marketplace format 'username/agent-name'.",
+                    "description": "Agent identifier in format 'username/agent-name'",
                 },
                 "library_agent_id": {
                     "type": "string",
-                    "description": "Library agent ID.",
+                    "description": "Library agent ID from user's library",
                 },
                 "inputs": {
                     "type": "object",
-                    "description": "Input values for the agent.",
+                    "description": "Input values for the agent",
                     "additionalProperties": True,
                 },
                 "use_defaults": {
                     "type": "boolean",
-                    "description": "Run with default values (confirm with user first).",
+                    "description": "Set to true to run with default values (user must confirm)",
                 },
                 "schedule_name": {
                     "type": "string",
-                    "description": "Name for scheduled execution.",
+                    "description": "Name for scheduled execution (triggers scheduling mode)",
                 },
                 "cron": {
                     "type": "string",
-                    "description": "Cron expression (min hour day month weekday).",
+                    "description": "Cron expression (5 fields: min hour day month weekday)",
                 },
                 "timezone": {
                     "type": "string",
-                    "description": "IANA timezone (default: UTC).",
+                    "description": "IANA timezone for schedule (default: UTC)",
                 },
                 "wait_for_result": {
                     "type": "integer",
-                    "description": "Max seconds to wait for completion (0-300).",
+                    "description": (
+                        "Max seconds to wait for execution to complete (0-300). "
+                        "If >0, blocks until the execution finishes or times out. "
+                        "Returns execution outputs when complete."
+                    ),
                 },
             },
             "required": [],

autogpt_platform/backend/backend/copilot/tools/run_block.py

@@ -45,10 +45,13 @@ class RunBlockTool(BaseTool):
     @property
     def description(self) -> str:
         return (
-            "Execute a block. IMPORTANT: Always get block_id from find_block first "
-            "— do NOT guess or fabricate IDs. "
-            "Call with empty input_data to see schema, then with data to execute. "
-            "If review_required, use continue_run_block."
+            "Execute a specific block with the provided input data. "
+            "IMPORTANT: You MUST call find_block first to get the block's 'id' - "
+            "do NOT guess or make up block IDs. "
+            "On first attempt (without input_data), returns detailed schema showing "
+            "required inputs and outputs. Then call again with proper input_data to execute. "
+            "If a block requires human review, use continue_run_block with the "
+            "review_id after the user approves."
         )
 
     @property
@@ -58,14 +61,28 @@ class RunBlockTool(BaseTool):
             "properties": {
                 "block_id": {
                     "type": "string",
-                    "description": "Block ID from find_block results.",
+                    "description": (
+                        "The block's 'id' field from find_block results. "
+                        "NEVER guess this - always get it from find_block first."
+                    ),
+                },
+                "block_name": {
+                    "type": "string",
+                    "description": (
+                        "The block's human-readable name from find_block results. "
+                        "Used for display purposes in the UI."
+                    ),
                 },
                 "input_data": {
                     "type": "object",
-                    "description": "Input values. Use {} first to see schema.",
+                    "description": (
+                        "Input values for the block. "
+                        "First call with empty {} to see the block's schema, "
+                        "then call again with proper values to execute."
+                    ),
                 },
             },
-            "required": ["block_id", "input_data"],
+            "required": ["block_id", "block_name", "input_data"],
         }
 
     @property

autogpt_platform/backend/backend/copilot/tools/run_mcp_tool.py

@@ -57,9 +57,10 @@ class RunMCPToolTool(BaseTool):
     @property
     def description(self) -> str:
         return (
-            "Discover and execute MCP server tools. "
-            "Call with server_url only to list tools, then with tool_name + tool_arguments to execute. "
-            "Call get_mcp_guide first for server URLs and auth."
+            "Connect to an MCP (Model Context Protocol) server to discover and execute its tools. "
+            "Two-step: (1) call with server_url to list available tools, "
+            "(2) call again with server_url + tool_name + tool_arguments to execute. "
+            "Call get_mcp_guide for known server URLs and auth details."
         )
 
     @property
@@ -69,15 +70,24 @@ class RunMCPToolTool(BaseTool):
             "properties": {
                 "server_url": {
                     "type": "string",
-                    "description": "MCP server URL (Streamable HTTP endpoint).",
+                    "description": (
+                        "URL of the MCP server (Streamable HTTP endpoint), "
+                        "e.g. https://mcp.example.com/mcp"
+                    ),
                 },
                 "tool_name": {
                     "type": "string",
-                    "description": "Tool to execute. Omit to discover available tools.",
+                    "description": (
+                        "Name of the MCP tool to execute. "
+                        "Omit on first call to discover available tools."
+                    ),
                 },
                 "tool_arguments": {
                     "type": "object",
-                    "description": "Arguments matching the tool's input schema.",
+                    "description": (
+                        "Arguments to pass to the selected tool. "
+                        "Must match the tool's input schema returned during discovery."
+                    ),
                 },
             },
             "required": ["server_url"],

autogpt_platform/backend/backend/copilot/tools/search_docs.py

@@ -38,7 +38,11 @@ class SearchDocsTool(BaseTool):
 
     @property
     def description(self) -> str:
-        return "Search platform documentation by keyword. Use get_doc_page to read full results."
+        return (
+            "Search the AutoGPT platform documentation for information about "
+            "how to use the platform, build agents, configure blocks, and more. "
+            "Returns relevant documentation sections. Use get_doc_page to read full content."
+        )
 
     @property
     def parameters(self) -> dict[str, Any]:
@@ -47,7 +51,10 @@ class SearchDocsTool(BaseTool):
             "properties": {
                 "query": {
                     "type": "string",
-                    "description": "Documentation search query.",
+                    "description": (
+                        "Search query to find relevant documentation. "
+                        "Use natural language to describe what you're looking for."
+                    ),
                 },
             },
             "required": ["query"],

autogpt_platform/backend/backend/copilot/tools/tool_schema_test.py

@@ -1,81 +0,0 @@
-"""Schema regression tests for all registered CoPilot tools.
-
-Validates that every tool in TOOL_REGISTRY produces a well-formed schema:
-- description is non-empty
-- all `required` fields exist in `properties`
-- every property has a `type` and `description`
-- total token budget does not regress past 8000 tokens
-"""
-
-import json
-
-import pytest
-import tiktoken
-
-from backend.copilot.tools import TOOL_REGISTRY
-
-_TOKEN_BUDGET = 8_000
-
-
-def _get_all_tool_schemas() -> list[tuple[str, object]]:
-    """Return (tool_name, openai_schema) pairs for every registered tool."""
-    return [(name, tool.as_openai_tool()) for name, tool in TOOL_REGISTRY.items()]
-
-
-_ALL_SCHEMAS = _get_all_tool_schemas()
-
-
-@pytest.mark.parametrize(
-    "tool_name,schema",
-    _ALL_SCHEMAS,
-    ids=[name for name, _ in _ALL_SCHEMAS],
-)
-class TestToolSchema:
-    """Validate schema invariants for every registered tool."""
-
-    def test_description_non_empty(self, tool_name: str, schema: dict) -> None:
-        desc = schema["function"].get("description", "")
-        assert desc, f"Tool '{tool_name}' has an empty description"
-
-    def test_required_fields_exist_in_properties(
-        self, tool_name: str, schema: dict
-    ) -> None:
-        params = schema["function"].get("parameters", {})
-        properties = params.get("properties", {})
-        required = params.get("required", [])
-        for field in required:
-            assert field in properties, (
-                f"Tool '{tool_name}': required field '{field}' "
-                f"not found in properties {list(properties.keys())}"
-            )
-
-    def test_every_property_has_type_and_description(
-        self, tool_name: str, schema: dict
-    ) -> None:
-        params = schema["function"].get("parameters", {})
-        properties = params.get("properties", {})
-        for prop_name, prop_def in properties.items():
-            assert (
-                "type" in prop_def
-            ), f"Tool '{tool_name}', property '{prop_name}' is missing 'type'"
-            assert (
-                "description" in prop_def
-            ), f"Tool '{tool_name}', property '{prop_name}' is missing 'description'"
-
-
-def test_total_schema_token_budget() -> None:
-    """Assert total tool schema size stays under the token budget.
-
-    This locks in the 34% token reduction from #12398 and prevents future
-    description bloat from eroding the gains. Budget is set to 8000 tokens.
-    Note: this measures tool JSON only (not the full system prompt); the actual
-    baseline for tool schemas alone is ~6470 tokens, giving ~19% headroom.
-    """
-    schemas = [tool.as_openai_tool() for tool in TOOL_REGISTRY.values()]
-    serialized = json.dumps(schemas)
-    enc = tiktoken.get_encoding("cl100k_base")
-    total_tokens = len(enc.encode(serialized))
-    assert total_tokens < _TOKEN_BUDGET, (
-        f"Tool schemas use {total_tokens} tokens, exceeding budget of {_TOKEN_BUDGET}. "
-        f"Description bloat detected — trim descriptions or raise the budget intentionally."
-    )

autogpt_platform/backend/backend/copilot/tools/validate_agent.py

@@ -21,7 +21,19 @@ class ValidateAgentGraphTool(BaseTool):
 
     @property
     def description(self) -> str:
-        return "Validate agent JSON for correctness (block_ids, links, types, schemas). On failure, use fix_agent_graph to auto-fix."
+        return (
+            "Validate an agent JSON graph for correctness. Checks:\n"
+            "- All block_ids reference real blocks\n"
+            "- All links reference valid source/sink nodes and fields\n"
+            "- Required input fields are wired or have defaults\n"
+            "- Data types are compatible across links\n"
+            "- Nested sink links use correct notation\n"
+            "- Prompt templates use proper curly brace escaping\n"
+            "- AgentExecutorBlock configurations are valid\n\n"
+            "Call this after generating agent JSON to verify correctness. "
+            "If validation fails, either fix issues manually based on the error "
+            "descriptions, or call fix_agent_graph to auto-fix common problems."
+        )
 
     @property
     def requires_auth(self) -> bool:
@@ -34,7 +46,11 @@ class ValidateAgentGraphTool(BaseTool):
             "properties": {
                 "agent_json": {
                     "type": "object",
-                    "description": "Agent JSON with 'nodes' and 'links' arrays.",
+                    "description": (
+                        "The agent JSON to validate. Must contain 'nodes' and 'links' arrays. "
+                        "Each node needs: id (UUID), block_id, input_default, metadata. "
+                        "Each link needs: id (UUID), source_id, source_name, sink_id, sink_name."
+                    ),
                 },
             },
             "required": ["agent_json"],

autogpt_platform/backend/backend/copilot/tools/web_fetch.py

@@ -59,7 +59,13 @@ class WebFetchTool(BaseTool):
 
     @property
     def description(self) -> str:
-        return "Fetch a public web page. Public URLs only — internal addresses blocked. Returns readable text from HTML by default."
+        return (
+            "Fetch the content of a public web page by URL. "
+            "Returns readable text extracted from HTML by default. "
+            "Useful for reading documentation, articles, and API responses. "
+            "Only supports HTTP/HTTPS GET requests to public URLs "
+            "(private/internal network addresses are blocked)."
+        )
 
     @property
     def parameters(self) -> dict[str, Any]:
@@ -68,11 +74,14 @@ class WebFetchTool(BaseTool):
             "properties": {
                 "url": {
                     "type": "string",
-                    "description": "Public HTTP/HTTPS URL.",
+                    "description": "The public HTTP/HTTPS URL to fetch.",
                 },
                 "extract_text": {
                     "type": "boolean",
-                    "description": "Extract text from HTML (default: true).",
+                    "description": (
+                        "If true (default), extract readable text from HTML. "
+                        "If false, return raw content."
+                    ),
                     "default": True,
                 },
             },

autogpt_platform/backend/backend/copilot/tools/workspace_files.py

@@ -321,7 +321,13 @@ class ListWorkspaceFilesTool(BaseTool):
 
     @property
     def description(self) -> str:
-        return "List persistent workspace files. For ephemeral session files, use SDK Glob/Read instead. Optionally filter by path prefix."
+        return (
+            "List files in the user's persistent workspace (cloud storage). "
+            "These files survive across sessions. "
+            "For ephemeral session files, use the SDK Read/Glob tools instead. "
+            "Returns file names, paths, sizes, and metadata. "
+            "Optionally filter by path prefix."
+        )
 
     @property
     def parameters(self) -> dict[str, Any]:
@@ -330,17 +336,24 @@ class ListWorkspaceFilesTool(BaseTool):
             "properties": {
                 "path_prefix": {
                     "type": "string",
-                    "description": "Filter by path prefix (e.g. '/documents/').",
+                    "description": (
+                        "Optional path prefix to filter files "
+                        "(e.g., '/documents/' to list only files in documents folder). "
+                        "By default, only files from the current session are listed."
+                    ),
                 },
                 "limit": {
                     "type": "integer",
-                    "description": "Max files to return (default 50, max 100).",
+                    "description": "Maximum number of files to return (default 50, max 100)",
                     "minimum": 1,
                     "maximum": 100,
                 },
                 "include_all_sessions": {
                     "type": "boolean",
-                    "description": "Include files from all sessions (default: false).",
+                    "description": (
+                        "If true, list files from all sessions. "
+                        "Default is false (only current session's files)."
+                    ),
                 },
             },
             "required": [],
@@ -423,10 +436,18 @@ class ReadWorkspaceFileTool(BaseTool):
     @property
     def description(self) -> str:
         return (
-            "Read a file from persistent workspace. Specify file_id or path. "
-            "Small text/image files return inline; large/binary return metadata+URL. "
-            "Use save_to_path to copy to working dir for processing. "
-            "Use offset/length for paginated reads."
+            "Read a file from the user's persistent workspace (cloud storage). "
+            "These files survive across sessions. "
+            "For ephemeral session files, use the SDK Read tool instead. "
+            "Specify either file_id or path to identify the file. "
+            "For small text files, returns content directly. "
+            "For large or binary files, returns metadata and a download URL. "
+            "Use 'save_to_path' to copy the file to the working directory "
+            "(sandbox or ephemeral) for processing with bash_exec or file tools. "
+            "Use 'offset' and 'length' for paginated reads of large files "
+            "(e.g., persisted tool outputs). "
+            "Paths are scoped to the current session by default. "
+            "Use /sessions/<session_id>/... for cross-session access."
         )
 
     @property
@@ -436,30 +457,48 @@ class ReadWorkspaceFileTool(BaseTool):
             "properties": {
                 "file_id": {
                     "type": "string",
-                    "description": "File ID from list_workspace_files.",
+                    "description": "The file's unique ID (from list_workspace_files)",
                 },
                 "path": {
                     "type": "string",
-                    "description": "Virtual file path (e.g. '/documents/report.pdf').",
+                    "description": (
+                        "The virtual file path (e.g., '/documents/report.pdf'). "
+                        "Scoped to current session by default."
+                    ),
                 },
                 "save_to_path": {
                     "type": "string",
-                    "description": "Copy file to this working directory path for processing.",
+                    "description": (
+                        "If provided, save the file to this path in the working "
+                        "directory (cloud sandbox when E2B is active, or "
+                        "ephemeral dir otherwise) so it can be processed with "
+                        "bash_exec or file tools. "
+                        "The file content is still returned in the response."
+                    ),
                 },
                 "force_download_url": {
                     "type": "boolean",
-                    "description": "Always return metadata+URL instead of inline content.",
+                    "description": (
+                        "If true, always return metadata+URL instead of inline content. "
+                        "Default is false (auto-selects based on file size/type)."
+                    ),
                 },
                 "offset": {
                     "type": "integer",
-                    "description": "Character offset for paginated reads (0-based).",
+                    "description": (
+                        "Character offset to start reading from (0-based). "
+                        "Use with 'length' for paginated reads of large files."
+                    ),
                 },
                 "length": {
                     "type": "integer",
-                    "description": "Max characters to return for paginated reads.",
+                    "description": (
+                        "Maximum number of characters to return. "
+                        "Defaults to full file. Use with 'offset' for paginated reads."
+                    ),
                 },
             },
-            "required": [],  # At least one of file_id or path must be provided
+            "required": [],  # At least one must be provided
         }
 
     @property
@@ -614,9 +653,15 @@ class WriteWorkspaceFileTool(BaseTool):
     @property
     def description(self) -> str:
         return (
-            "Write a file to persistent workspace (survives across sessions). "
-            "Provide exactly one of: content (text), content_base64 (binary), "
-            f"or source_path (copy from working dir). Max {Config().max_file_size_mb}MB."
+            "Write or create a file in the user's persistent workspace (cloud storage). "
+            "These files survive across sessions. "
+            "For ephemeral session files, use the SDK Write tool instead. "
+            "Provide content as plain text via 'content', OR base64-encoded via "
+            "'content_base64', OR copy a file from the ephemeral working directory "
+            "via 'source_path'. Exactly one of these three is required. "
+            f"Maximum file size is {Config().max_file_size_mb}MB. "
+            "Files are saved to the current session's folder by default. "
+            "Use /sessions/<session_id>/... for cross-session access."
         )
 
     @property
@@ -626,31 +671,51 @@ class WriteWorkspaceFileTool(BaseTool):
             "properties": {
                 "filename": {
                     "type": "string",
-                    "description": "Filename (e.g. 'report.pdf').",
+                    "description": "Name for the file (e.g., 'report.pdf')",
                 },
                 "content": {
                     "type": "string",
-                    "description": "Plain text content. Mutually exclusive with content_base64/source_path.",
+                    "description": (
+                        "Plain text content to write. Use this for text files "
+                        "(code, configs, documents, etc.). "
+                        "Mutually exclusive with content_base64 and source_path."
+                    ),
                 },
                 "content_base64": {
                     "type": "string",
-                    "description": "Base64-encoded binary content. Mutually exclusive with content/source_path.",
+                    "description": (
+                        "Base64-encoded file content. Use this for binary files "
+                        "(images, PDFs, etc.). "
+                        "Mutually exclusive with content and source_path."
+                    ),
                 },
                 "source_path": {
                     "type": "string",
-                    "description": "Working directory path to copy to workspace. Mutually exclusive with content/content_base64.",
+                    "description": (
+                        "Path to a file in the ephemeral working directory to "
+                        "copy to workspace (e.g., '/tmp/copilot-.../output.csv'). "
+                        "Use this to persist files created by bash_exec or SDK Write. "
+                        "Mutually exclusive with content and content_base64."
+                    ),
                 },
                 "path": {
                     "type": "string",
-                    "description": "Virtual path (e.g. '/documents/report.pdf'). Defaults to '/{filename}'.",
+                    "description": (
+                        "Optional virtual path where to save the file "
+                        "(e.g., '/documents/report.pdf'). "
+                        "Defaults to '/{filename}'. Scoped to current session."
+                    ),
                 },
                 "mime_type": {
                     "type": "string",
-                    "description": "MIME type. Auto-detected from filename if omitted.",
+                    "description": (
+                        "Optional MIME type of the file. "
+                        "Auto-detected from filename if not provided."
+                    ),
                 },
                 "overwrite": {
                     "type": "boolean",
-                    "description": "Overwrite if file exists (default: false).",
+                    "description": "Whether to overwrite if file exists at path (default: false)",
                 },
             },
             "required": ["filename"],
@@ -777,7 +842,12 @@ class DeleteWorkspaceFileTool(BaseTool):
 
     @property
     def description(self) -> str:
-        return "Delete a file from persistent workspace. Specify file_id or path."
+        return (
+            "Delete a file from the user's persistent workspace (cloud storage). "
+            "Specify either file_id or path to identify the file. "
+            "Paths are scoped to the current session by default. "
+            "Use /sessions/<session_id>/... for cross-session access."
+        )
 
     @property
     def parameters(self) -> dict[str, Any]:
@@ -786,14 +856,17 @@ class DeleteWorkspaceFileTool(BaseTool):
             "properties": {
                 "file_id": {
                     "type": "string",
-                    "description": "File ID from list_workspace_files.",
+                    "description": "The file's unique ID (from list_workspace_files)",
                 },
                 "path": {
                     "type": "string",
-                    "description": "Virtual file path.",
+                    "description": (
+                        "The virtual file path (e.g., '/documents/report.pdf'). "
+                        "Scoped to current session by default."
+                    ),
                 },
             },
-            "required": [],  # At least one of file_id or path must be provided
+            "required": [],  # At least one must be provided
         }
 
     @property

autogpt_platform/backend/backend/util/text.py

@@ -1,4 +1,5 @@
 import logging
+import re
 
 import bleach
 from bleach.css_sanitizer import CSSSanitizer
@@ -154,3 +155,76 @@ class TextFormatter:
         )
 
         return rendered_subject_template, rendered_base_template
+
+
+# ---------------------------------------------------------------------------
+# CamelCase splitting
+# ---------------------------------------------------------------------------
+
+# Map of split forms back to their canonical compound terms.
+# Mirrors the frontend exception list in frontend/src/lib/utils.ts.
+_CAMELCASE_EXCEPTIONS: dict[str, str] = {
+    "Auto GPT": "AutoGPT",
+    "Open AI": "OpenAI",
+    "You Tube": "YouTube",
+    "Git Hub": "GitHub",
+    "Linked In": "LinkedIn",
+}
+
+_CAMELCASE_EXCEPTION_RE = re.compile(
+    "|".join(re.escape(k) for k in _CAMELCASE_EXCEPTIONS),
+)
+
+
+def split_camelcase(text: str) -> str:
+    """Split CamelCase into separate words.
+
+    Uses a single-pass character-by-character algorithm to avoid any
+    regex backtracking concerns (guaranteed O(n) time).
+
+    After splitting, known compound terms are restored via an exception
+    list (e.g. ``"YouTube"`` stays ``"YouTube"`` instead of becoming
+    ``"You Tube"``).  The list mirrors the frontend mapping in
+    ``frontend/src/lib/utils.ts``.
+
+    Examples::
+
+        >>> split_camelcase("AITextGeneratorBlock")
+        'AI Text Generator Block'
+        >>> split_camelcase("OAuth2Block")
+        'OAuth2 Block'
+        >>> split_camelcase("YouTubeBlock")
+        'YouTube Block'
+    """
+    if len(text) <= 1:
+        return text
+
+    parts: list[str] = []
+    prev = 0
+    for i in range(1, len(text)):
+        # Insert split between lowercase/digit and uppercase: "camelCase" -> "camel|Case"
+        if (text[i - 1].islower() or text[i - 1].isdigit()) and text[i].isupper():
+            parts.append(text[prev:i])
+            prev = i
+        # Insert split between uppercase run (2+ chars) and uppercase+lowercase:
+        # "AIText" -> "AI|Text".  Requires at least 3 consecutive uppercase chars
+        # before the lowercase so that the left part keeps 2+ uppercase chars
+        # (mirrors the original regex r"([A-Z]{2,})([A-Z][a-z])").
+        elif (
+            i >= 2
+            and text[i - 2].isupper()
+            and text[i - 1].isupper()
+            and text[i].islower()
+            and (i - 1 - prev) >= 2  # left part must retain at least 2 upper chars
+        ):
+            parts.append(text[prev : i - 1])
+            prev = i - 1
+
+    parts.append(text[prev:])
+    result = " ".join(parts)
+
+    # Restore known compound terms that should not be split.
+    result = _CAMELCASE_EXCEPTION_RE.sub(
+        lambda m: _CAMELCASE_EXCEPTIONS[m.group()], result
+    )
+    return result