MCP Orchestration Router — How Claude Selects and Sequences Tools

flowchart TD
    UM([User Message]) --> SP[System Prompt\nRole + constraints + tool inventory]
    SP --> CI[Claude Inference\nIntent classification via tool descriptions]
    CI --> TD{Requires\ntool call?}
    TD -->|No| DR([Direct Response\ne.g. general manga trivia])
    TD -->|Yes - single intent| ST[Single Tool Call]
    TD -->|Yes - multi-intent| MT[Parallel Tool Calls\nasyncio.gather pattern]

    ST --> TR[Tool Result]
    MT --> TR
    TR --> CV{Needs follow-up\ntool call?}
    CV -->|Yes - chained| CT[Chain: next tool call\nusing prior result as input]
    CV -->|No| FA([Final Answer Synthesis])
    CT --> TR

    style UM fill:#4A90D9,color:#fff
    style FA fill:#27AE60,color:#fff
    style CI fill:#8E44AD,color:#fff

flowchart LR
    SP([System Prompt]) --> RD[Role Definition\n'You are MangaAssist...']
    SP --> TC[Tool Constraints\n'For policy Qs always use support MCP'\n'Never estimate prices']
    SP --> TI[Tool Inventory Summary\n7 MCP servers listed with scope]
    SP --> RS[Response Style\nConcise · Cite sources · No hallucination]
    SP --> ES[Escalation Rules\nWhen to call escalate_to_agent]

    RD --> CL[Claude at Inference]
    TC --> CL
    TI --> CL
    RS --> CL
    ES --> CL

    style SP fill:#8E44AD,color:#fff
    style CL fill:#4A90D9,color:#fff

TOOL USAGE RULES:
1. For any price question, ALWAYS call get_price. Never state or estimate a price.
2. For any order-related question, ALWAYS call get_order_status or check_stock.
3. For return/refund questions, ALWAYS call answer_faq or check_refund_eligibility. Never answer from training knowledge.
4. For recommendations, ALWAYS call get_recommendations or get_similar_titles.
5. For trending content, ALWAYS call get_trending or get_new_releases.
6. ALWAYS cite the tool source when answering policy questions.
7. If a tool returns escalation_suggested=true, ALWAYS call escalate_to_agent next.

# BAD — ambiguous, causes misrouting
@app.tool()
async def search(query: str) -> dict:
    """Search for manga information."""
    ...

# GOOD — specific, scoped, with negative examples
@app.tool()
async def search_manga(query: str, filters: dict = {}) -> dict:
    """
    Search the MangaAssist catalog by title, author, genre, or free-text description.
    Use for: browsing/discovering titles, finding manga by description, author search.
    Do NOT use for: checking stock (use check_stock), recommendations (use get_recommendations),
    or trending titles (use get_trending).
    Returns: ranked list of manga with title, author, genres, and manga_id.
    """
    ...

sequenceDiagram
    actor User
    participant Claude
    participant CatalogMCP
    participant TrendingMCP
    participant ReviewMCP

    User->>Claude: "What's trending in dark fantasy, and how\nare readers rating those titles?"

    par Tool dispatch
        Claude->>TrendingMCP: get_trending(genre="dark_fantasy")
    and
        Claude->>ReviewMCP: get_sentiment_summary(aspect="overall")
    end

    TrendingMCP-->>Claude: [Vinland Saga, Claymore, Dorohedoro]
    ReviewMCP-->>Claude: [4.8, 4.6, 4.4] avg ratings

    Claude->>User: Synthesised: trending titles + their community reception

sequenceDiagram
    actor User
    participant Claude
    participant CatalogMCP
    participant OrderMCP

    User->>Claude: "Is volume 10 of Claymore available?"

    Claude->>CatalogMCP: search_manga(query="Claymore")
    CatalogMCP-->>Claude: {manga_id: "CLAYMORE", ...}

    Claude->>OrderMCP: check_stock(manga_id="CLAYMORE", volume_number=10)
    OrderMCP-->>Claude: {in_stock: true, quantity: 7}

    Claude->>User: "Yes, Claymore volume 10 is in stock (7 copies available)."

