Designing Agent Tools

123456789101112
import { Tool, ToolParameter } from '@anthropic/sdk';

const createSupportTicketTool: Tool = {
  name: 'create_support_ticket',
  description: `Creates a new support ticket in the AWS-hosted helpdesk system.
    
    USE THIS TOOL WHEN:
    - User reports a new issue or problem
    - User requests help with a feature
    - User needs to escalate a concern
    
    DO NOT USE WHEN:

123456789101112
{
  "type": "object",
  "properties": {
    "action": {
      "type": "string",
      "enum": ["approve", "reject", "escalate", "defer"],
      "description": "Decision action for the request. approve: Grant the request immediately, notify user of success. reject: Deny the request, must provide rejection_reason. escalate: Forward to human reviewer for complex cases or policy exceptions. defer: Postpone decision, requires defer_until date and defer_reason."
    },
    "rejection_reason": {
      "type": "string",
      "enum": ["policy_violation", "insufficient_documentation", "budget_exceeded", "duplicate_request", "other"],
      "description": "Required when action is 'reject'. policy_violation: Request violates company policy (cite specific policy). insufficient_documentation: Missing required attachments or details. budget_exceeded: Requested amount exceeds available budget. duplicate_request: Similar request already exists. other: Requires custom explanation in rejection_notes."

123456789101112
const customerLookupTool: AgentTool = {
  name: 'lookup_customer',
  description: `Retrieves detailed customer information from the CRM database.

    PURPOSE: Find customer records by email, phone, or customer ID to answer 
    account-related questions or verify identity.

    CAPABILITIES:
    - Returns: name, email, phone, account status, subscription tier, 
      created date, last activity, support history summary
    - Search by: exact email, phone (any format), or customer ID
    - Data freshness: Real-time, reflects changes within 30 seconds

123456789101112
{
  "type": "object",
  "properties": {
    "customer_id": {
      "type": "string",
      "pattern": "^cust_[a-zA-Z0-9]{10,20}$",
      "description": "Unique customer identifier. Format: cust_ followed by 10-20 alphanumeric characters. Example: cust_abc123def456"
    },
    "date_range": {
      "type": "object",
      "properties": {
        "start": {

123456789101112
enum ErrorCategory {
  TRANSIENT = 'transient',
  INPUT = 'input',
  STATE = 'state',
  PERMISSION = 'permission',
  SYSTEM = 'system'
}

interface ClassifiedError {
  category: ErrorCategory;
  originalError: Error;
  recoveryHint: string;

123456789101112
// Primitive tools - single responsibility
const primitiveTools = {
  getCustomer: {
    name: 'get_customer',
    description: 'Retrieve customer record by ID. Returns customer details or null if not found.',
    execute: async (params: { customerId: string }) => {
      return await db.customers.findById(params.customerId);
    }
  },
  
  calculateInvoice: {
    name: 'calculate_invoice',

123456789101112
from typing import Optional, List
from pydantic import BaseModel, Field, validator
from enum import Enum
import structlog
import time

logger = structlog.get_logger()

class ToolError(Exception):
    """Base exception for tool errors with structured context"""
    def __init__(self, message: str, error_code: str, recoverable: bool = True, 
                 suggested_action: Optional[str] = None):

123456789101112
{
  "name": "search_knowledge_base",
  "description": "Searches the company knowledge base for articles, documentation, and FAQs. Returns relevant excerpts with source links. Use this tool when users ask questions about products, policies, or procedures. Results are ranked by relevance and recency.",
  "parameters": {
    "type": "object",
    "properties": {
      "query": {
        "type": "string",
        "description": "Natural language search query. Be specific and include key terms. Example: 'return policy electronics 30 days' not just 'returns'",
        "minLength": 3,
        "maxLength": 200
      },

123456789101112
from prometheus_client import Counter, Histogram, Gauge
import functools
import time

# Define metrics
TOOL_INVOCATIONS = Counter(
    'agent_tool_invocations_total',
    'Total tool invocations',
    ['tool_name', 'status', 'error_code']
)

TOOL_DURATION = Histogram(