The Definitive Guide to
Effective Agent Skills

from pydantic import BaseModel, Field
from langchain_core.tools import tool, ToolException

class WeatherQuery(BaseModel):
    city: str = Field(description="City name, e.g., 'San Francisco'")
    units: str = Field(default="celsius", description="'celsius' or 'fahrenheit'")

@tool("get_weather", args_schema=WeatherQuery,
      response_format="content_and_artifact")
def get_weather(city: str, units: str = "celsius"):
    """Retrieve current weather. Returns summary + full sensor data."""
    if not city.strip():
        raise ToolException("City name cannot be empty.")
    raw = {"city": city, "temp": 22, "humidity": 65}
    summary = f"Weather in {city}: {raw['temp']}° {units}"
    return summary, raw  # (LLM content, full artifact)

server.tool(
  "query_customer",
  "Retrieve customer records by ID or email.",
  {
    customerId: z.string().optional().describe("Unique UUID"),
    email: z.string().email().optional().describe("Customer email")
  },
  async ({ customerId, email }) => {
    try {
      const result = await db.query({ customerId, email });
      return { content: [{ type: "text", text: JSON.stringify(result) }] };
    } catch (err) {
      return {
        content: [{ type: "text", text: `Error: ${err.message}` }],
        isError: true  // Enables LLM self-correction
      };
    }
  }
);

{
  "type": "function",
  "function": {
    "name": "execute_readonly_sql",
    "description": "Execute read-only SELECT queries. Mutations rejected.",
    "parameters": {
      "type": "object",
      "properties": {
        "query": { "type": "string", "description": "PostgreSQL SELECT query." },
        "limit": { "type": "integer", "description": "Max rows (1-500)." },
        "reasoning": { "type": "string", "description": "Why this query." }
      },
      "required": ["query", "limit", "reasoning"],
      "additionalProperties": false
    },
    "strict": true
  }
}

def query_users(role: str = "all", limit: int = 20) -> str:
    """
    Search and list enterprise user accounts by role.

    WHEN TO USE:
    - Looking up user profiles, permissions, or listings.

    WHEN NOT TO USE:
    - Do NOT use for support tickets (use 'search_support_tickets').
    - Do NOT use for modifying accounts (use 'admin_manage_user').

    RETURNS:
    - JSON: {"users": [...], "total_count": 42, "has_more": true}

    EXAMPLES:
    - List admins: query_users(role="admin", limit=20)
    - Recent users: query_users(created_after="2024-01-01")
    """