The New Toolkit: LLMs, Prompts, and Basic Tool Interaction

LLMs interact differently. Instead of just checking data against a schema, an LLM reads a description in plain language about what a tool or another system can do. As a developer, I have to expose the information that a calling LLM can read, consume, and ultimately use to understand how to operate my interface. You don’t give the LLM a strict schema. Instead, you provide a description including a tool’s purpose, inputs, and expected results.

The LLM uses its language understanding to figure out how to use the tool based on this description. It’s like going from checking a rigid form to understanding verbal instructions. This is more flexible, especially for less structured tasks, but it means the interaction depends on interpretation, which can be less predictable than strict formats. You can see this methodology being used across a range of things, from Managed Control Protocol (MCP) to Google’s open-source Agent Development Kit, as I mentioned in my last blog.

Prompts are the New “API Docs”

So, for LLMs, the “API contract” or documentation is essentially the prompt you write to describe the tool or capability. Instead of writing code annotations or schema files, developers now write clear, detailed descriptions that tell the LLM:

• What it does: The main function of the tool.
• What it needs: The inputs required, perhaps with examples or format hints.
• What it gives back: The expected output or action.
• Any rules: Important constraints or guidelines.

This means that prompt engineering is becoming a crucial skill. For these systems to work, it’s imperative that development teams can write instructions that LLMs can reliably understand and act upon.

Simple Example: A “Calendar Assistant” Tool for an LLM

Let’s picture a more dynamic tool, like a calendar assistant, and describe it for an LLM:

Overall Tool Description: “This is a Calendar Assistant Tool. It can schedule new meetings and find available time slots for a group of people.”

Function 1: CreateMeeting Prompt: Tool Name: CreateMeeting. Description: Schedules a new meeting in the calendar. Required inputs: attendees (a list of email addresses), subject (text for the meeting title), startTime (the date and time the meeting should start; try to interpret relative times like ‘tomorrow at 3 PM’ or ‘next Monday morning’), and duration (text describing the length, e.g., ‘1 hour’, ’30 minutes’). Optional input: location (text, e.g., ‘Conference Room B’ or a video call link). Responds with a confirmation message including the final meeting details or an error if scheduling fails (e.g., time conflict, invalid attendees). If the start time or duration is ambiguous, ask the user for clarification before proceeding. Assume times are in the user’s local timezone unless specified otherwise.

How the LLM might use it (after interpreting user request): CreateMeeting(attendees=["alice@example.com", "bob@example.com"], subject="Project Sync", startTime="2025-05-02T15:00:00", duration="45 minutes", location="Video Call")

Function 2: FindFreeTime Prompt: Tool Name: FindFreeTime. Description: Finds common available time slots for a group of people within a specified timeframe. Required inputs: attendees (a list of email addresses) and duration (text describing the desired meeting length, e.g., ‘1 hour’). Optional input: timeWindow (text describing when to look, e.g., ‘next week’, ‘this Friday afternoon’, ‘within the next 3 days’; defaults to the current work week if not specified). Responds with a list of available start times (date and time) or a message indicating no common slots were found. Be specific about the date range being searched if a relative window like ‘next week’ is used. Assume times are in the user’s local timezone unless specified otherwise.

How the LLM might use it (after interpreting user request): FindFreeTime(attendees=["alice@example.com", "bob@example.com", "charlie@example.com"], duration="1 hour", timeWindow="next Tuesday")

Here, the prompts guide the LLM on how to handle lists, interpret potentially fuzzy inputs like dates and durations, and even when to ask for clarification. This is closer to how real-world LLM tool interactions work.

The Challenge: Ambiguity and Prompt Precision (Setting the Stage for Part 3 of this series)

The first time you create a tool like this as a developer, you think to yourself, ‘This is amazing! Writing these agents is a total breeze”. And then, as so often happens in the life of a developer, reality hits you in the face…

While the Calendar Assistant prompts try to handle some fuzziness (like “tomorrow at 3 PM”), relying on natural language descriptions can introduce new and exciting ways for your software to do something you really were not expecting.

Consider these examples:

• Conflicting CreateMeeting Request:
  • User: “Book a 2-hour meeting for me and Charlie this Friday afternoon, but make sure it’s before 2 PM.”
  • Problem: “Friday afternoon” usually implies times after 12 PM or 1 PM. “Before 2 PM” creates a potential conflict or a very narrow window (e.g., 1 PM to 2 PM). The prompt doesn’t explicitly tell the LLM how to handle conflicting constraints within a single parameter like time. Should it prioritize “afternoon” or “before 2 PM”? Should it present the user with the conflict?
• Vague FindFreeTime Request:
  • User: “Find time for a quick chat with Dave next week.”
  • Problem: What is a “quick chat”? The duration parameter needs something more specific like “15 minutes” or “30 minutes”. The current prompt requires a duration and doesn’t specify a default or how to handle vague terms like “quick chat”. The LLM might fail or have to guess.
• Implicit Assumptions in FindFreeTime:
  • User: “Find an hour for the team meeting next Wednesday.”
  • Problem: Who is “the team”? The LLM needs the list of attendees (email addresses). The prompt requires this, but the user request relies on the LLM knowing the context of “the team”. A good interaction flow might involve the LLM asking, “Who is on the team?” if the attendee list isn’t provided or inferable from conversation history. This might be where the calling agent might be able to call another agent to figure out who is ‘the team’.
• Unspecified Time Zones:
  • User (in London): “Schedule a meeting with Priya (in New York) for 9 AM tomorrow.”
  • Problem: Is that 9 AM London time or 9 AM New York time? The current prompts include a basic assumption (“Assume times are in the user’s local timezone unless specified otherwise”), but handling time zones correctly is complex. What if the user doesn’t specify, and the attendees are in different zones? The tool needs either sophisticated backend logic to handle time zones or much more explicit instructions in the prompt about how to request and confirm time zone information if multiple locations are involved. A simple assumption might lead to scheduling errors.

These examples show that even with decent prompts, ambiguity in user requests, conflicting information, or unstated assumptions (like time zones) can lead to errors, incorrect actions, or frustrating clarification loops. The effectiveness of the LLM-API interaction hinges directly on the quality and completeness of the prompt describing the tool’s capabilities and limitations. It needs to cover not just the happy path but also how to handle vagueness, missing information, potential conflicts, and contextual details like time zones.

Getting Complex: When Multiple AI Agents Talk (Transition to Deeper Issues)

Describing a single tool accurately is one thing, but it gets much trickier when you have multiple AI agents trying to work together. How do you write prompts so that Agent A clearly understands what Agent B can and cannot do, including how Agent B handles ambiguity? How do they coordinate? How do you make sure they work together reliably without unexpected problems caused by how they interpret each other’s instructions? Figuring out how to define these interactions clearly and reliably using language is a big challenge we’re facing as these systems evolve.