Formatting Tool Specifications for LLM Comprehension

For an AI agent to reliably use an external tool, it must first understand what the tool is, what it does, how to call it, and what to expect in return. This understanding doesn't come from innate knowledge but from carefully crafted descriptions we provide. Think of it like this: you wouldn't hand a new software library to a developer without API documentation. Similarly, an LLM needs a "manual" for each tool it might use, and this manual comes in the form of a tool specification. Properly structuring these specifications is essential for an LLM to effectively comprehend and utilize the tools at its disposal.

The way an LLM "reads" a tool specification is fundamentally different from how a human programmer does. LLMs process information as sequences of text. The specification becomes part of the context the LLM considers when deciding to use a tool and how to format its request. A well-formatted specification allows the LLM to accurately identify the tool's purpose, map user intent to tool inputs, and correctly structure the information it needs to send to the tool. Without this, the agent might select the wrong tool, provide malformed inputs, or misinterpret the tool's output, leading to errors and failed tasks.

Essential Components of a Tool Specification

To ensure an LLM can effectively use a tool, its specification should clearly define several important pieces of information. These components act as the primary interface between the LLM's reasoning process and the tool's functionality.

1. Tool Name:

   • A unique and consistent identifier for the tool. The LLM will use this name to signal its intent to use the tool.
   • Best Practices: Use clear, descriptive names. Common conventions include snake_case (e.g., get_stock_price) or camelCase (e.g., fetchWeatherData). Avoid spaces or special characters that might be difficult for the LLM to parse or generate consistently.
   • Example: calculator, web_search_engine, product_database_lookup

2. Description:

   • A concise, natural language explanation of the tool's purpose, its capabilities, and importantly, when it should be used. This description is not only for understanding how to use the tool but also for the LLM's decision-making process in selecting the tool.
   • Example for a unit_converter tool: "Converts values between different units of measurement (e.g., Celsius to Fahrenheit, kilograms to pounds). Use this when a conversion between specified units is requested."

3. Input Parameters (Arguments):

   • This is arguably the most critical part for correct tool invocation. Each parameter the tool accepts needs to be clearly defined.
     • Name: A descriptive name for the parameter (e.g., query, unit_from, value_to_convert).
     • Type: The expected data type (e.g., string, number, boolean, array, object). Specifying types helps the LLM format the data correctly. Using JSON Schema-like type definitions is often beneficial.
     • Description: A clear explanation of what the parameter represents and any specific constraints or formats (e.g., "The search term to look up on the web," or "The temperature value, must be a numerical type.").
     • Required/Optional: Indicates whether the parameter is mandatory for the tool to function.
   • Example snippet for a send_email tool's parameters:

     {
       "recipient_address": {
         "type": "string",
         "description": "The email address of the recipient, e.g., '[email protected]'."
       },
       "subject_line": {
         "type": "string",
         "description": "The subject of the email."
       },
       "email_body": {
         "type": "string",
         "description": "The main content of the email."
       }
     }
     

4. Output Structure (Return Value):

   • A description of the data structure and types the tool is expected to return upon successful execution. This helps the LLM anticipate the format of the tool's response and parse it correctly.
   • Type: The data type of the output (e.g., string, number, object, array).
   • Description: What the output represents. If it's an object, describe its properties.
   • Example for the unit_converter tool:

     {
       "converted_value": {
         "type": "number",
         "description": "The numerical result of the conversion."
       },
       "new_unit": {
         "type": "string",
         "description": "The unit to which the value was converted."
       }
     }
     

5. Usage Examples (Optional but Highly Recommended):

   • Providing a few examples of how the tool is invoked (input arguments) and what a typical output looks like can significantly improve the LLM's ability to use the tool correctly. This aligns with few-shot prompting principles.
   • Example for calculator.add:

     User query: "What is 15 plus 27?"
     Agent action: { "tool_name": "calculator", "operation": "add", "parameters": { "num1": 15, "num2": 27 } }
     Tool response: { "result": 42 }
     

Common Formatting Structures for Tool Specifications

While the content of the specification is primary, its format also matters. The LLM needs to parse this information efficiently. Here are a few common approaches:

JSON (JavaScript Object Notation)

JSON is a widely used format for data interchange and is generally well-understood by LLMs. Describing tools using a JSON structure, often inspired by JSON Schema for parameter and output definitions, is a method.

