create-builtin-tool

name	create-builtin-tool
description	Guide for creating builtin MCP tools in LibrAgent. Use when creating a new builtin MCP server, adding tools to existing builtin servers, refactoring tool implementations to follow best practices, or auditing tool compliance with the Tool Design Manifesto v2.1.

Create Builtin MCP Tool Skill

When to Use This Skill

Use this skill when:

• Creating a new builtin MCP server for LibrAgent
• Adding tools to existing builtin servers
• Refactoring tool implementations to follow best practices
• Auditing tool compliance with the Tool Design Manifesto v2.1

Prerequisites: Understanding of Rust async/await, Tauri backend architecture, and MCP protocol basics.

---

Architecture Overview

3-Layer Architecture

┌─────────────────────────────────────────────────────────┐
│  React Frontend (src/lib/backend/, src/features/)       │
│  - TypeScript API wrappers (builtin-tools.ts)           │
│  - UI components (BuiltInToolsEditor.tsx)               │
└────────────────┬────────────────────────────────────────┘
                 │ Tauri Commands (invoke)
┌────────────────▼────────────────────────────────────────┐
│  Proxy Layer (src-tauri/src/mcp/service_proxy_manager/) │
│  - MCPServiceProxyManager (session routing)             │
│  - MCPServiceProxy (per-session instances)              │
└────────────────┬────────────────────────────────────────┘
                 │ BuiltinMCPServer trait
┌────────────────▼────────────────────────────────────────┐
│  Rust Backend (src-tauri/src/mcp/builtin/)              │
│  - Tool definitions (tools/*.rs)                        │
│  - Tool handlers (handlers/*.rs, mod.rs)                │
│  - Business logic (*.rs modules)                        │
└─────────────────────────────────────────────────────────┘

---

Step-by-Step Implementation Guide

Step 1: Create Server Module Structure

src-tauri/src/mcp/builtin/
└── your_server/
    ├── mod.rs              # Server struct + BuiltinMCPServer impl
    ├── tools.rs            # Tool schema definitions
    ├── handlers.rs         # Tool execution handlers
    └── types.rs            # Domain-specific types (optional)

Step 2: Define the Server Struct

File: src-tauri/src/mcp/builtin/your_server/mod.rs

use async_trait::async_trait;
use serde_json::{json, Value};
use std::sync::Arc;

use super::BuiltinMCPServer;
use crate::mcp::types::{MCPResult, ServiceContext};
use crate::mcp::MCPTool;

pub mod handlers;
pub mod tools;

/// Your server description
/// Explain its purpose and capabilities
#[derive(Debug)]
pub struct YourServer {
    pub(crate) session_id: String,
    // Add dependencies (e.g., database, managers)
    // Example: db: Arc<DatabaseConnection>,
}

impl YourServer {
    pub fn new(session_id: String /* , dependencies */) -> Self {
        Self {
            session_id,
            // Initialize dependencies
        }
    }

    /// Static tool definitions (called during registry initialization)
    pub fn tools_static() -> Vec<MCPTool> {
        vec![
            tools::create_your_tool(),
            // Add more tools
        ]
    }

    /// Static metadata for UI
    pub fn metadata_static() -> crate::mcp::types::BuiltinServerMetadata {
        crate::mcp::types::BuiltinServerMetadata {
            display_name: "Your Server".to_string(),
            description: "Brief description for UI".to_string(),
            icon: None,
        }
    }
}

Step 3: Implement BuiltinMCPServer Trait

Critical: declare pub const NAME as the single source of truth for the server name. This constant is referenced by both fn name() and the regression tests in agent/tools.rs. A typo in a string literal would compile silently; a typo here breaks the build immediately.

/// Canonical server name – must exactly match the entry in BUILTIN_SERVICE_REGISTRY.
pub const NAME: &str = "your_server"; // lowercase_snake_case, no spaces

#[async_trait]
impl BuiltinMCPServer for YourServer {
    fn name(&self) -> &str {
        NAME // ← reference the const, never a raw string literal
    }

    fn description(&self) -> &str {
        "Detailed description of server capabilities"
    }

    fn display_name(&self) -> String {
        "Your Server".to_string()
    }

    fn tools(&self) -> Vec<MCPTool> {
        Self::tools_static()
    }

    async fn get_service_context(&self, options: Option<&Value>) -> ServiceContext {
        // Extract session_id if provided in options
        let session_id = if let Some(opts) = options {
            opts.get("session_id")
                .and_then(|v| v.as_str())
                .unwrap_or(&self.session_id)
                .to_string()
        } else {
            self.session_id.clone()
        };

        // Build context prompt for AI (what the agent SEES)
        // ✅ RULE 7: Echo recent changes with context
        let context_prompt = format!(
            "## Your Server

**Session**: {}
**Status**: Active

**Recent Activity**:
- Resource 'A' created (ID: 123)
- Resource 'B' updated: 'Refactoring login flow' (ID: 456)

**Available Features**: Feature A, Feature B

💡 Use listYourResources() to see available items.",
            session_id
        );

        // Build structured state for UI (what the agent DOESN'T see)
        ServiceContext {
            context_prompt,
            structured_state: Some(json!({
                "session_id": session_id,
                "server_type": "your_server",
                "initialized": true
            })),
        }
    }

    async fn call_tool(
        &self,
        tool_name: &str,
        args: Value,
        session_id: Option<String>,
    ) -> Result<MCPResult, String> {
        match tool_name {
            "yourTool" => handlers::handle_your_tool(self, args, session_id).await,
            "listResources" => handlers::handle_list_resources(self, args, session_id).await,
            _ => Err(format!("Tool '{}' not found", tool_name)),
        }
    }
}

Step 4: Define Tool Schemas (Following Manifesto Rules)

Critical rule for tool docs:

• input_schema property descriptions are the single source of truth for parameter semantics.
• Tool description should focus on purpose, prerequisites, workflow, and next actions.
• Do not add PARAMETERS: blocks in tool description when the same details already exist in schema.

Parameter ordering (LLM generation):

• Use SchemaProperties / props.insert() order deliberately — it is preserved through Rust serialization and the frontend tool pipeline.
• Insert fields as: identifiers → enums/flags → small scalars → structured arrays/objects → large text blobs last (e.g. path, mode, content for writeFile).
• Models often emit tool arguments in schema order; putting large content fields first makes later enums/paths easier to omit.

File: src-tauri/src/mcp/builtin/your_server/tools.rs

use crate::mcp::{utils::schema_builder::*, MCPTool};
use serde_json::json;
use std::collections::HashMap;

/// ✅ CREATE TOOL: No ID parameter (Rule 1: Immutable ID Rule)
pub fn create_your_resource_tool() -> MCPTool {
    let mut props = HashMap::new();

    // ❌ NEVER include "id" field in create tools
    props.insert(
        "name".to_string(),
        string_prop(
            Some(1),
            Some(100),
            Some("Resource name (required)")
        ),
    );

    props.insert(
        "description".to_string(),
        string_prop(
            None,
            Some(500),
            Some("Resource description (optional)")
        ),
    );

    MCPTool {
        name: "createResource".to_string(),
        title: Some("Create Resource".to_string()),
        description: "Create a new resource in the system.

⚠️ WORKFLOW:
1. System generates unique ID automatically
2. Returns ID in response for future operations
3. Use listResources() to verify creation

RESPONSE:
- Created resource with system-generated ID
- Use returned ID for updateResource() or deleteResource()

💡 NEXT STEPS: Use getResource(id) to verify or updateResource(id) to modify"
            .to_string(),
        input_schema: object_schema(props, vec!["name".to_string()]),
        output_schema: None,
        annotations: None,
    }
}

