Finding the Right MCP Tool: Decision Trees and Routing Protocols for Autonomous Agents

Autonomous coding agents interacting with modern knowledge bases require rigorous tool selection protocols. When an agent chooses an improperly scoped tool, it incurs severe context pollution, latency spikes, or catastrophic authorization rejections. Wikantik exposes exactly 51 distinct Model Context Protocol (MCP) tools distributed across two cryptographically partitioned server interfaces: 22 read-only tools on /knowledge-mcp and 29 privileged write, curation, and analytical tools on /wikantik-admin-mcp.

While simple agent implementations treat an MCP server as an undifferentiated bag of functions, production agentic architectures—such as those operating across the Simple Agility ecosystem—leverage strict functional decision trees. This runbook provides the definitive operational decision procedure, routing taxonomy, token economic equations, and error recovery workflows necessary to navigate Wikantik's dual-MCP surface with maximal precision and minimal token expenditure.

graph TD
    A["Agent Intent Received"] --> B{"Requires Mutation or Admin Analytics?"}
    
    %% Write Branch
    B -- "Yes (Write / Mutate / Curate)" --> C["Authenticate on /wikantik-admin-mcp (mcp_admin Key)"]
    C --> D{"Mutation Category"}
    D -- "Create New Pages" --> D1["write_pages (Batch Creation)"]
    D -- "Edit Existing Content" --> D2["update_page (Optimistic Locking + removeKeys)"]
    D -- "Taxonomy / Cluster Refactor" --> D3["rename_cluster or rename_page"]
    D -- "Verification Gate" --> D4["verify_pages → mark_page_verified"]
    D -- "Knowledge Graph Curation" --> D5["curate_nodes / curate_edges"]
    D -- "Traffic & Query Signals" --> D6["list_content_opportunities / list_retrieval_queries"]

    %% Read Branch
    B -- "No (Read-Only Grounding)" --> E["Authenticate on /knowledge-mcp (mcp_read Key)"]
    E --> F{"Information Goal"}
    F -- "Answer Specific Question" --> F1["assemble_bundle (Check coverage.confidence)"]
    F -- "Discover Relevant Pages" --> F2["retrieve_context (Query-driven Chunks)"]
    F -- "Metadata & Structural Faceting" --> F3["list_pages_by_filter (Cluster / Tag / Freshness)"]
    F -- "Page Orientation & Verification" --> F4["get_page_for_agent (Token-Budgeted Projection)"]
    F -- "Deep Code / Content Extraction" --> F5["read_pages (Batched Raw Markdown, ≤20 pages)"]
    F -- "Entity Triples & Ontological Graph" --> F6["traverse / query_nodes / sparql_query"]

1. Architectural Bifurcation: Dual-MCP Topology and Trust Boundaries

Wikantik partitions its MCP tools into two distinct server endpoints. This bifurcation enforces the principle of least privilege, protects sensitive corpus telemetry, and optimizes transport serialization over HTTP Server-Sent Events (SSE).

Security Boundaries and Authentication Contracts

Every interaction begins with an HTTP POST JSON-RPC handshake against the appropriate endpoint:

1. The Knowledge MCP Endpoint (/knowledge-mcp):
   • Scope: Strictly read-only operations. Hosts 22 tools covering semantic search, chunk retrieval, metadata listing, structural Page Graph navigation, RDF triple queries, and ontology inspection.
   • Authentication: Requires a bearer token with mcp_read authorization. If an agent presents an invalid or administrative token, it is accepted under read constraints; however, attempting any mutating operation returns JSON-RPC Method Not Found (-32601).
   • Security Guarantees: Guarantees read parity with anonymous site visitors. Guest access control lists (ACLs) are strictly enforced at the database layer. An agent cannot leak private drafts or unverified administrative telemetry through /knowledge-mcp.
