docs: corrige API de hooks (CocoDB::getInstance no existe) y documenta modelo de ejecución, escape() y aviso de fiabilidad de write-ops del MCP

Hallazgos de fricción real en producción (turismo, onefix-appv1, pisorentado.com):
- CocoDB::getInstance() no existe (fatal), sustituido por DB::getInstance() como última opción
- El enrutado HTTP directo de /hooks/<id>/ da 404 en Forge; documentado el patrón vía filtro | hook
- Modelo de ejecución eval(): __DIR__ vs APP_ROOT_PATH, params por HTTP vs filtro Twig
- DB::escape() ya entrecomilla el literal; patrón seguro documentado
- Nunca delegar hashing de contraseñas en el CMS (create_field no tiene tipo password; SHA1 inadecuado)
- Aviso de que success:true en write-ops/DDL del MCP no garantiza que la operación se aplicó

docs/mcp-tools-reference.md

@@ -1,5 +1,21 @@
 # MCP Tools Reference
 
+## ⚠️ `success:true` no siempre significa que la operación se aplicó
+
+Las write-ops/DDL (`create_field`, `update_field`, `acai-write`, `acai-line-replace`,
+`set_layout_field`, `update_table_metadata`, `create_table`…) pueden devolver `success:true` /
+`writeCompleted:true` **aunque el cambio real (ALTER de MySQL, insert, compilación Twig) no se haya
+aplicado**. `get_table_schema` refleja el registro/`.ini`, no necesariamente el estado real de MySQL.
+
+**Verifica siempre con una operación real posterior**, nunca te fíes solo de la respuesta del tool:
+- Tras escribir/editar un módulo: `compile_module` o recargar la página y comprobar que renderiza.
+- Tras crear/editar un campo: hacer un insert/update real en esa tabla y confirmar que no falla.
+- Tras un insert, si necesitas el id, no te fíes ciegamente de `lastId`/`insert_id` — si algo no cuadra,
+  relee por un campo único ya conocido.
+
+Es más lento que confiar en la respuesta, pero el coste de no hacerlo es peor: este es el fallo más
+repetido del equipo (bloqueos de insert silenciosos, módulos servidos rotos, registros fantasma).
+
 ## Quick Reference
 
 | Tool | Categoría | Acción |