You've got two ways to connect an agent to your backend, and each one breaks somewhere different.

Wrap every endpoint as a tool and you keep flexibility: the agent can combine steps in ways nobody planned. It breaks when the job needs a long chain and the ordering rules live in the prompt. Build a few deep tools shaped around whole tasks and the steps run in code. That breaks when a job falls outside what you modelled. For exploratory or research agents, the flexibility can be worth the cost. For customer-facing automation that moves money, my default is deep tools.

The idea comes from John Ousterhout's A Philosophy of Software Design. A deep module puts a simple interface over a lot of hidden functionality. A shallow one hides very little, so the caller does the work. A 1:1 API wrapper is shallow, and the caller is now a probabilistic model.

That costs you three ways. Every schema sits in context on every turn: in Anthropic's example, 58 tools took about 55K tokens before the conversation started. Errors compound: cancelling a $29 subscription through thin tools is a six-step chain, and if you assume 92% per step (an assumption, not a measurement) you land near 60.6% end to end. And invariants leak into the prompt as "always call X before Y", which the model may skip.

The evidence is useful, but narrower than a clean curve. A Meta preprint, not yet peer-reviewed, found an adaptive shortlist averaging 2.2 tools picked the right tool 93.1% of the time when it was shown, against 87.1% for a fixed five. That measures shortlist length, not catalog size, and it doesn't test merged tools. None of the sources I could check is a controlled test of shallow versus deep. They do point the same way: more overlapping options make the right one harder to pick.

So split the work. The model understands the request, picks one high-level tool and shows the user a preview. The code handles authorization, locking, invariant checks and idempotent payments.

Deterministic doesn't mean correct, though. The model can still pick the wrong tool or pass the wrong email, and code repeats a bad proration rule just as reliably as a good one. You still need tests against the real business rules and explicit confirmation before a refund.

If you're reviewing a tool registry, I'd start with three things:

  • Merge tools that nearly always run in sequence.
  • Search the system prompt for "always call X before Y", turn each rule into a check inside the tool, then delete the sentence.
  • Record tool boundaries in an ADR, so no endpoint becomes a tool until someone's reviewed whether it belongs inside a deeper one.

The full article has the diagrams, sources and complete checklist: https://aiadvances.org/the-swiss-army-knife-trap-why-wrapping-every-api-as-an-agent-tool-backfires-45c917478da4