Core Concepts

Tool pruning

Orqen reduces the tools sent to the model on each request while preserving the user's original intent. The result is lower prompt cost, less tool-selection noise, and faster agent loops.

What happens on a request

Read intent

Orqen extracts the current user intent, domain, action, target objects, slots, and safety signals.

Score tools

Each tool is mapped to a capability card and scored against the intent, schema, examples, embeddings, and learned signal.

Choose K

Orqen picks an adaptive tool window. Crisp requests can route to one tool; risky or ambiguous requests widen.

Forward safely

Only the selected tools are forwarded. If pruning times out or fails, Orqen forwards the full set.

Intent-aware routing

Orqen does not only compare text similarity. It builds an intent frame such as:

{
  "domain": "weather",
  "action": "forecast",
  "slots": { "location": "Sittingbourne Kent" },
  "side_effect_allowed": false,
  "previous_tool_error": false,
  "confidence": 0.73
}

That frame is matched against tool capability cards derived from function names, descriptions, schemas, required inputs, and optional routing examples.

{
  "type": "function",
  "function": {
    "name": "open_meteo_weather",
    "description": "Get real weather forecast for a city.",
    "x-orqen-examples": [
      "weather in London",
      "forecast for Sittingbourne Kent"
    ],
    "parameters": {
      "type": "object",
      "properties": { "city": { "type": "string" } },
      "required": ["city"]
    }
  }
}

Adaptive K

Orqen chooses how many tools to forward based on confidence and risk:

Crisp single intent	1 tool	Example: list files, weather in London.
Moderate confidence	2-3 tools	Enough room for close alternatives.
Multi-step or failed retry	up to 4 tools	Protects recall when the agent is recovering.
Side effects	minimum 3 tools	Write/send/execute operations are widened unless confidence is very high.
Timeout or error	all tools	Fail-open behavior keeps customer requests reliable.

Learning loop

Orqen stores privacy-safe routing traces: detected intent, selected tools, top candidates, recall, and shadow-route variants. This lets Orqen calibrate K from real data without storing raw prompts.

x-orqen-tools-input:  51
x-orqen-tools-output: 1
x-orqen-prune-ratio:  1/51
x-orqen-routing:      semantic

Best practice

Write tool descriptions with explicit scope: Use this when... andReturns.... Add x-orqen-examples when two tools have similar names or overlapping domains.

Continue to the Chat Completions API reference →