Access Denied You don’t have permission to access “http://zeenews.india.com/technology/telegram-removed-from-google-play-store-after-govt-restrictions-still-available-on-apple-app-store-3055695.html” on this server. Reference #18.c4f43717.1781615221.1391809 https://errors.edgesuite.net/18.c4f43717.1781615221.1391809

Access Denied You don’t have permission to access “http://zeenews.india.com/technology/redmi-turbo-5-vs-oneplus-nord-6-compared-what-smartphone-is-better-to-buy-price-camera-features-performance-battery-3055659.html” on this server. Reference #18.eff43717.1781609102.1cb8836 https://errors.edgesuite.net/18.eff43717.1781609102.1cb8836

Access Denied You don’t have permission to access “http://zeenews.india.com/technology/redmi-turbo-5-launched-in-india-with-7540-mah-battery-price-camera-features-performance-and-durability-3055621.html” on this server. Reference #18.cc1cc517.1781601043.6921c2fa https://errors.edgesuite.net/18.cc1cc517.1781601043.6921c2fa

Access Denied You don’t have permission to access “http://zeenews.india.com/technology/hack-of-the-day-how-to-make-old-smartphone-feel-faster-without-buying-new-one-3055578.html” on this server. Reference #18.85277368.1781589177.14b2c1c1 https://errors.edgesuite.net/18.85277368.1781589177.14b2c1c1

Access Denied You don’t have permission to access “http://zeenews.india.com/technology/do-you-know-every-app-on-your-phone-is-tracking-you-right-now-here-is-how-to-stop-it-3055583.html” on this server. Reference #18.eff43717.1781585115.f5201a https://errors.edgesuite.net/18.eff43717.1781585115.f5201a