/// ✅ UPDATE/DELETE TOOLS: ID is required (Rule 1)
pub fn create_update_resource_tool() -> MCPTool {
    let mut props = HashMap::new();

    // ✅ ID is REQUIRED for updates
    props.insert(
        "id".to_string(),
        string_prop(
            Some(1),
            Some(50),
            Some("Resource ID (from createResource or listResources)")
        ),
    );

    props.insert(
        "name".to_string(),
        string_prop(
            Some(1),
            Some(100),
            Some("New resource name")
        ),
    );

    // ✅ RULE 6: Memory-Augmented Mutation
    props.insert(
        "summary".to_string(),
        string_prop(
            None,
            Some(200),
            Some("Optional context: why this change is being made (e.g., 'Refactoring X', 'Fixing bug Y')")
        ),
    );

    MCPTool {
        name: "updateResource".to_string(),
        title: Some("Update Resource".to_string()),
        description: "Update an existing resource.

⚠️ PREREQUISITE: Obtain valid ID from:
- createResource() response
- listResources() output

ERROR HANDLING:
- If ID not found, returns error with suggestion to use listResources()

💡 WORKFLOW:
1. Call listResources() to find the resource
2. Extract the 'id' field from the result
3. Pass exact ID to this tool"
            .to_string(),
        input_schema: object_schema(props, vec!["id".to_string(), "name".to_string()]),
        output_schema: None,
        annotations: None,
    }
}

/// ✅ LIST TOOL: Returns IDs in BOTH text and structured content
pub fn create_list_resources_tool() -> MCPTool {
    let props = HashMap::new();  // No parameters needed

    MCPTool {
        name: "listResources".to_string(),
        title: Some("List Resources".to_string()),
        description: "List all available resources with their IDs.

RETURNS:
- Complete list of resources with IDs and details
- Use returned IDs for updateResource() or deleteResource()

OUTPUT FORMAT (text):
Each resource shows: ID | Name | Status

💡 Use getResource(id) to see full details of a specific resource"
            .to_string(),
        input_schema: object_schema(props, vec![]),
        output_schema: None,
        annotations: None,
    }
}

Step 5: Implement Tool Handlers (Following Manifesto Rules)

File: src-tauri/src/mcp/builtin/your_server/handlers.rs

use super::YourServer;
use crate::mcp::builtin::error_guidance::{operation_failed_error, ToolGroup};
use crate::mcp::types::{text, MCPContent, MCPResult};
use crate::mcp::utils::success_hint::SuccessHint;
use serde::{Deserialize, Serialize};
use serde_json::{json, Value};

#[derive(Debug, Deserialize)]
#[serde(rename_all = "camelCase")]
struct CreateResourceArgs {
    name: String,
    description: Option<String>,
}

#[derive(Debug, Deserialize)]
#[serde(rename_all = "camelCase")]
struct UpdateResourceArgs {
    id: String,  // ✅ Required for updates
    name: String,
    summary: Option<String>, // ✅ Rule 6
}

/// ✅ CREATE HANDLER: Generates ID, returns it in BOTH channels (Rule 3)
pub async fn handle_create_resource(
    server: &YourServer,
    args: Value,
    _session_id: Option<String>,
) -> Result<MCPResult, String> {
    let args: CreateResourceArgs = serde_json::from_value(args)
        .map_err(|e| format!("Invalid arguments: {}", e))?;

    // ✅ SYSTEM GENERATES ID (Rule 1: Immutable ID Rule)
    let resource_id = generate_id();  // Use UUID, CUID, or domain-specific format

    // TODO: Insert into database
    // db.resources.insert(Resource {
    //     id: resource_id.clone(),
    //     name: args.name.clone(),
    //     description: args.description.clone(),
    //     session_id: server.session_id.clone(),
    // }).await?;

    // ✅ DUAL-CHANNEL RESPONSE (Rule 3)
    // Channel 1: TEXT (What the AI SEES)
    let result_text = format!(
        "Resource created successfully (ID: {}).\n\n\
         Name: {}\n\
         Description: {}\n\n\
         💡 NEXT STEPS:\n\
         - Use getResource(\"{}\") to view details\n\
         - Use updateResource(\"{}\", ...) to modify\n\
         - Use listResources() to see all resources",
        resource_id,  // ✅ ID IN TEXT for AI to read
        args.name,
        args.description.as_deref().unwrap_or("None"),
        resource_id,
        resource_id
    );

    // Channel 2: STRUCTURED CONTENT (What the UI sees, AI DOESN'T)
    let structured_data = json!({
        "resource_id": resource_id,  // For UI parsing/rendering
        "name": args.name,
        "description": args.description,
        "created_at": chrono::Utc::now().to_rfc3339()
    });

    Ok(MCPResult {
        content: vec![text(result_text)],
        structured_content: Some(structured_data),
        is_error: Some(false),
    })
}

