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

## 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

## 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

## 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:

{
  "e": { "type": "str", "description": "email" },
  "n": { "type": "str", "description": "name" }
}

Strong:

{
  "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:

{
  "date": {
    "type": "str",
    "description": "The date"
  }
}

Strong:

{
  "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:

{
  "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

{
  "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:

{
  "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

## 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)

## 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

## 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

## 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:

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:

{
  "user_id": { "type": "str", "description": "The user ID" }
}

Solution: Explain where to get it:

{
  "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:

{
  "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

{
  "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

{
  "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 — Tools overview
• Agent Best Practices — Design patterns