remdb 0.3.221__tar.gz → 0.3.240__tar.gz

{remdb-0.3.221 → remdb-0.3.240}/.githooks/pre-push

@@ -28,7 +28,7 @@ echo ""
 echo ">>> Running integration tests (skipping LLM tests and files with event loop conflicts)..."
 # Skip LLM-marked tests which require real API calls
 # Ignore files that have TestClient + asyncpg event loop conflicts
-POSTGRES__CONNECTION_STRING="postgresql://rem:rem@localhost:5433/rem" \
+POSTGRES__CONNECTION_STRING="postgresql://rem:rem@localhost:5051/rem" \
     uv run pytest tests/integration/ -v -m "not llm" \
     --ignore=tests/integration/test_session_management.py \
     --ignore=tests/integration/test_api_endpoints.py \

remdb-0.3.240/.kreuzberg/mime/16abeec91e023b5b.msgpack

@@ -0,0 +1 @@
+��type�str�data�application/pdf�cached_at�A�U��	�5

remdb-0.3.240/.kreuzberg/mime/394432a951453a5d.msgpack

@@ -0,0 +1 @@
+��type�str�data�application/pdf�cached_at�A�Uo�:�

remdb-0.3.240/.kreuzberg/mime/bfcef627f6134a1d.msgpack

@@ -0,0 +1 @@
+��type�str�data�application/pdf�cached_at�A�Uo/sHc

remdb-0.3.240/.kreuzberg/mime/dccd2eed35d5d08b.msgpack

@@ -0,0 +1 @@
+��type�str�data�application/pdf�cached_at�A�Uf���

{remdb-0.3.221 → remdb-0.3.240}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: remdb
-Version: 0.3.221
+Version: 0.3.240
 Summary: Resources Entities Moments - Bio-inspired memory system for agentic AI workloads
 Project-URL: Homepage, https://github.com/Percolation-Labs/reminiscent
 Project-URL: Documentation, https://github.com/Percolation-Labs/reminiscent/blob/main/README.md
@@ -39,7 +39,7 @@ Requires-Dist: opentelemetry-instrumentation-fastapi>=0.49b0
 Requires-Dist: opentelemetry-instrumentation>=0.49b0
 Requires-Dist: opentelemetry-sdk>=1.28.0
 Requires-Dist: psycopg[binary]>=3.2.0
-Requires-Dist: pydantic-ai>=0.0.14
+Requires-Dist: pydantic-ai>=1.0.0
 Requires-Dist: pydantic-settings>=2.6.0
 Requires-Dist: pydantic>=2.10.0
 Requires-Dist: pydub>=0.25.0

