Reglas de Diseño de Herramientas para Agentes Claude Seguros y Componibles
Estas son las reglas enumeradas que este sitio utiliza para diseñar herramientas que los agentes de Claude llaman: definir su alcance, nombrarlas y validarlas para que múltiples herramientas se compongan de forma segura en lugar de acumular riesgos ocultos a medida que crece el conjunto de herramientas de un agente.
Cómo Usar Esta Lista de Verificación
- Aplica estas reglas al definir cualquier herramienta nueva, no solo para herramientas con efectos secundarios obvios.
- Considera el "alcance estrecho" y la "nomenclatura clara" como requisitos previos para la revisión: una herramienta que es difícil de describir en una oración generalmente intenta hacer demasiado.
- Reaudita el conjunto completo de herramientas de un agente periódicamente, no solo cada herramienta de forma aislada: el riesgo de composibilidad aparece entre herramientas, no dentro de una sola.
- Utiliza las reglas de validación y permisos como una lista de verificación previa a la fusión para cualquier herramienta que toque datos o sistemas de producción.
Reglas de Alcance
- Dale a cada herramienta exactamente una acción bien definida. Una herramienta llamada
manage_orderque puede buscar, modificar, cancelar y reembolsar son cuatro herramientas con un solo nombre; divídela para que cada acción pueda ser razonada, autorizada y registrada de forma independiente. - Prefiere varias herramientas estrechas sobre una herramienta amplia "para mayor flexibilidad". La flexibilidad en la capa de definición de herramientas se convierte en imprevisibilidad en la capa de comportamiento del agente: Claude utilizará cualquier superficie que exponga una herramienta, incluidas partes que no pretendías para uso rutinario.
- Haz que los efectos secundarios de una herramienta coincidan exactamente con su descripción. Una herramienta
get_user_profileque también actualiza una marca de tiempo de "última visualización" tiene un efecto secundario no documentado: nómbrala para reflejar todo lo que hace, o separa la escritura. - Limita los datos a los que una herramienta puede acceder a lo que la tarea realmente necesita. Una herramienta que consulta un registro completo del cliente cuando la tarea solo necesita una dirección de envío conlleva un riesgo innecesario sin beneficio funcional.
- Trata las herramientas
basho de comandos genéricos como la excepción, no como la regla. Una herramienta de ejecución de shell amplia otorga al agente la máxima influencia y al sistema de control la mínima capacidad para controlar, auditar o paralelizar; promueve acciones específicas a herramientas dedicadas en su lugar.
Reglas de Nomenclatura
- Nombra las herramientas por lo que hacen, no por cómo se implementan.
refund_order, nocall_billing_endpoint: el modelo razona sobre el propósito de la herramienta, y un nombre con forma de implementación lo obliga a inferir la intención a partir de los internos. - Utiliza un patrón verbo-objeto de forma consistente en todo el conjunto de herramientas.
create_ticket,search_orders,send_email: una nomenclatura consistente reduce la incertidumbre del modelo sobre qué herramienta se aplica a un paso dado. - Nunca reutilices el nombre de una herramienta para una acción funcionalmente diferente en diferentes agentes. Si dos agentes en el mismo sistema exponen
search, pero uno busca documentos y el otro busca registros de clientes, un sistema de control compartido o un fragmento de prompt compartido pueden redirigir silenciosamente de forma incorrecta. - Escribe descripciones de herramientas que indiquen cuándo llamarlas, no solo lo que hacen. "Buscar saldos de cuentas" invita a más ambigüedad de activación que "Llama a esto cuando el usuario pregunte por su saldo actual o el total de transacciones recientes".
Reglas de Validación
- Valida cada entrada de herramienta antes de que se ejecute, nunca confíes en que esté pre-sanitizada. Los argumentos del modelo son texto generado, no datos verificados; aplica la misma validación de entrada que aplicarías a un formulario enviado por el usuario.
- Valida cada salida de herramienta antes de que vuelva a entrar en el contexto del modelo. Un resultado inesperadamente grande, mal formado o de forma inesperada debe ser capturado y truncado o rechazado, no devuelto al modelo sin verificar.
- Rechaza las entradas silenciosamente incorrectas de forma ruidosa. Devolver un resultado de herramienta con
is_error: truey un mensaje claro permite a Claude adaptarse; devolver silenciosamente un valor vacío o predeterminado le enseña que la llamada tuvo éxito cuando no fue así. - Impón restricciones de esquema que el modelo no pueda ignorar. Utiliza enums para conjuntos de valores fijos y campos obligatorios para cualquier cosa sin lo cual la herramienta no pueda funcionar; no confíes solo en una descripción para imponer una restricción que el esquema puede imponer directamente.
- Sanitiza las rutas de archivos y los identificadores antes de tocar el sistema de archivos o una base de datos. Una ruta o ID proporcionada por el modelo es una entrada no confiable; resuélvela y válídala contra una raíz permitida o un conjunto de IDs permitidos antes de usarla en cualquier operación con efectos secundarios.
Reglas de Permiso y Seguridad
- Controla las llamadas a herramientas destructivas o irreversibles detrás de una confirmación explícita. Las eliminaciones, los pagos y las escrituras en producción nunca deben ejecutarse automáticamente sin un paso de aprobación humana o una justificación sólida y revisada para omitir uno.
- Limita las credenciales por herramienta, no por agente. Una herramienta que solo necesita leer un calendario no debe compartir una credencial que también pueda escribir en facturación; el radio de explosión de una herramienta comprometida o mal utilizada debe limitarse a lo que esa herramienta realmente necesita.
- Registra cada llamada a una herramienta con efectos secundarios, independientemente de la transcripción de la conversación. Un registro de conversación puede ser editado, truncado o perdido; un registro de auditoría dedicado para llamadas a herramientas sensibles sobrevive de forma independiente.
- Establece un límite estricto en cuántas veces se puede llamar a una herramienta en un solo turno del agente. Un reintento o bucle ilimitado contra una herramienta con efectos secundarios puede convertir un error en un incidente más rápido de lo que un humano puede intervenir.
Reglas de Composibilidad
- Revisa el conjunto completo de herramientas en busca de propósitos superpuestos, no solo cada herramienta individualmente. Dos herramientas que pueden realizar una tarea técnicamente crean ambigüedad que el modelo debe resolver por sí solo, a menudo de manera inconsistente entre llamadas.
- Mantén el recuento de herramientas enfocado: demasiadas herramientas degradan la precisión de la selección. Un agente que elige entre cuarenta herramientas vagamente relacionadas toma peores decisiones que uno que elige entre ocho herramientas bien definidas; utiliza la búsqueda de herramientas o conjuntos de herramientas específicos de la tarea en lugar de exponer todo en todas partes.
- Prueba las interacciones de herramientas, no solo los esquemas de herramientas individuales. Una herramienta que funciona correctamente de forma aislada aún puede producir un mal resultado cuando su salida alimenta la entrada de una segunda herramienta de una manera que nadie probó.
- Documenta qué herramientas son seguras para llamar en paralelo y cuáles no. Una herramienta de solo lectura y una herramienta que muta el estado se comportan de manera diferente bajo llamadas concurrentes; haz explícita esa distinción en lugar de dejar que el sistema de control adivine.
Preguntas Frecuentes
¿Cuál es la regla de mayor apalancamiento en esta lista?
Limitar cada herramienta a una acción bien definida: la mayoría de las reglas de nomenclatura, validación y permisos se vuelven más fáciles de aplicar una vez que el propósito de una herramienta es estrecho y no ambiguo.
¿Por qué validar las entradas y salidas de la herramienta por separado?
Fallan de manera diferente. Una entrada incorrecta permite que un argumento mal formado o malicioso llegue a un sistema real; una salida incorrecta permite que un resultado roto o sobredimensionado corrompa silenciosamente el siguiente turno del modelo. Capturar uno no captura el otro.
¿No es una herramienta `bash` amplia más flexible que muchas herramientas estrechas?
Es más flexible para el modelo, pero menos controlable para el sistema de control: una herramienta dedicada te da un punto de conexión para controlar, auditar, renderizar o paralelizar una acción específica, mientras que un comando de shell es una cadena opaca cada vez. Reserva bash para necesidades de amplitud genuinas y promueve cualquier cosa sensible a su propia herramienta.
¿Cuántas herramientas son "demasiadas" para un solo agente?
No hay un número fijo, pero la precisión de la selección se degrada a medida que crece el conjunto de herramientas y se vuelven más difíciles de distinguir. Si las herramientas comienzan a superponerse en propósito o el modelo comienza a elegir de manera inconsistente, esa es la señal para dividir por tarea o agregar búsqueda de herramientas en lugar de agregar más herramientas de forma plana.
¿Debería cada herramienta requerir confirmación humana para ser segura?
No, eso haría que los agentes fueran inutilizables para el trabajo rutinario. Reserva las puertas de confirmación para acciones destructivas, irreversibles o de alto costo, y deja que las acciones de solo lectura o de bajo riesgo se ejecuten automáticamente.
¿Contra qué protege "limitar las credenciales por herramienta"?
Una única credencial sobrerreglada compartida entre muchas herramientas significa que cualquier herramienta mal utilizada, por un error, una llamada incorrecta del modelo o una inyección de prompt, puede afectar todo lo que esa credencial puede tocar. Las credenciales limitadas mantienen el radio de explosión contenido.
¿Por qué la nomenclatura de herramientas importa si la descripción es precisa?
Porque el modelo utiliza el nombre como una señal de primer paso antes de leer la descripción completa, y un nombre que engaña (con forma de implementación, patrón de verbo inconsistente) agrega fricción que la descripción luego tiene que superar en cada llamada.
¿Cómo se relaciona esta lista con las reglas de protección de seguridad en otras partes de esta sección?
Las reglas de diseño de herramientas se refieren a la forma de la herramienta en sí; Reglas de Protección de Seguridad que Todo Líder Técnico Debe Aplicar cubren el sistema más amplio que la rodea: permisos, registro y validación de salida como una preocupación de todo el sistema en lugar de una por herramienta.
¿Cuál es una señal concreta de que una herramienta necesita ser dividida?
Si no puedes describir lo que hace en una oración sin usar "y", o si dos sitios de llamada diferentes la usan para propósitos funcionalmente diferentes, está manejando más de una acción y debería dividirse.
¿Deben los esquemas de herramientas ser estrictos con los tipos y los enums?
Sí, siempre que el conjunto de valores sea conocido: los enums y los campos obligatorios permiten que el propio esquema rechace entradas inválidas antes de que el código de la herramienta se ejecute, lo cual es más confiable que depender de la prosa en la descripción.
¿Por qué establecer un límite estricto en el número de llamadas a herramientas por turno?
Porque un bucle ilimitado contra una herramienta con efectos secundarios, una tormenta de reintentos, un agente descontrolado, convierte lo que debería ser un error detectado en un incidente de producción antes de que nadie se dé cuenta, especialmente fuera del horario comercial.
Relacionados
- Reglas de Protección de Seguridad que Todo Líder Técnico Debe Aplicar - las reglas de permisos y auditoría a nivel de sistema que se basan en el alcance a nivel de herramienta.
- Higiene de Prompts y Contexto: Reglas para Mantener los Agentes Confiables - cómo los resultados de las herramientas se retroalimentan en el contexto que estas reglas protegen.
- Las Reglas Centrales de Claude: Una Lista de Referencia Rápida - la versión condensada de estas reglas junto con todas las demás categorías.
- Mejores Prácticas de las Reglas de Claude - cada regla en esta sección reformulada como una lista de verificación.
Versiones de Stack: Escrito contra la línea de modelos Claude actual a partir de ~junio de 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (el predeterminado) y Claude Haiku 4.5 - y el SDK oficial de Python
anthropic(última versión 0.x). Los nombres de los modelos, los precios y las versiones del SDK cambian rápidamente; verifica los detalles actuales en platform.claude.com/docs antes de confiar en ellos.