# 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. Version 1.0 · 2026-07-29 · 9 min ## 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 - Tool names describe stable capabilities; aliases absorb the language used by people and products. - Negative boundaries explain when a similar tool must not be selected. - Selection tests should include neighbouring tools, missing parameters and cases where no tool is appropriate. ## 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. ## A concise capability contract Write each mapping so a person can explain why it was selected over its closest neighbour. ### 1. Name 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. ### 2. State 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. ### 3. Minimise 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. ### 4. Map user language Attach product labels, common abbreviations and domain aliases to the canonical capability. Do not multiply tools only to cover synonyms. ### 5. Define result semantics Return typed success, empty, denied, invalid, partial and failed states where relevant. Keep user-facing progress and confirmation visible in the interface. ### 6. Scope, 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. ## Examples ### 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. ## Checklist 1. Every mapping has a stable capability name. 2. Purpose, positive conditions and negative boundaries are explicit. 3. The input schema is minimal and typed. 4. Identity, tenant and permissions are derived by the host. 5. Aliases reflect real product and user language. 6. Outputs distinguish operational result states. 7. Selection tests include close neighbours, paraphrases and no-tool cases. 8. Any retrieved selection is revalidated before execution. ## Limitations - 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 1. [AI Elements documentation](https://elements.ai-sdk.dev/docs) — Vercel, 2026; type: official-documentation. 2. [Tool Calling to Connect to External Data Sources](https://vercel.com/academy/ai-sdk/tool-use) — Vercel Academy, 2026; type: official-documentation. 3. [EASYTOOL: Enhancing LLM-based Agents with Concise Tool Instruction](https://arxiv.org/abs/2401.06201) — Yuan et al., 2024; type: research. 4. [ToolRet: Tool Retrieval for Large Language Models](https://aclanthology.org/2025.findings-acl.1258/) — ACL Findings, 2025; type: research. 5. [ToolRerank: Adaptive and Hierarchy-Aware Reranking for Tool Retrieval](https://aclanthology.org/2024.lrec-main.1413/) — LREC-COLING, 2024; type: research. ## 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. --- Canonical: https://scoperail.fokalabs.io/en/guides/concise-tool-mappings-for-ai Author: Ramzi Laieb, FokaLabs