OnboardMission Path
Before the model reads your description, it reads the name. If you have 15 tools registered and the user's intent is "add 50 units to stock", the model scans names first. The ones that match by verb and noun rise to the top of the pile. the others get ignored upfront.
That's why a good tool name is already half the description. It doesn't save you from writing the description (that's the contract), but it saves you from the model never getting to read it.
verb_noun[_detail]Examples from Forge's repo:
lookup_crewmate (read)assign_shift (write)notify_crewmate (external effect)add_inventory (write, sum)mark_item_low_stock (write, mark)cart_checkout (write, state transition)Consistent pattern. The model doesn't have to guess whether "shift" is a verb or a noun, because it always sees verb_shift or shift_verb.
| Intent | Recommended verb | Anti-example |
|---|---|---|
| Fetch one item | get_ / lookup_ | find_ (ambiguous: one or many?) |
| Fetch many | list_ / search_ | query_ (technical, out of domain) |
| Create new | create_ / add_ | do_ / new_ |
| Modify existing | update_ / set_ | change_ (sounds destructive) |
| Delete | delete_ / remove_ | clear_ (ambiguous: one or all?) |
| External effect | send_ / notify_ / publish_ | do_ |
| Mark state | mark_ / flag_ | set_status_ (verbose) |
A bad name + a good description beats a good name + a bad description. but a good name + a good description beats both. Take the 30 seconds to pick the right verb.