> ## Documentation Index
> Fetch the complete documentation index at: https://ago.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Writing Tool Descriptions

> Write tool descriptions that help agents use tools effectively

Clear tool descriptions help your AI agents pick the right tool and call it correctly. This page covers techniques for writing descriptions, prompts, and input schemas.

## How Tool Descriptions Affect Agent Behavior

Tool descriptions are the primary way the LLM understands when and how to use a tool. Poor descriptions lead to:

* Tools not being called when they should
* Tools being called inappropriately
* Incorrect parameter values being passed
* Frustrated users and failed interactions

Well-crafted descriptions ensure:

* Reliable tool activation
* Correct parameter extraction from user input
* Appropriate tool selection when multiple tools could apply
* Better user experiences

***

## The Three Key Elements

Every tool has three elements that guide LLM behavior:

| Element          | Purpose                                              | Where Used                      |
| ---------------- | ---------------------------------------------------- | ------------------------------- |
| **Description**  | What the tool does (for tool selection)              | Tool model `description` field  |
| **Prompt**       | When and how to use the tool (detailed instructions) | Tool model `prompt` field       |
| **Input Schema** | What parameters are needed and why                   | Tool model `input_schema` field |

All three must work together for reliable tool usage.

***

## Writing Effective Tool Descriptions

### Be Specific About Purpose

The `description` field helps the LLM choose between tools.

**Weak:**

```
Gets user information
```

**Strong:**

```
Retrieves customer profile information including name, email, subscription status,
and account creation date from the CRM system.
```

### Include Key Triggers

Mention the types of questions or requests that should trigger the tool:

**Weak:**

```
Creates tickets
```

**Strong:**

```
Creates a support ticket to escalate the conversation to a human agent.
Use when the customer explicitly requests human assistance, when issues
require account-level access, or when the customer remains frustrated
after troubleshooting attempts.
```

### Distinguish From Similar Tools

If you have multiple similar tools, make distinctions clear:

**Tool 1:**

```
Searches the product documentation knowledge base for feature explanations,
how-to guides, and configuration instructions.
```

**Tool 2:**

```
Searches the troubleshooting knowledge base for error messages, known issues,
and their solutions.
```

***

## Writing Effective Tool Prompts

The `prompt` field provides detailed instructions for tool usage. This is where you add nuance and context.

### Structure Your Prompt

```markdown theme={null}
## When to Use
[Specific scenarios that should trigger this tool]

## When NOT to Use
[Scenarios where another approach is better]

## Parameter Guidelines
[How to extract and format parameters]

## Response Handling
[How to present results to users]
```

### Example: Ticketing Tool Prompt

```markdown theme={null}
## When to Use This Tool

Use the ticketing tool ONLY in these situations:

1. **Explicit Human Request**: User says "talk to a human", "speak with support",
   "I want a real person", or similar phrases
2. **Complex Account Issues**: User needs account changes you cannot verify or perform
3. **Repeated Frustration**: User has tried your suggestions 3+ times without success
4. **Sensitive Topics**: Refunds over $50, legal inquiries, compliance questions

## When NOT to Use This Tool

- User just has a question you can answer from knowledge base
- User is mildly frustrated but hasn't asked for human help
- Issue can be resolved with available information
- User is just venting but doesn't need human intervention

## Before Creating a Ticket

1. Summarize what you've already tried to help
2. Ask if they'd like you to create a support ticket
3. Collect any missing required information (email, issue description)

## After Creating a Ticket

1. Confirm the ticket was created with the ticket ID
2. Set expectations for response time
3. Offer to continue helping while they wait
```

### Example: HTTP API Tool Prompt

```markdown theme={null}
## When to Use This Tool

Use this tool when:
- User asks about their order status and provides an order number
- User wants to track a shipment
- User needs real-time inventory information

## Parameter Extraction

- **order_id**: Extract from user message. Valid formats: ORD-XXXXX or just the 5-digit number
- **email**: Use the user's authenticated email if available, otherwise ask for it

## Response Handling

The API returns JSON with shipping status. Present it as:
- Current status (Processing, Shipped, Delivered)
- Estimated delivery date in user-friendly format (not ISO)
- Tracking link if available

If the API returns an error, explain that you couldn't retrieve the information
and offer to create a support ticket.
```

***

## Input Schema Best Practices

### Use Descriptive Parameter Names

**Weak:**

```json theme={null}
{
  "e": { "type": "str", "description": "email" },
  "n": { "type": "str", "description": "name" }
}
```

**Strong:**

```json theme={null}
{
  "customer_email": {
    "type": "str",
    "description": "Customer's email address for sending the receipt"
  },
  "customer_name": {
    "type": "str",
    "description": "Customer's full name as it should appear on the receipt"
  }
}
```

### Write Detailed Parameter Descriptions

