Universal Tool Design Patterns

// Bad — describes implementation, not agent behavior
{
  name: "get_order",
  description: "Fetches an order from the database by order ID.",
  schema: { ... }
}

// Good — tells the agent when and why to call this tool
{
  name: "get_order",
  description: `Retrieves full details for a single order including line items,
    payment status, and shipping information. Use this when the user asks about
    a specific order and you have the order ID. For searching orders by customer
    or date range, use search_orders instead. Returns 404 if the order does not
    exist or belongs to a different account.`,
  schema: { ... }
}

// Bad — agent is responsible for auth context it should never handle
{
  name: "create_document",
  schema: {
    properties: {
      auth_token: { type: "string" },     // Wrong — execution layer concern
      user_id: { type: "string" },        // Wrong — comes from session
      organization_id: { type: "string" }, // Wrong — comes from session
      title: { type: "string" },
      content: { type: "string" }
    }
  }
}

// Good — only domain inputs; auth/session context injected at runtime
{
  name: "create_document",
  schema: {
    properties: {
      title: { type: "string" },
      content: { type: "string" },
      folder_id: { type: "string", description: "Optional folder to place the document in" }
    },
    required: ["title"]
  }
}

list_projects → create_task (requires project_id)
get_user → update_user (requires current values to avoid overwriting)
list_team_members → assign_task (requires assignee_id)

preview_invoice → send_invoice
validate_migration → run_migration
estimate_charges → execute_charge

// Conceptual pattern — search tool registry before injecting tools
async function selectTools(userQuery: string, allTools: Tool[]): Promise<Tool[]> {
  const ranked = bm25Search(userQuery, allTools, { topK: 5 })
  return ranked
}

const result = await generateText({
  model,
  tools: allTools,
  activeTools: ["get_order", "list_orders", "cancel_order"], // only these are active
  prompt: userMessage
})

get_user + get_order + get_invoice  →  can run simultaneously

create_order → add_line_items → calculate_totals → submit_order

{
  "name": "get_order",
  "description": "Retrieves full details for a single order. Use when you have an order ID and need complete order information including line items and shipping status. For searching orders, use search_orders.",
  "inputSchema": {
    "type": "object",
    "required": ["order_id"],
    "properties": {
      "order_id": {
        "type": "string",
        "description": "The order identifier returned by list_orders or create_order"
      }
    }
  },
  "outputSchema": {
    "type": "object",
    "properties": {
      "id": { "type": "string" },
      "status": { "type": "string", "enum": ["pending", "processing", "shipped", "delivered", "cancelled"] },
      "total": { "type": "number" },
      "line_items": {
        "type": "array",
        "items": { "$ref": "#/components/schemas/LineItem" }
      }
    }
  },
  "annotations": {
    "readOnlyHint": true,
    "idempotentHint": true
  }
}

import { tool } from "ai"
import { z } from "zod"

const getOrder = tool({
  description: `Retrieves full details for a single order including line items,
    payment status, and shipping information. Use when you have a specific order ID.
    For searching orders by customer or date, use searchOrders instead.`,
  parameters: z.object({
    orderId: z.string().describe("The order ID returned by listOrders or createOrder")
  }),
  execute: async ({ orderId }) => {
    const order = await db.orders.findUnique({ where: { id: orderId } })
    if (!order) throw new Error(`Order ${orderId} not found`)
    return order
  }
})

const deleteOrder = tool({
  description: "Permanently deletes an order. This cannot be undone.",
  parameters: z.object({
    orderId: z.string()
  }),
  needsApproval: async ({ orderId }) => {
    // Return true to require human approval before execution
    const order = await db.orders.findUnique({ where: { id: orderId } })
    return order?.status === "completed" // Require approval for completed orders
  },
  execute: async ({ orderId }) => {
    await db.orders.delete({ where: { id: orderId } })
    return { deleted: true, orderId }
  }
})

import { createTool } from "@mastra/core/tools"
import { z } from "zod"