/// ✅ UPDATE HANDLER: Validates ID existence FIRST (Rule 2: Hallucination Firewall)
pub async fn handle_update_resource(
    server: &YourServer,
    args: Value,
    _session_id: Option<String>,
) -> Result<MCPResult, String> {
    let args: UpdateResourceArgs = serde_json::from_value(args)
        .map_err(|e| format!("Invalid arguments: {}", e))?;

    // ✅ HALLUCINATION FIREWALL (Rule 2)
    // Check existence BEFORE attempting database write
    // let exists = db.resources.exists(&args.id).await
    //     .map_err(|e| format!("Database error: {}", e))?;

    let exists = false;  // TODO: Replace with actual DB check

    if !exists {
        // ✅ SUCCESS HINT PATTERN (Rule 5)
        return Ok(operation_failed_error(
            "Update Resource",
            &format!("Resource '{}' not found", args.id),
            vec![
                "Use listResources() to find the correct resource ID".to_string(),
                "IDs are case-sensitive and must match exactly".to_string(),
                format!("You provided: '{}'", args.id)
            ],
            ToolGroup::YourServer  // Replace with actual group
        ));
    }

    // Proceed with update only after validation passes
    // db.resources.update(&args.id, UpdateData {
    //     name: args.name.clone(),
    // }).await?;

    // ✅ RULE 7: State Echo
    // If a summary was provided, echo it back so the agent knows it was recorded
    let summary_echo = args.summary.as_deref().unwrap_or("No summary provided");

    let result_text = format!(
        "Resource updated successfully (ID: {}).\n\n\
         New name: {}\n\
         Context: {}\n\n\
         💡 Use getResource(\"{}\") to view updated details",
        args.id,
        args.name,
        summary_echo,
        args.id
    );

    Ok(SuccessHint::new(
        result_text,
        vec![format!("Use getResource(\"{}\") to verify changes", args.id)]
    ).to_mcp_result_with_data(Some(json!({
        "resource_id": args.id,
        "updated_fields": ["name"],
        "timestamp": chrono::Utc::now().to_rfc3339()
    }))))
}

/// ✅ LIST HANDLER: Shows IDs in text for AI to read (Rule 3)
pub async fn handle_list_resources(
    server: &YourServer,
    _args: Value,
    _session_id: Option<String>,
) -> Result<MCPResult, String> {
    // TODO: Fetch from database
    // let resources = db.resources.list(&server.session_id).await?;

    // Mock data for example
    let resources = vec![
        ("res_abc123", "Example Resource 1", "Active"),
        ("res_def456", "Example Resource 2", "Inactive"),
    ];

    // ✅ IDs VISIBLE IN TEXT (Rule 3: Dual-Channel Response)
    let resource_list = resources.iter()
        .map(|(id, name, status)| format!("  • {} | {} | {}", id, name, status))
        .collect::<Vec<_>>()
        .join("\n");

    let result_text = format!(
        "Found {} resource(s):\n\n{}\n\n\
         💡 NEXT STEPS:\n\
         - Use getResource(id) for full details\n\
         - Use updateResource(id, ...) to modify\n\
         - Use deleteResource(id) to remove",
        resources.len(),
        resource_list
    );

    // Structured data for UI table rendering
    let structured_data = json!({
        "resources": resources.iter().map(|(id, name, status)| json!({
            "id": id,
            "name": name,
            "status": status
        })).collect::<Vec<_>>(),
        "total": resources.len()
    });

    Ok(MCPResult {
        content: vec![text(result_text)],
        structured_content: Some(structured_data),
        is_error: Some(false),
    })
}