Descriptions should explain:

* What the parameter represents
* Expected format
* Where to get the value
* Any constraints

**Weak:**

```json theme={null}
{
  "date": {
    "type": "str",
    "description": "The date"
  }
}
```

**Strong:**

```json theme={null}
{
  "appointment_date": {
    "type": "str",
    "description": "Appointment date in YYYY-MM-DD format. Extract from user's natural language date (e.g., 'next Tuesday' becomes the actual date). Must be a future date."
  }
}
```

### Use Enums for Constrained Values

When parameters have limited valid values, use enums:

```json theme={null}
{
  "priority": {
    "type": "str",
    "enum": ["low", "medium", "high", "urgent"],
    "default": "medium",
    "description": "Ticket priority. Use 'urgent' only for business-critical issues affecting multiple users."
  }
}
```

### Provide Helpful Defaults

```json theme={null}
{
  "language": {
    "type": "str",
    "enum": ["en", "fr", "de", "es"],
    "default": "en",
    "description": "Response language. Default to the user's conversation language if detectable."
  }
}
```

### Handle Complex Data Types

For arrays and objects, be explicit about structure:

```json theme={null}
{
  "items": {
    "type": "str",
    "description": "JSON array of product IDs to check inventory. Example: [\"SKU-123\", \"SKU-456\"]. Maximum 10 items."
  }
}
```

***

## Patterns for Common Tool Types

### Search Tools

```markdown theme={null}
## Description
Searches the [specific knowledge area] for [types of content]. Returns the most
relevant documents based on semantic similarity.

## Prompt
Use this search tool when:
- User asks a specific question about [topic area]
- You need to verify information before answering
- User asks "how do I..." or "what is..."

Search query guidelines:
- Convert user question to key concepts
- Remove conversational words ("Can you tell me", "I want to know")
- Include specific product names or features mentioned

After receiving results:
- Synthesize information from multiple results if needed
- Cite the source document when providing information
- If no relevant results, acknowledge and offer alternatives
```

### Action Tools (Create/Update/Delete)

```markdown theme={null}
## Description
Creates a new [resource] with the specified parameters. This action [consequences].

## Prompt
ALWAYS confirm before creating:
1. Summarize what will be created
2. Ask "Should I proceed with creating this?"
3. Only call the tool after explicit confirmation

Required information before creating:
- [field 1]: [how to obtain]
- [field 2]: [how to obtain]

If any required information is missing, ask for it before calling the tool.

After successful creation:
- Confirm what was created
- Provide reference number/ID
- Explain next steps
```

### External API Tools

```markdown theme={null}
## Description
Calls the [Service Name] API to [action]. Requires [authentication/parameters].

## Prompt
Use this tool when:
- [specific trigger scenario 1]
- [specific trigger scenario 2]

Before calling:
- Validate that user has provided necessary identifiers
- Format parameters according to API requirements

Error handling:
- 404 errors: "I couldn't find [resource] with that ID. Please verify the [identifier]."
- 401/403 errors: "I don't have access to retrieve this information. Let me create a support ticket."
- Timeout: "The service is taking longer than expected. Would you like me to try again?"
```

### Multi-Step Tools

```markdown theme={null}
## Description
[First step], then [second step], and finally [third step].

## Prompt
This tool performs multiple actions in sequence:

Step 1: [Action]
- What happens
- What's needed

Step 2: [Action]
- What happens
- Depends on Step 1 results

Step 3: [Action]
- Final outcome

If any step fails, explain which step failed and what the user can do.
```

***

## Testing Your Tool Descriptions

### Test Scenarios

| Scenario             | Test Goal                             |
| -------------------- | ------------------------------------- |
| Direct request       | Tool activates when explicitly needed |
| Indirect need        | Tool activates from context clues     |
| Similar alternatives | Correct tool chosen among options     |
| Missing parameters   | Agent asks for missing info           |
| Edge cases           | Tool handles unusual inputs           |
| Negative cases       | Tool NOT called inappropriately       |

### Example Test Prompts

For a ticketing tool:

| User Message                  | Expected Behavior          |
| ----------------------------- | -------------------------- |
| "I want to speak to a human"  | Create ticket              |
| "This is frustrating"         | Do NOT create ticket (yet) |
| "Can you create a ticket?"    | Confirm, then create       |
| "Transfer me to support"      | Create ticket              |
| "How do I reset my password?" | Use knowledge, not ticket  |

### Iterative Improvement

```
1. Write initial description and prompt
2. Run simulation tests
3. Identify failure patterns:
   - Tool not called when should be
   - Tool called when shouldn't be
   - Wrong parameters passed
4. Refine descriptions based on patterns
5. Re-test and compare
```

***

## Common Mistakes to Avoid

### Too Generic

**Problem:**

```
description: "Helps users"
prompt: "Use when helpful"
```

