monolithic vs atomic tools, same task surface
monolithic (selection accuracy drops)
notes_do_everything({
action: "list" | "get" | "search"
| "create" | "update" | "delete",
target, options: {...}
problems:
- model picks action by string, not by tool name
- options: {} is untyped -> hallucinations
- description has to explain six behaviors
- impossible to disambiguate close-competitor cases
benchmarks on internal registries:
- 15-30 pp lower selection accuracy vs atomic
- higher hallucination rate on options payload
- harder retry recovery (which field was wrong?)
rule of thumb:
if action enum has > 3 values, split the tool.
if options has > 2 variant shapes, split the tool.
atomic (each tool one job)
notes_list(tag?)
"Use when user wants all or tag-filtered notes.
Do not use to read body; use notes_get."
notes_get(note_id)
"Use when user asks for a specific note body."
notes_search(query, limit?)
"Use when user searches by content keywords."
notes_create(title, body, tag?)
"Use when user writes a new note."
notes_update(note_id, title?, body?)
"Use when user edits an existing note."
notes_delete(note_id)
"Use when user explicitly deletes."
namespace: notes_*
- shared prefix = grouped in model context
- tight descriptions = reliable selection
- typed schemas = no argument hallucination
- +10 to +20 pp selection accuracy