# Tool Selection Errors

## The Problem

Agent chooses wrong tools or fails to use available tools effectively, leading to incomplete answers or inefficient processing.

### Symptoms

* ❌ Ignores available tools
* ❌ Uses wrong tool for task
* ❌ Calls tools in wrong order
* ❌ Calls same tool repeatedly
* ❌ Cannot combine tools effectively

### Real-World Example

```
Available tools:
→ search_knowledge_base()
→ get_user_permissions()
→ query_database()

Query: "What databases can I access?"

Correct approach:
1. get_user_permissions() → Get user's access rights
2. query_database(filter=permissions) → List accessible databases
3. Return filtered list

Agent chose:
1. search_knowledge_base("databases") → Generic database info
2. Return: "We have MySQL, PostgreSQL, MongoDB..."
→ Didn't use get_user_permissions()
→ Gave generic answer, not personalized

Tool selection error
```

***

## Deep Technical Analysis

### Tool Selection Logic

**Tool Matching:**

```
Agent must map query to appropriate tools:

Query intent → Tool:
→ "What can I access?" → get_user_permissions()
→ "Find documentation on X" → search_knowledge_base()
→ "Show me data about Y" → query_database()

Requires:
→ Understanding query intent
→ Knowing tool capabilities
→ Matching intent to tool
```

**Tool Descriptions:**

```
Provide clear tool descriptions:
{
  "name": "get_user_permissions",
  "description": "Retrieves current user's access permissions,
  team membership, and role. Use when query involves user-specific
  access, 'my', 'I', or permission-related questions.",
  "parameters": {...}
}

Better descriptions → Better selection
```

### Tool Combination Failures

**Sequential Dependencies:**

```
Query: "Show my team's recent projects"

Requires chain:
1. get_user_team() → Get user's team
2. get_team_projects(team_id) → Get team's projects
3. filter_by_date(projects, recent=true)

Agent must recognize:
→ Output of tool 1 feeds into tool 2
→ Cannot skip tool 1

Dependency: 2 depends on 1
```

**Parallel Tool Use:**

```
Query: "Compare Project A vs Project B"

Efficient approach:
→ Call get_project_info("A") and get_project_info("B") in parallel
→ Compare results

Inefficient:
→ Call sequentially (slower)

Agent should parallelize independent calls
```

### Tool Call Loops

**Redundant Calls:**

```
Agent calls:
1. search_knowledge_base("authentication")
2. search_knowledge_base("authentication")  ← duplicate
3. search_knowledge_base("auth")  ← slight variation

Problem:
→ Same tool, same/similar query
→ Wasted API calls
→ Inefficient

Should: Cache tool results, avoid duplicates
```

**Infinite Loops:**

```
Agent stuck:
1. query_database() → No results
2. Try different query
3. query_database() → Still no results
4. Try again...
→ Loop forever

Need: Loop detection, fallback strategy
```

### Tool Discovery

**Dynamic Tool Set:**

```
Tools available change by:
→ User role (admins have more tools)
→ Context (some tools only for certain queries)
→ Integration status (tool unavailable if service down)

Agent must:
→ Check available tools
→ Adapt to current tool set
→ Handle missing tools gracefully
```

**Tool Capability Awareness:**

```
Agent tries:
→ search_knowledge_base(filter_by_date=true)

But tool doesn't support date filtering:
→ Error

Agent should:
→ Know tool capabilities from schema
→ Not assume features
→ Validate before calling
```

### Fallback Strategies

**Tool Unavailable:**

```
Agent tries: get_user_permissions()
→ Service timeout

Fallback:
→ "I'm unable to retrieve your permissions right now.
   Would you like general information instead?"

Graceful degradation
```

**No Suitable Tool:**

```
Query: "What's the weather today?"
Available tools: Knowledge base, database, permissions

Agent recognizes:
→ No tool can answer this
→ Out of scope

Response:
"I can help with documentation, data access, and permissions.
I cannot provide weather information."

Clear boundaries
```

***

## How to Solve

**Provide clear tool descriptions (purpose, when to use) + implement intent-to-tool mapping logic + detect tool dependencies (sequential ordering) + parallelize independent tool calls + cache tool results to avoid duplicates + implement loop detection (max 3 same-tool calls) + handle tool errors with fallback strategies + validate tool capabilities before calling + test tool selection accuracy on eval queries + monitor tool usage patterns (identify selection errors).** See [Tool Selection](/rag-scenarios-and-solutions/agent/tool-selection.md).


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://help.twig.so/rag-scenarios-and-solutions/agent/tool-selection.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.