Tool Lifecycle

Your MCP Server (GitHub, Slack, etc.)
        ↓
Sends: MCP_INIT message with tool list
        ↓
Agent-CoreX receives:
{
  "tools": [
    {
      "name": "create-pull-request",
      "description": "Create a new PR on GitHub",
      "inputSchema": { ... }
    },
    {
      "name": "list-issues",
      "description": "List issues in a repository",
      "inputSchema": { ... }
    }
  ]
}
        ↓
Validation:
- Tool names are unique
- Schemas are valid JSON Schema
- Required fields present
        ↓
Status: ✅ Registered & Ready

{
  "name": "string",                    // Required: unique identifier
  "description": "string",             // Required: human-readable description
  "inputSchema": {                     // Required: JSON Schema
    "type": "object",
    "properties": { ... },
    "required": [...]
  }
}

{
  "name": "create-pull-request",
  "description": "Create a new pull request on GitHub. Requires repository name, branch names, and PR details.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "repository": {
        "type": "string",
        "description": "Repository in owner/repo format"
      },
      "title": {
        "type": "string",
        "description": "PR title"
      },
      "from_branch": {
        "type": "string",
        "description": "Source branch"
      },
      "to_branch": {
        "type": "string",
        "description": "Target branch (usually main)"
      }
    },
    "required": ["repository", "title", "from_branch", "to_branch"]
  }
}

Raw Tool Data
        ↓
1. Parse & Validate
   - Extract metadata
   - Validate schemas
   - Check for duplicates
        ↓
2. Generate Embeddings
   - Embed tool name (20% weight)
   - Embed description (60% weight)
   - Embed parameter names (20% weight)
   - Store multi-dimensional vectors
        ↓
3. Store in Vector DB
   - Qdrant or similar vector database
   - Index by tool name (exact match)
   - Index by vector (semantic match)
   - Add metadata for filtering
        ↓
4. Cache Layer
   - Hot tools cached in memory
   - Popular servers cached
   - TTL: 1 hour
        ↓
Status: ✅ Indexed & Searchable

Tool: create-pull-request

Vectors:
- name_vector: [0.12, 0.45, ..., 0.89]    (20 dim)
- desc_vector: [0.34, 0.22, ..., 0.71]    (384 dim)
- param_vector: [0.56, 0.88, ..., 0.33]   (128 dim)

Metadata:
- server: "github-mcp"
- category: "version-control"
- popularity: 0.92
- tags: ["github", "git", "pr", "automation"]

Agent Query: "Create a GitHub pull request"
        ↓
Step 1: Query Preprocessing
- Normalize text (lowercase, remove punctuation)
- Tokenize: ["create", "github", "pull", "request"]
- Extract entities: intent=create, target=github/pr
        ↓
Step 2: Vector Embedding
- Convert query to vector (same model as tools)
- Produce 384-dimensional vector
        ↓
Step 3: Semantic Search
- Query vector DB for similar tools
- Return top 50 candidates by cosine similarity
- Candidates: [
    {score: 0.97, name: "create-pull-request"},
    {score: 0.91, name: "create-github-issue"},
    {score: 0.88, name: "fork-repository"},
    ...
  ]
        ↓
Step 4: Re-Ranking
- Apply ranking algorithm (next section)
- Filter by user permissions
- Apply contextual boosts
        ↓
Step 5: Return Top-K
- Default K=5, user can request up to 50
- Return tool metadata + scores
        ↓
Agent receives: [
  {name: "create-pull-request", score: 0.98},
  {name: "create-github-issue", score: 0.91},
  ...
]

Tool List from Discovery:
[
  {name: "create-pull-request", score: 0.98},
  {name: "deploy-pr-preview", score: 0.89}
]
        ↓
Agent Decision:
"I want to use create-pull-request with these params:
{
  repository: 'owner/repo',
  title: 'New feature',
  from_branch: 'feature/x',
  to_branch: 'main'
}"
        ↓
Validation:
- Tool exists? ✅
- Params match schema? ✅
- User has permission? ✅
- Rate limit OK? ✅
        ↓
