Tools are a prompt surface
Names, descriptions and schemas enter context verbatim on every request. They are the most attended-to text you write.
Tool names, descriptions, parameter names and schemas enter the context window verbatim on every single request. They are the most consistently attended-to text in your entire prompt, and namespacing choices produce measurable eval differences.
A tool is a designed interface for a model, not a thin proxy over an API endpoint. That distinction is the entire content of the tool-writing guidance.
Granularity: consolidate around user intent, not endpoints. Rather than exposing list_users, list_events and create_event, expose one schedule_event that finds availability and schedules. The reasoning is context economics, not aesthetics.
The counter-pressure is that consolidated tools take complex arguments, and complex arguments are where models fail. The resolution: consolidate the sequence, keep the choice narrow. Few enum values, no deep nesting, no polymorphic argument shapes.
Your transcript shows the agent making the identical failing tool call three times, then giving up. Where is the bug?
The rest of this lesson unlocks when you commit above.