Esta es la llamada de creación que recibe una conexión de Claude para las Notes de osFoundry. Se obtuvo con un tools/list sin autenticar contra el endpoint MCP público el 2026-11-09 y está recortada:
{"name": "create_note_tab",
"description": "Create a new Slides or Sheet tab in an approved Note. Use the version from list_note_tabs; returns the exact new tab ID for later edits. An optional outline fills a Slides tab. A repeated idempotency key returns the first tab.",
"inputSchema": {
"required": ["note_id", "expected_version", "idempotency_key", "tab_type"],
"properties": {
"tab_type": {"enum": ["slides", "sheet"]},
"label": {"type": "string"},
"slides": {"type": "array", "minItems": 1, "maxItems": 20,
"items": {"required": ["title"], "additionalProperties": false,
"properties": {"title": {}, "body": {}, "notes": {}}}}},
"additionalProperties": false},
"annotations": {"readOnlyHint": false, "destructiveHint": true},
"securitySchemes": [{"type": "oauth2", "scopes": ["osfoundry:write"]}]}
Sus dos vecinas para este trabajo:
{"name": "add_note_source",
"description": "Add an HTTP or HTTPS citation to the Sources tab of an approved Note. Uses the Note version and an idempotency key; returns the new source ID.",
"inputSchema": {"required": ["note_id", "expected_version", "idempotency_key", "title", "url"]}}
{"name": "list_note_tabs",
"description": "List every tab instance and its type. A Note may have multiple Slides or Sheet tabs; use the exact tab ID returned here."}
Tres frases sostienen el diseño: "every tab instance", "returns the exact new tab ID" y "a repeated idempotency key returns the first". El resto del post reconstruye las herramientas en Python y mide qué evita cada una de esas frases. El bloqueo optimista sobre la versión de la Note es tema de otro post y aquí solo aparece donde interactúa con las otras dos.
¿Qué puede poner Claude realmente en una diapositiva?
Menos que el asistente propio de la app de escritorio. Dentro de osFoundry, slide_create_deck_from_outline y slide_add_slide del asistente de Notes (en apps/web/src/screens/notes/lib/note-surface-tools.ts) aceptan layouts, viñetas, contenido a dos columnas, tablas, imágenes y uno de cinco temas. El elemento de outline del conector es title, body, notes, con additionalProperties: false. edit_note_tab ofrece slide_add para una diapositiva y slides_add_outline para un array, ambos con los mismos tres campos.
code/note_store.py carga la respuesta guardada de tools/list y valida los payloads contra ella con un validador mínimo (required, enum, additionalProperties, minItems/maxItems). Ocho payloads que un modelo podría enviar perfectamente:
edit_note_tab {"operation": "slide_add", "title": "Sources", "body": "3 links"} -> ok
edit_note_tab {"operation": "slide_add", "title": "Sources", "index": 0} -> unexpected index
edit_note_tab {"operation": "slides_add", "slides": [{"title": "a"}]} -> operation: not in enum
edit_note_tab {"operation": "slides_add_outline", "slides": [{... "bullets"}]} -> slides: [0] unexpected bullets
create_note_tab {"tab_type": "slides", "slides": "[21 items]"} -> slides: maxItems 20
create_note_tab {"tab_type": "markdown"} -> tab_type: not in enum
add_note_source {"url": "https://example.org/report"} -> missing title
list_note_attachments {"kind": "sources", "limit": 100} -> ok
El último pasa este validador, pero no el esquema real completo: limit tiene maximum: 50, y la reconstrucción no lo comprueba. slide_add no puede elegir posición, create_note_tab no puede crear una pestaña Markdown y un deck de más de 20 diapositivas necesita más de una llamada. Un esquema estrecho es una decisión sobre quién da estilo al deck: el conector escribe el contenido y una persona en la app de escritorio aplica temas y layout.
¿Por qué un ID de pestaña exacto y no "la pestaña de slides"?
Porque la propia app de escritorio sigue aceptando el atajo, y el atajo elige la primera coincidencia. resolveTabInstanceId() en apps/web/src/screens/notes/types.ts:
if (cfg.some((t) => t.id === rawTabId)) return rawTabId
const byType = cfg.find((t) => t.type === rawTabId)
if (byType) return byType.id
Ese fallback mantiene funcionando enlaces antiguos como …/slides. Para un agente significa que "editar slides" va a parar a la pestaña de Slides que esté primero en la barra. Las pestañas nuevas reciben IDs como slides-9-mh8z1k2a de nextTabId() en NotesContentPanel.tsx, las fijas son markdown, files y sources, y una persona puede añadir tantas pestañas de Slides como quiera, arrastrarlas a otro orden y renombrarlas, incluso con nombres repetidos (handleRename solo hace trim).
La reconstrucción le da a una Note K pestañas de Slides con etiquetas distintas. Un agente scriptado lista las pestañas, elige un deck como objetivo y guarda una referencia a él: su posición en la barra, su tipo, su etiqueta o su ID. Entre turnos del agente, la persona hace de cero a dos cambios aleatorios (mover una pestaña 40%, renombrar una pestaña de Slides con una de las cinco etiquetas 35%, añadir una pestaña de Slides 25%). Después el agente vuelve a listar y resuelve su referencia. 10,000 pruebas por K, seed 7:
| K decks | referencia | correcto | deck equivocado | no encontrado |
|---|---|---|---|---|
| 2 | posición | 83.7% | 16.3% | 0.0% |
| 2 | tipo | 50.7% | 49.3% | 0.0% |
| 2 | etiqueta | 85.6% | 2.1% | 12.3% |
| 2 | ID | 100% | 0 | 0 |
| 5 | posición | 82.7% | 17.3% | 0.0% |
| 5 | tipo | 19.7% | 80.3% | 0.0% |
| 5 | etiqueta | 92.1% | 3.0% | 5.0% |
| 5 | ID | 100% | 0 | 0 |
La referencia por tipo acierta 1/K de las veces, como era de esperar. La posición falla cada vez que un arrastre cruza el objetivo, sea cual sea K. La etiqueta es la tentadora, porque es lo que la persona escribe en el prompt, y acierta la mayoría de las veces. El 2–3% en que falla son los casos malos: otro deck lleva ahora esa etiqueta y el agente escribe en él sin ningún error. "No encontrado" es el fallo seguro. Un ID se asigna una vez y nunca se reutiliza, así que sobrevive a cualquier cambio que la persona pueda hacer en la barra de pestañas.
¿La comprobación de versión no detecta ya una pestaña equivocada?
No. Cada cambio en la barra de pestañas de los de arriba incrementa la versión de la Note, así que una escritura obsoleta se rechaza y el agente vuelve a listar. El nuevo listado le da una versión actual, y entonces resuelve su referencia antigua contra la lista nueva. En la reconstrucción, el 100% de esas escrituras pasa la comprobación de versión, incluidas todas las que apuntan al deck equivocado. La versión demuestra que el agente vio la Note más reciente. No dice nada de si encontró la pestaña correcta dentro de ella. De eso se encarga el ID de pestaña.
¿Dónde va la comprobación de idempotencia, antes o después de la de versión?
Antes, o la promesa de la descripción de la herramienta se rompe. Se ejecuta create_note_tab 50 veces por run con un 30% de respuestas perdidas después de que el servidor hiciera commit, que es como se ve un timeout del host desde el cliente. El cliente reenvía la misma llamada. Tres políticas de cliente, dos órdenes de servidor, seeds 1–3:
| el servidor comprueba | política de clave del cliente | pestañas creadas (llamadas enviadas) |
|---|---|---|
| clave, luego versión | clave nueva por llamada | 63 (76) / 75 (100) / 62 (74) |
| clave, luego versión | misma clave al reintentar | 50 (67) / 50 (81) / 50 (62) |
| clave, luego versión | clave nueva tras un conflicto | 50 (67) / 50 (81) / 50 (62) |
| versión, luego clave | clave nueva por llamada | 63 (76) / 75 (100) / 62 (74) |
| versión, luego clave | misma clave al reintentar | 50 (79) / 50 (98) / 50 (72) |
| versión, luego clave | clave nueva tras un conflicto | 72 (94) / 73 (96) / 61 (72) |
El reenvío lleva la versión de antes del commit perdido. Un servidor que comprueba primero la versión ve una versión obsoleta y devuelve un conflicto en lugar del primer resultado. Un cliente que reacciona a los conflictos de la forma sensata, volviendo a leer y tratando el siguiente intento como una intención nueva con una clave nueva, crea ahora un segundo deck. Incluso un cliente que conserva su clave envía un 16–21% más de llamadas. Con la clave comprobada primero, el reenvío devuelve el ID de pestaña original diga lo que diga la versión. Eso es lo que tiene que significar "a repeated idempotency key returns the first tab".
¿Qué clave debería llevar add_note_source?
La reconstrucción ejecuta 300 sesiones de investigación. Cada una tiene tres turnos, en cada turno se citan 6 de 8 páginas, y una página puede volver en cualquiera de siete formas de escribirla: con barra final, con www., con ?utm_source=…, con un #fragment, con http:// o sin esquema. El 20% de las respuestas se pierde y se reenvía con la misma clave.
| clave | fuentes guardadas | duplicados | por sesión |
|---|---|---|---|
| UUID nuevo por cita, reutilizado al reenviar | 5,400 | 3,038 | 10.13 |
| hash de la URL tal como está escrita | 4,814 | 2,452 | 8.17 |
| hash de la URL normalizada y el ID de la Note | 2,362 | 0 | 0.00 |
Una clave nueva por cita cubre las respuestas perdidas (ninguna fila de esa primera línea viene de un reenvío) y nada más. Una investigación vuelve a citar la misma página en el siguiente turno, y cada turno nuevo es una clave nueva. Hacer hash de la URL tal como está escrita detecta repeticiones exactas, pero no ?utm_source= ni una barra final. La clave que elimina los duplicados nombra la intención, "esta página es una fuente de esta Note", haciendo hash de note_id más una URL normalizada (https, host en minúsculas sin www., sin fragmento, sin utm_*, sin barra final).
El formulario de Sources de la propia app de escritorio hace una versión más ligera de esto. NotesSourcesTab.tsx normaliza el enlace escrito con new URL(...) y rechaza uno que ya esté adjunto ("This source is already attached"). En la reconstrucción, comparar hrefs al estilo del navegador habría detectado 725 de los 3,038 duplicados de la primera fila. El add_note_source del conector no anuncia ninguna comprobación de URL, así que la clave es donde el agente la expresa. Una clave derivada de la URL tiene un efecto secundario: volver a añadir la misma página con una descripción mejor devuelve la primera fila. Editarla es trabajo de la pestaña Sources.
¿Una sola creación con outline o diapositiva por diapositiva?
Coste de un deck de 12 diapositivas, con cada petición validada contra el esquema real:
| enfoque | escrituras | bytes de petición | conflictos por deck |
|---|---|---|---|
create_note_tab con slides
|
1 | 1,673 | 0.070 |
creación vacía + 12 × slide_add
|
13 | 5,237 | 0.817 |
La columna de conflictos es un modelo, no una medición de osFoundry: 4 s entre la lectura del agente y su escritura, una persona guardando en algún lugar de la Note una vez por minuto de media (exponencial), 2,000 decks simulados. Cada escritura abre una nueva ventana en la que la versión de la Note puede moverse, así que construir diapositiva por diapositiva exige unas doce veces más relecturas. Mete el deck en el outline (hasta 20 diapositivas) y usa slide_add para la diapositiva que solo descubres después.
La paginación es el otro número que conviene conocer. list_note_attachments limita limit a 50, así que una Note con 120 fuentes necesita 3 llamadas para listarse.
Cómo se ejecutó la reconstrucción
En esta máquina no corre ningún binario de Claude. code/run.py hace de agente y llama directamente a code/note_store.py. El store vive en memoria detrás de un único lock, con un contador como versión. Los nombres de herramientas, campos obligatorios, enums y límites de elementos vienen del esquema real en code/tools_list.raw, y los IDs de pestaña siguen a nextTabId(). La forma de los errores, el ámbito de las claves (aquí, por Note) y el orden de idempotencia son decisiones propias de la reconstrucción, y el segundo orden existe solo para mostrar qué sale mal. Python 3.9.6 en Apple Silicon, los cinco experimentos en 1.0 s de tiempo real. La salida está en code/run.out.
Si lo montas tú mismo
- Devuelve un ID por instancia en cada llamada de listado y de creación, y haz que las herramientas de edición lo exijan. No resuelvas tipos ni etiquetas en el camino de escritura, aunque tu UI todavía los acepte en las URLs.
- Comprueba la clave de idempotencia antes que la versión. Un reenvío tras una respuesta perdida siempre lleva la versión antigua.
- Explica a los agentes en la descripción de la herramienta qué debe nombrar una clave. Para citas, "esta URL en este documento", normalizada, elimina repeticiones entre turnos. Un UUID aleatorio solo cubre los reenvíos.
- Mantén pequeña la forma de diapositiva del conector (title, body, notes) y deja el diseño a la persona en el editor. Un esquema pequeño significa menos campos en los que un modelo puede equivocarse.
- Deja que los agentes envíen un outline completo en una sola llamada y ponle un tope (osFoundry usa 20). Menos escrituras significa menos ventanas de conflicto en un documento compartido.
- Devuelve metadatos de los adjuntos, nunca contenido ni enlaces firmados, por el canal del agente. Un enlace sobrevive a la sesión que lo obtuvo.
Lo que guarda la pestaña Sources del lado de la persona está en la página de la pestaña Sources. El protocolo que hay debajo se resume en la entrada del glosario sobre MCP de osFoundry.
Top comments (0)