Routing:
- Look up tool's MCP server (GitHub MCP)
- Get credentials for server (decrypted from vault)
- Prepare MCP call
        ↓
Execution:
MCP_CALL {
  method: "tools/call",
  params: {
    name: "create-pull-request",
    arguments: { /* params */ }
  }
}
        ↓
GitHub API Call:
POST /repos/owner/repo/pulls
{
  "title": "New feature",
  "head": "feature/x",
  "base": "main"
}
        ↓
Result:
{
  "success": true,
  "pull_request": {
    "id": 123,
    "url": "https://github.com/owner/repo/pull/123"
  }
}
        ↓
Return to Agent:
{
  "status": "success",
  "output": { /* result */ }
}

// Execute multiple tools in parallel
const results = await Promise.all([
  agent.executeTool({
    toolName: "create-pull-request",
    params: { /* ... */ }
  }),
  agent.executeTool({
    toolName: "send-slack-message",
    params: { /* ... */ }
  }),
  agent.executeTool({
    toolName: "create-jira-issue",
    params: { /* ... */ }
  })
]);

// All three tools run simultaneously
// Results aggregated and returned

Event: Tool Executed
{
  "tool_name": "create-pull-request",
  "server": "github-mcp",
  "user_id": "user_123",
  "timestamp": "2024-01-15T10:30:00Z",
  "duration_ms": 245,
  "status": "success",
  "input_tokens": 150,
  "output_tokens": 200,
  "error": null
}

┌────────────────────────┐
│ Tool Usage Data        │
│ (Collected Daily)      │
└─────────────┬──────────┘
              │
┌─────────────▼──────────┐
│ Analyze Patterns       │
│ - Which tools work?    │
│ - User preferences     │
│ - Error rates          │
└─────────────┬──────────┘
              │
┌─────────────▼──────────────┐
│ Update Ranking Weights     │
│ - Popularity: +2% if used  │
│ - Reliability: -5% if error│
│ - User history: +10% reuse │
└─────────────┬──────────────┘
              │
┌─────────────▼──────────────┐
│ Next Query Benefits        │
│ - Tools ranked better      │
│ - Personalized results     │
│ - Less failures            │
└────────────────────────────┘

Day 1:
- Query: "Deploy to production"
- Result: [terraform, ansible, docker]
- User picks: terraform (success!)

Day 2:
- Query: "Deploy to production"
- Result: [terraform, docker, ansible]
  ↑ terraform moved higher (user used it)

Day 3-7:
- User uses terraform 5 more times
- terraform moves to top position consistently
- Other tools deprioritized for this user

Result: Faster, more relevant results over time

Time: 0s (Tool Added)
├─ MCP server registers tool
├─ Tool stored in database
└─ Status: Waiting for indexing

Time: 5s
├─ Tool metadata extracted
├─ Vectors generated
├─ Added to vector index
└─ Status: Discoverable

Time: 10s-∞
├─ First query uses tool
├─ Metrics collected
├─ Ranking weights updated
├─ Cached for hot access
└─ Status: Optimized

Time: ∞ (Tool Deprecated)
├─ Tool usage drops
├─ Ranking weight decreases
├─ Still available but lower score
└─ Status: Available but not recommended

// ❌ Bad
"name": "pr",
"description": "Make a PR"

// ✅ Good
"name": "create-pull-request",
"description": "Create a new pull request on GitHub. Specify source and target branches, title, and optional description. Requires GitHub authentication."

// ❌ Bad
"inputSchema": {
  "type": "object"
}

// ✅ Good
"inputSchema": {
  "type": "object",
  "properties": {
    "repository": {
      "type": "string",
      "description": "Repository in 'owner/repo' format"
    },
    "title": {
      "type": "string",
      "description": "PR title (1-200 characters)"
    },
    "from_branch": { /* ... */ },
    "to_branch": { /* ... */ }
  },
  "required": ["repository", "title", "from_branch", "to_branch"]
}

Target Performance Targets:
├─ P50: <500ms
├─ P99: <2000ms
├─ Error Rate: <1%
├─ Uptime: 99.9%+
└─ Success Rate: >95%