flowchart TD
    Q([User: 'I want a refund for my last order']) --> OS[get_order_status\nfetch last order]
    OS --> OD{Order found?}
    OD -->|No| EX[escalate_to_agent\nCan't find order]
    OD -->|Yes| RE[check_refund_eligibility\norder_id + reason]
    RE --> EL{Eligible?}
    EL -->|Yes| PI[Return eligible\nProvide steps]
    EL -->|No, borderline| GW[Offer goodwill credit\nas alternative]
    EL -->|No| DN[Explain ineligibility\nwith policy citation]
    DN --> SU{User unsatisfied?}
    SU -->|Yes| EX
    SU -->|No| END([End])

    style Q fill:#4A90D9,color:#fff
    style EX fill:#C0392B,color:#fff
    style PI fill:#27AE60,color:#fff

flowchart TD
    TC([Tool Call]) --> TR{Tool result\nstatus?}
    TR -->|success| PR([Process result normally])
    TR -->|not_found| FB[Use fallback_strategy\nfrom tool result]
    TR -->|error 5xx| RT{Retry count\n< 2?}
    RT -->|Yes| TC
    RT -->|No| DG[Degrade gracefully\nReturn partial answer + disclaimer]
    TR -->|timeout| TM[Inform user of delay\nOffer to try again]
    TR -->|escalation_suggested| ES[Call escalate_to_agent\nmandatory per system prompt]

    style TC fill:#4A90D9,color:#fff
    style PR fill:#27AE60,color:#fff
    style DG fill:#E67E22,color:#fff
    style ES fill:#C0392B,color:#fff

pie title Context Window Budget (200k tokens)
    "System prompt" : 2000
    "Conversation history" : 40000
    "Pending tool results" : 30000
    "Claude reasoning scratchpad" : 20000
    "Safety buffer" : 108000

# BAD — prose burns context tokens
return {"answer": "Berserk is a dark fantasy manga by Kentaro Miura published by Hakusensha..."}

# GOOD — structured, Claude synthesises prose
return {
    "manga_id": "BERSERK",
    "title_en": "Berserk",
    "author": "Kentaro Miura",
    "genre": ["dark_fantasy", "action", "seinen"],
    "volumes": 42,
    "status": "ongoing",
    "avg_rating": 4.9,
}

gantt
    title End-to-End Latency Budget (P99) for Complex Multi-Tool Query
    dateFormat X
    axisFormat %Lms

    section Phase 1 — First inference
    Claude reads user message + tools list   :0, 300
    Claude decides which tools to call       :300, 500

    section Phase 2 — Parallel tool execution
    Catalog MCP                              :500, 1000
    Trending MCP                             :500, 800
    Review MCP                               :500, 950

    section Phase 3 — Final synthesis
    Claude reads all tool results            :1000, 1200
    Claude generates final answer            :1200, 1700
    Streaming tokens to user begins          :1500, 1700

@xray_recorder.capture("mcp_tool_call")
async def dispatch_tool(tool_name: str, args: dict, user_id: str) -> dict:
    subsegment = xray_recorder.current_subsegment()
    subsegment.put_annotation("tool", tool_name)
    subsegment.put_annotation("user_id", user_id)

    start = time.monotonic()
    result = await _call_mcp_server(tool_name, args)
    latency_ms = (time.monotonic() - start) * 1000

    subsegment.put_metadata("latency_ms", latency_ms)
    subsegment.put_metadata("result_size_bytes", len(json.dumps(result)))

    # Emit to CloudWatch for SLA dashboard
    cloudwatch.put_metric_data(
        Namespace="MangaAssist/MCP",
        MetricData=[{
            "MetricName": "ToolLatencyMs",
            "Dimensions": [{"Name": "Tool", "Value": tool_name}],
            "Value": latency_ms,
            "Unit": "Milliseconds",
        }]
    )
    return result