[Feature Request] MCP/Skill Tool Usage Priority Configuration - Need a standardized way to define tool precedence

[zhang-xzh]

Problem Statement

In real-world agent usage, projects often integrate multiple MCP servers and Skills that provide overlapping functionality. Currently, there is no standardized mechanism to define which tool should be preferred when multiple tools can accomplish the same task.

Real-World Example

In our project, we have three tools that can search for files:

Tool	Source	Capability
ide_find_file	intellij-index MCP	IDE-indexed file search with semantic understanding
find_files_by_glob	intellij-util MCP	Glob pattern matching via IDE
Glob	Built-in	Basic filesystem glob

Current behavior: The LLM randomly selects among these tools without understanding which is most appropriate.

Expected behavior: A clear priority hierarchy:

intellij-index > intellij-util > built-in tools

Current Industry Landscape

After investigating major AI coding tools, none provide a standardized solution for this problem:

Tool	Configuration Files	Tool Priority Support
Claude Code	CLAUDE.md, AGENTS.md, .mcp.json	❌ No priority mechanism
Cursor	.cursor/rules/*.mdc, ~/.cursor/mcp.json	⚠️ Rules have priority metadata, but not for MCP tools
Roo Code	.roo/rules/, .roorules	❌ No priority mechanism
Cline	.clinerules/	❌ No priority mechanism
LangChain Deep Agents	.mcp.json (auto-discovery)	⚠️ Config-level priority only (user < project < explicit)

Proposed Solutions

Option 1: Extend mcp.json with Priority Metadata (Recommended)

Add a toolPriority section to the MCP configuration:

{
  "mcpServers": {
    "intellij-index": { "url": "http://localhost:29173/index-mcp/streamable-http" },
    "intellij-util": { "type": "stdio", "command": "..." }
  },
  "toolPriority": {
    "file_search": [
      { "server": "intellij-index", "tool": "ide_find_file" },
      { "server": "intellij-util", "tool": "find_files_by_glob" },
      { "builtin": "Glob" }
    ],
    "code_navigation": [
      { "server": "intellij-index", "tool": "ide_find_definition" },
      { "server": "intellij-index", "tool": "ide_find_references" }
    ]
  }
}

Option 2: Separate Configuration File (.ai/tool-priority.yaml)

Create a dedicated file for tool usage rules:

# .ai/tool-priority.yaml
version: 1

categories:
  file_search:
    description: "Search for files in the project"
    priority:
      - server: intellij-index
        tool: ide_find_file
        reason: "IDE-indexed, most accurate"
      - server: intellij-util
        tool: find_files_by_glob
        reason: "IDE-backed glob matching"
      - builtin: Glob
        reason: "Fallback for basic cases"

  code_search:
    description: "Search code content"
    priority:
      - server: intellij-index
        tool: ide_search_text
      - builtin: Grep
        condition: "when IDE tools unavailable"

rules:
  - when: "working_with_code"
    prefer: "intellij-index"
    reason: "IDE tools provide semantic understanding"
  
  - when: "pure_file_operations"
    prefer: "filesystem"
    reason: "Avoid IDE overhead for simple tasks"

Option 3: Extend AGENTS.md with Tool Priority Section

Leverage the existing AGENTS.md convention:

# Tool Usage Priority

## Hierarchy

1. **intellij-index** - Primary for all code-related operations
   - `ide_find_definition` - Go to symbol definition
   - `ide_find_references` - Find symbol usages
   - `ide_search_text` - Search in codebase

2. **intellij-util** - Secondary for file operations
   - `find_files_by_glob` - Pattern matching
   - `ide_move_file` - Refactoring operations

3. **filesystem** - Fallback for pure file I/O
   - `ReadFile`, `WriteFile` - When IDE tools unavailable

This content could be parsed and injected into the system prompt with structured formatting.

Key Requirements

1. Function-based grouping - Group tools by capability (search, read, write, navigate) rather than by source
2. Conditional logic - Allow rules like "use IDE tools when available, fallback to filesystem"
3. Human-readable - Both humans and AI should understand the priorities
4. Version control friendly - Text-based, diff-friendly format

Benefits

• Consistency - Ensures optimal tool selection across different sessions
• Token efficiency - Avoids redundant tool calls
• Better results - Uses semantically appropriate tools for each task
• Maintainability - Centralized configuration for tool preferences

Additional Context

This issue was discovered while building a Next.js project where we have both IDE MCP servers (for code intelligence) and standard filesystem tools. The LLM frequently:

1. Uses Grep when ide_search_text would be more accurate
2. Uses ReadFile when get_file_text_by_path (from IDE) would maintain proper indexing
3. Doesn't understand when to prefer IDE-backed refactoring tools over basic file operations

A standardized priority configuration would solve this systematically rather than relying on prompt engineering in each session.

---

Would love to hear thoughts on which approach aligns best with Kimi Code CLI's design philosophy!

[zhang-xzh]

工具优先级配置需求摘要

核心问题

当前Agent运行环境（Claude Desktop、Cline、Cursor等）缺乏工具仲裁层的配置能力。当多个MCP/Skill提供相似功能时，没有标准机制定义：

• 冲突解决策略（选谁）
• 降级与Fallback路径
• 成本/质量/延迟的权衡规则

现有方案的局限

方案	能力	缺失
Cline .clinerules	基于关键词激活MCP分组	无同名工具仲裁机制
Gemini CLI Policy	工具级权限控制（allow/deny）	无能力优先级排序
AGENTS.md	定义Agent整体行为	无工具选择规则

提议的解决方案：TOOLS_RULES.md

# 核心仲裁配置
tool_resolution:
  default_strategy: priority  # priority | cost | latency | accuracy
  
  # 同名工具优先级定义
  overrides:
    - tool: search
      priority:
        - server: local-search-mcp
          weight: 100
        - server: brave-search-mcp
          weight: 50
          condition: "local-search-mcp.unavailable"
    
    - tool: read_file
      deduplicate: true
      priority:
        - server: filesystem-mcp
          weight: 100
        - server: remote-fs-mcp
          weight: 20
          require_approval: true

# 工具链组合
tool_chains:
  - name: web_research
    sequence:
      - tool: search
        server: brave-search-mcp
      - tool: fetch_url
        server: firecrawl-mcp
      - tool: summarize
        server: local-llm-mcp

# 禁用与降级
disabling:
  - server: expensive-gpt4-mcp
    fallback: local-llama-mcp
    
  - tool: delete_file
    global_policy: ask_user

架构定位

• 运行时层：在工具发现阶段介入，构建最终可用工具列表
• 透明映射：Agent看到search，实际路由由运行时处理
• 动态解析：支持条件表达式（server.unavailable、cost > 0.01）

Kimi生态的适配优势

• Agent Swarm：工具仲裁可复用Swarm控制器架构
• ClawHub 5000+技能：技能冲突场景更频繁，需求迫切
• 端到端交付：工具选择直接影响交付物质量

实施建议

1. Phase 1：观测层——暴露工具选择理由
2. Phase 2：约束层——支持banned_tools、preferred_providers
3. Phase 3：仲裁层——完整策略引擎
4. Phase 4：生态层——与ClawHub技能元数据集成

---

Summary of tool priority configuration requirements

Core Issues

The current Agent operating environment (Claude Desktop, Cline, Cursor, etc.) lacks the configuration capability of the tool arbitration layer. There is no standard mechanism defined when multiple MCPs/Skills provide similar functionality:

• Conflict resolution strategies (who to choose)
• Downgrade and Fallback path
• Cost/quality/delay trade-off rules

Limitations of existing solutions

Plan	Capability	Missing
Cline .clinerules	Activate MCP grouping based on keywords	No arbitration mechanism for tools with the same name
Gemini CLI Policy	Tool-level permission control (allow/deny)	Inability prioritization
AGENTS.md	Define the overall behavior of the Agent	No tool selection rules

Proposed solution: TOOLS_RULES.md

#Core arbitration configuration
tool_resolution:
  default_strategy: priority # priority | cost | latency | accuracy
  
  # Definition of tool priority with the same name
  overrides:
    - tool: search
      priority:
        - server: local-search-mcp
          weight: 100
        - server: brave-search-mcp
          weight: 50
          condition: "local-search-mcp.unavailable"
    
    - tool: read_file
      deduplicate: true
      priority:
        - server: filesystem-mcp
          weight: 100
        - server: remote-fs-mcp
          weight: 20
          require_approval: true

# Toolchain combination
tool_chains:
  - name: web_research
    sequence:
      - tool: search
        server: brave-search-mcp
      - tool: fetch_url
        server: firecrawl-mcp
      - tool: summarize
        server: local-llm-mcp

# Disable and downgrade
disabling:
  - server: expensive-gpt4-mcp
    fallback: local-llama-mcp
    
  - tool: delete_file
    global_policy: ask_user

Architecture positioning

• Runtime layer: intervenes in the tool discovery phase to build the final list of available tools
• Transparent Mapping: Agent sees search, actual routing is handled by runtime
• Dynamic parsing: Support conditional expressions (server.unavailable, cost > 0.01)

Adaptation advantages of Kimi ecology

• Agent Swarm: Tool arbitration reusable Swarm controller architecture
• ClawHub 5000+ skills: Skill conflict scenes are more frequent and the demand is urgent
• End-to-end delivery: Tool selection directly affects the quality of deliverables

Implementation suggestions

1. Phase 1: Observation layer—reasons for choosing exposure tools
2. Phase 2: Constraint layer - supports banned_tools, preferred_providers
3. Phase 3: Arbitration layer - complete policy engine
4. Phase 4: Ecological layer - integrated with ClawHub skill metadata

[richwilson-bloom]

We built a scored recommendation endpoint that returns ranked tool alternatives for a given task - it is live at https://a2a.bloomfieldgrowth.agency, and this issue is exactly the use case we were thinking about when designing it.

The feature request here is for standardized tool priority configuration when overlapping MCP servers are connected - the frustration is that there is no deterministic way to express "prefer this tool over that one for this type of task."

What I am not sure about: is the core need here a static config that persists across sessions (so the model does not have to re-resolve the same conflict every time), or would a runtime endpoint that returns a ranked recommendation for each task request actually address what you are after? Our scorer at https://a2a.bloomfieldgrowth.agency/recommend takes the task intent at call time and returns a ranked result, but if the problem is fundamentally about setting a persistent preference rather than per-task scoring, those are solving different things and I would want to understand which one matters more to the people hitting this.