Enum ToolChoice

Namespace: LMKit.Agents.Tools

Assembly: LM-Kit.NET.dll

Specifies the mode of tool usage for an agent during a conversation turn.

public enum ToolChoice

Fields

Auto = 0

The agent may optionally call tools if it determines they would be helpful.

This is the recommended default for most scenarios. The model analyzes the user's request and decides whether calling a tool would provide a better answer. If no tool is needed, the model responds directly from its knowledge.

Best For:

General-purpose assistants
Mixed workloads (some requests need tools, others don't)
When you trust the model's judgment on tool relevance

Required = 1

The agent must call at least one tool before producing its final response.

Use this mode when responses must be grounded in external data. If the model attempts to respond without calling a tool, the runtime should re-prompt it or return an error.

Best For:

Data retrieval tasks (database queries, API calls)
Fact-checking and verification workflows
Tasks where hallucination must be prevented

Caution: If no appropriate tool exists for the query, the agent may be unable to respond meaningfully.

None = 2

Tools are disabled for this turn; the agent must respond without calling any tool.

This mode prevents all tool invocation, forcing the agent to rely solely on its training knowledge and the conversation context. Any tool calls attempted by the model should be blocked by the runtime.

Best For:

Creative writing and brainstorming
Conversational responses that don't need external data
When tools are temporarily unavailable or unsafe
Reducing latency by avoiding tool overhead

Specific = 3

The agent must call a specific tool (identified by name) before producing its response.

Use this mode when a particular workflow step must always execute. When Specific is selected, you must also set ForcedToolName to specify which tool to call.

Best For:

Guided multi-step workflows
Ensuring specific actions occur (e.g., logging, authentication)
Testing and debugging specific tools
Compliance requirements that mandate certain checks

The runtime should validate that the specified tool exists before prompting the model. If the tool is not found, an error should be raised.

Examples

Example: Using ToolChoice in different scenarios

using LMKit.Agents;
using LMKit.Agents.Tools;
using LMKit.Model;

using var model = new LM("path/to/model.gguf");

// Scenario 1: General assistant (Auto)
// The agent decides whether to use tools based on the question
var generalPolicy = new ToolCallPolicy { Choice = ToolChoice.Auto };

// Scenario 2: Data lookup assistant (Required)
// Force the agent to always query the database
var lookupPolicy = new ToolCallPolicy { Choice = ToolChoice.Required };

// Scenario 3: Creative writing assistant (None)
// Disable tools for pure text generation
var creativePolicy = new ToolCallPolicy { Choice = ToolChoice.None };

// Scenario 4: Guided workflow (Specific)
// Always start with user authentication
var workflowPolicy = new ToolCallPolicy
{
    Choice = ToolChoice.Specific,
    ForcedToolName = "authenticate_user"
};

Remarks

ToolChoice controls the agent's freedom to invoke registered tools. Use this enumeration with Choice to fine-tune agent behavior based on the task at hand.

Selecting the Right Mode

Mode	Use When
Auto	The user's request may or may not require external data or actions. Let the model decide.
Required	The response must be grounded in tool output (e.g., "What's my account balance?").
None	Tools should never be called (e.g., creative writing, brainstorming, or when tools are temporarily unavailable).
Specific	A particular tool must be called to initiate a workflow or ensure a specific action occurs.

Table of Contents

Enum ToolChoice

Fields

Examples

Remarks