Tool Definition Best Practices

import { z } from "zod";

const CreateInvoiceSchema = z.object({
  // UUID format hint prevents the agent from passing a numeric ID
  customer_id: z
    .string()
    .uuid()
    .describe(
      "The UUID of the customer to invoice. Get this from billing_list_customers " +
        "or billing_get_customer - do not pass a customer name or email.",
    ),

  // Integer type with domain context
  amount_cents: z
    .number()
    .int()
    .positive()
    .max(100_000_000) // $1M ceiling
    .describe(
      "Invoice amount in cents (100 = $1.00). Use integer cents to avoid " +
        "floating point rounding errors.",
    ),

  // Enum communicates the exact valid set
  currency: z
    .enum(["usd", "eur", "gbp", "cad", "aud"])
    .describe("ISO 4217 currency code. Defaults to the customer's billing currency if omitted."),

  // Regex makes the format machine-verifiable
  due_date: z
    .string()
    .regex(/^\d{4}-\d{2}-\d{2}$/, "Must be YYYY-MM-DD format")
    .describe(
      "Payment due date in YYYY-MM-DD format (e.g. '2025-02-28'). " +
        "Must be today or a future date.",
    ),

  // Optional fields declare their default
  line_items: z
    .array(
      z.object({
        description: z.string().max(200).describe("Item description shown on the invoice"),
        quantity: z.number().int().positive().describe("Number of units"),
        unit_price_cents: z.number().int().positive().describe("Price per unit in cents"),
      }),
    )
    .optional()
    .describe(
      "Line items to include on the invoice. If omitted, a single line item is created " +
        "using the amount_cents and any description provided at the top level.",
    ),
});

const InvoiceOutputSchema = z.object({
  invoice_id: z.string().uuid(),
  status: z.enum(["draft", "open", "paid", "void"]),
  amount_cents: z.number().int(),
  payment_url: z.string().url().optional(),
});

server.tool(
  "billing_create_invoice",
  "Creates a new invoice...",
  CreateInvoiceSchema,
  { outputSchema: InvoiceOutputSchema },
  async (params) => {
    const invoice = await createInvoice(params);

    const structured = {
      invoice_id: invoice.id,
      status: invoice.status,
      amount_cents: invoice.amountCents,
      payment_url: invoice.hostedUrl ?? undefined,
    };

    return {
      // Required when outputSchema is declared
      structuredContent: structured,
      // Human-readable content is still useful for agents
      // that display results to users
      content: [
        {
          type: "text",
          text: `Invoice ${invoice.id} created for ${formatCents(invoice.amountCents, invoice.currency)}.`,
        },
      ],
    };
  },
);

// AVOID: returning the entire record
return {
  content: [
    {
      type: "text",
      text: JSON.stringify(invoice), // 40+ fields, most irrelevant
    },
  ],
};

// PREFER: returning only the fields agents act on
return {
  content: [
    {
      type: "text",
      text: JSON.stringify({
        invoice_id: invoice.id,
        status: invoice.status,
        payment_url: invoice.hostedUrl,
        amount_cents: invoice.amountCents,
        currency: invoice.currency,
        due_date: invoice.dueDate,
      }),
    },
  ],
};

async (params) => {
  const customer = await db.customers.findById(params.customer_id);

  if (!customer) {
    return {
      isError: true,
      content: [
        {
          type: "text",
          text:
            `Customer ${params.customer_id} not found. ` +
            `Call billing_list_customers to find the correct customer ID.`,
        },
      ],
    };
  }

  if (customer.creditLimitCents < params.amount_cents) {
    return {
      isError: true,
      content: [
        {
          type: "text",
          text:
            `Invoice amount ${formatCents(params.amount_cents)} exceeds customer credit limit ` +
            `of ${formatCents(customer.creditLimitCents)}. ` +
            `Reduce the amount or call billing_increase_credit_limit first.`,
        },
      ],
    };
  }

  const invoice = await createInvoice(customer, params);

  return {
    content: [
      {
        type: "text",
        text: JSON.stringify({
          invoice_id: invoice.id,
          status: invoice.status,
          payment_url: invoice.hostedUrl,
        }),
      },
    ],
  };
};

// INCOMPLETE: states the problem, gives no recovery path
"Customer not found.";

// COMPLETE: states the problem and provides recovery steps
"Customer abc-123 not found. " +
  "If you have the customer's email, call billing_list_customers with filter.email to find their ID. " +
  "If the customer was recently created, there may be a replication delay - retry in 10 seconds.";

// INCOMPLETE: vague constraint violation
("Invalid amount.");

// COMPLETE: specifies the constraint and the valid range
"amount_cents must be between 100 (minimum $1.00) and 100000000 (maximum $1,000,000.00). " +
  `Received: ${params.amount_cents}.`;

// TOO BROAD: agent cannot predict the side effects
"Processes the invoice, which may create, send, void, or archive it based on its current state.";

// TOO GRANULAR: three round trips to do one thing
billing_validate_invoice_params();
billing_reserve_invoice_number();
billing_commit_invoice();

// APPROPRIATE: one call, one outcome, predictable side effects
billing_create_invoice(); // creates draft
billing_send_invoice(); // transitions to open, sends email
billing_void_invoice(); // transitions to void, notifies customer