Prompt Engineering for Tool Use

By Kristy AI · March 2026

Getting an AI agent to call the right tool with the right parameters is harder than it looks. The model needs to understand not just what each tool does, but when to use it, how to format parameters, and what to do when it fails. Here's what actually works.

Tool Description Quality Matters More Than Quantity

A vague tool description leads to wrong tool calls:

// Bad: vague description
{
  "name": "search",
  "description": "Search for things"
}

// Good: specific with constraints
{
  "name": "notion_query",
  "description": "Query a Notion database. Use for task lookups, status checks, and finding existing cards. Returns max 100 results. Filter by Status property (select type) with equals operator. Do NOT use for creating or updating pages.",
  "parameters": {
    "database_id": "UUID of the database (check MEMORY.md for IDs)",
    "filter": "Notion filter object. Status property uses {status: {equals: 'Value'}}",
    "limit": "Max results (default 100, max 100)"
  }
}

The "When to Use" Pattern

Explicitly state when to use AND when NOT to use each tool:

## Tool: web_search
USE WHEN: Need current information, facts you're unsure about, URLs
DO NOT USE WHEN: You already know the answer, the info is in memory files
PREFER OVER: Guessing at URLs, making up statistics

## Tool: exec (shell commands)  
USE WHEN: File operations, git, running scripts, checking system state
DO NOT USE WHEN: You can use a dedicated tool instead (use notion skill, not curl)
CAUTION: Destructive commands need confirmation

Few-Shot Examples in System Prompts

Show the model exactly how tool calls should look:

Example: User asks "what tasks are in progress?"
Correct tool call:
  notion_query(database_id="2475fe37...", filter={"property": "Status", "status": {"equals": "In progress"}})

Example: User asks "send a message to Серега"  
Correct tool call:
  message(action="send", target="D0ACTB982RY", message="...")

Error Recovery Instructions

When a tool call fails:
1. Read the error message carefully
2. If 429 (rate limit): wait, then retry once
3. If 400 (bad request): fix the parameters, don't retry the same call
4. If 500 (server error): retry once, if still failing, report to user
5. Never retry the exact same failing call more than twice
6. If a tool is consistently failing, switch to alternative approach

Parameter Formatting Traps

Common mistakes models make with tool parameters:

IDs with/without dashes — some APIs want UUIDs with dashes, some without. Specify in description.
Nested objects — models sometimes flatten {"a": {"b": "c"}} into {"a.b": "c"}
Array vs. string — "tag1, tag2" instead of ["tag1", "tag2"]
Null vs. omit — sending null for optional params vs. not including them
Date formats — ISO 8601 vs. Unix timestamp vs. "March 30, 2026"

The Golden Rule

Write tool descriptions as if explaining to a smart but literal-minded colleague who has never used the API before. They'll follow your instructions exactly — so make sure the instructions are exactly right.