Designing Tool Granularity: Few Big Tools vs Many Small Ones

Every tool-using system eventually confronts the same design question: how many tools should the agent have, and how much should each one do? A codebase that exposes a database has two extreme options — one `execute_query` tool that accepts arbitrary SQL, or thirty narrow tools like `get_user_by_id`, `list_orders_for_customer`, and `update_shipping_address`. Both are shipped in production systems today, and both fail in characteristic, predictable ways when applied to the wrong problem.

This is not a solved problem with a best-practice answer you can memorize. It is a trade-off with real costs on both sides — token overhead, selection accuracy, authorization granularity, and blast radius per mistake — and the right point on that spectrum depends on what the tools actually do, who calls them, and what happens when one of them is used wrong. This lesson gives you the criteria to make that call instead of a rule to apply blindly.

By the end, you will be able to look at a toolset — your own or someone else's — and say specifically which tools are too coarse, which are too fine, and what forces (not preferences) should decide the split. The `input_schema`, `name`, and `description` fields you have already been writing carry more design weight than they look like they do; this lesson is about using that weight deliberately.

Analogy🏏Cricket

🏏 Think of it like cricket: A T20 captain filling the death-overs slot has two philosophies available. One is to hand the ball to a single all-format weapon like Jasprit Bumrah for every situation — yorkers at the death, the new ball, a testing over to a set batter — and trust him to read the moment and adapt. The other is to carry five specialists: a new-ball swing bowler, a middle-overs spinner, a death-overs yorker specialist, a bouncer specialist, and a part-timer for a rain-shortened over. Bumrah-for-everything means the captain's decision is trivial — there is only one name to call — but Bumrah himself must silently decide, ball by ball, which of five jobs he is doing right now, and if he misreads the situation the damage is one bowler's whole spell. Five specialists means the captain's job gets harder — which of five near-identical spinners does Chinnaswamy's turning pitch actually call for — but each bowler's role is unambiguous and a bad over from the yorker specialist doesn't touch the others. Building a tool set is the same call: one tool that can do anything is trivial to name but hard to use correctly, while many narrow tools are each obvious alone but hard to choose between as the set grows. There is no universally correct bowling attack, only one suited to the match in front of you.