In this article, you will learn how tool design — not model capability — is the root cause of most AI agent failures, and what concrete design patterns you can apply to fix it. Topics we will cover include: Tool design practices that improve agent reliability, including single-responsibility tools, tight schemas, and structured error returns. Common failure modes such as unfiltered API exposure, silent partial success, and overlapping tool names that break real-world workloads. Schema and error handling patterns that reduce hallucination and unreliable behavior at the tool boundary. Let’s get into it. AI Agent Tool Design: What Works and What Doesn’t Introduction Most AI agent failures look like model mistakes: choosing the wrong tool, passing bad arguments, or mishandling errors. But in practice, the model is usually working with the interface it was given. The underlying issue is often the tool design itself. A model can only reason from the information exposed through the tool interface: the tool name, its description, the parameter schema, and the parameter descriptions. Those details shape how the model interprets intent, plans actions, and executes tasks. When the tool design is unclear, incomplete, or loosely structured, failures become predictable rather than accidental. Problems like vague naming, ambiguous instructions, inconsistent schemas, weak parameter definitions, and poor error handling all increase the likelihood of failures. Stronger models can reduce some mistakes, but they cannot reliably compensate for a flawed interface. This article covers: Tool design practices that improve reliability Failure modes that look fine in demos but break under real workloads Schema and error design that reduces hallucination at the tool boundary Each pattern is paired with its failure counterpart, because understanding why a design fails is as important as knowing what to replace it with. What Works in AI Agent Tool Design 1. One Tool, One Responsibility In most agent systems, a tool should represent a single, clear operation. When one tool handles multiple behaviors through an action parameter, the model must first figure out which mode to invoke before it can solve the actual task. The difference becomes clearer when comparing a multi-action tool against dedicated single-purpose tools: # Avoid: action-based multi-behavior tool @tool def manage_customer( action: str, customer_id: str | None = None, data: dict | None = None ): “”” action: create | get | update | delete | suspend “”” … # Prefer: single-responsibility tools @tool def create_customer(data: CustomerInput) -> Customer: “””Create a new customer record.””” … @tool def get_customer(customer_id: str) -> Customer: “””Retrieve a customer by ID.””” … @tool def suspend_customer(customer_id: str, reason: str) -> SuspensionResult: “””Suspend a customer account.””” … 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 # Avoid: action-based multi-behavior tool @tool def manage_customer(     action: str,     customer_id: str | None = None,     data: dict | None = None ):     “”“     action: create | get | update | delete | suspend     ““”     …   # Prefer: single-responsibility tools @tool def create_customer(data: CustomerInput) -> Customer:     “”“Create a new customer record.”“”     …   @tool def get_customer(customer_id: str) -> Customer:     “”“Retrieve a customer by ID.”“”     …   @tool def suspend_customer(customer_id: str, reason: str) -> SuspensionResult:     “”“Suspend a customer account.”“”     … One Tool, One Responsibility Single-responsibility tools give the model an unambiguous function and give you cleaner error handling and easier observability. ⚠️ Note: This is a useful default rather than a universal rule. Some domains — such as shell, filesystem, browser, or calendar tools — may benefit from a constrained multi-action interface because the action space itself is part of the underlying abstraction. 2. Schemas That Make Invalid States Impossible In tool-calling agents, the model constructs tool call arguments by reasoning from your schema. A loose schema means the model guesses at constraints. A tight schema encodes those constraints so no guessing is needed. Here’s an example: from pydantic import BaseModel, Field from enum import Enum class Priority(str, Enum): LOW = “low” MEDIUM = “medium” HIGH = “high” class CreateTaskInput(BaseModel): title: str = Field( description=”Short, actionable task title. Use imperative form: ‘Review PR’, not ‘PR Review’.”, min_length=5, max_length=100 ) priority: Priority = Field( description=”Task priority. Use HIGH only for blockers affecting other work.”, default=Priority.MEDIUM ) due_date: str = Field( description=”Due date in ISO 8601 format: YYYY-MM-DD. Must be a future date.”, pattern=r”^\d{4}-\d{2}-\d{2}$” ) 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 from pydantic import BaseModel, Field from enum import Enum   class Priority(str, Enum):     LOW = “low”     MEDIUM = “medium”     HIGH = “high”   class CreateTaskInput(BaseModel):     title: str = Field(         description=“Short, actionable task title. Use imperative form: ‘Review PR’, not ‘PR Review’.”,         min_length=5,         max_length=100     )     priority: Priority = Field(         description=“Task priority. Use HIGH only for blockers affecting other work.”,         default=Priority.MEDIUM     )     due_date: str = Field(         description=“Due date in ISO 8601 format: YYYY-MM-DD. Must be a future date.”,         pattern=r“^\d{4}-\d{2}-\d{2}$”     ) Enums are particularly useful for fields with a small set of valid values because they eliminate a class of plausible-but-invalid outputs. Validation failures surface at the tool boundary rather than as cryptic downstream errors. 3. Descriptions That Define Scope, Not Just Purpose Tool descriptions are model-facing documentation. They need to do two things: explain when to use the tool, and explain when not to. Most descriptions only do the first. # Weak: explains what it does, not when not to use it “””Search for documents in the knowledge base.””” # Strong: defines purpose, scope, and boundaries “”” Search the internal knowledge base for documents, policies, and reference material. Use this when the user asks about company procedures, product specs, or documented workflows. Do NOT use this for real-time data (prices, availability, current status) — use get_live_data() instead. Returns up to 5 results ranked by relevance. If no results are returned, the information is not in the knowledge base. “”” # Weak: explains what it does, not when not to use it “”“Search

Access Denied You don’t have permission to access “http://zeenews.india.com/technology/someone-is-using-your-wi-fi-right-now-and-you-probably-do-not-know-it-here-s-how-to-identify-hidden-users-3055495.html” on this server. Reference #18.d7f43717.1781530618.7e67f6c9 https://errors.edgesuite.net/18.d7f43717.1781530618.7e67f6c9

Access Denied You don’t have permission to access “http://zeenews.india.com/technology/apple-s-2026-software-cut-16-devices-are-losing-support-check-if-yours-is-on-the-list-3055413.html” on this server. Reference #18.eff43717.1781521208.a8fd9864 https://errors.edgesuite.net/18.eff43717.1781521208.a8fd9864

Access Denied You don’t have permission to access “http://zeenews.india.com/technology/realme-p4r-5g-launched-in-india-with-8000mah-battery-144hz-display-and-latest-ai-features-check-price-3054233.html” on this server. Reference #18.d61cc517.1781406379.7afdfd5c https://errors.edgesuite.net/18.d61cc517.1781406379.7afdfd5c

Access Denied You don’t have permission to access “http://zeenews.india.com/technology/clicked-a-suspicious-x-link-here-s-what-to-do-immediately-in-next-60-seconds-before-hackers-get-in-your-smartphone-3054358.html” on this server. Reference #18.54fdd417.1781402749.4e95090c https://errors.edgesuite.net/18.54fdd417.1781402749.4e95090c