**Solution:** Be specific about what, when, and how.

### Conflicting Instructions

**Problem:**

```
description: "Create tickets for all user issues"
prompt: "Only create tickets as a last resort"
```

**Solution:** Ensure description and prompt are aligned.

### No Negative Cases

**Problem:** Only describing when TO use the tool.

**Solution:** Also describe when NOT to use it:

```markdown theme={null}
Do NOT use this tool when:
- User has not yet tried the suggested solutions
- Question can be answered from documentation
- User is just asking a general question
```

### Missing Parameter Context

**Problem:**

```json theme={null}
{
  "user_id": { "type": "str", "description": "The user ID" }
}
```

**Solution:** Explain where to get it:

```json theme={null}
{
  "user_id": {
    "type": "str",
    "description": "User's account ID. Use the authenticated user's ID if available. Otherwise, ask the user for their account ID or email to look it up."
  }
}
```

### Assuming Perfect Input

**Problem:** Not handling variations in user input.

**Solution:** Include format guidance:

```json theme={null}
{
  "phone_number": {
    "type": "str",
    "description": "User's phone number. Accept any format (with or without country code, dashes, spaces). Normalize to E.164 format before calling."
  }
}
```

***

## Examples Gallery

### Product Lookup Tool

```json theme={null}
{
  "name": "product_lookup",
  "display_name": "Product Lookup",
  "description": "Looks up product details including price, availability, specifications, and compatible accessories by product name or SKU.",
  "prompt": "## When to Use\nUse when the user:\n- Asks about a specific product by name or SKU\n- Wants to know price, availability, or specs\n- Asks 'Do you have...' or 'How much is...'\n\n## Parameter Extraction\n- product_query: Use the product name or SKU exactly as the user stated it\n- include_accessories: Set to true if user asks about compatible items or 'what goes with'\n\n## Response Format\nPresent results as:\n- Product name and SKU\n- Price (formatted with currency)\n- Availability status\n- Key specifications (bulleted list)\n- Accessories (if requested)\n\nIf product not found, suggest searching with different terms or browsing categories.",
  "input_schema": {
    "product_query": {
      "type": "str",
      "description": "Product name or SKU to look up. Examples: 'MacBook Pro 14', 'SKU-12345', 'wireless headphones'"
    },
    "include_accessories": {
      "type": "bool",
      "default": false,
      "description": "Whether to include compatible accessories in the results"
    }
  }
}
```

### Appointment Booking Tool

```json theme={null}
{
  "name": "book_appointment",
  "display_name": "Book Appointment",
  "description": "Books a customer appointment for service, consultation, or support. Checks availability and creates calendar entry.",
  "prompt": "## When to Use\nUse when the user wants to:\n- Schedule an appointment\n- Book a consultation\n- Reserve a time slot\n- Meet with a representative\n\n## Required Information\nBefore calling, ensure you have:\n1. Appointment type (service, consultation, support)\n2. Preferred date and time\n3. Customer contact info (email at minimum)\n\nIf any is missing, ask for it.\n\n## Handling Unavailability\nIf the requested time is unavailable:\n1. Show 3 alternative times closest to their preference\n2. Ask which works best\n3. Call tool again with selected time\n\n## Confirmation\nAfter successful booking:\n- Confirm date, time, and type\n- Provide confirmation number\n- Mention confirmation email will be sent\n- Explain cancellation/rescheduling policy",
  "input_schema": {
    "appointment_type": {
      "type": "str",
      "enum": ["service", "consultation", "support"],
      "description": "Type of appointment to book"
    },
    "preferred_datetime": {
      "type": "str",
      "description": "Preferred date and time in ISO 8601 format. Convert natural language like 'tomorrow at 2pm' or 'next Monday morning' to actual datetime."
    },
    "customer_email": {
      "type": "str",
      "description": "Customer's email for confirmation. Use authenticated user's email if available."
    },
    "notes": {
      "type": "str",
      "description": "Any special requests or context for the appointment. Optional."
    }
  }
}
```

***

## Quick Reference Checklist

Before deploying a tool, verify:

* [ ] **Description** clearly explains what the tool does
* [ ] **Description** mentions key trigger scenarios
* [ ] **Prompt** specifies when TO use the tool
* [ ] **Prompt** specifies when NOT to use the tool
* [ ] **Prompt** explains how to handle results
* [ ] **Prompt** covers error scenarios
* [ ] **Parameters** have descriptive names
* [ ] **Parameters** have detailed descriptions
* [ ] **Parameters** specify formats when relevant
* [ ] **Enums** used for constrained values
* [ ] **Defaults** provided where appropriate
* [ ] Tool tested with simulation scenarios

***

## Related

* [Tools](../features/tools) — Tools overview
* [Agent Best Practices](./agent-best-practices) — Design patterns