Build Your First AI Agent · Lesson 2 of 8

Lesson 2 — Tools and tool definitions

60 minutes. The vocabulary that lets the model know what it can do.

---

A tool in Claude's API is just a JSON object that describes what the function does, what arguments it takes, and what kind of arguments those are:

```json { "name": "read_customer_record", "description": "Look up a customer by email address and return their record from the CRM.", "input_schema": { "type": "object", "properties": { "email": { "type": "string", "description": "Customer email address" } }, "required": ["email"] } } ```

That's a tool. You pass an array of these to Claude. Now the model knows: when I need to look up a customer, I can request `read_customer_record({ email: "..." })`.

• Names what it does, not how. `read_customer_record` ≠ `db_query`. The model is choosing between tools by name and description, not by implementation.
• Describes the args in detail. The model uses the description to know when to call. Good: "Customer email address — must be the full email." Bad: "the email."
• Is small enough to compose. Three small focused tools beat one giant do-everything tool.

For the customer-reply agent we're building:

• `read_inbox` → returns N unread emails as a list
• `lookup_customer` → takes email, returns customer record or null
• `draft_reply` → takes email + customer record, returns draft text
• `log_action` → takes a proposed action, writes it to the audit table
• `request_approval` → takes a draft action, waits for human OK

In Lesson 3 we'll wire these into the tool-use loop.

→ Lesson 3 — The tool-use loop

Previous: Lesson 1 — What an agent actually is · Next: Lesson 3 — The tool-use loop