Enséñale a tu agente de IA qué hace tu aplicación XAF realmente.
Apúntalo a un módulo XAF. Lee tus entidades, controladores, acciones, reglas de negocio, navegación y personalizaciones del Model Editor directamente desde el código fuente — y entrega el resultado a cualquier agente con el que programes.
DevExpress ha hecho un excelente trabajo para que los agentes de IA dominen XAF. Ya existen dos piezas, y esta es la tercera:
Enseña al agente… | Herramienta |
Cómo funciona XAF en general | |
Lo que dice la documentación oficial | |
Lo que hace TU aplicación | XAF Logic Explainer ← estás aquí |
Un agente que ha leído cada página de la documentación de XAF aún no sabe que tu total de Invoice
se calcula a partir de sus líneas, que ApproveController se niega a ejecutarse cuando el período está
cerrado, o que tres columnas se ocultaron en el Model Editor y no aparecen en ningún archivo C#.
Inventará con confianza las tres.
Ese vacío no se soluciona con mejores indicaciones. Se soluciona con extracción.
Estas herramientas se complementan. Instala las habilidades de DevExpress para el conocimiento del framework, usa el Docs MCP para la referencia oficial, y usa esto para tu propia base de código. Ninguna reemplaza a las otras.
Related MCP server: mcp-digger
Todo lo siguiente se lee como sintaxis, usando Roslyn. Tu proyecto nunca necesita compilarse, y esta herramienta nunca se enlaza contra los ensamblados de DevExpress:
Entidades — propiedades, tipos, asociaciones y los atributos XAF que les dan significado
([Association], [Aggregated], [RuleRequiredField], [Appearance], [ModelDefault], …).
XPO y EF Core, detectados automáticamente a partir de tus sentencias using.
Controladores y acciones — SimpleAction, PopupWindowShowAction, SingleChoiceAction,
sus criterios de destino y el código del manejador que se ejecuta cuando se activan.
Reglas de negocio — atributos de validación y reglas de código, con las condiciones adjuntas.
Configuración del módulo — datos semilla de ModuleUpdater y lo que se crea en la primera ejecución.
Navegación — los grupos y elementos que tus usuarios ven realmente.
Model Editor (.xafml) — las personalizaciones que existen solo en XML y son invisibles para
cualquiera que lea tu C#. Los archivos del módulo y de la plataforma se fusionan como lo hace XAF.
Editores de propiedades y listas personalizados — incluyendo el JavaScript del que no pueden prescindir, y
editores integrados reconfigurados en tiempo de ejecución a través de View.CustomizeViewItemControl<T>(). Estos
viven en el proyecto de plataforma junto al módulo, por lo que nadie que lea los objetos de negocio los encuentra.
Migraciones controladas por versión — los bloques CurrentDBVersion < new Version(…) en tu actualizador.
Cada uno se ejecuta como máximo una vez para cualquier base de datos, y es la única explicación para datos que el código actual
no puede justificar.
Cada pantalla, y qué se carga en ella — ver más abajo.
Estas son la razón por la que un agente que ha leído cada clase de negocio aún puede estar equivocado con confianza sobre la aplicación:
Nada en un repositorio XAF responde a eso, y ambas mitades faltan por diferentes razones.
Las pantallas en sí mismas no están en ningún archivo. XAF genera una vista de lista, detalle y búsqueda para
cada clase de negocio, más una vista de lista para cada colección, y el Model Editor almacena solo aquellas
que alguien modificó. Buscar en tu código fuente Patient_Prescriptions_ListView no encuentra nada —
y eso no es evidencia de que falte.
Qué controladores se ejecutan allí se decide en tiempo de ejecución, mediante cuatro condiciones que XAF combina con AND: anidación, tipo de vista, tipo de objeto e id de vista. Cada una no tiene restricciones cuando no se establece, por lo que un controlador que no establece ninguna se carga en todas las pantallas que tienes.
Esto lee las cuatro como ViewController.IsFitToView las evalúa, contra un inventario de vistas construido a partir de los generadores de id del propio framework — y registra por qué coincidió cada una, para que la respuesta
pueda verificarse en lugar de confiarse:
Dos capas, mantenidas separadas. Lo que escribió tu equipo recibe el tratamiento completo; lo que proporciona XAF está plegado detrás de una línea, porque hay mucho y no es tuyo para cambiarlo. Con un catálogo de referencia también se nombra — limitado a los módulos que realmente registras, para que un controlador de WinForms nunca aparezca en una pantalla de Blazor.
Lo que no afirmará: un controlador listado aquí aún puede desactivarse mediante
Active["reason"], que depende de los datos y del usuario. Esto es lo que XAF carga en una
pantalla, no lo que necesariamente hará algo — y cualquier cosa que no pudo leer del código fuente se lista aparte,
con el motivo, en lugar de tratarse silenciosamente como "se ejecuta en todas partes".
dotnet tool install -g XafLogicExplainer.Cli
xaflogic agents --project "C:\MySolution\MyApp.Module"Eso escribe AGENTS.md, CLAUDE.md y .github/copilot-instructions.md en la raíz de tu solución.
Sin cuenta, sin clave API, sin servidor. Tu agente entiende la aplicación en su siguiente pregunta.
AGENTS.md se antepone a cada solicitud que un agente hace en el repositorio, por lo que su costo se paga
para siempre. Volcar 70 KB de detalle de entidades allí desplazaría la pregunta real. Por lo tanto, la salida está
organizada en niveles:
| ∼11 KB | Siempre cargado: reglas básicas, inventarios completos, convenciones, recetas |
| ∼70 KB | Abierto bajo demanda: propiedades completas, código de manejador, mensajes de reglas, |
La parte más valiosa es la más pequeña. AGENTS.md comienza con reglas básicas — que esta aplicación
usa XPO y nunca EF Core, que los inventarios son completos por lo que cualquier cosa ausente
realmente no existe, y que algo del comportamiento vive en el Model Editor en lugar de en C#. Esos
pocos párrafos detienen la mayor parte de la invención confiada que los agentes producen sobre bases de código XAF desconocidas.
Los archivos existentes nunca se sobrescriben: el texto generado vive entre marcadores, cualquier cosa que hayas escrito a mano se conserva, y la regeneración es idéntica byte a byte cuando nada ha cambiado.
Los archivos generados son una instantánea. El servidor MCP es una conexión en vivo — el agente consulta tu aplicación mientras trabajas en ella, y no puede quedar obsoleto.
/plugin marketplace add peopleworks/XAFLogicExplainer
/plugin install xaf-logic-explainer@peopleworks-xafEso instala una habilidad y un servidor MCP en un solo paso. Para cualquier otro cliente MCP, ejecútalo directamente desde NuGet sin instalación:
{
"mcpServers": {
"xaf": { "command": "dnx", "args": ["XafLogicExplainer.Mcp", "--yes"] }
}
}…o apunta a la CLI si ya la tienes:
{ "mcpServers": { "xaf": { "command": "xaflogic", "args": ["mcp"] } } }Iniciado desde un directorio de solución, encuentra el módulo XAF por sí mismo, por lo que ninguna de las formas necesita una ruta.
Herramienta | Respuestas |
| Qué es esta aplicación y la lista completa de todo lo que contiene |
| Dónde se define un campo, concepto o término de negocio |
| Cada propiedad, relación, regla y cálculo de una entidad |
| Qué hace una acción — incluido el C# que se ejecuta cuando se dispara |
| Qué valida, calcula, oculta y desactiva la aplicación |
| Personalizaciones del Editor de Modelo que no existen en ningún archivo C# |
| Editores personalizados, el JavaScript que necesitan y editores integrados modificados en tiempo de ejecución |
| Qué se ejecutó una vez contra una base de datos en vivo y el comentario que explica por qué |
| Todo lo cargado en una pantalla — qué controladores se activan y por qué |
| Releer el código fuente (los cambios se detectan automáticamente) |
Pregunta por algo que no esté ahí y la respuesta es la útil:
No existe una entidad llamada 'PurchaseOrder' en esta aplicación. Esta es la lista completa de 19 entidades, extraída de todo el árbol fuente: … Si el usuario espera que 'PurchaseOrder' exista, aún no se ha creado.
Combínalo con las habilidades oficiales de DevExpress. /plugin install dx-xaf@DevExpress-agent-skills
enseña cómo funciona XAF; esto enseña qué hace tu aplicación. Un agente que solo tenga la primera
escribirá XAF correcto contra entidades que no tienes.
Un agente lee AGENTS.md o consulta el servidor MCP. Alguien que acaba de heredar una aplicación
XAF de diez años necesita los mismos hechos organizados de forma muy diferente:
xaflogic explain --project "C:\MySolution\MyApp.Module" --openUn archivo HTML. Sin servidor, sin paso de compilación, sin solicitud a la red — se abre desde un archivo adjunto de correo electrónico en una máquina sin internet, que es como realmente ocurren las transferencias.
Dibuja un mapa de tu modelo de dominio a partir de los atributos de asociación dispersos en tu código base. La mayoría de los equipos nunca han visto el suyo: existe en la cabeza de una persona, que es exactamente el conocimiento que se va cuando esa persona se marcha.
Salida real, de la aplicación de ejemplo en este repositorio. Pasa el ratón sobre una entidad y todo lo que no toca se desvanece; el morado significa que eliminar el padre elimina al hijo.
Junto a él: cada entidad y qué es cada propiedad, cada acción con el código que ejecuta, validación con el mensaje que el usuario verá realmente y la configuración del Editor de Modelo que aparece en ningún archivo C#.
Y un índice de cada expresión de criterio en la aplicación — un dialecto que no es ni SQL ni C#, recopilado de atributos dispersos por el código fuente y que de otro modo no se recopila en ningún lado:
Pruébalo con el ejemplo sin tocar tu propio código:
xaflogic explain --project tests/XafLogicExplainer.Tests/Fixtures/DemoSolution/PharmacyDemo.Module --openLa extracción lee tu código fuente sin saber nada del framework contra el que está escrito,
lo que deja una pregunta sin respuesta: ¿DeleteObjectsViewController es algo que escribió tu equipo
o algo que envía DevExpress? Sin respuesta, la documentación generada presenta el comportamiento del framework
y tu propia lógica como si fueran lo mismo.
Si tienes una licencia de DevExpress:
xaflogic catalog buildEso lee tu propia instalación y registra lo que XAF mismo proporciona — atributos, controladores, interfaces de modelo y módulos, con los resúmenes oficiales y enlaces de documentación que DevExpress envía. En DevExpress 26.1 eso son alrededor de 850 tipos del framework.
Si también instalaste el componente de código fuente de DevExpress, registra dónde se activa
cada controlador del framework — las cuatro condiciones que XAF verifica antes de ejecutarlo. Eso no se puede leer
de los ensamblados: cuatro de cada cinco controladores integrados establecen su destino dentro de un constructor. Pasa
--dx-sources <Components/Sources> si no están junto a tus ensamblados.
La extracción lo recoge automáticamente y puede decir cosas que de otro modo no podría:
"ArchiveController extiende el DeleteObjectsViewController integrado" — estás cambiando cómo
funciona la eliminación en toda la aplicación, no añadiendo una característica a su lado.
"[AuditedByFinance] no es un atributo de XAF ni de .NET" — tu equipo lo inventó, por lo que su significado
vive en este código base y en ninguna documentación en ningún lado.
"32 controladores del framework también se cargan en esta pantalla" — nombrados, con lo que hace cada uno, y limitados a los módulos que tu aplicación realmente registra, por lo que un controlador de WinForms nunca aparece en una pantalla de Blazor.
El catálogo se escribe en ~/.xaflogic/catalog/, nunca en tu repositorio: se deriva de
software con licencia. Todo funciona sin él — solo agudiza la salida. Consulta
NOTICE.md.
Comando | Qué hace |
| Escribe |
| Ejecuta como servidor MCP para que los agentes puedan consultar la aplicación en vivo |
| Escribe una página HTML autocontenida que explica la aplicación a una persona |
| Construye el catálogo de referencia de DevExpress ( |
| Lee el proyecto, escribe Markdown + JSON localmente |
| Compara con la extracción anterior e informa qué cambió |
| Muestra el hash de detección de cambios y si se necesita una reextracción |
| Reextrae al cambiar archivos, con debounce |
| Extrae y publica en un destino remoto |
| Haz preguntas sobre el proyecto extraído |
| Establece valores predeterminados en |
| Gestiona varios proyectos XAF; la mayoría de los comandos aceptan |
La documentación se genera en inglés o español (--lang en|es).
Banderas útiles: --orm auto| xpo|efcore, --lang en|es, --enrich (resúmenes de lógica de negocio generados por IA
por controlador y acción), --force, --all.
--enrich necesita un modelo, y cualquiera de estos es suficiente — una clave en la línea de comandos tiene prioridad, luego el
entorno, luego una cuenta de PeopleWorks Copilot si tienes una:
xaflogic extract --enrich --api-key sk-... # or any OpenAI-compatible endpoint:
xaflogic extract --enrich --api-key ... --ai-base-url http://localhost:11434/v1 --ai-model qwen2.5-coder
export OPENAI_API_KEY=sk-... # picked up with no configuration at all
export ANTHROPIC_API_KEY=sk-ant-...Todo lo demás en esta herramienta funciona sin clave, sin cuenta y sin red.
La extracción es incremental — un SHA-256 sobre tus archivos .cs y .xafml significa que un proyecto
sin cambios es una no operación. Hay un archivo .targets de MSBuild si quieres que se ejecute al compilar.
v0.14.0. El motor de extracción es la parte madura: se ejecuta en producción contra aplicaciones XAF reales. La superficie orientada al agente es lo que está llegando ahora, en abierto.
✅ | Extracción Roslyn — entidades, controladores, reglas, actualizador, navegación, |
✅ | XPO y EF Core, detectados automáticamente |
✅ | Editores de propiedades y listas personalizados, sus activos de cliente y editores integrados reconfigurados en tiempo de ejecución |
✅ | Migraciones de datos controladas por versión — qué pasó con las bases de datos que no estaban nuevas |
✅ | Detección incremental de cambios, informes de diferencias, multiproyecto, modo de vigilancia |
✅ | Enriquecimiento con IA de controladores y acciones ( |
✅ | Panel de ayuda en la aplicación Blazor |
✅ |
|
✅ |
|
✅ | Destinos de publicación conectables ( |
✅ | Servidor MCP — 10 herramientas, en vivo contra tu código fuente |
✅ | Plugin instalable de Claude Code con habilidad y servidor MCP |
✅ | 345 pruebas sobre fixtures sintéticos de XPO y EF Core — no se necesita DevExpress |
✅ | Catálogo de referencia de DevExpress, generado localmente por titulares de licencia |
PeopleWorks Copilot, donde creció esta herramienta, es ahora un destino entre varios, en lugar del destino alrededor del cual se construyó todo. Las salidas que más importan no necesitan ningún servidor.
Por qué un tercio del comportamiento de una aplicación XAF vive fuera de sus clases de negocio, los cuatro lugares donde se esconde y cómo se ve realmente la salida extraída:
Cada uno está escrito en su propio idioma en lugar de traducido del otro. Fuentes en
docs/Blog/.
src/
XafLogicExplainer.Core Roslyn extraction engine — no DevExpress reference
XafLogicExplainer.Mcp MCP server (ModelContextProtocol 2.1)
XafLogicExplainer.Cli the `xaflogic` command
XafLogicExplainer.CopilotSync PeopleWorks Copilot target + AI enrichment
XafLogicExplainer.DescriptionAnnotator generates missing [Description] attributes
XafLogicExplainer.Blazor in-app help panel for XAF Blazor apps
plugins/
xaf-logic-explainer the installable Claude Code pluginConstruido sobre .NET 10.
Solo XafLogicExplainer.Blazor hace referencia a paquetes de DevExpress; necesita la fuente NuGet de DevExpress
y una licencia para compilar. Todo lo demás se compila en cualquier lugar, por lo que CI puede verificarlo gratis.
La contribución más valiosa es decirnos qué se perdió el extractor. XAF es enorme, cada código base usa una porción diferente, y ningún proyecto individual ejercita todo el framework. Hay una plantilla de issue de brecha de extracción exactamente para esto: muestra el patrón XAF que usa tu proyecto y qué no pudo ver la herramienta.
Consulta CONTRIBUTING.md. Los informes de errores, la documentación y las traducciones son igualmente bienvenidos.
MIT. Consulta NOTICE.md para la relación con DevExpress.
Un proyecto comunitario independiente — no afiliado, respaldado ni apoyado por Developer Express Inc. No contiene código fuente de DevExpress y no necesita una licencia de DevExpress para compilar o ejecutar. DevExpress, XAF y eXpressApp Framework son marcas comerciales de Developer Express Inc.
Construido por Pedro Hernández (PeopleWorks), Microsoft MVP para .NET — para la comunidad de DevExpress y XAF.
Full detail of one controller: which views it applies to, every action it defines with the actual C# that runs when the action fires, and its helper methods. Use when asked what a button or command actually does.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Controller class name, e.g. 'ApproveInvoiceController'. Case-insensitive. | |
| project | No | Project name, when several are configured. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description must carry the full burden. It describes the output contents (views, actions, C# code, helper methods) but does not explicitly state that it is read-only or non-destructive, nor does it mention any side effects or limitations. It is informative but not exhaustive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (two sentences), front-loaded with the core purpose, and every sentence adds value. There is no redundancy or unnecessary detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema or annotations, the description carries the load of explaining what is returned. It does so by listing the key content areas (views, actions with C# code, helper methods). It could be slightly more detailed about response format, but it is adequate for an agent to know what to expect.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already describes both parameters (name and project) with 100% coverage. The tool description adds little beyond implying that 'name' identifies the controller. Baseline of 3 is appropriate given the high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the resource (one controller) and exactly what it returns: views, actions with actual C# code, and helper methods. It distinguishes itself from siblings like xaf_search and xaf_overview by focusing on deep controller internals.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides an explicit use case: 'Use when asked what a button or command actually does.' This gives clear context for when to use the tool, though it does not mention alternatives or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Custom property and list editors this application defines, and built-in editors its controllers reconfigure at run time. IMPORTANT — a property rendered by one of these does NOT show the control its type implies, and the business class says nothing about it. Check this before describing or changing how anything appears on screen.
| Name | Required | Description | Default |
|---|---|---|---|
| project | No | Project name, when several are configured. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full responsibility for behavioral disclosure. It prominently discloses a non-obvious behavioral trait: properties rendered by these editors do not show the control their type implies, and the business class gives no indication. This adds valuable context beyond a simple resource listing.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences: the first defines the scope of editors, and the second delivers an important caveat in caps. Every sentence earns its place, with no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple optional parameter and the absence of an output schema and annotations, the description covers the key behavioral trap and defines what types of editors are included. It could explicitly state what the tool returns (e.g., a list of editor names or settings), but the critical warning makes it sufficiently complete for likely use cases.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema fully describes the sole optional 'project' parameter with a clear description, so the baseline is 3. The tool description adds no additional context about how this parameter affects results, but it does not need to because the schema already covers it completely.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool's focus on custom property/list editors and reconfigured built-in editors, which distinguishes it from siblings like xaf_controller and xaf_model. However, it lacks an explicit action verb such as 'list' or 'get', relying on the resource name to imply the tool's function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance to consult this tool before describing or changing UI appearance, and highlights a critical caveat about misleading assumptions. It does not mention alternative tools or when not to use it, so it stops short of offering full decision criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Full detail of one business entity: every property with its type and attributes, relationships to other entities, validation rules, appearance rules, and calculated property expressions. Use before writing or changing any code that touches an entity.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Entity class name, e.g. 'Invoice'. Case-insensitive. | |
| project | No | Project name, when several are configured. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden of indicating the tool's behavior. It discloses the full detail returned and implicitly signals a read-only operation via 'Use before writing or changing'. However, it does not explicitly state side effects or permissions, though likely unnecessary for this context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with a clear definition of what the tool does, followed by a concise usage directive. No filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite lacking an output schema, the description thoroughly enumerates the return content and provides a clear usage context. It is sufficient for an agent to know when and how to use this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already provides 100% coverage, including type and description for each parameter. The description adds no additional parameter-level guidance, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns full detail of a single business entity, enumerating the categories of information included. This is specific and distinguishes it from sibling tools like xaf_search or xaf_overview, which likely provide broader or partial views.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance to use this tool before writing or changing code that touches an entity, which establishes a clear 'when to use' context. However, it does not explicitly name alternative tools or state when not to use it, so it falls short of full differentiation guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Updater blocks that ran once when an existing database was upgraded past a version, and never again. Use when asked why a column contains what it contains, where legacy data came from, or what changed between releases — the code running today cannot explain any of that, and reasoning from it produces a plausible wrong answer.
| Name | Required | Description | Default |
|---|---|---|---|
| project | No | Project name, when several are configured. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the disclosure burden. It clearly states these blocks ran once and never again, establishing a read-only historical nature, and the caution about current code adds interpretive context. It does not mention output format, but that is less critical.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences: the first defines the resource, the second provides usage guidance. The wording is slightly dense but efficient, with no wasted words or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with one optional parameter and no output schema, the description adequately covers purpose, usage, and behavioral context. It does not describe return values, but the use cases make clear the tool returns historical migration information.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter 'project' is already fully described in the schema (100% coverage), and the description adds no additional parameter-level details. This matches the baseline of 3 when the schema handles the semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description identifies the resource as updater blocks that ran once during database upgrades, which clearly distinguishes it from sibling tools about current code. It lacks an explicit verb like 'list' or 'show', but the noun phrase and usage guidance communicate its role as a historical reference.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use: when asked about column origins, legacy data provenance, or changes between releases. It also warns against reasoning from current code because it produces plausible wrong answers, effectively guiding the agent away from inappropriate alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Model Editor (.xafml) customizations: captions, list and detail view settings, columns, filters and application options. IMPORTANT — this behavior exists only in XML and cannot be inferred from the C# at all, so check it before concluding how a screen behaves.
| Name | Required | Description | Default |
|---|---|---|---|
| project | No | Project name, when several are configured. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It does disclose that behavior is XML-defined and cannot be inferred from C#—a valuable insight. However, it doesn't state whether the tool reads or writes, what side effects occur, or what output to expect. This ambiguity is significant for a tool with 'customizations' in its scope.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences: the first lists the tool's scope compactly, the second provides a crucial caveat. It is front-loaded with the domain and keeps the warning high-priority. No wasted words or redundant structure.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This tool operates in a complex domain (XAF model customization) with no output schema and no annotations. The description tells you what the tool covers but not what it returns, whether it mutates state, or how it relates to the many sibling tools. The XML caveat is helpful but insufficient for confident use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter 'project' is already fully described in the schema ('Project name, when several are configured.'). Since schema coverage is 100%, the description adds no new semantic value, and the baseline of 3 applies. No extra usage details are given for the parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the resource (Model Editor .xafml customizations) and enumerates specific content areas (captions, list/detail views, columns, filters, app options). However, the verb is implicit ('customizations' rather than 'get' or 'edit'), so it doesn't crisply state the action. It does distinguish itself from sibling tools by focusing on .xafml model behavior.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'IMPORTANT' statement gives a clear directive: check this tool before concluding how a screen behaves because behavior exists in XML, not C#. This implies when to use it, but it doesn't explicitly name alternatives or exclusions. Still, the usage context is strong enough to guide an agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
What this XAF application is and everything it contains: ORM, module setup, and the COMPLETE list of entities, controllers, actions and navigation groups. Call this first when asked anything about the application as a whole. The lists are exhaustive: if something is not in them, it does not exist in this application.
| Name | Required | Description | Default |
|---|---|---|---|
| project | No | Project name, when several are configured. Omit for the default. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the transparency burden. It does disclose a key behavioral trait—that the lists are exhaustive and authoritative—which is valuable. However, it does not mention other behavioral aspects such as performance implications, response format, or whether it reads from a cache or scans files, leaving some transparency gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences. The first sentence encapsulates the tool's content, and the second provides usage and behavioral guidance. There is no redundant or filler text, making it well-structured and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an overview tool with no output schema, the description provides a solid sense of what the response will contain (complete lists of key components). It stops short of detailing the exact result format or organization, but the content scope is clear enough for the agent to infer what to expect.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema fully documents the single 'project' parameter with a clear description, so schema coverage is 100%. The tool description adds no additional parameter semantics, so it does not go beyond the schema baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly defines the tool as an overview of the entire XAF application, listing ORM, module setup, and exhaustive enumerations of entities, controllers, actions, and navigation groups. It distinguishes itself from sibling tools by emphasizing it is the complete index and should be called first for whole-app questions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states 'Call this first when asked anything about the application as a whole', giving a direct usage trigger. It also implies the tool serves as a definitive existence check ('if something is not in them, it does not exist'), which guides when to rely on its results versus diving into specific sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Discard cached analysis and re-read the source on the next query. The server already detects file changes automatically, so this is only needed if you believe the cached view is wrong.
| Name | Required | Description | Default |
|---|---|---|---|
| project | No | Project name, or omit to refresh all configured projects. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries the burden. It discloses the cache-discarding behavior, the deferred effect ('on the next query'), and the caveat about automatic file change detection. It omits details about side effects or permissions, but for a cache refresh tool, the description is fairly transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tight sentences: first states the action, second gives the usage condition. No filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Low complexity (one optional param, no output schema). The description tells what happens, when to use it, and why it exists. Fully adequate for an AI agent to decide and invoke this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description covers 100% of the single parameter, giving the project name and its optionality. The tool description does not add parameter-specific meaning, but the baseline of 3 applies since schema already documents the parameter well.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a clear action ('Discard cached analysis and re-read the source') on a specific resource (the analysis cache). This clearly distinguishes it from sibling xaf_* tools, which focus on searching, overviews, entities, etc.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly tells when to use: 'only needed if you believe the cached view is wrong,' and provides context that the server auto-detects changes, implying regular use is unnecessary. This is direct when-to-use guidance with an implicit alternative (do nothing).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Reports the application registers in source: what each is over, the filter and expressions in its layout, and the parameters dialog it opens with. Use when asked what a report shows, why its numbers differ from a screen's, or before writing a new one. Says explicitly when the list is a lower bound because users can also design reports at run time.
| Name | Required | Description | Default |
|---|---|---|---|
| project | No | Project name, when several are configured. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the behavioral burden. It adds a key limitation: 'Says explicitly when the list is a lower bound because users can also design reports at run time.' This is extra behavioral context beyond the raw purpose. It does not mention side effects or auth, but the tool is clearly read-only in nature.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences with no wasted words. Purpose is front-loaded, usage is provided, and the limitation is appended concisely. Efficient and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one optional parameter and no output schema, the description covers what the tool returns, when to use it, and a caveat about completeness. Nothing essential is missing for an agent to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for the single parameter, so the schema already documents the 'project' parameter. The description adds no additional parameter-specific guidance, matching the baseline for high coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Reports the application registers in source' and details what it covers (what each report is over, filter/expressions, parameters dialog). This clearly distinguishes it from sibling tools like xaf_search or xaf_entity, even without naming them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use: 'Use when asked what a report shows, why its numbers differ from a screen's, or before writing a new one.' However, it does not mention when not to use it or name alternative tools, so it falls short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The business rules the application enforces: validation rules with their messages and conditions, conditional appearance rules, and calculated properties. Use when asked what the system requires, forbids, or computes. Optionally narrowed to one entity.
| Name | Required | Description | Default |
|---|---|---|---|
| entity | No | Restrict to one entity. Omit for every rule in the application. | |
| project | No | Project name, when several are configured. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It details what the tool returns (validation rules with messages, conditions, appearance rules, calculated properties) and implies a read-only query. It does not explicitly state side effects or return format, but the level of detail is strong.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is only three sentences and every sentence serves a distinct purpose: defining the resource, specifying when to use it, and explaining parameter narrowing. It is front-loaded with the most important information and contains no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter tool with no output schema, the description adequately captures content, usage, and parameter filtering. It does not mention empty responses or error handling, but that is not critical for an agent to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with both parameters fully described in the input schema. The description adds a small reiteration for 'entity' ('narrowed to one entity') but does not need to compensate for any schema gaps, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states what the tool does: it returns the business rules the application enforces, specifically enumerating validation rules with messages and conditions, conditional appearance rules, and calculated properties. This goes beyond a generic resource name and effectively distinguishes the tool from sibling tools like xaf_model or xaf_entity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'Use when asked what the system requires, forbids, or computes,' providing a clear when-to-use directive. It also notes optional narrowing by entity, which adds practical usage guidance beyond the schema.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search the whole application for a term: entity and property names, controllers, actions, validation messages, criteria expressions and seed data. Use when you know roughly what you are looking for but not where it lives — for example a field name mentioned by the user, or a business concept like 'discount'. Returns what matched and where.
| Name | Required | Description | Default |
|---|---|---|---|
| kind | No | Optional filter: entity, property, controller, action, rule, or seed. | |
| query | Yes | Text to look for. Case-insensitive, matches substrings. | |
| project | No | Project name, when several are configured. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses what is searched (entity names, validation messages, etc.), that it is case-insensitive, and that it returns what matched and where. It does not state side effects or permissions, but as a search tool, the read-only nature is implied and adequately covered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, each earning its place. Front-loaded with the verb 'Search', followed by scope and usage context, with no redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is complete for a simple search tool. It covers purpose, usage, and return behavior, and no output schema means it needn't explain return structure beyond what is stated.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with clear descriptions for each parameter. The tool description reinforces the 'kind' parameter by listing examples (entity, property, controller, etc.) and gives a concrete query example, but it adds minimal new information beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Search the whole application for a term' which clearly states the verb and scope. It enumerates specific resource types (entity, property, controllers, actions, etc.), distinguishing it from sibling tools like xaf_entity or xaf_controller.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly says 'Use when you know roughly what you are looking for but not where it lives' and provides an example. It gives clear context but does not mention exclusions or alternative tools, falling short of a fully explicit when-not/alternatives guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
What is loaded when a screen opens: every controller XAF activates on that view, why each one matches, and which of their actions appear. Call with no view to list the application's screens. IMPORTANT — most views exist in no file at all; XAF generates them from the business classes, so neither the C# nor the .xafml can be read to find them. Use before changing a controller, adding an action, or answering what a screen does.
| Name | Required | Description | Default |
|---|---|---|---|
| view | No | View id, e.g. 'Order_ListView'. Omit to list every view. Case-insensitive. | |
| project | No | Project name, when several are configured. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full transparency burden. It discloses the critical fact that most views are generated from business classes and not present in C# or .xafml files, preventing the agent from mistakenly reading files. It also reveals that omitting the view returns a screen list, a behavioral trait not visible from the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences that front-load the core definition, then add an important caveat, then provide usage context. Every sentence contributes new information with no filler or repetition of schema details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no output schema and no annotations, the description gives a complete picture: what data the tool returns (controllers, actions, match reasons), how to invoke it (with or without a view), a critical gotcha about generated views, and concrete use cases. This is sufficient for an agent to correctly select and call the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema documents both parameters (view, project) with 100% coverage, including default null and case-insensitivity. The description reinforces the view parameter's behavior by explaining the effect of omitting it (list all screens) but adds no new meaning for the project parameter. This meets the baseline for high schema coverage without major additional semantic value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly defines the tool as showing what controllers and actions are loaded for a screen, with a specific resource (view) and detailed output (why each matches, which actions appear). It also explains the no-view invocation to list all application screens, distinguishing it from sibling tools like xaf_controller or xaf_model. This goes beyond a vague verb to explain the exact output scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives explicit use cases: 'Use before changing a controller, adding an action, or answering what a screen does.' It also explains the no-view pattern to list screens. However, it does not name alternative tools or specify when not to use it, so it's strong but not fully exhaustive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Trace one business process end to end: what runs, in what order, which entities it touches and which rules govern them, every step citing file and line. Start from an action, a controller method, a controller or an entity. Use this when asked HOW something works — 'how does approval work', 'what happens when I press this' — rather than what exists. Calls the trace could not follow are reported explicitly, so an empty list of them means the path really is complete.
| Name | Required | Description | Default |
|---|---|---|---|
| from | Yes | Where to start: an action, a controller method, a controller or an entity. | |
| depth | No | How many hops to follow. Three covers an ordinary XAF process. | |
| project | No | Project name, when several are configured. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description takes the full burden of behavioral disclosure. It successfully discloses a important limitation: calls the trace cannot follow are reported explicitly, and an empty list has a meaningful interpretation. It does not explicitly state whether the tool is side-effect free, but the read-only affordance of a trace is strongly implied.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three dense sentences with no filler. It opens with a concise definition of the tool, then quickly gives usage criteria, and ends with an important nuance about the completeness of the path.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex exploration/walkthrough tool with no output schema and no annotations, the description covers the needed invocation context: starting points, scope, traversal boundaries, citation by file and line, and interpretation of missing-boundary results. It gives enough structure for an agent to know both when and how to call it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers all three parameters with descriptions, so schema coverage is 100%; the baseline is 3. The description only reinforces the required 'from' parameter's valid starting points without adding behavior or details about 'depth' or 'project' beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action—'Trace e one business process end to end'—and specifies what the trace covers: what runs, execution order, touched entities, and governing rules. The phrase 'rather than what exists' distills the tool from sibling existence/search tools, so selected against and invocation are unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly says to use this path 'when asked HOW something works' and gives concrete examples like 'how does approval work' and 'what happens when I press this'. It also contrasts it with what-exists questions, giving an explicit when-to-use and when-not-to-use distinction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.16.0xaf_reportsv0.15.0xaf_walkthroughv0.12.1xaf_viewv1.0.0xaf_controllerxaf_editorsxaf_entityxaf_migrationsxaf_modelxaf_overviewxaf_refreshxaf_rulesxaf_searchScored across 12 tools
Each tool targets a distinct source of truth (overview, entity, view, controller, model, editors, rules, reports, migrations, search, trace). A couple of adjacent tools (xaf_entity vs xaf_rules, xaf_view vs xaf_model) cover overlapping facts, but the use-case guidance clearly separates them.
All tools share a uniform `xaf_` prefix followed by a short, descriptive noun/verb, so the family is instantly recognizable. `xaf_refresh` is the only imperatively named tool, but this is a deliberate and predictable exception for a cache-control function.
Twelve tools is within the ideal range and each tool addresses a distinct aspect of explaining an XAF application. The count feels intentional rather than padded; there is no obvious redundancy or token-for-count inflation.
The surface covers static structure (overview, entities, views, model, editors), dynamic behavior (controllers, walkthrough, rules), historical data (migrations), and search/reporting (search, reports), plus a cache refresh for correctness. No essential operation for the stated explainer purpose is missing.
Give your AI agent a persistent map of your project's structure, dependencies, and bugs.
AI Agent with Architectural Memory. Impact analysis (free), tests and code from the graph (pro).
Code intelligence platform for AI agents. 20 tools for architecture, security & impact analysis.
Shared memory for coding agents. Stop re-explaining your codebase every session.
