Practical Tutorial on AI Agent Tool Descriptions: Parameter Schema Design

AI Agent tool descriptions are the basis for a model to choose tools. Invocation decisions are constrained through function names, purpose descriptions, parameter Schemas, and required fields. Suitable for developers to reduce parameter hallucinations, API misuse, and execution risks in Function Calling.

What Is an AI Agent Tool Description?

An AI Agent tool description is a set of explanatory information provided to the model so it can understand the available tools. It helps the model determine whether it needs to invoke a tool and how to fill in parameters when invoking it. In the tool invocation pipeline, the model is mainly responsible for decision-making, while the program is responsible for actual execution.

Therefore, a tool description is not an ordinary code comment, but an important input for the model’s invocation decision-making. When the description is clear, the model can more easily map user intent to the correct tool; when the description is too broad or the boundaries are unclear, the model may select the wrong tool, omit parameters, or even generate parameters that the tool does not support.

You can think of a tool description as an “API description for the model.” It does not directly complete business actions, but it affects which API the model chooses, which fields it passes in, and whether an external execution should be triggered.

Key point: The core division of labor in tool invocation is that “the model is responsible for judging, and the program is responsible for execution.” The goal of designing tool descriptions and parameter Schemas is to reduce the model’s room for guessing and make validation easier on the program side.

What Does a Tool Definition in Function Calling Usually Include?

In Function Calling scenarios, before initiating an invocation, you usually need to define a tool information array tools in code and pass it as a parameter in subsequent requests. This array describes the set of tools available to the model.

A tool definition usually contains three types of core information:

InformationRoleDesign focus
Function nameIdentifies the tool capabilityThe name should reflect the real capability and avoid being overly abstract
DescriptionTells the model what the tool does and when to use itClearly state the purpose, input requirements, and applicable boundaries
Parameter definitionConstrains the fields that need to be filled in during invocationUse clear types, field descriptions, and required items

The Schema in a tool definition is usually used to describe the tool name, purpose, parameter types, parameter descriptions, and required fields. The model refers to this information to decide whether to invoke a tool and how each parameter should be filled in.

If a tool definition only uses a vague description such as “query information,” it is difficult for the model to determine whether it applies to querying orders, querying weather, or querying a knowledge base. In contrast, if the description clearly states “query order status based on the order number” and is paired with a required field such as order_id, the model’s selection and parameter filling will be more stable.

Parameter Schema Design Should Help the Model Guess Less and the Program Validate More Easily

The key value of a parameter Schema is to convert vague intent in natural language into structured fields. The clearer the fields are, the less the model needs to improvise; the clearer the constraints are, the easier it is for the program side to intercept erroneous inputs before execution.

Clarify Parameter Types and Field Meanings

Each parameter should have a clear type and description. For example, the same “time” can be a date, a timestamp, a time range, or a natural language expression. If the Schema does not explain it, the model may fill in a format that the program cannot handle.

During design, prioritize answering these questions:

  • Does the field name directly express its meaning?
  • Is the parameter type clear, such as string, number, boolean, array, or object?
  • Does the field description explain the meaning of the value?
  • Are all required fields fully listed?
  • Do optional fields explain their default behavior or applicable conditions?

Avoid Cramming Multiple Meanings into One Broad Parameter

Broad parameters expand the model’s room for guessing. For example, using one query to carry a user ID, order number, filter conditions, and sorting requirements at the same time means the program side needs to parse it again, and the model is also more likely to mix values together.

A more reliable approach is to split key inputs into explicit fields:

Not recommendedPossible problemClearer direction
query: query contentToo broad in meaning and difficult to validateSplit into fields such as order_id, user_id, and status
data: submitted dataThe program has difficulty determining the structureDefine object fields and required items
type: typeThe value boundaries are unclearClearly state the meaning of allowed values in the description

Let the Schema Serve Subsequent Validation

A Schema affects not only how the model fills in parameters, but also program-side validation and error handling. Clear types, descriptions, and required items can help the program determine before execution whether the input is complete, whether fields meet expectations, and whether it needs to return an error or trigger a retry.

Key point: Do not stop after treating the Schema as “format instructions for the model.” It should also become the foundation for strict program-side validation, exception handling, and reliability governance.

Tool Descriptions Should Clearly State Applicable Boundaries and Invocation Intent

The model determines whether to invoke a tool based on the tool description, so the description should answer three questions as much as possible: what the tool does, when to use it, and what inputs are required.

Clear tool descriptions usually have the following characteristics:

  • They accurately explain the tool’s business capability;
  • They describe applicable scenarios instead of only using a broad verb;
  • They remain consistent with the parameter Schema and do not promise capabilities that the tool cannot complete through its parameters;
  • When necessary, they explain inapplicable situations to prevent the model from mixing up adjacent capabilities.
