Router Tool Selector

Tool Selector

Purpose

Every tool activated in the response pipeline has a cost: latency, compute, and potentially a per-call API charge (for the legal data hunter and some web search providers). The tool selector's job is to activate the minimum set of tools that genuinely improves the response, and nothing more.

Default: no tools. Start from zero and add tools only when each addition clears a concrete justification.

Available Tools

Decision Rules

Apply rules in this order. Each rule adds a specific tool to the activated set; rules are additive.

Rule 1 — Skip RAG entirely for clean-query requests

Source: [[router-skip-rag-when-not-needed]] result

If the skip-RAG gate returns skip_rag: true, do not add any RAG tool to the active set. This rule overrides all others for RAG decisions.

Rule 2 — Activate firm RAG when workspace is scoped

If skip_rag: false AND the user's session has an active workspace/matter AND the request is about a specific document or matter: → Add tool.RAG-firm-knowledge

Cite results as [Firm KB] in the response. Never present firm KB results as verified legal authority — they are the firm's own documents.

Rule 3 — Activate personal RAG when user document is referenced

If skip_rag: false AND the user uploaded a document AND references it in the current message (by name or as "the document", "the file", "the contract"): → Add tool.RAG-personal-knowledge

Rule 4 — Activate public corpus RAG for deep-research

If complexity is deep-research AND the question requires verified statute/regulation text beyond model training: → Add tool.RAG-public-legal-corpus

Cite results as official source names (e.g., "UAE Federal Decree-Law No. 33 of 2021 — confirmed via public corpus"). Do not add this tool for medium or short-answer requests.

Rule 5 — Activate web search only for freshness

If the question requires information from the last 6 months (recent amendments, regulatory guidance, new rulings): → Add tool.web-search-orchestrator

Do NOT add web search to verify statute text that the model already has in training — it adds latency without improvement and risks returning low-quality web results instead of authoritative text.

Rule 6 — Legal data hunter only when corpus is insufficient

If the relevant jurisdiction or topic is not covered in the public corpus AND the question requires a specific statute citation or case text: → Add tool.legal-data-hunter

This is a paid API call. Use sparingly. Flag in the response that a paid data lookup was used.

Rule 7 — Activate calculator for arithmetic tasks

If the intent is calculate AND the relevant calculator tool is identifiable (EOSG, interest, deadline, stamp duty): → Add the relevant tool.calculator-*

Do not activate calculators for simple mental arithmetic. Only for jurisdiction-specific statutory calculations with multiple variables.

Rule 8 — Activate OCR when input is a scan

If the input includes an image or PDF scan (detected via attachment type or user statement "I'm attaching a scanned document"): → Add tool.OCR-arabic or tool.OCR-english based on language

Rule 9 — Activate connectors only in eFirm context

Connector tools (Linear, HubSpot, Stripe) are only available and appropriate when:

• The tenant is an eFirm tenant
• The user's request specifically involves CRM data, matter data, or billing data → Add the relevant connector

Never activate connectors on consumer or public-access surfaces.

Tier Check

After assembling the candidate tools list from Rules 1–9, apply the tier filter from [[router-tier-aware]]:

• Remove any tool that is not available in the user's current tier
• For each blocked tool: note it in the output with the tier it requires
• If a blocked tool is essential to answer the question: surface an upgrade CTA before proceeding without the tool

Output

{
  "tools": ["<tool-id>", ...],
  "tools_blocked_by_tier": [
    { "tool": "<tool-id>", "required_tier": "<tier>", "why_needed": "<short>" }
  ],
  "reason": "<one sentence explaining the active tool selection>"
}

An empty tools array is a valid and common output — it means the model answers from training with no external retrieval.

Common Failure Modes to Avoid

• Activating RAG on every request "just in case" — a common mistake that kills latency
• Activating web search for statute text questions — the model knows the statute; web search adds noise
• Activating the legal data hunter for well-covered jurisdictions — the model + public corpus can handle UAE, KSA, LB, EG without a paid call
• Activating calculators for trivial arithmetic — "add 30 days to a date" does not need a calculator tool

Related Skills

• [[router-skip-rag-when-not-needed]]
• [[router-tier-aware]]
• [[router-complexity-grader]]
• [[router-confidence-scorer]]
• [[router-intent-detection]]