// Helper: Generate unique ID
fn generate_id() -> String {
    use rand::Rng;
    let mut rng = rand::thread_rng();
    format!("res_{:x}", rng.gen::<u32>())
    // Or use: uuid::Uuid::new_v4().to_string()
    // Or use: crate::utils::generate_short_id()
}

Step 6: Register Server in Global Registry

Registration requires three coordinated edits. Miss any one and the regression tests will fail immediately.

6a. Module declaration — src-tauri/src/mcp/builtin/mod.rs

pub mod your_server; // Add this line

6b. Service registry — src-tauri/src/agent/tools.rs

This is the single source of truth for every service canonical name.

pub(crate) const BUILTIN_SERVICE_REGISTRY: &[BuiltinServiceEntry] = &[
    // ... existing entries ...
    BuiltinServiceEntry { canonical: "your_server", optional: false },
    //                                ^^^^^^^^^^^^
    //                                Must exactly match your_server::NAME
];

Set optional: true if the service should only be enabled when the agent config explicitly lists it (e.g. browser, bootstrap). Core services use false.

6c. Regression test list — src-tauri/src/agent/tools.rs (tests module)

fn each_builtin_server_name_is_in_registry() {
    use crate::mcp::builtin;
    let all_names: &[&str] = &[
        // ... existing entries ...
        builtin::your_server::NAME, // ← add this
    ];
    // ...
}
// Also add to: builtin_server_names_are_unique, registry_and_server_list_are_in_sync

All four regression tests share the same all_names pattern. Update each one.

6d. Session instantiation — src-tauri/src/mcp/builtin/mod.rs

impl BuiltinServerRegistry {
    pub fn new_session_instance(
        &self,
        server_id: &str,
        session_id: String,
    ) -> Option<Arc<dyn BuiltinMCPServer>> {
        match server_id {
            // ... existing servers
            "your_server" => Some(Arc::new(YourServer::new(session_id))),
            _ => None,
        }
    }
}

Why three places? mod.rs wires the module into the build; BUILTIN_SERVICE_REGISTRY drives runtime routing and alias resolution; the regression test list enforces that every registered canonical has a concrete server NAME backing it — and vice-versa.

Step 7: Add Integration Tests

File: src-tauri/src/mcp/builtin/your_server/mod.rs

#[cfg(test)]
mod tests {
    use super::*;

    #[tokio::test]
    async fn test_create_resource_generates_id() {
        let server = YourServer::new("test_session".to_string());

        let args = json!({
            "name": "Test Resource",
            "description": "Test description"
        });

        let result = handlers::handle_create_resource(&server, args, None).await.unwrap();

        // ✅ Verify ID is in text content (Rule 3)
        let text_content = result.content.iter()
            .find_map(|c| match c {
                MCPContent::Text { text } => Some(text.as_str()),
                _ => None
            })
            .expect("Expected text content");

        assert!(text_content.contains("ID:"), "ID must be in text for AI");
        assert!(text_content.contains("res_"), "ID must be visible in output");

        // ✅ Verify ID is also in structured content (for UI)
        assert!(result.structured_content.is_some());
        let data = result.structured_content.unwrap();
        assert!(data.get("resource_id").is_some(), "ID must be in structured data");
    }

    #[tokio::test]
    async fn test_update_validates_id_existence() {
        let server = YourServer::new("test_session".to_string());

        let args = json!({
            "id": "nonexistent_id",
            "name": "Updated Name"
        });

        let result = handlers::handle_update_resource(&server, args, None).await.unwrap();

        // ✅ Verify hallucination firewall (Rule 2)
        assert_eq!(result.is_error, Some(true), "Should return error for invalid ID");

        let text_content = result.content.iter()
            .find_map(|c| match c {
                MCPContent::Text { text } => Some(text.as_str()),
                _ => None
            })
            .unwrap();

        // ✅ Verify success hint pattern (Rule 5)
        assert!(text_content.contains("listResources"), "Error should suggest recovery tool");
    }

