# Writing tool descriptions: the prompt your agent never reads [Skip to content](#lm-inhoud)Network/[NL](/en/tool-descriptions-schrijven-de-prompt-die-je-agent-niet-leest)EN[Hubhub.llmnet.nlCompare models on task, language, cost and license.](https://hub.llmnet.nl/en/)[Communitycommunity.llmnet.nlPrompt techniques, patterns and system prompts.](https://community.llmnet.nl/en/)[APIapi.llmnet.nlLLMs in production: rate limits, routing, structured output.](https://api.llmnet.nl/en/)[Consultancyconsultancy.llmnet.nlRolling out AI in an organization, pilot to production.](https://consultancy.llmnet.nl/en/)[Newsnieuws.llmnet.nlAI developments, explained for the Netherlands.](https://nieuws.llmnet.nl/en/)[Benchmarkbenchmark.llmnet.nlMeasure AI quality yourself, on your own tasks.](https://benchmark.llmnet.nl/en/)[Careersvacatures.llmnet.nlAI roles, salaries and career paths in the Netherlands.](https://vacatures.llmnet.nl/en/)[Learnleren.llmnet.nlAI concepts in plain language, beginner to builder.](https://leren.llmnet.nl/en/)[Guidegids.llmnet.nlRun AI privately on your own Mac, PC, NAS or home server.](https://gids.llmnet.nl/en/)[Directorydirectory.llmnet.nlMapping the AI ecosystem: tools, models, companies.](https://directory.llmnet.nl/en/)[Radarradar.llmnet.nlSignals from X, research and communities for indie developers.](https://radar.llmnet.nl/en/)[Appsapps.llmnet.nlReviews of AI apps and open-source repos, with tips for builders.](https://apps.llmnet.nl/en/)[llmnet.nl — main site](https://llmnet.nl/en/)[](https://x.com/intent/post?url=https%3A%2F%2Fcommunity.llmnet.nl%2Fen%2Ftool-descriptions-schrijven-de-prompt-die-je-agent-niet-leest&text=Writing%20tool%20descriptions%3A%20the%20prompt%20your%20agent%20never%20reads)[](https://www.linkedin.com/sharing/share-offsite/?url=https%3A%2F%2Fcommunity.llmnet.nl%2Fen%2Ftool-descriptions-schrijven-de-prompt-die-je-agent-niet-leest)[](https://www.reddit.com/submit?url=https%3A%2F%2Fcommunity.llmnet.nl%2Fen%2Ftool-descriptions-schrijven-de-prompt-die-je-agent-niet-leest&title=Writing%20tool%20descriptions%3A%20the%20prompt%20your%20agent%20never%20reads)[](#)[](https://x.com/intent/post?url=https%3A%2F%2Fcommunity.llmnet.nl%2Fen%2Ftool-descriptions-schrijven-de-prompt-die-je-agent-niet-leest&text=Writing%20tool%20descriptions%3A%20the%20prompt%20your%20agent%20never%20reads)[](https://www.linkedin.com/sharing/share-offsite/?url=https%3A%2F%2Fcommunity.llmnet.nl%2Fen%2Ftool-descriptions-schrijven-de-prompt-die-je-agent-niet-leest)[](https://www.reddit.com/submit?url=https%3A%2F%2Fcommunity.llmnet.nl%2Fen%2Ftool-descriptions-schrijven-de-prompt-die-je-agent-niet-leest&title=Writing%20tool%20descriptions%3A%20the%20prompt%20your%20agent%20never%20reads)[](#) # Writing tool descriptions: the prompt your agent never reads By Ivo Donker — compiled with AI assistance · August 7, 2026 When a Large Language Model (LLM) decides to call an external tool, it does not look at the underlying Python code, the REST API implementation, or the function's internal logic. The model sees only the JSON schema definition and the accompanying textual description (the description). In agentic systems, a poor tool description turns out to be by far the most common cause of failed tool calls, incorrect argument values, or unwanted side effects. Without a clear and unambiguous description, the agent is left in the dark. This article covers systematically writing effective tool descriptions, the balance between token budget and precision, and how to test and maintain these descriptions as full-fledged code artifacts. ## 1. Why the description is the crucial link In a traditional software architecture, a developer calls a function directly via an explicit signature and type definition. In agent-based systems, the language model acts as the dynamic router. Based on the user context and the list of available tools, the agent decides what action to take. Since the code behind the scenes is invisible to the model, the description forms the only interface between the agent's intent and the code's execution. When a tool description contains vague or incomplete information, three specific failure patterns arise: - Incorrect tool selection: The agent chooses the wrong tool for a task, or ignores the tool precisely when it is actually needed. - Invalid or incorrect arguments: The model guesses the format of parameters, such as passing a date as a UNIX timestamp instead of an ISO 8601 string, or omitting required units. - Unexpected side effects: The agent calls an expensive or irreversible write action without the model realizing that the operation makes permanent changes. In the article on [prompt patterns for agents](https://community.llmnet.nl/en/prompt-patronen-voor-agents) we cover the general calling patterns of tools, but the quality of the individual tool description ultimately determines whether those patterns hold up in practice. ## 2. The three core tasks of a tool description A well-formulated description fulfills three distinct tasks within the context of an agentic loop: ### a. Deciding whether the tool is relevant The model must judge within a fraction of a second whether a specific tool matches the current intermediate step. The description must therefore make clear in the very first sentence what the primary function is and, just as importantly, when the tool should explicitly not be used. This prevents tools with overlapping functionality from competing with each other. ### b. Filling in arguments correctly Although JSON schemas enforce data types (such as string or integer), standard schemas often fall short for semantic restrictions. The description must explain the exact meaning of a parameter, what range is allowed, and in which unit values are expected (for example, seconds versus milliseconds, or EUR versus EUR cents). ### c. Avoiding errors and side effects An agent must know in advance what the consequences of the tool call are. Is the action read-only, or is data overwritten? Can the call fail due to a network outage, and what does an empty return value mean? By including any preconditions and error scenarios, the agent can recover better after a failed call. During the [debugging agentic loops](https://community.llmnet.nl/en/agentic-loops-debuggen) we trace various failure patterns back to unclear preconditions in the description of the called functions. ## 3. Anatomy of an effective tool description A structured tool description consists of fixed components. Using a consistent structure not only helps the language model recognize patterns, but also simplifies review by team members. ### Naming the tool The tool's name formally forms part of the schema and serves as the first filter for the model. Use a unique combination of a verb and an object (for example get_user_profile or cancel_subscription). Avoid generic or ambiguous names such as process_data or do_action. ### When to use it and when not to Start the textual description with the tool's main purpose. Add the situations in which the tool is explicitly not suitable. If an alternative tool exists for a related task, name it explicitly. ### Parameter specifications For each parameter, describe not only the name, but also clarify the semantics: - Meaning: What does the argument represent? - Unit and format: Think of YYYY-MM-DD for dates or ISO-3166-1 alpha-2 for country codes. - Range and restrictions: Minimum and maximum values, or allowed options if an enumeration doesn't fit directly into the JSON schema. - Optional vs. Required: What is the behavior if the value is omitted, and what is the default value? ### Return values and side effects Indicate what the tool returns on success and what the expected structure of the response is. Also mention any side effects: does the tool incur costs on an external API, does execution take a long time, or does it send an email to an end user? ### Edge cases and error handling Explain how the tool responds to invalid input or missing data. If a search yields zero results, indicate whether the tool returns an empty list or generates an error message. ## 4. The limits of context: token budget and model size Writing a tool description is a balancing act between completeness and efficiency. Every tool description you add to the API call consumes tokens in the system context. In systems with dozens of tools, the combined size of the schemas can span thousands of tokens. This incurs costs and can negatively affect processing speed (latency). A commonly used rule of thumb in production is a budget of 50 to 150 words per tool description. For simple request-response tools, 50 words is more than sufficient. Complex tools with many parameters or critical side effects may require up to 150 or 200 words. The type of model you deploy has a direct influence on how the description should be formulated: - Large models (e.g., 70B+ parameters or commercial flagship models): These models have a strong trained ability for implicit reasoning. They understand contextual hints and can infer the correct arguments from minimal descriptions. For details on the technical dispatch of requests, see the documentation on [function calling](https://api.llmnet.nl/en/function-calling) on the API environment. - Small models (e.g., 3B to 8B parameters in a homelab setup): Smaller models interpret text much more literally and get confused more quickly by vague phrasing or unnecessary preconditions. For smaller models, short, explicit instructions and clear 'When NOT to use' clauses are necessary to prevent hallucinations. You can find more background on this in the guide on [prompting for smaller models](https://community.llmnet.nl/en/prompting-voor-kleinere-modellen). When designing your agentic architecture, also take into account the total token usage of all registered toolset schemas combined. Should the context become too full, consider dynamic tool filtering or routing via an overarching graph structure. ## 5. Common mistakes in practice In practice, we regularly see recurring mistakes in tool descriptions that are easy to avoid: ### 1. Ambiguous or overlapping tool names If two tools have a similar name, such as fetch_user and get_user_details, the model cannot choose reliably. Ensure a clear separation of responsibilities, or merge both functionalities into one robust function. ### 2. Missing units or formats A parameter named timeout without clarification is guaranteed to cause problems. Certain models fill in 30 and mean seconds, while the underlying API expects milliseconds. Always state units explicitly in the description of the parameter. ### 3. Overly long blocks of text Adding complete manuals or background stories to the description pollutes the context window and distracts from the essential argument structure. Stick to the functional core. ### 4. Promises the code doesn't keep A description that claims the tool "searches all historical customer data," while the Python code behind the tool only retrieves the last 30 days, causes the model to make incorrect assumptions. The description and the actual code implementation must remain 100% in sync. ### 5. Concealing error scenarios If a tool returns an HTTP 404 for a missing value, the description must state what this means. Otherwise, the model may assume the entire system is down, instead of simply concluding that the requested entity does not exist. ## 6. Testing tool descriptions Because tool descriptions are effectively prompts sent by the API, they must be tested with the same care as your application code. Testing a description involves three phases: ### Schema validation Check in advance whether the generated JSON schema is valid and parses correctly according to the OpenAPI or JSON Schema specification. Use the online [JSON Schema validator tool](https://benchmark.llmnet.nl/en/tool-json-schema-validator) to rule out syntax errors before putting the schema into production. ### Distraction and selection tests Place the tool being tested in a list with 10 to 20 other registered tools. Run prompts specifically intended for the target tool, as well as prompts that come close but should be handled by a different tool. This lets you verify whether the 'When NOT to use' instructions function properly. ### Self-test via a test harness Have the model make the tool choice in an automated test environment based on a set of 50 to 100 realistically phrased user questions. Use an evaluation step to determine whether the model chooses the right tool and fills in the parameters in the correct format. By automating this process, you discover regressions immediately after a change to the description. ## 7. Iterating and managing: treat descriptions as code A tool description is not static text that you write once and then forget. As your application grows and the agent's usage varies, edge cases will come to light. - Version control: Store tool schemas and descriptions in the same version control module (such as Git) as the underlying code. A change to a Python function signature must be accompanied by a mandatory commit that updates the JSON schema and description. Check the recommendations for [prompt version control](https://community.llmnet.nl/en/prompt-versiebeheer) for practical workflows. - Peer reviews: Have a fellow developer read the description without showing the underlying code. If the colleague cannot deduce exactly what the function does and which arguments are required, the language model will most likely struggle with it too. Read more about this process in the article on [reviewing prompts as a team](https://community.llmnet.nl/en/prompts-reviewen-in-team). - Quality metrics: Monitor the percentage of failed tool calls and invalid JSON responses in production. Use [LLM-as-a-judge](https://benchmark.llmnet.nl/en/llm-as-a-judge) evaluations to determine whether the root cause lies in the prompt structure or in an unclear tool description. ## 8. Copyable artifact: Template, Checklist & Examples Use the structure below as a guide when designing and reviewing your own tool descriptions. ================================================================================ 1. TOOL DESCRIPTION TEMPLATE (JSON SCHEMA ANNOTATIE) ================================================================================ { "name": "[actie]_[entiteit]", "description": "[Eén heldere zin die de primaire functie beschrijft]. Gebruik deze tool wanneer [specifieke use-case]. Gebruik deze tool UITDRUKKELIJK NIET voor [alternatieve use-case, verwijst naar alternatieve_tool_naam]. Let op: [belangrijke bijwerking, kosten of restrictie].", "parameters": { "type": "object", "properties": { "param_naam": { "type": "string", "description": "[Betekenis van de parameter]. Indeling: [bijv. YYYY-MM-DD of ISO-code]. Bereik/Opties: [toegestane waarden]. Default: [standaardwaarde indien optioneel]." } }, "required": ["param_naam"] } } ================================================================================ 2. CHECKLIST VOOR TOOL-DESCRIPTIONS ================================================================================ [ ] Unieke en heldere naam (werkwoord + object)? [ ] Hoofddoel beschreven in de eerste zin? [ ] Expliciet vermeld wanneer de tool NIET gebruikt mag worden? [ ] Alle parameters voorzien van betekenis, formaat en eventuele eenheden? [ ] Duidelijk onderscheid gemaakt tussen verplichte en optionele parameters? [ ] Bijwerkingen (kosten, schrijfoperaties, latentie) vermeld? [ ] Foutgedrag en afhandeling van lege resultaten kort toegelicht? [ ] Lengte binnen het afgesproken tokenbudget (50-150 woorden)? [ ] JSON Schema gevalideerd tegen de specificatie? ================================================================================ 3. CONCREET VOORBEELD: SLECHT VS. GOED ================================================================================ --- SLECHT VOORBEELD --- { "name": "get_data", "description": "Haalt gegevens op uit het systeem over klanten.", "parameters": { "type": "object", "properties": { "query": { "type": "string", "description": "De zoekopdracht of ID." }, "time": { "type": "string", "description": "De tijd." } }, "required": ["query"] } } -- Ruimte voor fouten: Wat voor ID? Welk formaat heeft 'time'? Wat gebeurt er als er niets gevonden wordt? Is 'get_data' voor alle gegevens? --- GOED VOORBEELD --- { "name": "search_customer_orders", "description": "Zoekt historische bestellingen van een specifieke klant op basis van klant-ID of ordernummer. Gebruik deze tool wanneer een gebruiker vraagt om bestelstatus, factuurhistorie of artikelen uit een eerdere order. Gebruik deze tool NIET voor het opvragen van algemene productinformatie (gebruik daarvoor 'search_catalog') of het aanmaken van nieuwe bestellingen. Retourneert een lijst van maximaal 50 order-objecten. Bij geen resultaten wordt een lege lijst [] geretourneerd.", "parameters": { "type": "object", "properties": { "customer_id": { "type": "string", "description": "Het unieke klant-ID opgebouwd uit 'CUST-' gevolgd door 6 cijfers (bijv. CUST-123456)." }, "start_date": { "type": "string", "description": "Optionele begindatum voor het filteren van orders. Indeling volgens ISO-8601: 'YYYY-MM-DD'. Als deze wordt weggelaten, wordt gezocht vanaf 12 maanden geleden." }, "include_cancelled": { "type": "boolean", "description": "Geeft aan of geannuleerde bestellingen ook in het overzicht moeten worden opgenomen. Standaardwaarde is false." } }, "required": ["customer_id"] } } ## 9. From tool description to agentic graph Writing a tight tool description is the foundation for a stable agentic workflow. Without clear descriptions, even the most advanced language model fails to call functions correctly. Once your individual tool descriptions are in order, you can combine them into more complex patterns and loops. In the architecture of [from prompt to graph engineering](https://community.llmnet.nl/en/van-prompt-naar-graph-engineering) you can see how isolated tool calls come together into robust, multi-step decision trees and automated networks. Dutch-language knowledge network on AI and LLMs. Independent, practical and with sources cited. More on llmnet.nl: [Hub](https://hub.llmnet.nl/en/) · [Community](https://community.llmnet.nl/en/) · [Consultancy](https://consultancy.llmnet.nl/en/) · [News](https://nieuws.llmnet.nl/en/) · [Benchmark](https://benchmark.llmnet.nl/en/) · [Jobs](https://vacatures.llmnet.nl/en/) · [Learn](https://leren.llmnet.nl/en/) · [Guide](https://gids.llmnet.nl/en/) · [Directory](https://directory.llmnet.nl/en/) · [Radar](https://radar.llmnet.nl/en/) © 2026 llmnet.nl · Ivo DonkerKnowledge network on AI & LLMs