Core Concepts Overview

// ❌ Old approach: Tools hardcoded at startup
const agent = new Agent({
  tools: [
    githubTool,
    slackTool,
    jiraTool,
    // Need a new tool? Restart the agent.
  ]
});

// ✅ New approach: Tools retrieved on-demand
const agent = new Agent();

// When the agent needs tools:
const tools = await agent.retrieveTools({
  query: "Deploy to production using Terraform"
});

// Only relevant tools are returned, ranked by relevance
// Context window stays lean, performance stays fast

User/Agent Request:
  "I need to merge a PR and deploy to AWS"
        ↓
Query Processing:
  - Tokenize the request
  - Extract intent (merge PR, deploy)
  - Identify requirements (AWS, deployment)
        ↓
Semantic Search:
  - Convert to embeddings
  - Search tool database
  - Find semantically similar tools
        ↓
Ranking:
  - Score by relevance
  - Consider user history
  - Weight by popularity
        ↓
Result:
  [
    {name: "merge-pull-request", score: 0.98},
    {name: "deploy-aws", score: 0.96},
    {name: "github-deploy-action", score: 0.94}
  ]

┌─────────────────────────────────────────────────────┐
│ PHASE 1: REGISTRATION                              │
│ MCP server registers with Agent-CoreX              │
│ Tools automatically indexed                         │
└──────────────┬──────────────────────────────────────┘
               │
┌──────────────┴──────────────────────────────────────┐
│ PHASE 2: INDEXING                                  │
│ Tool metadata stored in vector database            │
│ Descriptions, parameters, schemas added            │
└──────────────┬──────────────────────────────────────┘
               │
┌──────────────┴──────────────────────────────────────┐
│ PHASE 3: DISCOVERY                                 │
│ Agents search for tools via natural language       │
│ Tools ranked and returned to agent                 │
└──────────────┬──────────────────────────────────────┘
               │
┌──────────────┴──────────────────────────────────────┐
│ PHASE 4: EXECUTION                                 │
│ Agent selects tool and executes via MCP            │
│ Results returned to agent                          │
└──────────────┬──────────────────────────────────────┘
               │
┌──────────────┴──────────────────────────────────────┐
│ PHASE 5: MONITORING                                │
│ Tool usage tracked and metrics collected           │
│ Ranking weights updated based on performance       │
└─────────────────────────────────────────────────────┘

// Simplified ranking formula
score = (
  semantic_match * 0.40 +      // How well does it match the query?
  popularity * 0.25 +          // How popular is this tool?
  user_history * 0.20 +        // Has the user used it before?
  performance * 0.15           // How reliable/fast is it?
)

await agent.retrieveTools({
  query: "Send a message to Slack",
  topK: 3
});

[
  {
    "name": "send-slack-message",
    "server": "slack-mcp",
    "score": 0.99,
    "description": "Send a message to a Slack channel",
    "params": {
      "channel": "string",
      "message": "string"
    }
  },
  {
    "name": "post-thread-reply",
    "server": "slack-mcp",
    "score": 0.94,
    "description": "Reply to a thread in Slack"
  },
  {
    "name": "create-jira-comment",
    "server": "jira-mcp",
    "score": 0.72,
    "description": "Create a comment on a Jira issue"
  }
]

await agent.retrieveTools({
  query: "Deploy my Node.js app to AWS Lambda with environment variables, trigger CI/CD, and notify the team when it's done",
  topK: 5
});

[
  {
    "name": "deploy-to-lambda",
    "score": 0.97,
    "description": "Deploy Node.js app to AWS Lambda"
  },
  {
    "name": "set-lambda-environment",
    "score": 0.96,
    "description": "Configure Lambda environment variables"
  },
  {
    "name": "trigger-github-action",
    "score": 0.95,
    "description": "Trigger GitHub Actions workflow"
  },
  {
    "name": "send-slack-notification",
    "score": 0.93,
    "description": "Send message to Slack channel"
  },
  {
    "name": "create-cloudwatch-alarm",
    "score": 0.87,
    "description": "Create CloudWatch monitoring alarm"
  }
]

await agent.retrieveTools({
  query: "Get me some devops stuff 4 deploying infra"
});

[
  {
    "name": "deploy-terraform",
    "score": 0.91
  },
  {
    "name": "run-ansible-playbook",
    "score": 0.88
  },
  {
    "name": "docker-deploy",
    "score": 0.85
  }
]

1. Retrieval: "What tools do I have?"
   → Get list of 5 tools

2. Selection: Agent picks which tools to use
   → Usually top 1-3 tools

3. Execution: "Run these tools"
   → Actually execute via MCP

4. Results: Integrate results into agent response