Tool Contract Intent-to-Tool Routing Rule Prompt

This prompt is for agent framework developers and platform engineers who need to build a deterministic, auditable routing layer between a user's natural language intent and a specific tool. The job-to-be-done is not just classification; it's generating a precise, machine-readable routing rule that includes confidence thresholds, disambiguation logic, and fallback chains. The ideal user is someone integrating a heterogeneous tool ecosystem—such as a set of MCP servers, internal APIs, or database connectors—where a single vague user request like 'get the Q3 report' could map to multiple tools with overlapping capabilities. This prompt is the first step in preventing silent agent failures caused by ambiguous tool selection.

Use this prompt when you have a defined tool contract with clear metadata (descriptions, argument schemas, and side-effect tags) and you need to create a routing rule that can be executed by a lightweight, non-LLM router or as a strict guardrail for an LLM-based router. It is appropriate when the cost of misrouting is high—for example, routing a 'delete' intent to a read-only tool is unacceptable, or sending a PII-laden request to a public API is a compliance violation. You should also use it when you need to scale your tool ecosystem without manually writing a routing rule for every new tool. The prompt takes a tool contract and a set of representative intents as input and outputs a structured rule that can be version-controlled and tested like code.

Do not use this prompt for simple, single-tool applications where routing is trivial. It is overkill if you have fewer than three tools or if all tools have completely non-overlapping domains. Avoid using it as a replacement for a proper semantic search or embedding-based retrieval system when your tool count is in the hundreds; at that scale, the prompt is better suited for generating training data for a dedicated router model. Crucially, do not use this prompt without first normalizing your tool descriptions. Garbage tool metadata in will produce garbage routing rules out. Your next step after generating a rule is to immediately run it through the evaluation harness described in the 'Testing & Evaluation' section, specifically testing for intent overlap and misrouting scenarios before any production deployment.

This prompt template is designed for agent framework developers who need to generate deterministic routing rules from tool contract metadata. It takes a user intent description and a set of available tool contracts as input, then produces a structured routing configuration that includes confidence thresholds, disambiguation questions, and fallback chains. The template is built to be wired directly into a routing layer that sits between intent detection and tool execution.

textCopy
You are an intent-to-tool routing rule generator for an AI agent platform. Your task is to analyze a user intent and a set of available tool contracts, then produce a routing configuration that maps the intent to the correct tool with appropriate safeguards.

## INPUT

**User Intent:** [USER_INTENT]

**Available Tools:** [TOOL_CONTRACTS]

**Routing Constraints:** [CONSTRAINTS]

## INSTRUCTIONS

1. Analyze the user intent against each tool contract's name, description, capability summary, and argument schema.
2. Identify the best-matching tool for the intent.
3. If multiple tools could satisfy the intent, rank them by fit and generate disambiguation questions.
4. If no tool matches, produce a fallback chain with escalation guidance.
5. Assign a confidence score (0.0 to 1.0) to the primary match.
6. Define a confidence threshold below which the system should ask for clarification rather than route.

## OUTPUT SCHEMA

Return a JSON object with this exact structure:
{
  "primary_match": {
    "tool_name": "string",
    "confidence": 0.0,
    "reasoning": "string"
  },
  "confidence_threshold": 0.0,
  "requires_clarification": true,
  "disambiguation_questions": ["string"],
  "alternative_matches": [
    {
      "tool_name": "string",
      "confidence": 0.0,
      "reasoning": "string"
    }
  ],
  "fallback_chain": ["string"],
  "no_match_handling": "string"
}

## RULES

- Do not route to a tool if the confidence is below the threshold you set.
- Disambiguation questions must be specific enough to distinguish between the top alternatives.
- Fallback chains must include at least one escalation path to a human or a general-purpose handler.
- If the intent is ambiguous, set requires_clarification to true.
- If the intent requests an action that no tool can perform, set primary_match to null and populate no_match_handling.
- Base all decisions on the provided tool contracts only. Do not invent tool capabilities.

## EXAMPLES

[EXAMPLES]

## RISK LEVEL

[RISK_LEVEL]

To adapt this template, replace the square-bracket placeholders with your actual data. [USER_INTENT] should contain the raw or processed user request. [TOOL_CONTRACTS] should include the full tool definitions with names, descriptions, argument schemas, and capability summaries. [CONSTRAINTS] can specify routing policies such as 'prefer read-only tools' or 'require confirmation for destructive operations.' [EXAMPLES] should contain 2-4 few-shot examples showing correct routing decisions for common intents in your domain. [RISK_LEVEL] should be set to 'low', 'medium', or 'high' to adjust the confidence threshold and escalation behavior. After generating the routing rule, validate the output against your tool registry to ensure the selected tool exists and the arguments are compatible. For high-risk domains, route the output through a human review step before activating the rule in production.

The intent-to-tool routing prompt is not a standalone artifact; it is a decision node inside a larger agent orchestration loop. The typical integration point is after user intent classification but before tool invocation. The prompt receives a structured intent object and a list of available tool contracts, then returns a routing decision. Wire this prompt into your agent's planning or routing middleware so that every tool call is preceded by an explicit routing step rather than relying on the model's implicit tool selection during function calling. This separation gives you a clean audit point and allows you to apply routing-specific validation, rate limiting, and fallback logic before any tool executes.

Implement the harness as a deterministic wrapper around the LLM call. First, validate that the input intent object contains the required fields: intent_label, confidence_score, and extracted_entities. Reject malformed intents before they reach the model. After the model returns a routing decision, validate the output against the expected schema: selected_tool must match a tool ID in the provided tool list, confidence must be a float between 0.0 and 1.0, and disambiguation_question must be non-null when confidence is below the configured threshold. If validation fails, log the raw output and retry with the error message appended to the prompt context. After three failed retries, escalate to a human-in-the-loop queue rather than guessing. For high-risk tool categories such as destructive or write, require an additional confirmation gate even after successful routing.

Model choice matters for routing reliability. Use a model with strong structured output support and low latency, such as Claude 3.5 Haiku or GPT-4o-mini, since routing is a high-frequency, cost-sensitive operation. Enable structured output mode with the routing decision schema rather than relying on free-text parsing. Log every routing decision with the intent, available tools, selected tool, confidence, and any disambiguation question. This trace data is essential for detecting intent overlap, tool description drift, and confidence miscalibration over time. Avoid routing prompts that embed tool implementation details; the prompt should only reason over tool contract metadata such as name, description, argument schema, and operation tags. If your tool registry exceeds 25 tools, pre-filter the candidate list by capability tags before passing it to the routing prompt to stay within context windows and reduce decision latency.