Tus tools están bien construidas. Tu agente no sabe cuándo usarlas.

Construiste las tools. La lógica funciona. Cada función hace exactamente lo que tiene que hacer, tiene tests, y el código pasa revisión.

Y en producción tu agente llama a la tool equivocada. O llama a dos cuando solo necesita una. O ignora la que más necesita y empieza a improvisar.

El problema no está en el código. Está en el schema.

El LLM no lee tu código. Lee tus descripciones.

Cuando Claude, GPT-4 o cualquier modelo decide qué tool usar, no analiza la implementación. No ejecuta nada. Solo tiene acceso a lo que tú pusiste en name, description y el schema de parámetros.

Eso significa que si tu descripción es ambigua, el modelo toma decisiones ambiguas. Si los parámetros son genéricos, el modelo los rellena con valores genéricos. Si no especificas cuándo usar la tool y cuándo no, el modelo adivina.

Y adivinar a escala es impredecible.

Este es el primer problema que detectamos en casi todos los proyectos de integración de agentes IA: el equipo ha invertido semanas en la lógica de las tools, pero cinco minutos en los schemas. El resultado es un agente que técnicamente funciona en los happy paths y falla sistemáticamente en producción.

Error 1: Nombres genéricos que no dicen nada

// ❌ El modelo no sabe cuándo usar esto
{
  name: "process",
  description: "Procesa la solicitud del usuario",
}

// ✅ El modelo sabe exactamente cuándo usar esto
{
  name: "send_invoice_reminder",
  description: "Envía un recordatorio de pago a un cliente cuya factura lleva más de 7 días vencida. NO usar si el cliente ya ha confirmado el pago o si hay una disputa abierta.",
}

El nombre debe ser un verbo + objeto concreto. La descripción debe incluir cuándo usar la tool y cuándo no. Este segundo punto es el que más diferencia hace.

Error 2: Parámetros con tipo any o string sin contexto

// ❌ El modelo no sabe qué poner aquí
{
  name: "update_client",
  parameters: {
    data: { type: "object" }
  }
}

// ✅ El modelo sabe exactamente qué se espera
{
  name: "update_client_contact",
  parameters: {
    clientId: {
      type: "string",
      description: "ID único del cliente en formato UUID (ej: 'abc-123-def'). No usar el email ni el nombre."
    },
    email: {
      type: "string",
      description: "Nuevo email de contacto. Solo actualizar si el usuario lo ha proporcionado explícitamente en este turno de conversación."
    },
    phone: {
      type: "string",
      description: "Teléfono con prefijo internacional (ej: '+34612345678'). Opcional.",
    }
  },
  required: ["clientId"]
}

Cada parámetro necesita su propio description. No solo el tipo. El modelo usa esa descripción para decidir qué valor poner, cuándo es obligatorio y en qué formato.

Error 3: Una tool que hace demasiadas cosas

Este es el error de arquitectura más caro. Consolidas lógica en una sola tool porque "es más limpio" y el resultado es que el modelo no sabe qué camino tomar dentro de ella.

// ❌ Una tool, demasiadas responsabilidades
{
  name: "manage_invoice",
  description: "Gestiona facturas: crea, actualiza, cancela, envía o marca como pagada",
  parameters: {
    action: { type: "string", enum: ["create", "update", "cancel", "send", "mark_paid"] },
    // ... 15 parámetros más, la mayoría opcionales según la acción
  }
}

// ✅ Una tool por responsabilidad
{
  name: "create_invoice",
  description: "Crea una nueva factura en borrador. Solo usar cuando el usuario confirma los detalles del servicio y el importe.",
},
{
  name: "send_invoice",
  description: "Envía la factura al email del cliente. Solo usar cuando la factura ya está creada y en estado 'draft'.",
},
{
  name: "mark_invoice_paid",
  description: "Marca una factura como pagada. Usar cuando el usuario confirma que ha recibido el pago.",
}

Más tools no es más complejo para el modelo. Es más claro. La selección correcta es más fácil con herramientas atómicas y bien nombradas.

Si estás construyendo agentes para automatización de negocio, la granularidad del schema es una de las primeras decisiones que tomamos en los proyectos de agentes IA y automatización. Hacerlo bien desde el principio evita semanas de debugging.

Error 4: No especificar cuándo NO usar la tool

Los modelos tienden a usar las tools que tienen disponibles aunque no sean necesarias. Especificar exclusiones explícitas reduce llamadas innecesarias y errores en cascada.

{
  name: "query_client_database",
  description: `Busca información de un cliente en la base de datos.
  
  USAR cuando el usuario pregunte por datos de un cliente específico.
  NO USAR si el usuario solo quiere información general sobre el servicio.
  NO USAR si ya tienes los datos del cliente en el contexto de esta conversación.
  NO USAR si el usuario no ha proporcionado un identificador (nombre, email o ID).`,
}

Las instrucciones negativas en la description reducen las llamadas espurias entre un 40% y un 70% según el tipo de agente. Es el cambio con mejor ratio de impacto por esfuerzo.

Error 5: Ignorar el orden en el que declaras las tools

Los LLMs tienen sesgos de posición. Las tools declaradas primero tienen más probabilidad de ser elegidas en situaciones de ambigüedad. Esto no es un bug del modelo, es un comportamiento documentado.

// ❌ Las tools de mayor riesgo declaradas primero
const tools = [
  deleteTool,       // primera → más propensión a ser elegida
  updateTool,
  readTool,
];

// ✅ Las tools de solo lectura primero, las destructivas al final
const tools = [
  readTool,         // lectura: favorecerla en caso de duda
  updateTool,
  deleteTool,       // destructiva: requerir más contexto explícito
];

Ordena siempre las tools de menor a mayor impacto. Las operaciones de lectura primero. Las destructivas (borrar, enviar, pagar) al final, con descriptions que exijan confirmación explícita del usuario.

Cómo probar tu schema antes de producción

No necesitas métricas de producción para saber si tu schema funciona. Basta con un conjunto de prompts de prueba ejecutados contra las tools antes de desplegar.

const schemaTestCases = [
  {
    prompt: "¿Cuánto debe el cliente García?",
    expectedTool: "query_client_balance",
    shouldNotCall: ["update_client", "delete_invoice"],
  },
  {
    prompt: "Manda la factura número 234",
    expectedTool: "send_invoice",
    requiredParams: ["invoiceId"],
  },
  {
    prompt: "Hola, buenos días",
    expectedTool: null, // ninguna tool debería llamarse
  },
];

for (const testCase of schemaTestCases) {
  const result = await agent.run(testCase.prompt);
  assert(result.toolCalled === testCase.expectedTool);
}

Ejecutar estos tests antes de cada deploy cuesta menos de un euro en tokens y detecta regresiones en el schema cuando cambias una description o añades una tool nueva.

El schema es parte del sistema, no documentación

La diferencia entre un agente que funciona en un demo y uno que funciona en producción es precisamente esta: que el equipo trata el schema con el mismo rigor que el código.

En producción, el schema es tu contrato con el modelo. Si es ambiguo, el modelo lo interpreta. Si es preciso, el modelo lo sigue.

Cada proyecto de AI Driven Development que llevamos incluye una revisión de schemas como paso obligatorio antes del primer despliegue. No como optimización posterior — como parte del diseño inicial.

Si estás construyendo un agente IA para tu empresa y quieres que funcione desde el primer día, en lugar de pasar semanas ajustando comportamientos en producción, cuéntame qué necesitas.