> ## Documentation Index > Fetch the complete documentation index at: https://docs.agent-corex.com/llms.txt > Use this file to discover all available pages before exploring further. # Core Concepts Overview > Understand the fundamental concepts behind Agent-CoreX: dynamic retrieval, tool lifecycle, and intelligent ranking. ## Core Concepts Agent-CoreX introduces a new paradigm for AI agent tool selection. Instead of hardcoding tools upfront, agents dynamically discover and request tools based on their current task. This section explains the key concepts. ### The Problem with Static Tools Traditional AI agents follow this pattern: ```javascript theme={null} // ❌ Old approach: Tools hardcoded at startup const agent = new Agent({ tools: [ githubTool, slackTool, jiraTool, // Need a new tool? Restart the agent. ] }); ``` **Issues:** * Inflexible - adding tools requires code changes * Token-wasteful - every tool is in context (even unused ones) * Not scalable - 100 tools? Context explodes. * Not adaptive - can't use the best tool, only available ones ### The Agent-CoreX Solution: Dynamic Retrieval ```javascript theme={null} // ✅ 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 ``` **Benefits:** * ✅ Flexible - any MCP server, anytime * ✅ Token-efficient - only relevant tools in context * ✅ Scalable - handles 100+ tools smoothly * ✅ Adaptive - always gets the best tools for the task *** ## Key Concepts ### 1. Tool Retrieval **Definition:** The process of finding the right tools for a given task using natural language. **How it works:** ``` 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} ] ``` **Key Points:** * Works with ANY natural language query * Doesn't require exact tool names * Returns tools ranked by relevance (0.0 to 1.0) * Configurable top-k results (default: 5) ### 2. Tool Lifecycle Every tool in Agent-CoreX goes through this lifecycle: ``` ┌─────────────────────────────────────────────────────┐ │ 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 │ └─────────────────────────────────────────────────────┘ ``` ### 3. Dynamic vs. Static Tools | Aspect | Static | Dynamic (Agent-CoreX) | | --------------- | ------------------------- | --------------------------- | | **Definition** | Tools defined at startup | Tools discovered at runtime | | **Flexibility** | Limited to pre-configured | Any available tool | | **Token Usage** | All tools in context | Only relevant tools | | **Scalability** | Degrades with tool count | Scales to 100+ tools | | **Maintenance** | Requires code changes | Automatic marketplace | | **Speed** | Instant (all known) | 15-50ms retrieval | ### 4. Ranking & Relevance Agent-CoreX uses a multi-factor ranking algorithm: ```javascript theme={null} // 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? ) ``` **Semantic Matching (40%)** * How similar is the tool description to the query? * Uses vector embeddings for deep semantic understanding * Example: "deploy" matches "deployment", "ship to prod", "release" **Popularity (25%)** * How often is the tool used across all users? * Tools used more often are generally more reliable * Prevents recommending niche/buggy tools **User History (20%)** * Has this user used this tool successfully before? * Preferences are learned and personalized * Example: If you always use "deploy-with-terraform", it gets boosted **Performance (15%)** * Response time metrics * Error rates * Uptime/reliability * Prevents recommending slow or flaky tools *** ## Practical Examples ### Example 1: Simple Query **Request:** ```javascript theme={null} await agent.retrieveTools({ query: "Send a message to Slack", topK: 3 }); ``` **Response:** ```json theme={null} [ { "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" } ] ``` **What happened:** * Query matched "send message" + "Slack" * Most relevant tool scores 0.99 * Less relevant tools (Jira comment) scores lower * User gets ranked list in milliseconds ### Example 2: Complex Query **Request:** ```javascript theme={null} 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 }); ``` **Response:** ```json theme={null} [ { "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" } ] ``` **What happened:** * Query contains multiple concepts: deploy, Lambda, env vars, CI/CD, notify * Agent-CoreX broke down the query semantically * Each tool matched different parts of the request * All tools are ordered by relevance to the overall task ### Example 3: Misspelled or Colloquial Query **Request:** ```javascript theme={null} await agent.retrieveTools({ query: "Get me some devops stuff 4 deploying infra" }); ``` **Response:** ```json theme={null} [ { "name": "deploy-terraform", "score": 0.91 }, { "name": "run-ansible-playbook", "score": 0.88 }, { "name": "docker-deploy", "score": 0.85 } ] ``` **What happened:** * Query is informal and misspelled * Semantic matching still understands intent (DevOps + deployment + infrastructure) * Returns relevant tools despite casual language * This is the power of vector embeddings *** ## Tool Retrieval vs. Tool Execution It's important to understand the distinction: ### Tool Retrieval * **Purpose:** Find available tools * **Input:** Natural language query * **Output:** Ranked list of tool names + metadata * **Timing:** 15-50ms * **No execution** - just discovery ### Tool Execution * **Purpose:** Actually run a tool * **Input:** Tool name + parameters * **Output:** Tool result * **Timing:** 100ms-5s (depends on external API) * **Requires authentication** - credentials for MCP server **Workflow:** ``` 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 ``` *** ## Next Steps Understand how tools are registered, indexed, and executed. Explore ranking algorithms and optimization strategies. Learn about the Model Context Protocol that powers tool integration. See real-world examples of tool retrieval and execution. *** **Key Takeaway:** Agent-CoreX transforms tool selection from static configuration into dynamic, intelligent discovery. Your agent always gets the right tools for the job. 🚀