    #[test]
    fn test_tools_have_no_id_in_create_schema() {
        let tools = YourServer::tools_static();
        let create_tool = tools.iter()
            .find(|t| t.name.starts_with("create"))
            .expect("Should have create tool");

        // ✅ Verify Rule 1: Immutable ID Rule
        let props = &create_tool.input_schema.properties;
        assert!(!props.contains_key("id"), "Create tool must NOT have ID parameter");
    }
}

---

Design Manifesto Compliance Checklist

Use this checklist before submitting any builtin tool implementation:

Rule 1: The Immutable ID Rule ✅

• CREATE tools have NO id parameter in schema
• UPDATE/DELETE tools have REQUIRED id parameter
• System generates IDs using UUID/CUID/domain format
• Generated IDs are returned in tool responses

Rule 2: The Hallucination Firewall ✅

• All UPDATE/DELETE handlers validate ID existence FIRST
• Validation happens BEFORE any database write
• Invalid IDs return structured errors (not raw DB errors)
• Error messages suggest recovery tools (Rule 5)

Rule 3: The Dual-Channel Response Rule ✅

• Critical IDs are in TEXT content (AI can read them)
• Text content is complete narrative (what happened, IDs, status)
• Structured content is in JSON (for UI rendering)
• AI-visible content is self-sufficient (no dependency on JSON)

Rule 4: AI-Native Descriptions ✅

• Tool descriptions use data-oriented language (extract, use, target)
• No human UI actions (click, type, enter, copy)
• Parameter semantics are documented only in input_schema field descriptions
• Tool descriptions do not duplicate schema parameter docs (no PARAMETERS: blocks)
• Prerequisites explicitly documented
• Workflow steps numbered and clear
• Examples show expected patterns

Rule 5: The Success Hint Pattern ✅

• All errors include recovery suggestions
• Suggestions reference tools from same server
• Error format: "❌ Problem. 💡 Use toolName() to fix"
• No raw "Not Found" errors without context

Rule 6: Memory-Augmented Mutation Rule (New) ✅

• All state-changing tools (UPDATE/DELETE/COMPLETE) have optional summary or reason parameter
• This parameter allows agent to Explain Why/How
• Stored alongside the data change (not discarded)

Rule 7: The State Echo Rule (New) ✅

• Agent-provided summaries are echoed back in get_service_context
• Echoed summaries are truncated if too long (e.g., >50 chars)
• Context prompt prioritizes recent state changes + reasons

Rule 8: Outcome-Conditioned Augmentation ✅

• Next-action hints depend on post-call outcome class (not a fixed always-on template)
• Steady successes stay lean when context already enables the next step
• Phase-boundary successes escalate once to an in-domain consolidating/review action
• Repeated/identical failures escalate to diagnosis or strategy-reset (no identical retry loop)
• Escalation is gated by state — not confused with unconditional hint spam

---

Common Pitfalls to Avoid

❌ Pitfall 1: Hidden IDs (Rule 3 Violation)

// ❌ WRONG: ID only in structured_content
let result_text = "Resource created successfully.";
let data = json!({ "id": resource_id });  // AI can't see this!

// ✅ CORRECT: ID in BOTH channels
let result_text = format!(
    "Resource created (ID: {}).\n\nUse getResource(\"{}\") to view",
    resource_id, resource_id
);
let data = json!({ "id": resource_id });

❌ Pitfall 2: Trusting Agent IDs (Rule 2 Violation)

// ❌ WRONG: Direct database access
db.resources.update(&args.id, data).await?;

// ✅ CORRECT: Validate first
if !db.resources.exists(&args.id).await? {
    return Ok(operation_failed_error(...));
}
db.resources.update(&args.id, data).await?;

❌ Pitfall 3: Human-Centric Language (Rule 4 Violation)

// ❌ WRONG: UI-oriented description
description: "Click the resource to select it, then copy the ID"

// ✅ CORRECT: AI-oriented description
description: "Extract resource ID from listResources() output for subsequent operations"

