Ir al contenido principal
Español— Elegir un idioma
Menú

Diseño: casos de uso y herramientas

Lección 3 de 14 Actualizado el 3 de noviembre de 2026 Desarrollador
En esta página
  1. Empieza por las expectativas, no por la API
  2. El inventario de casos de uso
  3. Excluye y documéntalo
  4. De los casos de uso a las herramientas
  5. El contrato de cada herramienta
  6. Descripciones escritas para ser elegidas
  7. Anotaciones de seguridad
  8. Un plan que sirve como plan de pruebas
  9. Puntos clave

Lección reescrita el 3 de noviembre de 2026 basándose en las páginas de documentación de OpenAI Brainstorm plugin use cases y Define tools. La lección anterior instalaba un paquete inexistente @openai/apps-sdk y un manifiesto chatgpt-app.json; la instalación de las herramientas reales (SDK oficiales de MCP) tiene lugar en la Lección 4. Fuentes: Brainstorm plugin use cases · Define tools.

Empieza por las expectativas, no por la API

La documentación de OpenAI indica que debes empezar a construir un complemento antes de escribir una sola línea de código: enumerando qué esperarán los usuarios de él. El nombre del complemento, su descripción, capacidades, herramientas y el producto al que se adjunta generan expectativas; tu implementación debe cumplirlas o tener una razón deliberada para no hacerlo.

Imagina a alguien que ha instalado tu complemento sin leer su documentación. ¿Qué le pedirá que haga? Para averiguarlo, basa tu análisis en las tareas que tus usuarios ya realizan en tu producto, tickets de soporte, consultas de búsqueda, solicitudes de funciones, el vocabulario que emplean y las soluciones temporales que les obligan a copiar datos de una herramienta a otra. Ten en cuenta las solicitudes directas que nombran el complemento y las indirectas que solo indican el objetivo: un complemento de gestión de proyectos debe gestionar «Mostrar el tablero de lanzamiento de Acme» igual que «¿Qué está bloqueando el lanzamiento?».

No limites este inventario a lo que tu API ya hace. Enumera primero las expectativas y compáralas después con lo que puedes ofrecer de forma segura y fiable.

El inventario de casos de uso

Para cada caso de uso, OpenAI recomienda responder a siete preguntas:

CampoPregunta
Objetivo¿Qué intenta conseguir la persona?
Solicitudes de ejemplo¿Cómo lo formularía, de forma directa o indirecta?
Resultado esperado¿Qué haría que la interacción fuera exitosa?
Contexto necesario¿Qué información, acceso a la cuenta o estado previo se necesita?
Capacidad¿Es suficiente una habilidad o se requiere una herramienta MCP?
Límite de seguridad¿Podría exponer datos, modificar el estado, gastar dinero o afectar a un tercero?
Decisión¿Primera versión, más adelante o exclusión intencionada?

Agrupa las solicitudes que compartan un objetivo: «Listar mis tareas abiertas», «¿Qué tengo que hacer hoy?» y «Mostrar trabajo atrasado» probablemente pertenezcan al mismo caso de uso de revisión de tareas, con diferentes filtros.

Verifica después la cobertura. Cada caso de uso seleccionado debe tener un camino completo desde la solicitud hasta el resultado; las escrituras deben incluir autorización y confirmación; y el complemento debe saber indicar qué no hace mientras ofrece un siguiente paso útil. Un complemento que permite crear proyectos pero no listarlos, verlos ni editarlos promete más de lo que entrega: o bien complétalo o reduce su posicionamiento.

Excluye y documéntalo

No tienes que implementarlo todo, pero cada exclusión importante merece una razón: riesgo inaceptable de seguridad o privacidad, una API que no puede soportarlo de forma fiable, permisos no verificables, resultados engañosos por falta de información o un alcance de primera versión claramente declarado en el listado del complemento. Registra estas decisiones: informan los límites de las habilidades, las descripciones de las herramientas, los rechazos, las pruebas y el texto del listado público.