Tool nameDescription focusKey parametersApplicable scenarioCommon misuse point
get_order_statusQuery order status based on the order numberorder_idThe user asks about the current status of a specific orderMisused to modify an order or query all orders of a user
search_knowledge_baseRetrieve knowledge base content based on a questionqueryThe user needs to find documents, instructions, or knowledge contentMisused to perform actions such as writing or deleting
send_notificationSend a notification to a specified recipientrecipient, messageThe user explicitly requests that a message be sentSends directly before the content or recipient is confirmed

Vague descriptions make the boundaries between tools thinner. For example, if multiple tools are all described as “handle user requests,” it is difficult for the model to determine whether it should choose retrieval, querying, writing, or sending. A better way is to clearly state the action verb, target object, input conditions, and limitations.

To Reduce Mis-invocation, Separate Model Decision-Making from Execution Defenses

Common risks in tool invocation include parameter hallucination, API misuse, and uncontrolled side effects. Parameter hallucination means the model generates parameters that do not exist, are incomplete, or do not comply with constraints; API misuse means the model selects a tool that is not suitable for the current task; uncontrolled side effects are common in operations that change external state, such as writing, deleting, sending, and payment.

You cannot rely solely on the model to “consciously follow” the tool instructions. A more reliable design should separate model decision-making from program execution and add engineering defenses before execution.

DefenseRoleKey applicable areas
Strict Schema validationIntercepts parameters with missing fields, type mismatches, or structural errorsShould be prioritized for all kinds of tools
Sandbox isolationLimits the scope of tool execution and reduces the impact of side effectsScenarios such as files, code execution, and external system operations
Intelligent retryGuides the model to correct parameters or reselect a tool after recoverable errorsScenarios such as missing parameters, format errors, and temporary failures

For tools with side effects, constraints should be stricter. For example, when operations involve writing, deleting, sending, payment, and similar actions, you can require more explicit parameters, additional confirmation, pre-execution validation, and an isolated environment to prevent one erroneous model decision from directly causing irreversible results.

Key point: Strict Schema validation cannot guarantee that the model will never make mistakes, but it can block errors before execution. Reliability comes from the combination of “less guessing by the model” and “strict defense by the program.”

In Multi-Tool Scenarios, Control the Tool Set and Context Overhead

Multi-tool Agents are often more prone to selection difficulties than single-tool scenarios. The model needs to judge among multiple tools; if tool descriptions are similar, parameters overlap, or there are too many irrelevant tools, it is more likely to become confused.

At the same time, re-rendering all tool Schemas in every round introduces fixed context overhead. The more tools there are, the more information the model needs to read and compare, and this also squeezes the context space originally used to understand the user’s task.

When designing a multi-tool set, you can expose only the tools necessary for the task instead of handing all tools to the model at once for selection:

  • Does the current task really need this tool?
  • Are there tools with duplicate or highly similar functions?
  • Are the applicable boundaries between similar tools clearly stated?
  • Can the tool set be split by scenario?
  • Can overly fine-grained tools be merged, or overly broad tools be split?

If two tools differ only slightly, their invocation conditions should be clearly distinguished in the descriptions; if one tool handles too many actions, consider splitting it into clearer single-responsibility tools.

Design Checklist for Tool Descriptions and Parameter Schemas

Before launching or debugging tool invocation, you can use the following checklist for a quick review:

Tool Naming

  • Does the tool name reflect its real capability?
  • Does it avoid overly generalized names, such as only handle or process?
  • Is the name consistent with the description and parameter Schema?

Tool Description

  • Does it explain what the tool does?
  • Does it explain when it should be used?
  • Does it explain which key inputs are required?
  • Does it clearly state inapplicable situations or easily confused boundaries?
  • Does it avoid promising capabilities that the tool cannot actually complete?

Parameter Schema

  • Does it include parameter types, field descriptions, and required fields?
  • Are the field names intuitive?
  • Does it reduce broad fields and avoid letting the model mix multiple meanings together?
  • Are the required items sufficient for the program to complete execution?
  • Do optional fields have clear meanings?

Execution Defenses

  • Has the program side implemented strict Schema validation?
  • Is there clear exception handling when parameters are wrong?
  • Is intelligent retry needed to correct recoverable errors?
  • Have tools with side effects undergone sandbox isolation, additional confirmation, or stricter execution restrictions?

Designing AI Agent tool descriptions and parameter Schemas is essentially about establishing clear “actionable boundaries” for the model. Descriptions determine how the model understands tools, Schemas determine how the model fills in parameters, and program-side validation determines whether errors enter real execution. Only when the three work together can mis-invocation be reduced more reliably.