Module 4: Tool Design and Integration

Lesson 4: Input/Output Schema Clarity

Inside the model, Claude doesn't "See" your variables. It sees JSON. If your tool definitions use ambiguous schemas, Claude will try to "Guess" the right format. Our goal as Architects is to eliminate "Guessing" and replace it with Constraints.

In this lesson, we master the JSON Schema features that provide the highest reliability for tool calling.

---

1. The "Required" Field (The "Stick")

Always explicitly define which parameters are non-negotiable.

• Weak Schema: { "city": "string", "country": "string" }
• Architect Schema: { "type": "object", "properties": { ... }, "required": ["city"] }

By making city required, you tell Claude: "Do not call this tool until you have found a city name in the user's message." This prevents "Missing Argument Errors."

---

2. Using Enums (The "List")

If a parameter has a fixed set of choices, use an Enum. Never leave a categorical field as a generic "String."

• Bad: category: string
• Good: category: { "type": "string", "enum": ["Support", "Sales", "Inquiry"] }

Enums are the most powerful way to prevent hallucinations. Claude cannot "Invent" a new category if you have strictly defined the list.

---

3. The Power of "Descriptions" within Properties

Most developers describe the tool, but forget to describe the parameter.

• Bad: "start_date": { "type": "string" }
• Good: "start_date": { "type": "string", "description": "The ISO-8601 formatted date string, e.g., 2023-01-20. Must not be in the future." }

This description acts as a Local Prompt for that specific variable.

---

4. Output Schema: What does the agent get back?

In Lesson 3, we discussed error feedback. But for "Success" cases, your output should also be Structured.

If a tool returns raw HTML or a 5MB text block, the agent is "Blinded" by noise.

• Architect's Strategy: Return a clean, summarized JSON object.
• Tool Result: {"summary": "Found 5 items", "item_ids": [101, 102, 103], "status": "success"}

This allows the agent to consume the result without blowing its context window.

---

5. Summary

• Use required to force data collection.
• Use enum to constrain choices.
• Use description on every property to provide local guidance.
• Keep outputs summarized and structured.

In the final lesson of this module, we look at the safety of these actions: Idempotency and Side-effect Control.

---

Interactive Quiz

1. Why are enums better than strings for tool parameters?
2. What happens if Claude calls a tool and misses a required parameter?
3. How can you use a property description to enforce a date format?
4. Write a JSON schema for a schedule_meeting tool that requires start_time (string) and attendees (array of strings).

---

Reference Video: