Summary

Tools defined via MCP are presented identically to all models regardless of capability. A 1.5B model on a Raspberry Pi receives the same tool schemas as Claude Opus. This wastes tokens, degrades accuracy, and makes small models unusable with large tool registries.

I propose adding optional capability hints to the MCP tool schema, enabling servers to declare tier-aware descriptions and parameters.

The Problem

Empirical data across 1,000+ native tool calling inference calls (4 models, 80 tools, 50 prompts):

Small models can't navigate large tool sets. But a decomposition reveals the bottleneck is tool discovery, not tool selection:

P(correct tool) = P(correct family) × P(correct tool | correct family)

Even a 1.5B model picks the right tool 89% of the time when shown the right tool neighborhood.

Proposed Schema Addition

Add an optional capabilityHints field to the Tool definition:

{
  "name": "file_read",
  "description": "Read file contents with line numbers, offset, and encoding control",
  "inputSchema": { ... },
  "capabilityHints": {
    "tiers": {
      "small": {
        "description": "Read file",
        "inputSchema": {
          "type": "object",
          "properties": {
            "path": { "type": "string" }
          },
          "required": ["path"]
        }
      },
      "medium": {
        "description": "Read a file from disk",
        "inputSchema": {
          "type": "object",
          "properties": {
            "path": { "type": "string" },
            "encoding": { "type": "string" }
          },
          "required": ["path"]
        }
      }
    },
    "category": "filesystem",
    "priority": 0.8
  }
}

Backwards compatible: Clients that don't understand capabilityHints ignore it and use the existing description/inputSchema (which becomes the "large" tier default). No breaking changes.

What This Enables

1. MCP clients (Claude Code, Cursor, Windsurf) can detect the connected model's capability and present the appropriate tier's description/schema
2. MCP servers declare once, serve all model sizes — no need for separate server configs
3. Tool builders think about small model usability upfront (shorter descriptions, fewer params)
4. Token savings of 83-92% for filtered/adapted strategies, translating directly to cost and latency reduction

Benchmark Results

With tier-adapted presentation:

Evidence

• Whitepaper: Tier-Based Adaptive Tool Routing for Capability-Heterogeneous AI Agents (DOI: 10.5281/zenodo.19228710)
• Benchmark data: 1,000+ inference calls, native Ollama tool calling API
• Open-source SDK: yantrikos-sdk on PyPI
• Reference implementation: github.com/yantrikos/tier
• Production origin: Architecture from YantrikOS (116+ tools, 4 model tiers)

Design Considerations

1. Tier names: small / medium / large (or parameter-range based) — open to discussion
2. Tier detection: Client-side based on model metadata, not server-side
3. Fallback: If a tier isn't declared, client uses the top-level description/inputSchema
4. Category field: Enables family-based routing which improves accuracy by +4-20pp
5. Priority field: Hints for ordering when presenting multiple tools

Relationship to Existing Work

• AgentFlux (arXiv:2510.00229): Decouples tool selection from argument generation but doesn't address presentation adaptation
• TinyLLM (arXiv:2511.22138): Evaluates small models on tool use but doesn't propose solutions
• This proposal provides the missing protocol-level solution

Happy to discuss implementation details or provide additional benchmark data.