2. The Admin MCP Endpoint (/wikantik-admin-mcp):
   • Scope: Authoritative mutations, verification gates, link-graph repair, sitemap pings, Knowledge Graph curation, and search query analytics. Hosts 29 tools.
   • Authentication: Requires a high-privilege bearer token with mcp_admin authorization. Presenting an mcp_read token immediately results in an HTTP 403 Forbidden status code.
   • Safety Guarantees: Enforces optimistic concurrency control on every document update via cryptographic content hashes (expectedContentHash), preventing concurrent agent overwrites.

Transport Lifecycle and SSE Connection State

Both endpoints follow the standard Model Context Protocol transport specification over HTTP:

• Handshake (initialize): The agent sends client identification (clientInfo) and negotiated protocol version (2024-11-05). The server responds with server metadata, supported capabilities, and issues an Mcp-Session-Id header.
• Session Continuity: Agents must preserve the returned Mcp-Session-Id header across all subsequent POST requests within the same operational loop to maintain stateful cache bindings and avoid redundant token-bucket initializations.
• Payload Streaming: Tool execution responses are streamed using text/event-stream format with JSON-RPC envelopes emitted on standard data: lines.

2. Decision Tree for MCP Tool Selection

When an agent needs to retrieve data or mutate state, it must evaluate three sequential branching criteria:

Branching Criterion 1: Access Level (Privilege)

• Does the task modify wiki state, curate graph edges, check search engine telemetry, or inspect unlinked drafts?
  • Yes: Route directly to /wikantik-admin-mcp. Ensure the active environment provides WIKANTIK_ADMIN_API_KEY.
  • No: Route to /knowledge-mcp. Use WIKANTIK_KNOWLEDGE_API_KEY.

Branching Criterion 2: Retrieval Granularity (Read Path)

• If reading, what specific representation of knowledge does the downstream prompt require?
  • Direct Answer Synthesis: When the agent needs to answer a prompt (e.g., "How does Simple Agility manage consignment inventory?"), call assemble_bundle. It executes hybrid BM25 + dense vector retrieval, deduplicates overlapping passages, and emits a composite text bundle.
  • Discovery and Relevance Exploration: When the agent needs to know which articles exist without ingesting their bodies, call retrieve_context. It returns scored page names and excerpt coordinates.
  • Structural Categorization: When the agent needs to enumerate articles belonging to a specific cluster, tag, or freshness status, call list_pages_by_filter. Do not use search tools for faceted enumeration.
  • Orientation and Citation Fact-Checking: When an agent needs to inspect a known article's structural facts, verification state, section outline, and derived hints without consuming thousands of prose tokens, call get_page_for_agent.
  • Full Markdown Parsing: When an agent must rewrite, refactor, or perform deep code extraction on specific pages, call read_pages (supporting up to 20 slugs in a single batched network round-trip).
  • Entity and Ontological Querying: When the agent requires formal class hierarchies or entity relationship chains, call query_nodes or sparql_query.

Branching Criterion 3: Mutation Class (Write Path)

• If writing, what is the scope of the mutation?
  • Creating Fresh Content: Use write_pages. It enforces atomic creation and rejects pages that already exist, preventing inadvertent overwrites.
  • Updating Existing Documents: Use update_page. Always supply the existing content hash to enable optimistic locking. Use removeKeys to prune deprecated frontmatter fields like hubs.
  • Restructuring Taxonomies: When renaming clusters or slugs, use rename_cluster or rename_page. Never manually edit frontmatter cluster: across dozens of files individually; rename_cluster cascades across all member pages automatically.
  • Automated Verification: Use verify_pages to run structural sanity checks, followed by mark_page_verified to stamp confidence headers.

3. High-Efficiency Read Routing on /knowledge-mcp

The read server exposes 22 specialized tools designed to satisfy the spectrum between high-level orientation and deep graph queries.

Deep-Dive: The assemble_bundle Confidence Protocol