❌ Pitfall 4: Dead-End Errors (Rule 5 Violation)

// ❌ WRONG: No recovery path
Err(format!("Resource '{}' not found", id))

// ✅ CORRECT: With recovery hints
Ok(operation_failed_error(
    "Get Resource",
    &format!("Resource '{}' not found", id),
    vec!["Use listResources() to see available IDs".to_string()],
    ToolGroup::YourServer
))

❌ Pitfall 5: Duplicated Parameter Docs (Schema Drift Risk)

// ❌ WRONG: Parameters documented in both schema and description
description: "Update resource.\n\nPARAMETERS:\n- id: Resource ID\n- name: New name"

// ✅ CORRECT: Keep parameter details in schema only
props.insert("id".to_string(), string_prop(Some(1), Some(50), Some("Resource ID")));
props.insert("name".to_string(), string_prop(Some(1), Some(100), Some("New resource name")));

description: "Update an existing resource.\n\nPREREQUISITE: get valid ID from listResources()."

❌ Pitfall 6: Fixed Follow-Up Spam (Rule 8 Violation)

// ❌ WRONG: Same next-action on every success, even when context already has the data
SuccessHint::new(message, vec!["Use listItems() to see the list".to_string()])

// ❌ WRONG: Identical recovery forever after N matching failures
vec!["Retry with corrected parameters".to_string()]

// ✅ CORRECT: Condition on outcome class
match classify_outcome(&before, &after, &error_history) {
    Outcome::Steady => SuccessHint::new(message, vec![]),
    Outcome::PhaseBoundary => SuccessHint::new(
        message,
        vec!["Milestone reached — run the in-domain review/consolidate action.".to_string()],
    ),
    Outcome::RepeatedFailure => guided_error(...).with_guidance(vec![
        "Same failure repeated — stop retrying; diagnose root cause or reset strategy.".to_string(),
    ]),
}

---

🚫 Critical Anti-Patterns

Check for these subtle design flaws that cripple agent reasoning:

1. The "State Amnesia" Pattern

• Symptom: Agent completes a task but loses the reason context.
• Example: completeTask(id) (No summary)
• Result: Agent forgets how it solved the problem. If user asks "How did we fix X?", the agent has to search chat history or Hallucinate.
• Fix: Always include optional summary, reason, or context parameters in state-changing tools (Rule 6).

2. The "Implementation Gap"

• Symptom: Tool design docs specify rich parameters, but implementation omits them as "optional/skippable".
• Example: Design says checkTodo(id, summary), code implements checkTodo(id).
• Result: Agent tries to use the planned feature but fails silently or gives poor data.
• Fix: Treat the Tool Schema as a binding contract. Optional parameters are functional requirements for AI reasoning.

3. The "Blind Alley" Response

• Symptom: Tool returns void or generic "Success".
• Result: Agent is left in a void, unsure if the action persisted.
• Fix: Dual-channel response with IDs and status in text (Rule 3). Always return an "Echo" of the new state (Rule 7).

4. The "Retry Treadmill" Pattern

• Symptom: Every failure returns the same "retry with X" hint; every success promotes the same sibling tool.
• Result: Agent loops at the same abstraction level instead of consolidating wins or resetting strategy after stuck failures.
• Fix: Outcome-conditioned augmentation (Rule 8) — lean on steady progress, escalate at phase boundaries, escalate on repeated identical failures.

---

Code Templates

Template: Error Response with Hints

use crate::mcp::builtin::error_guidance::{operation_failed_error, ToolGroup};

return Ok(operation_failed_error(
    "Operation Name",
    "Specific error description",
    vec![
        "Use suggestedTool() to find correct value".to_string(),
        "Additional context or constraint".to_string(),
    ],
    ToolGroup::YourServer
));

Template: Success Response with Dual Channels

use crate::mcp::utils::success_hint::SuccessHint;

let result_text = format!(
    "Operation completed (ID: {}).\n\n\
     Details: {}\n\n\
     💡 Use nextTool(\"{}\") to continue workflow",
    generated_id, details, generated_id
);

