--- title: Designing Tool Calls for an AI Travel Agent description: "The infrastructure behind the 70+ tools our AI agent uses to search flights, book hotels, and plan trips — design principles, authorization, and monitoring." canonical: https://nowah.xyz/blog/designing-tool-calls-ai-travel-agent lastModified: "2026-08-07T03:52:05.918Z" --- # Designing Tool Calls for an AI Travel Agent The infrastructure behind the 70+ tools our AI agent uses to search flights, book hotels, and plan trips — design principles, authorization, and monitoring. Our AI agent has 70+ tools. It can [search flights](/blog/launching-[tool-calling](/blog/tool-calling-at-scale-ai-travel-search)-layer-ai-agent-search-flights), check hotel availability, look up [visa requirements](/blog/ai-agents-visa-requirements-documents), get weather forecasts, check airport information, manage bookings, process payments, and dozens of other operations. When a traveler says "Find me a flight to Tokyo," the agent has to pick the right tool from 70+ options, call it with the right parameters, and make sense of the result. In milliseconds. This doesn't happen by accident. The tool library is a carefully designed infrastructure layer that determines what the agent can do, how well it does it, and how safely it operates. Bad tool design means an agent that picks the wrong tool, passes wrong parameters, or misinterprets results. Good tool design makes the agent look smart because the tools are smart. ## Design principles ![Illustration for this section](https://pics.nowah.xyz/website-media/infrastructure-034-img-1.webp) We follow several principles that have held up as the tool count grew from 10 to 70+. **Clear inputs, predictable outputs.** Every tool has a typed input schema that specifies exactly what parameters it expects, which are required, and what constraints apply (date formats, valid airport codes, price ranges). The output schema is equally strict. The agent knows exactly what data it will receive, which makes response generation more reliable. Ambiguous inputs lead to ambiguous behavior. If a flight search tool accepts a "date" parameter without specifying the format, the agent might pass "next Thursday" or "March 20" or "2026-03-20." By requiring ISO 8601 format, we force the agent to do the date resolution before calling the tool, which it's good at. **Self-documenting schemas.** Each tool has a description that explains what it does, when to use it, and what it doesn't do. These descriptions are part of the agent's context. "Search for available flights between two airports on a specific date. Use this for one-way searches. For round trips, call this tool twice with swapped origin and destination." The description is as important as the code. A well-described tool gets chosen correctly by the agent. A poorly described tool gets called when it shouldn't be or not called when it should be. **Idempotent where possible.** Search tools are naturally idempotent. Calling a flight search twice with the same parameters returns the same results (modulo price changes). State-changing tools (create booking, process payment) are made idempotent through the booking attempt mechanism described elsewhere. ## Authorization checks This is the line between a useful agent and a dangerous one. Search tools are unrestricted. Any authenticated user can search flights, check weather, or look up visa requirements. These are read-only operations with no side effects. State-changing tools have authorization checks. When the agent calls a booking tool, the tool implementation verifies: Is the user authenticated? Does this user own the trip being booked? Is the payment method associated with this user? Does the user have permission to perform this action? These checks happen at the tool execution layer, not at the agent reasoning layer. The agent might decide to call a booking tool. The tool itself enforces authorization before executing. This means [prompt injection](/blog/prompt-injection-new-sql-injection) attacks that convince the agent to make unauthorized tool calls fail at the authorization layer, not at the prompt layer. The authorization check uses the user identity propagated from the original HTTP request through the middleware. The agent doesn't decide who the user is. The auth middleware decides, and the tool enforces it. ## Timeout and retry handling ![Supporting diagram](https://pics.nowah.xyz/website-media/infrastructure-034-img-2.webp) External API tools have unpredictable latency. A flight search might return in 800 milliseconds or 5 seconds depending on route complexity and provider load. The agent can't wait forever. Each external tool has a configurable timeout. Flight search gets a generous timeout (up to 8 seconds for complex [multi-city](/blog/multi-city-flight-booking-ai-agents) queries) because the alternative is returning no results. Simpler tools (airport lookup, weather check) get tight timeouts (2-3 seconds) because fallback data is usually available. When a tool times out, the result returned to the agent is an explicit timeout message, not an exception. "Flight search timed out. The search might still be processing. Consider trying again with a simpler query." The agent can then decide how to communicate this to the traveler. Some tools have automatic retry for transient failures. A network blip that causes a failed API call gets retried once before returning an error. The retry uses the same [idempotency](/blog/idempotency-travel-booking) mechanisms as the original call to prevent duplicate side effects. ## Result formatting Tool results need to be in a format that the language model can reason about effectively. Raw API responses from external providers are often deeply nested JSON with dozens of fields, most irrelevant to the traveler's query. We transform tool results into a clean, flat structure that highlights the information the agent typically needs. A flight search result becomes: origin, destination, departure time, arrival time, duration, stops, carrier, cabin class, price, and seat availability. Not the full GDS response with fare rules, baggage policies, and reservation system codes. The cleaned result saves tokens in the model's context window and reduces the chance of the agent fixating on irrelevant details. If the traveler asks about baggage, the agent can call a separate tool for that specific information. We also include metadata in tool results that helps the agent decide what to do next. A flight search result might include a flag indicating whether prices should be re-validated before booking (because the search is now several minutes old). This guidance helps the agent make better decisions without needing to reason about data freshness from first principles. ## Monitoring tool call patterns We monitor every tool call across three dimensions: how often it's called, how long it takes, and how often it fails. Frequency patterns reveal agent behavior. If the agent is calling the flight search tool 5 times for a simple one-way query, something is wrong with either the tool description (the agent doesn't understand when it has enough results) or the search results (the agent is unsatisfied with the options and keeps searching). Latency patterns reveal external dependency health. A gradual increase in flight search latency might indicate provider degradation before their status page reflects it. We detect this early because we're monitoring continuously across all conversations. Failure patterns reveal bugs and edge cases. A tool that fails 5% of the time for a specific parameter combination (e.g., flights to a small regional airport) points to an edge case in the tool implementation or the external API. We review the top 10 tools by frequency weekly and investigate any with anomalous patterns. The tool call data is our most direct window into how the agent behaves in production, and behavioral changes in tool usage almost always correspond to quality changes in the traveler experience. ## Scaling to 100+ tools As we add more capabilities (car rentals, restaurant reservations, activity bookings), the tool count will grow. Here's what we've learned about keeping a large tool library manageable. Organize tools by category. Search tools, booking tools, information tools, management tools. The category structure helps both the agent (narrowing its search space) and engineers (finding and maintaining tools). Keep tool descriptions current. A tool whose description doesn't match its behavior causes the agent to misuse it. Description maintenance is as important as code maintenance. Deprecate rather than delete. When a tool is superseded, mark it as deprecated in its description before removing it. This gives time to verify the replacement tool covers all the same use cases. Test tools independently. Each tool should have its own test suite that verifies correct behavior with various inputs, including edge cases. Tool-level tests are faster and more focused than end-to-end agent tests. --- Nowah is an AI travel agent that searches and books real flights and hotels through conversation — no filters, no thirty open tabs. [Plan your next trip](https://app.nowah.xyz).