{remdb-0.3.221 → remdb-0.3.240}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "remdb"
-version = "0.3.221"
+version = "0.3.240"
 description = "Resources Entities Moments - Bio-inspired memory system for agentic AI workloads"
 readme = "README.md"
 authors = [
@@ -24,7 +24,7 @@ dependencies = [
     "pydantic>=2.10.0",
     "pydantic-settings>=2.6.0",
     # Agentic AI
-    "pydantic-ai>=0.0.14",
+    "pydantic-ai>=1.0.0",
     # API Framework
     "fastapi>=0.115.0",
     "uvicorn[standard]>=0.32.0",
@@ -140,15 +140,11 @@ testpaths = ["tests"]
 python_files = ["test_*.py"]
 python_classes = ["Test*"]
 python_functions = ["test_*"]
-asyncio_mode = "auto"
-# Use session scope for both fixtures and tests to share one event loop
-# This prevents "Event loop is closed" errors with asyncpg connections
-asyncio_default_fixture_loop_scope = "session"
-asyncio_default_test_loop_scope = "session"
 addopts = [
     "-v",
     "--strict-markers",
     "--tb=short",
+    "--asyncio-mode=auto",
 ]
 markers = [
     "asyncio: marks tests as async",

{remdb-0.3.221 → remdb-0.3.240}/src/rem/agentic/README.md

@@ -718,263 +718,37 @@ See `rem/api/README.md` for full SSE event protocol documentation.
 
 ## Multi-Agent Orchestration
 
-REM supports hierarchical agent orchestration where agents can delegate work to other agents via the `ask_agent` tool. This enables complex workflows with specialized agents.
-
-### Architecture
-
-```mermaid
-sequenceDiagram
-    participant User
-    participant API as Chat API
-    participant Orchestrator as Orchestrator Agent
-    participant EventSink as Event Sink (Queue)
-    participant Child as Child Agent
-    participant DB as PostgreSQL
-
-    User->>API: POST /chat/completions (stream=true)
-    API->>API: Create event sink (asyncio.Queue)
-    API->>Orchestrator: agent.iter(prompt)
-
-    loop Streaming Loop
-        Orchestrator->>API: PartDeltaEvent (text)
-        API->>User: SSE: data: {"delta": {"content": "..."}}
-    end
-
-    Orchestrator->>Orchestrator: Decides to call ask_agent
-    Orchestrator->>API: ToolCallPart (ask_agent)
-    API->>User: SSE: event: tool_call
-
-    API->>Child: ask_agent("child_name", input)
-    Child->>EventSink: push_event(child_content)
-    EventSink->>API: Consume child events
-    API->>User: SSE: data: {"delta": {"content": "..."}}
-
-    Child->>Child: Completes
-    Child-->>Orchestrator: Return result
-
-    Orchestrator->>API: Final response
-    API->>DB: Save tool calls
-    API->>DB: Save assistant message
-    API->>User: SSE: data: [DONE]
-```
-
-### Event Sink Pattern
-
-When an agent delegates to a child via `ask_agent`, the child's streaming events need to bubble up to the parent's stream. This is achieved through an **event sink** pattern using Python's `ContextVar`:
-
-```python
-# context.py
-from contextvars import ContextVar
-
-_parent_event_sink: ContextVar["asyncio.Queue | None"] = ContextVar(
-    "parent_event_sink", default=None
-)
-
-async def push_event(event: Any) -> bool:
-    """Push event to parent's event sink if available."""
-    sink = _parent_event_sink.get()
-    if sink is not None:
-        await sink.put(event)
-        return True
-    return False
-```
-
-The streaming controller sets up the event sink before agent execution:
-
-```python
-# streaming.py
-child_event_sink: asyncio.Queue = asyncio.Queue()
-set_event_sink(child_event_sink)
-
-async for node in agent.iter(prompt):
-    # Process agent events...
-
-    # Consume any child events that arrived
-    while not child_event_sink.empty():
-        child_event = child_event_sink.get_nowait()
-        if child_event["type"] == "child_content":
-            yield format_sse_content_delta(child_event["content"])
-```
-
-### ask_agent Tool Implementation
-
-The `ask_agent` tool in `mcp_router/tools.py` uses Pydantic AI's streaming iteration:
-
-```python
-async def ask_agent(agent_name: str, input_text: str, ...):
-    """Delegate work to another agent."""
-
-    # Load and create child agent
-    schema = await load_agent_schema_async(agent_name, user_id)
-    child_agent = await create_agent(context=context, agent_schema_override=schema)
-
-    # Stream child agent with event proxying
-    async with child_agent.iter(prompt) as agent_run:
-        async for node in agent_run:
-            if Agent.is_model_request_node(node):
-                async with node.stream(agent_run.ctx) as request_stream:
-                    async for event in request_stream:
-                        if isinstance(event, PartDeltaEvent):
-                            # Push content to parent's event sink
-                            await push_event({
-                                "type": "child_content",
-                                "agent_name": agent_name,
-                                "content": event.delta.content_delta,
-                            })
-
-    return agent_run.result
-```
-
-### Pydantic AI Features Used
+Agents can delegate work to other agents via the `ask_agent` tool. This enables orchestrator patterns where a parent agent routes to specialists.
 
-#### 1. Streaming Iteration (`agent.iter()`)
+### How It Works
 
-Unlike `agent.run()` which blocks until completion, `agent.iter()` provides fine-grained control over the execution flow:
+1. **Parent agent** calls `ask_agent(agent_name, input_text)`
+2. **Child agent** executes and streams its response
+3. **Child events** bubble up to parent via an event sink (asyncio.Queue in ContextVar)
+4. **All tool calls** are saved to the database for the session
 
-```python
-async with agent.iter(prompt) as agent_run:
-    async for node in agent_run:
-        if Agent.is_model_request_node(node):
-            # Model is generating - stream the response
-            async with node.stream(agent_run.ctx) as stream:
-                async for event in stream:
-                    if isinstance(event, PartStartEvent):
-                        # Tool call starting
-                    elif isinstance(event, PartDeltaEvent):
-                        # Content chunk
-        elif Agent.is_call_tools_node(node):
-            # Tools are being executed
-            async with node.stream(agent_run.ctx) as stream:
-                async for event in stream:
-                    if isinstance(event, FunctionToolResultEvent):
-                        # Tool completed
-```
-
-#### 2. Node Types
-
-- **`ModelRequestNode`**: The model is generating a response (text or tool calls)
-- **`CallToolsNode`**: Tools are being executed
-- **`End`**: Agent execution complete
-
-#### 3. Event Types
+### Key Components
 
-- **`PartStartEvent`**: A new part (text or tool call) is starting
-- **`PartDeltaEvent`**: Content chunk for streaming text
-- **`FunctionToolResultEvent`**: Tool execution completed with result
-- **`ToolCallPart`**: Metadata about a tool call (name, arguments)
-- **`TextPart`**: Text content
+| Component | Location | Purpose |
+|-----------|----------|---------|
+| `ask_agent` tool | `mcp_router/tools.py` | Loads child agent, runs with streaming, pushes events to sink |
+| Event sink | `context.py` | ContextVar holding asyncio.Queue for child→parent event flow |
+| Streaming controller | `streaming.py` | Drains event sink, emits SSE events, saves to DB |
 
-### Message Persistence
-
-All messages are persisted to PostgreSQL for session continuity:
-
-```python
-# streaming.py - after agent completes
-async def save_session_messages(...):
-    store = SessionMessageStore(user_id=user_id)
-
-    # Save each tool call as a tool message
-    for tool_call in tool_calls:
-        await store.save_message(
-            session_id=session_id,
-            role="tool",
-            content=tool_call.result,
-            tool_name=tool_call.name,
-            tool_call_id=tool_call.id,
-        )
-
-    # Save the final assistant response
-    await store.save_message(
-        session_id=session_id,
-        role="assistant",
-        content=accumulated_content,
-    )
-```
+### Event Types
 
-Messages are stored with:
-- **Embeddings**: For semantic search across conversation history
-- **Compression**: Long conversations are summarized to manage context window
-- **Session isolation**: Each session maintains its own message history
+Child agents emit events that the parent streams to the client:
 
-### Testing Multi-Agent Systems
+- **`child_tool_start`**: Child is calling a tool (logged, streamed, saved to DB)
+- **`child_content`**: Child's text response (streamed as SSE content delta)
+- **`child_tool_result`**: Tool completed with result (metadata extraction)
 
-#### Integration Tests
+### Testing
 
-Real end-to-end tests without mocking are in `tests/integration/test_ask_agent_streaming.py`:
-
-```python
-class TestAskAgentStreaming:
-    async def test_ask_agent_streams_and_saves(self, session_id, user_id):
-        """Test delegation via ask_agent."""
-        # Uses test_orchestrator which always delegates to test_responder
-        agent = await create_agent(context=context, agent_schema_override=schema)
-
-        chunks = []
-        async for chunk in stream_openai_response_with_save(
-            agent=agent,
-            prompt="Hello, please delegate this",
-            ...
-        ):
-            chunks.append(chunk)
-
-        # Verify streaming worked
-        assert len(content_chunks) > 0
-
-        # Verify persistence
-        messages = await store.load_session_messages(session_id)
-        assert len([m for m in messages if m["role"] == "assistant"]) == 1
-        assert len([m for m in messages if m["tool_name"] == "ask_agent"]) >= 1
-
-    async def test_multi_turn_saves_all_assistant_messages(self, session_id, user_id):
-        """Test that each turn saves its own assistant message.
-
-        This catches scoping bugs like accumulated_content not being
-        properly scoped per-turn.
-        """
-        turn_prompts = [
-            "Hello, how are you?",
-            "Tell me something interesting",
-            "Thanks for chatting!",
-        ]
-
-        for prompt in turn_prompts:
-            async for chunk in stream_openai_response_with_save(...):
-                pass
-
-        # Each turn should save an assistant message
-        messages = await store.load_session_messages(session_id)
-        assistant_msgs = [m for m in messages if m["role"] == "assistant"]
-        assert len(assistant_msgs) == 3
-```
-
-#### Test Agent Schemas
-
-Test agents are defined in `tests/data/schemas/agents/`:
-
-- **`test_orchestrator.yaml`**: Always delegates via `ask_agent`
-- **`test_responder.yaml`**: Simple agent that responds directly
-
-```yaml
-# test_orchestrator.yaml
-type: object
-description: |
-  You are a TEST ORCHESTRATOR that ALWAYS delegates to another agent.
-  Call ask_agent with agent_name="test_responder" on EVERY turn.
-json_schema_extra:
-  kind: agent
-  name: test_orchestrator
-  tools:
-    - name: ask_agent
-      mcp_server: rem
-```
-
-#### Running Integration Tests
-
-```bash
-# Run individually (recommended due to async isolation)
-POSTGRES__CONNECTION_STRING="postgresql://rem:rem@localhost:5050/rem" \
-  uv run pytest tests/integration/test_ask_agent_streaming.py::TestAskAgentStreaming::test_multi_turn_saves_all_assistant_messages -v -s
-```
+Integration tests in `tests/integration/test_ask_agent_streaming.py` verify:
+- Child content streams correctly to client
+- Tool calls are persisted to database
+- Multi-turn conversations save all messages
 
 ## Future Work
 

{remdb-0.3.221 → remdb-0.3.240}/src/rem/agentic/context_builder.py

@@ -4,15 +4,12 @@ Centralized context builder for agent execution.
 Session History (ALWAYS loaded with compression):
 - Each chat request is a single message, so session history MUST be recovered
 - Uses SessionMessageStore with compression to keep context efficient
-- Long assistant responses include REM LOOKUP hints: "... [REM LOOKUP session-{id}-msg-{index}] ..."
-- Agent can retrieve full content on-demand using REM LOOKUP
 - Prevents context window bloat while maintaining conversation continuity
 
 User Context (on-demand by default):
-- System message includes REM LOOKUP hint for user profile
-- Agent decides whether to load profile based on query
-- More efficient for queries that don't need personalization
-- Example: "User: sarah@example.com. To load user profile: Use REM LOOKUP \"sarah@example.com\""
+- System message includes user email for context awareness
+- Fails silently if user not found - agent proceeds without user context
+- Example: "User: sarah@example.com"
 
 User Context (auto-inject when enabled):
 - Set CHAT__AUTO_INJECT_USER_CONTEXT=true
@@ -22,8 +19,8 @@ User Context (auto-inject when enabled):
 Design Pattern:
 1. Extract AgentContext from headers (user_id, tenant_id, session_id)
 2. If auto-inject enabled: Load User/Session from database
-3. If auto-inject disabled: Provide REM LOOKUP hints in system message
-4. Construct system message with date + context (injected or hints)
+3. If auto-inject disabled: Show user email for context (fail silently if not found)
+4. Construct system message with date + context
 5. Return complete context ready for agent execution
 
 Integration Points:
@@ -40,11 +37,10 @@ Usage (on-demand, default):
 
     # Messages list structure (on-demand):
     # [
-    #   {"role": "system", "content": "Today's date: 2025-11-22\nUser: sarah@example.com\nTo load user profile: Use REM LOOKUP \"sarah@example.com\"\nSession ID: sess-123\nTo load session history: Use REM LOOKUP messages?session_id=sess-123"},
+    #   {"role": "system", "content": "Today's date: 2025-11-22\n\nUser: sarah@example.com"},
     #   {"role": "user", "content": "What's next for the API migration?"}
     # ]
 
-    # Agent receives hints and can decide to load context if needed
     agent = await create_agent(context=context, ...)
     prompt = "\n".join(msg.content for msg in messages)
     result = await agent.run(prompt)
@@ -52,7 +48,7 @@ Usage (on-demand, default):
 Usage (auto-inject, CHAT__AUTO_INJECT_USER_CONTEXT=true):
     # Messages list structure (auto-inject):
     # [
-    #   {"role": "system", "content": "Today's date: 2025-11-22\n\nUser Context (auto-injected):\nSummary: ...\nInterests: ...\n\nSession History (auto-injected, 5 messages):"},
+    #   {"role": "system", "content": "Today's date: 2025-11-22\n\nUser Context (auto-injected):\nSummary: ...\nInterests: ..."},
     #   {"role": "user", "content": "Previous message"},
     #   {"role": "assistant", "content": "Previous response"},
     #   {"role": "user", "content": "What's next for the API migration?"}
@@ -110,13 +106,11 @@ class ContextBuilder:
 
         Session History (ALWAYS loaded with compression):
         - If session_id provided, session history is ALWAYS loaded using SessionMessageStore
-        - Compression keeps it efficient with REM LOOKUP hints for long messages
-        - Example: "... [Message truncated - REM LOOKUP session-{id}-msg-{index}] ..."
-        - Agent can retrieve full content on-demand using REM LOOKUP
+        - Compression keeps context efficient
 
         User Context (on-demand by default):
-        - System message includes REM LOOKUP hint: "User: {email}. To load user profile: Use REM LOOKUP \"{email}\""
-        - Agent decides whether to load profile based on query
+        - System message includes user email: "User: {email}"
+        - Fails silently if user not found - agent proceeds without user context
 
         User Context (auto-inject when enabled):
         - Set CHAT__AUTO_INJECT_USER_CONTEXT=true
@@ -137,9 +131,9 @@ class ContextBuilder:
 
             # messages structure:
             # [
-            #   {"role": "system", "content": "Today's date: 2025-11-22\nUser: sarah@example.com\nTo load user profile: Use REM LOOKUP \"sarah@example.com\""},
+            #   {"role": "system", "content": "Today's date: 2025-11-22\n\nUser: sarah@example.com"},
             #   {"role": "user", "content": "Previous message"},
-            #   {"role": "assistant", "content": "Start of long response... [REM LOOKUP session-123-msg-1] ...end"},
+            #   {"role": "assistant", "content": "Previous response"},
             #   {"role": "user", "content": "New message"}
             # ]
         """
@@ -189,18 +183,18 @@ class ContextBuilder:
                     context_hint += f"\n\nUser Context (auto-injected):\n{user_context_content}"
                 else:
                     context_hint += "\n\nNo user context available (anonymous or new user)."
-            elif context.user_id:
-                # On-demand: Provide hint to use REM LOOKUP
-                # user_id is UUID5 hash of email - load user to get email for display and LOOKUP
-                user_repo = Repository(User, "users", db=db)
-                user = await user_repo.get_by_id(context.user_id, context.tenant_id)
-                if user and user.email:
-                    # Show email (more useful than UUID) and LOOKUP hint
-                    context_hint += f"\n\nUser: {user.email}"
-                    context_hint += f"\nTo load user profile: Use REM LOOKUP \"{user.email}\""
-                else:
-                    context_hint += f"\n\nUser ID: {context.user_id}"
-                    context_hint += "\nUser profile not available."
+            elif context.user_id and db:
+                # On-demand: Show user email for context (no REM LOOKUP - it requires exact user_id match)
+                # Fail silently if user lookup fails - just proceed without user context
+                try:
+                    user_repo = Repository(User, "users", db=db)
+                    user = await user_repo.get_by_id(context.user_id, context.tenant_id)
+                    if user and user.email:
+                        context_hint += f"\n\nUser: {user.email}"
+                    # If user not found, just proceed without adding user context
+                except Exception as e:
+                    # Fail silently - don't block agent execution if user lookup fails
+                    logger.debug(f"Could not load user context: {e}")
 
             # Add system context hint
             messages.append(ContextMessage(role="system", content=context_hint))

{remdb-0.3.221 → remdb-0.3.240}/src/rem/agentic/providers/pydantic_ai.py

@@ -357,6 +357,9 @@ def _convert_properties_to_prompt(properties: dict[str, Any]) -> str:
     definition into natural language guidance that informs the agent
     about the expected response structure without forcing JSON output.
 
+    IMPORTANT: The 'answer' field is the OUTPUT to the user. All other
+    fields are INTERNAL tracking that should NOT appear in the output.
+
     Args:
         properties: JSON Schema properties dict
 
@@ -368,45 +371,59 @@ def _convert_properties_to_prompt(properties: dict[str, Any]) -> str:
             "answer": {"type": "string", "description": "The answer"},
             "confidence": {"type": "number", "description": "Confidence 0-1"}
         }
-        # Returns:
-        # "## Response Structure\n\nYour response should include:\n- **answer**: The answer\n..."
+        # Returns guidance that only answer should be output
     """
     if not properties:
         return ""
 
-    lines = ["## Response Guidelines", "", "Your response should address the following elements:"]
-
-    for field_name, field_def in properties.items():
-        field_type = field_def.get("type", "any")
-        description = field_def.get("description", "")
-
-        # Format based on type
-        if field_type == "array":
-            type_hint = "list"
-        elif field_type == "number":
-            type_hint = "number"
-            # Include min/max if specified
-            if "minimum" in field_def or "maximum" in field_def:
-                min_val = field_def.get("minimum", "")
-                max_val = field_def.get("maximum", "")
-                if min_val != "" and max_val != "":
-                    type_hint = f"number ({min_val}-{max_val})"
-        elif field_type == "boolean":
-            type_hint = "yes/no"
-        else:
-            type_hint = field_type
+    # Separate answer (output) from other fields (internal tracking)
+    answer_field = properties.get("answer")
+    internal_fields = {k: v for k, v in properties.items() if k != "answer"}
+
+    lines = ["## Internal Thinking Structure (DO NOT output these labels)"]
+    lines.append("")
+    lines.append("Use this structure to organize your thinking, but ONLY output the answer content:")
+    lines.append("")
+
+    # If there's an answer field, emphasize it's the ONLY output
+    if answer_field:
+        answer_desc = answer_field.get("description", "Your response")
+        lines.append(f"**OUTPUT (what the user sees):** {answer_desc}")
+        lines.append("")
+
+    # Document internal fields for tracking/thinking
+    if internal_fields:
+        lines.append("**INTERNAL (for your tracking only - do NOT include in output):**")
+        for field_name, field_def in internal_fields.items():
+            field_type = field_def.get("type", "any")
+            description = field_def.get("description", "")
+
+            # Format based on type
+            if field_type == "array":
+                type_hint = "list"
+            elif field_type == "number":
+                type_hint = "number"
+                if "minimum" in field_def or "maximum" in field_def:
+                    min_val = field_def.get("minimum", "")
+                    max_val = field_def.get("maximum", "")
+                    if min_val != "" and max_val != "":
+                        type_hint = f"number ({min_val}-{max_val})"
+            elif field_type == "boolean":
+                type_hint = "yes/no"
+            else:
+                type_hint = field_type
 
-        # Build field description
-        field_line = f"- **{field_name}**"
-        if type_hint and type_hint != "string":
-            field_line += f" ({type_hint})"
-        if description:
-            field_line += f": {description}"
+            field_line = f"- {field_name}"
+            if type_hint and type_hint != "string":
+                field_line += f" ({type_hint})"
+            if description:
+                field_line += f": {description}"
 
-        lines.append(field_line)
+            lines.append(field_line)
 
     lines.append("")
-    lines.append("Respond naturally in prose, addressing these elements where relevant.")
+    lines.append("⚠️ CRITICAL: Your response must be ONLY the conversational answer text.")
+    lines.append("Do NOT output field names like 'answer:' or 'diverge_output:' - just the response itself.")
 
     return "\n".join(lines)
 
@@ -664,26 +681,26 @@ async def create_agent(
 
         set_agent_resource_attributes(agent_schema=agent_schema)
 
-    # Extract schema metadata for search_rem tool description suffix
-    # This allows entity schemas to add context-specific notes to the search_rem tool
-    search_rem_suffix = None
-    if metadata:
-        # Check for default_search_table in metadata (set by entity schemas)
-        extra = agent_schema.get("json_schema_extra", {}) if agent_schema else {}
-        default_table = extra.get("default_search_table")
-        has_embeddings = extra.get("has_embeddings", False)
-
-        if default_table:
-            # Build description suffix for search_rem
-            search_rem_suffix = f"\n\nFor this schema, use `search_rem` to query `{default_table}`. "
-            if has_embeddings:
-                search_rem_suffix += f"SEARCH works well on {default_table} (has embeddings). "
-            search_rem_suffix += f"Example: `SEARCH \"your query\" FROM {default_table} LIMIT 10`"
-
     # Add tools from MCP server (in-process, no subprocess)
     # Track loaded MCP servers for resource resolution
     loaded_mcp_server = None
 
+    # Build map of tool_name → schema description from agent schema tools section
+    # This allows agent-specific tool guidance to override/augment MCP tool descriptions
+    schema_tool_descriptions: dict[str, str] = {}
+    tool_configs = metadata.tools if metadata and hasattr(metadata, 'tools') else []
+    for tool_config in tool_configs:
+        if hasattr(tool_config, 'name'):
+            t_name = tool_config.name
+            t_desc = tool_config.description or ""
+        else:
+            t_name = tool_config.get("name", "")
+            t_desc = tool_config.get("description", "")
+        # Skip resource URIs (handled separately below)
+        if t_name and "://" not in t_name and t_desc:
+            schema_tool_descriptions[t_name] = t_desc
+            logger.debug(f"Schema tool description for '{t_name}': {len(t_desc)} chars")
+
     for server_config in mcp_server_configs:
         server_type = server_config.get("type")
         server_id = server_config.get("id", "mcp-server")
@@ -708,8 +725,8 @@ async def create_agent(
                 mcp_tools_dict = await mcp_server.get_tools()
 
                 for tool_name, tool_func in mcp_tools_dict.items():
-                    # Add description suffix to search_rem tool if schema specifies a default table
-                    tool_suffix = search_rem_suffix if tool_name == "search_rem" else None
+                    # Get schema description suffix if agent schema defines one for this tool
+                    tool_suffix = schema_tool_descriptions.get(tool_name)
 
                     wrapped_tool = create_mcp_tool_wrapper(
                         tool_name,
@@ -718,7 +735,7 @@ async def create_agent(
                         description_suffix=tool_suffix,
                     )
                     tools.append(wrapped_tool)
-                    logger.debug(f"Loaded MCP tool: {tool_name}" + (" (with schema suffix)" if tool_suffix else ""))
+                    logger.debug(f"Loaded MCP tool: {tool_name}" + (" (with schema desc)" if tool_suffix else ""))
 
                 logger.info(f"Loaded {len(mcp_tools_dict)} tools from MCP server: {server_id} (in-process)")