When executing assemble_bundle, autonomous agents must not treat the output as raw, unquestioned truth. The tool returns a vital metadata block: coverage.confidence.

{
  "coverage": {
    "confidence": "strong",
    "directMatches": 4,
    "semanticClusters": ["agentic-coding", "context-engineering"],
    "scoreThreshold": 0.742
  },
  "bundle": "### AgenticCodingHub > Structural Spine\n..."
}

• strong Confidence: The retrieval engine located direct, highly ranked semantic matches across multiple authoritative sections. The agent may synthesize its response immediately.
• moderate Confidence: The bundle contains relevant context, but some query sub-aspects were weakly matched. The agent should supplement the bundle by querying retrieve_context or inspecting cluster neighbors via get_page_neighbors.
• sparse Confidence: The wiki lacks sufficient density on the requested topic. The agent should refrain from hallucinating, report the knowledge gap, and check list_content_opportunities on the admin server.

4. Authoritative Write Routing on /wikantik-admin-mcp

The admin server exposes 29 privileged tools governing document creation, mutation, schema migration, and graph curation.

Safe Document Updates via Optimistic Locking

The most critical write operation is update_page. To prevent race conditions between concurrent agents or human editors, update_page implements strict optimistic concurrency control:

{
  "pageName": "SkillsVsMcp",
  "expectedContentHash": "93c27087ed727cdfa4d8b95055f30cfdf1a4ba71b8bbb4c6be1532c7ea57cec4",
  "content": "---\nstatus: active\n...",
  "frontmatter": {
    "status": "active",
    "cluster": "agentic-coding"
  },
  "removeKeys": ["hubs", "legacy_category"]
}

1. expectedContentHash: The SHA-256 hash of the page content as received during the read phase. If another agent or user has modified the page in the interim, the server rejects the update with 412 Precondition Failed.
2. removeKeys: Explicitly unsets deprecated frontmatter fields. This provides safe, server-authoritative schema pruning (e.g., eliminating retired hubs: fields under the Wikantik v2.4+ Cluster Declaration Architecture).

5. Token Economics and Projection Mathematical Modeling

A central design failure in autonomous agent workflows is the unbudgeted consumption of raw markdown. When an agent reads full articles simply to discover metadata, verify citations, or extract section headers, it rapidly exhausts the active context window.

Token Consumption Model

The total token cost of a multi-turn agent interaction across N wiki interactions is defined as:

Where:

• T_transport is the JSON-RPC envelope and SSE protocol framing tokens (approximately 80 tokens per round trip).
• T_overhead represents the agent accumulated conversation history carried into each turn.
• T_payload represents the returned tool content.

When an agent invokes read_pages for an average deep-dive article (approximately 2,200 words or 2,900 tokens), the payload consumes substantial budget. Conversely, the agent projection emitted by get_page_for_agent emits only the compressed structural spine (approximately 350 words or 460 tokens).

Projection Efficiency Ratio

We define the Projection Token Efficiency Ratio as:

By routing orientation steps to get_page_for_agent, the agent achieves an 84.1% reduction in context consumption per orientation step. Over a 20-step autonomous research and curation trajectory, this preserves over 48,000 tokens, directly reducing inference costs from approximately $0.15 per session to less than $0.024 per session while eliminating prompt truncation and attention degradation.

6. Real-World Execution Patterns and JSON-RPC Schemas

The following concrete JSON-RPC payloads demonstrate compliant invocations across both endpoints.

Pattern 1: Targeted Question Answering via assemble_bundle

# POST /knowledge-mcp
{
  "jsonrpc": "2.0",
  "id": 101,
  "method": "tools/call",
  "params": {
    "name": "assemble_bundle",
    "arguments": {
      "query": "How do Simple Agility coding agents verify PRs before merging?",
      "max_tokens": 2500
    }
  }
}

Pattern 2: Token-Budgeted Orientation via get_page_for_agent

