Give the model a tool map, not an API manual.
Map business intent to stable tool names, minimal schemas, aliases, negative boundaries and testable result semantics.
Short answer
A useful tool mapping is short enough to compare and precise enough to exclude the wrong call. Give each capability a stable action name, one clear purpose, positive and negative use conditions, a minimal input schema and explicit result states. Add the words users actually employ as aliases, but keep the canonical tool name stable. Use 5, 50 and 500 as teaching ranges: expose the eligible map at small scale, scope by role and workflow at medium scale, then retrieve and rerank mappings at large scale. The executor still validates the selected operation. Test close neighbours and non-use cases, not only obvious prompts.
Key points
- 01
Tool names describe stable capabilities; aliases absorb the language used by people and products.
- 02
Negative boundaries explain when a similar tool must not be selected.
- 03
Selection tests should include neighbouring tools, missing parameters and cases where no tool is appropriate.
01 / SITUATION
Long documentation can hide the one distinction the model needs
Internal APIs are often documented for developers. They include transport details, historical options and implementation vocabulary. A model choosing an operation needs a different view: what this capability does, when it applies, what it requires and how its result should be interpreted.
Copying an API manual into context increases noise without creating a good catalogue. The mapping layer turns technical interfaces into concise product capabilities while preserving a direct link to the schema and executor that remain authoritative.
02 / MECHANISM
A concise capability contract
Write each mapping so a person can explain why it was selected over its closest neighbour.
- 01Name the capability
Use a stable verb and business object such as get_work_order or propose_invoice_correction. Avoid internal service names and vague verbs like handle.
- 02State when and when not
Write one direct purpose, the conditions for use and the nearest exclusion. Distinguish read, propose and execute tools in the name and description.
- 03Minimise the schema
Require only inputs the operation truly needs. Use enums and clear field descriptions where they reduce ambiguity; derive identity and scope from the host.
- 04Map user language
Attach product labels, common abbreviations and domain aliases to the canonical capability. Do not multiply tools only to cover synonyms.
- 05Define result semantics
Return typed success, empty, denied, invalid, partial and failed states where relevant. Keep user-facing progress and confirmation visible in the interface.
- 06Scope, rank and test
Expose all eligible mappings at small scale, filter deterministically as the catalogue grows and retrieve plus rerank at large scale. Execute tests against controlled fixtures.
03 / In real work
Work order lookup
get_work_order reads one authorised record. search_work_orders finds candidates. Their descriptions explain that neither creates or changes an intervention.
Invoice correction
propose_invoice_correction returns editable fields and evidence. post_invoice is a separate, restricted operation with its own confirmation and invariants.
Ticket intake
prepare_support_ticket accepts the user’s goal and validated context. submit_support_ticket requires a confirmed proposal and returns the canonical tracker identifier.
Common failure modes
- Passing raw vendor documentation as the tool catalogue.
- Using overlapping names and descriptions that differ only by one noun.
- Making every API field optional and asking the model to infer hidden requirements.
- Returning untyped text that cannot distinguish empty, denied and failed.
- Testing only prompts that repeat the exact tool name.
Implementation checklist
- Every mapping has a stable capability name.
- Purpose, positive conditions and negative boundaries are explicit.
- The input schema is minimal and typed.
- Identity, tenant and permissions are derived by the host.
- Aliases reflect real product and user language.
- Outputs distinguish operational result states.
- Selection tests include close neighbours, paraphrases and no-tool cases.
- Any retrieved selection is revalidated before execution.
What this approach does not claim
- A concise mapping can omit an important edge case if it is not reviewed with the operation owner.
- Research on tool instructions does not guarantee the same gains for a private catalogue or another model.
- The five, fifty and five-hundred ranges are teaching heuristics; overlap and description quality determine actual difficulty.
Sources and reference types
- 01AI Elements documentationVercel · 2026Official documentation
- 02Tool Calling to Connect to External Data SourcesVercel Academy · 2026Official documentation
- 03EASYTOOL: Enhancing LLM-based Agents with Concise Tool InstructionYuan et al. · 2024Research
- 04ToolRet: Tool Retrieval for Large Language ModelsACL Findings · 2025Research
- 05ToolRerank: Adaptive and Hierarchy-Aware Reranking for Tool RetrievalLREC-COLING · 2024Research
Practical questions
Should tool descriptions include examples?
Use a small number when they clarify a boundary or parameter. Large example sets belong in tests or retrieval, not in every prompt.
How should aliases be represented?
Keep one canonical capability and attach the terms used in screens, documentation and user requests as searchable metadata or examples.
When should a tool mapping be versioned?
Whenever its meaning, schema, result states or eligibility changes. Re-run selection and execution evaluations with the new version.