PM-301e · Module 1

Writing Tool Descriptions

5 min read

The tool description is the most important field in the tool definition. The model uses it to answer one question: "Is this the right tool for the current task?" A vague description produces wrong answers to that question. A precise description produces correct answers.

Do This

  • "Search the customer database by name, email, or account ID. Returns customer profile including subscription tier, last activity date, and support ticket count. Use when the user asks about a specific customer."
  • State what the tool does, what input it needs, what it returns, and when to use it
  • Distinguish overlapping tools explicitly: "Use search_customers for lookups by identifier. Use list_customers for browsing all customers with filters."
  • Include explicit "do not use when" guidance for tools that might be misapplied

Avoid This

  • "Query the database"
  • "Get customer information"
  • Leaving when-to-use guidance implicit
  • Describing what the function does internally rather than what it provides to the model
// WEAK: Insufficient description causes wrong selection
{
  "name": "get_customer",
  "description": "Gets customer data from the database.",
  "parameters": {
    "type": "object",
    "properties": {
      "id": { "type": "string" }
    },
    "required": ["id"]
  }
}

// PRODUCTION: Complete specification drives correct selection
{
  "name": "get_customer_by_id",
  "description": "Fetch a complete customer profile by account ID. Returns: customer name, email, subscription tier (starter/pro/enterprise), account creation date, last activity timestamp, lifetime value, and open support ticket count. Use when you have a specific account ID and need the full profile. Do NOT use for searching by name or email — use search_customers instead.",
  "parameters": {
    "type": "object",
    "properties": {
      "account_id": {
        "type": "string",
        "description": "The unique account identifier (format: ACC-XXXXXX)"
      }
    },
    "required": ["account_id"]
  }
}