# POST /knowledge-mcp
{
  "jsonrpc": "2.0",
  "id": 102,
  "method": "tools/call",
  "params": {
    "name": "get_page_for_agent",
    "arguments": {
      "pageName": "SpecDrivenDevelopment"
    }
  }
}

Pattern 3: Optimistic Document Update via update_page

# POST /wikantik-admin-mcp
{
  "jsonrpc": "2.0",
  "id": 201,
  "method": "tools/call",
  "params": {
    "name": "update_page",
    "arguments": {
      "pageName": "SpecDrivenDevelopment",
      "expectedContentHash": "a4f89d3c2b1e7f60...",
      "content": "---\ntitle: Spec-Driven Development\n...",
      "removeKeys": ["hubs"]
    }
  }
}

Pattern 4: Quality Gate Auditing via verify_pages

# POST /wikantik-admin-mcp
{
  "jsonrpc": "2.0",
  "id": 202,
  "method": "tools/call",
  "params": {
    "name": "verify_pages",
    "arguments": {
      "pageNames": ["SpecDrivenDevelopment", "SkillsVsMcp", "ContextEngineeringForCodingAgents"]
    }
  }
}

7. Recurring Antipatterns and Failure Modes

Antipattern 1: The get_page Void Traversal

• Failure Mode: An agent calls get_page expecting the article's markdown prose. It receives only a sparse JSON descriptor containing frontmatter metadata and a canonical URL. The agent then repeatedly re-queries or hallucinates the content.
• Remediation: Use get_page only when verifying frontmatter attributes or URL coordinates. For token-budgeted reading, call get_page_for_agent; for full markdown, call read_pages.

Antipattern 2: The Raw Ingestion Flood

• Failure Mode: An agent searches for a topic, receives 10 page names, and immediately passes all 10 into read_pages. This injects 30,000+ tokens into the conversation history, overwhelming the model's context window.
• Remediation: Call assemble_bundle first. Allow Wikantik's server-side ranking engine to extract and deduplicate the top 5 relevant sections into a single compact bundle.

Antipattern 3: Credential Misrouting

• Failure Mode: An agent attempts to invoke update_page or mark_page_verified on /knowledge-mcp, or attempts to use an mcp_read key on /wikantik-admin-mcp.
• Remediation: Implement client-side endpoint routing logic. Ensure that all read tools automatically target /knowledge-mcp and all write tools target /wikantik-admin-mcp.

Antipattern 4: The Graph-as-Search Fallacy

• Failure Mode: An agent uses find_similar or search_knowledge to search for document paragraphs or tutorials.
• Remediation: Understand the data models. search_knowledge and find_similar operate strictly over Knowledge Graph entity nodes (concepts, organizations, specifications). Document text retrieval must be routed through retrieve_context or assemble_bundle.

Antipattern 5: Blind Document Overwriting

• Failure Mode: An agent issues an update_page call without providing expectedContentHash. If an intervening edit occurred, the prior work is silently overwritten.
• Remediation: Always fetch the latest content hash immediately prior to drafting updates, and handle 412 Precondition Failed by performing a three-way diff.

See Also

• AgenticCodingHub — Master cluster index for agentic software engineering and knowledge-anchored agent workflows
• ContextEngineeringForCodingAgents — Context architecture, progressive disclosure, and token budgeting
• SkillsVsMcp — Procedural knowledge extensions vs protocol-level data access tools
• SpecDrivenDevelopment — Living specification patterns and deterministic verification loops
• ChoosingARetrievalMode — Detailed retrieval mode selection between vector search, BM25, and Page Graph navigation
• VerifyingAnAgentGeneratedPage — Complete end-to-end audit and verification workflow
• GoodMcpDesign — Architectural principles for designing agent-grade MCP tool surfaces
• AgentGradeContentDesign — Structural spine and schema requirements for agent-readable content
• McpIntegration — Operational guide for wiring IDEs and agent runtimes into Wikantik MCP servers