De los casos de uso a las herramientas

Una herramienta debe servir a un objetivo del usuario. No copies simplemente tu API interna tal cual. Para cada caso de uso seleccionado, escribe el resultado esperado, enumera la información necesaria, identifica lecturas, escrituras y acciones externas, agrupa lo que forma una acción coherente y separa lo que difiere por permisos, riesgo o necesidad de confirmación.

El ejemplo de OpenAI para un complemento de proyectos:

  • list_projects para encontrar proyectos;
  • get_project para examinar uno;
  • create_project para crear uno;
  • update_project para modificar detalles;
  • archive_project para un cambio de estado de alta consecuencia.

Las lecturas y escrituras se separan para que el modelo y el usuario puedan distinguir entre consulta y modificación.

El contrato de cada herramienta

CampoDefine
NombreUn identificador estable y orientado a la acción
TítuloUna acción concisa y legible para humanos
DescripciónEl objetivo del usuario y las condiciones que deberían activar la herramienta
Esquema de entradaParámetros obligatorios y opcionales, tipos, valores permitidos, límites
Esquema de salidaCampos estructurados que el modelo puede inspeccionar y reutilizar
AutorizaciónLa cuenta, rol o acceso que el servidor debe verificar
Efectos secundariosDatos o estado externo que la herramienta puede modificar
FallosErrores que el modelo puede explicar o de los que puede recuperarse

Tres reglas completan esta tabla. Entradas explícitas: no confíes en que el modelo adivine un ID o el ámbito de una cuenta. Salidas reutilizables: devuelve IDs estables y suficiente información para la siguiente llamada. Salidas limpias: sin secretos, tokens de acceso, diagnósticos internos ni datos personales innecesarios.

Descripciones escritas para ser elegidas

El modelo selecciona herramientas basándose en su descripción: describe la intención del usuario, no la implementación. Una buena descripción indica qué hace la herramienta, cuándo usarla, en qué se diferencia de sus vecinas y cuáles son sus límites o prerrequisitos. Evita aquellas que repiten el nombre de la herramienta o usan jerga interna que tus usuarios no conocen.

Anotaciones de seguridad

Cada herramienta lleva anotaciones, establecidas según su comportamiento real:

  • readOnlyHint es true solo si la herramienta no puede modificar ningún estado;
  • destructiveHint es true si la herramienta puede producir un resultado irreversible o difícil de deshacer;
  • openWorldHint es true si la herramienta accede a internet público o entidades externas abiertas, incluso si es de solo lectura como una búsqueda web. Una cuenta o espacio de trabajo privado y delimitado no es «abierto» solo porque esté alojado en otro lugar.

Las anotaciones ayudan a ChatGPT y Codex a elegir el nivel de confirmación adecuado, pero no sustituyen la autorización del lado del servidor, la validación de entradas ni la confirmación para acciones importantes.

Un plan que sirve como plan de pruebas

Mantén el inventario y el plan de herramientas: se convierten en tu lista de comprobación. Añade solicitudes directas, indirectas, de casos límite y fuera de alcance, y verifica que el complemento terminado se comporte como se espera para cada una. Busca también herramientas que no sirvan a ningún caso de uso documentado, lecturas faltantes antes de escrituras y descripciones demasiado similares que puedan confundir al modelo.

Puntos clave

  • Empieza por lo que los usuarios esperarán y compáralo con lo que puedes ofrecer de forma segura
  • Un inventario de siete preguntas por caso de uso, incluidas las exclusiones intencionadas
  • Una herramienta por acción coherente; lecturas y escrituras separadas
  • Un contrato por herramienta: nombre, título, descripción, esquemas, autorización, efectos secundarios, fallos
  • Las anotaciones (readOnlyHint, destructiveHint, openWorldHint) siguen el comportamiento real y no sustituyen la autorización