Ok(SuccessHint::new(
    result_text,
    vec![format!("Use verifyTool(\"{}\") to check status", generated_id)]
).to_mcp_result_with_data(Some(json!({
    "id": generated_id,
    "metadata": additional_data
}))))

Template: ID Generation

// Option 1: Short readable IDs
fn generate_id() -> String {
    use rand::Rng;
    let mut rng = rand::thread_rng();
    format!("prefix_{:x}", rng.gen::<u32>())
}

// Option 2: UUID (standard)
fn generate_id() -> String {
    uuid::Uuid::new_v4().to_string()
}

// Option 3: CUID (collision-resistant)
fn generate_id() -> String {
    use crate::utils::generate_short_id;
    generate_short_id()
}

---

Testing Strategy

Unit Tests (Per Tool)

#[tokio::test]
async fn test_create_tool_dual_channel_response() {
    let result = handlers::handle_create(...).await.unwrap();

    // Test text content has ID
    let text = extract_text(&result);
    assert!(text.contains("ID:"), "Must show ID in text");

    // Test structured content has ID
    let data = result.structured_content.unwrap();
    assert!(data.get("id").is_some(), "Must have ID in JSON");
}

#[tokio::test]
async fn test_update_tool_hallucination_firewall() {
    let result = handlers::handle_update(invalid_id_args).await.unwrap();

    assert_eq!(result.is_error, Some(true));
    let text = extract_text(&result);
    assert!(text.contains("listResources"), "Must suggest recovery");
}

Integration Tests (Full Workflow)

#[tokio::test]
async fn test_create_update_delete_workflow() {
    let server = YourServer::new("test_session".to_string());

    // 1. Create resource
    let create_result = server.call_tool(
        "createResource",
        json!({"name": "Test"}),
        None
    ).await.unwrap();

    // 2. Extract ID from text (simulate agent reading)
    let id = extract_id_from_text(&create_result);

    // 3. Update with extracted ID
    let update_result = server.call_tool(
        "updateResource",
        json!({"id": id, "name": "Updated"}),
        None
    ).await.unwrap();

    assert_eq!(update_result.is_error, Some(false));
}

---

Frontend Integration

After implementing the Rust backend, add TypeScript wrappers:

File: src/lib/backend/your-server-api.ts

import { safeInvoke } from './core';
import type { MCPResponse } from '@/lib/mcp';

export async function createYourResource(
  serverName: string,
  name: string,
  description?: string,
): Promise<MCPResponse<unknown>> {
  return safeInvoke('call_builtin_tool', {
    serverName,
    toolName: 'createResource',
    arguments: { name, description },
  });
}

export async function listYourResources(
  serverName: string,
): Promise<MCPResponse<unknown>> {
  return safeInvoke('call_builtin_tool', {
    serverName,
    toolName: 'listResources',
    arguments: {},
  });
}

---

Summary

Key Principles:

1. No ID inputs for CREATE - System generates, agent receives
2. Validate before writes - Hallucination firewall on all ID-based operations
3. Dual-channel responses - IDs visible in BOTH text (AI) and JSON (UI)
4. AI-native descriptions - Data operations, not UI actions
5. Recovery hints - Every error suggests a path forward

Quality Gates:

• pub const NAME: &str = "your_name"; declared in server module (not an inline literal in fn name())
• fn name(&self) returns NAME (the const), not a raw string
• BuiltinServiceEntry { canonical: "your_name", optional: … } added to BUILTIN_SERVICE_REGISTRY in agent/tools.rs
• builtin::your_server::NAME added to all_names in all three regression test functions in agent/tools.rs
• cargo test registry passes (4/4 registry regression tests green)
• All tests pass (unit + integration)
• Manifesto compliance checklist complete
• Frontend TypeScript wrappers added
• Server registered in builtin registry (mod.rs module decl + session instantiation match arm)
• Documentation includes workflow examples

When in doubt: Look at existing implementations (workspace, planning, knowledge) and follow their patterns for session management, error handling, and response formatting.