export const getOrderTool = createTool({
  id: "get-order",
  description: `Retrieves full details for a single order. Use when you have a
    specific order ID and need complete information including line items and status.
    For searching or listing orders, use the search-orders tool instead.`,
  inputSchema: z.object({
    orderId: z.string().describe("Order ID from a prior list-orders or create-order call")
  }),
  outputSchema: z.object({
    id: z.string(),
    status: z.enum(["pending", "processing", "shipped", "delivered", "cancelled"]),
    total: z.number(),
    lineItems: z.array(z.object({
      productId: z.string(),
      quantity: z.number(),
      unitPrice: z.number()
    }))
  }),
  execute: async ({ context }) => {
    const order = await fetchOrder(context.orderId)
    return order
  }
})

export const deleteOrderTool = createTool({
  id: "delete-order",
  description: "Permanently deletes an order. Cannot be undone.",
  inputSchema: z.object({ orderId: z.string() }),
  mcp: {
    annotations: {
      destructiveHint: true,
      idempotentHint: false
    }
  },
  execute: async ({ context }) => { ... }
})

from langchain_core.tools import tool
from pydantic import BaseModel, Field

class GetOrderInput(BaseModel):
    order_id: str = Field(
        description="The order ID returned by list_orders or create_order"
    )

@tool("get_order", args_schema=GetOrderInput)
def get_order(order_id: str) -> dict:
    """Retrieves full details for a single order including line items and status.
    
    Use when you have a specific order ID. For searching orders by customer
    or date range, use search_orders instead. Returns 404 error if the order
    does not exist or belongs to a different account.
    """
    order = db.orders.get(order_id)
    if not order:
        raise ToolException(f"Order {order_id} not found")
    return order.to_dict()

from langchain_core.tools import InjectedToolArg
from typing import Annotated

@tool
def create_order(
    product_ids: list[str],
    # Injected at runtime — never passed by the agent
    db_session: Annotated[Session, InjectedToolArg],
    current_user: Annotated[User, InjectedToolArg]
) -> dict:
    """Creates a new order for the current user."""
    ...

from openai import OpenAI
from openai.lib._tools import function_tool

@function_tool
def get_order(order_id: str) -> dict:
    """Retrieves full details for a single order.
    
    Use when you have a specific order ID and need complete order information
    including line items, payment status, and shipping details. For searching
    orders by customer or date, use search_orders instead.
    
    Args:
        order_id: The order identifier returned by list_orders or create_order
    """
    ...

{
  "type": "function",
  "function": {
    "name": "get_order",
    "description": "Retrieves full details for a single order...",
    "strict": true,
    "parameters": {
      "type": "object",
      "required": ["order_id"],
      "additionalProperties": false,
      "properties": {
        "order_id": {
          "type": "string",
          "description": "The order identifier"
        }
      }
    }
  }
}

from crewai import Agent, Task, Crew
from crewai_tools import BaseTool

class GetOrderTool(BaseTool):
    name: str = "get_order"
    description: str = """Retrieves full details for a single order including
        line items and shipping status. Use when you have an order ID and need
        complete order information."""

    def _run(self, order_id: str) -> str:
        order = fetch_order(order_id)
        return order.to_json()

order_agent = Agent(
    role="Order Manager",
    goal="Help customers track and manage their orders accurately",
    backstory="An expert in order fulfillment with access to the order management system",
    tools=[GetOrderTool()],
    verbose=True
)

from semantic_kernel.functions import kernel_function
from semantic_kernel.connectors.ai.function_choice_behavior import FunctionChoiceBehavior

class OrderPlugin:
    def __init__(self, order_service: OrderService):
        self._order_service = order_service

    @kernel_function(
        name="get_order",
        description="""Retrieves full details for a single order. Use when you have
            a specific order ID and need complete information including line items
            and shipping status. For searching orders, use search_orders instead."""
    )
    async def get_order(
        self,
        order_id: Annotated[str, "The order ID from list_orders or create_order"]
    ) -> str:
        order = await self._order_service.get(order_id)
        return json.dumps(order.to_dict())

tool_config = {
    "tools": [
        {
            "toolSpec": {
                "name": "get_order",
                "description": """Retrieves full details for a single order including
                    line items, payment status, and shipping information. Use when you
                    have a specific order ID. For searching orders, use search_orders.""",
                "inputSchema": {
                    "json": {
                        "type": "object",
                        "required": ["order_id"],
                        "properties": {
                            "order_id": {
                                "type": "string",
                                "description": "The order identifier"
                            }
                        }
                    }
                }
            }
        }
    ]
}