{
  "tool_name": "get_current_weather",
  "description": "Fetches the current weather conditions for a specified location.",
  "parameters": {
    "type": "object",
    "properties": {
      "location": {
        "type": "string",
        "description": "The city name (e.g., 'London', 'Tokyo')."
      },
      "unit": {
        "type": "string",
        "description": "Temperature unit: 'celsius' or 'fahrenheit'. Defaults to 'celsius'.",
        "enum": ["celsius", "fahrenheit"]
      }
    },
    "required": ["location"]
  },
  "returns": {
    "type": "object",
    "properties": {
      "temperature": {
        "type": "number",
        "description": "The current temperature in the specified unit."
      },
      "condition": {
        "type": "string",
        "description": "A brief description of weather conditions (e.g., 'Sunny', 'Cloudy')."
      },
      "humidity_percent": {
        "type": "integer",
        "description": "The current humidity percentage."
      }
    }
  }
}

A JSON object defining the get_current_weather tool, including its description, parameters with types and constraints, and the expected return structure.

Structured Natural Language with Delimiters

For simpler tools, or if you want to present the information in a more human-readable way within the prompt, structured natural language with clear delimiters can work. Consistency is important here.

Tool: find_city_timezone
Description: Retrieves the current IANA timezone for a given city.
Arguments:
  city_name (string, required): The name of the city (e.g., "New York", "Paris").
  country_code (string, optional): The two-letter ISO country code to disambiguate cities with the same name (e.g., "US", "FR").
Returns:
  timezone (string): The IANA timezone identifier (e.g., "America/New_York").
  error (string, optional): An error message if the timezone cannot be found.

A tool specification using structured natural language with clear labels for each component.

Dedicated Tool/Function Calling Formats

Many modern LLM APIs, such as those from OpenAI, provide specific "function calling" or "tool use" capabilities. These APIs typically expect tool specifications in a predefined JSON format. Adhering to these vendor-specific formats is necessary when using their dedicated tool-use features.

For example, OpenAI's API might expect a list of tool definitions like this:

[
  {
    "type": "function",
    "function": {
      "name": "get_flight_booking_status",
      "description": "Retrieves the status of a flight booking given a booking ID.",
      "parameters": {
        "type": "object",
        "properties": {
          "booking_id": {
            "type": "string",
            "description": "The unique identifier for the flight booking, e.g., 'FGH789'."
          }
        },
        "required": ["booking_id"]
      }
    }
  }
]

An example of how a tool might be defined for an LLM API that supports dedicated function calling, showing the nested structure typically required.

It's important to consult the documentation of the specific LLM or framework you are using, as they often dictate the preferred format for tool specifications.

Best Practices for Crafting Effective Tool Specifications

• Clarity and Conciseness: Avoid jargon or overly complex sentences in descriptions. The specification contributes to the overall prompt length, so be mindful of token limits.
• Consistency: Use uniform naming conventions (e.g., all snake_case for parameter names) and structuring across all your tool definitions. This helps the LLM learn patterns.
• Descriptive Naming: Choose names for tools and parameters that clearly indicate their purpose (e.g., user_query is better than inp1).
• Explicitly List Enum Values: If a parameter accepts only a specific set of values (an enumeration), list them clearly (e.g., status: "pending" | "completed" | "failed").
• Anticipate Common Variations: In descriptions, you might hint at how to handle slight variations in user requests. For instance, for a search tool, you might specify "Use this for finding information about topics, people, or events."
• Versioning: If your tools change over time (e.g., new parameters, different output), consider including a version field in your specification. Your agent's logic might need to handle different tool versions.
• Iterative Refinement: The first version of your tool specification might not be perfect. Test how well the LLM understands and uses the tool. Observe its generated tool calls and refine the specification based on any misunderstandings or errors. This is a common part of the prompt engineering workflow.

Elements of a comprehensive tool specification designed for LLM comprehension. The specification acts as a schema, guiding the LLM in parsing its details and formulating accurate tool calls.

By investing time in creating clear, comprehensive, and well-formatted tool specifications, you provide the LLM with the necessary knowledge to act as a capable and reliable component within your agentic system. This foundation is essential before moving on to managing the dynamic flow of inputs and outputs during actual tool execution, which we will discuss next.