教会你的 AI 编码助手你的 XAF 应用实际做了什么。
将其指向一个 XAF 模块。它会直接从源代码读取你的实体、控制器、操作、业务规则、导航和模型编辑器自定义——并将结果交给你的编码助手。
DevExpress 已经做了出色的工作，让 AI 助手熟悉 XAF。已经有两个现成的工具，这是第三个：
教会助手… | 工具 |
XAF 的一般工作原理 | |
官方文档的内容 | |
你的应用做了什么 | XAF Logic Explainer ← 你在这里 |
一个已经读过 XAF 文档每一页的助手仍然不知道你的 Invoice 总额是从其行项目计算出来的，不知道 ApproveController 在期间关闭时拒绝运行，也不知道有三列在模型编辑器中被隐藏，在任何 C# 文件中都不出现。它会自信地编造出这三者。
这个空白无法通过更好的提示来解决。它可以通过提取来解决。
这些工具可以组合使用。 安装 DevExpress 技能以获取框架知识，使用 Docs MCP 获取官方参考，使用本工具获取你自己的代码库。它们之间互不替代。
Related MCP server: mcp-digger
以下所有内容都作为语法读取，使用 Roslyn。你的项目永远不需要编译，此工具也从不链接 DevExpress 程序集：
实体 — 属性、类型、关联以及赋予它们意义的 XAF 属性（[Association]、[Aggregated]、[RuleRequiredField]、[Appearance]、[ModelDefault]，……）。XPO 和 EF Core，从你的 using 语句自动检测。
控制器和操作 — SimpleAction、PopupWindowShowAction、SingleChoiceAction，它们的目标条件，以及触发时运行的处理器代码。
业务规则 — 验证属性和代码规则，以及附加的条件。
模块设置 — ModuleUpdater 种子数据以及首次运行时创建的内容。
导航 — 用户实际看到的组和项。
模型编辑器（.xafml） — 仅存在于 XML 中、对任何阅读 C# 代码的人不可见的自定义。模块和平台文件按照 XAF 合并的方式合并。
自定义属性和列表编辑器 — 包括它们依赖的 JavaScript，以及通过 View.CustomizeViewItemControl<T>() 在运行时重新配置的内置编辑器。这些位于模块旁边的平台项目中，因此阅读业务对象的人不会遇到它们。
版本控制的迁移 — 更新器中的 CurrentDBVersion < new Version(…) 块。每个块对任何数据库最多运行一次，并且是当前代码无法解释的数据的唯一解释。
每个屏幕及其加载的内容 — 见下文。
这些是为什么一个已经读过所有业务类的助手仍然可能对应用做出自信错误判断的原因：
XAF 仓库中没有内容能回答这个问题，而且两个部分都因不同原因缺失。
屏幕本身不在任何文件中。 XAF 为每个业务类生成一个列表视图、一个详细视图和一个查找视图，以及为每个集合生成一个列表视图，模型编辑器只存储那些被修改过的。在你的源代码中搜索 Patient_Prescriptions_ListView 找不到任何东西——但这并不能证明它不存在。
哪些控制器在那里运行是在运行时决定的，由 XAF 对四个条件进行 AND 运算：嵌套、视图类型、对象类型和视图 ID。每个条件在未设置时不受限制，因此一个未设置任何条件的控制器会加载到你拥有的每个屏幕上。
本工具按照 ViewController.IsFitToView 评估它们的方式读取所有四个条件，对照从框架自己的 ID 生成器构建的视图清单——并记录每个条件匹配的原因，以便可以检查答案而不是信任它：
两个层次，分开处理。你的团队编写的内容得到完整处理；XAF 提供的内容被折叠到一行后面，因为它数量庞大且不属于你修改的范围。使用真实来源目录时，它也会被命名——范围限定为你实际注册的模块，因此 WinForms 控制器永远不会出现在 Blazor 屏幕上。
它不会声称的内容：这里列出的控制器仍然可以通过 Active["reason"] 自行关闭，这取决于数据和用户。这是 XAF 加载到屏幕上的内容，不一定是会执行某些操作的内容——任何无法从源代码读取的内容都会单独列出并说明原因，而不是被悄悄视为“到处运行”。
dotnet tool install -g XafLogicExplainer.Cli
xaflogic agents --project "C:\MySolution\MyApp.Module"这会在你的解决方案根目录写入 AGENTS.md、CLAUDE.md 和 .github/copilot-instructions.md。无需账户、无需 API 密钥、无需服务器。你的助手在下一个问题中就能理解应用。
AGENTS.md 会被附加到助手在仓库中的每个请求之前，因此其成本是永久性的。在那里倾倒 70 KB 的实体细节会挤占实际问题的空间。因此输出是分层的：
| ~11 KB | 始终加载：基本规则、完整清单、约定、配方 |
| ~70 KB | 按需打开：完整属性、处理器代码、规则消息、 |
最有价值的部分是最小的。AGENTS.md 以基本规则开头——此应用使用 XPO 且从不使用 EF Core，清单是完整的因此任何缺失的内容确实不存在，以及某些行为存在于模型编辑器中而不是 C# 中。这几段话阻止了助手对不熟悉的 XAF 代码库产生的大部分自信编造。
现有文件永远不会被覆盖：生成的文本位于标记之间，你手动编写的任何内容都会被保留，并且当没有任何变化时重新生成是字节相同的。
生成的文件是快照。MCP 服务器是实时连接——助手在你工作时查询你的应用，并且不会过时。
/plugin marketplace add peopleworks/XAFLogicExplainer
/plugin install xaf-logic-explainer@peopleworks-xaf这会在一步中安装一个技能和一个 MCP 服务器。对于任何其他 MCP 客户端，可以直接从 NuGet 运行，无需安装：
{
"mcpServers": {
"xaf": { "command": "dnx", "args": ["XafLogicExplainer.Mcp", "--yes"] }
}
}…或者如果你已经有 CLI，可以指向它：
{ "mcpServers": { "xaf": { "command": "xaflogic", "args": ["mcp"] } } }从解决方案目录启动时，它会自动找到 XAF 模块，因此两种形式都不需要路径。
工具 | 答案 |
| 这个应用程序是什么，以及其中所有内容的完整列表 |
| 字段、概念或业务术语的定义位置 |
| 一个实体上的所有属性、关系、规则和计算 |
| 某个动作的功能——包括触发时运行的 C# 代码 |
| 应用程序验证、计算、隐藏和禁用的内容 |
| 模型编辑器自定义项，这些不存在于任何 C# 文件中 |
| 自定义编辑器、它们所需的 JavaScript，以及在运行时更改的内置编辑器 |
| 曾经针对实时数据库运行过的操作，以及解释原因的注释 |
| 一个屏幕上加载的所有内容——哪些控制器被激活，以及为什么 |
| 重新读取源代码（更改会自动检测） |
询问不存在的内容，答案将非常有用：
此应用程序中没有名为 'PurchaseOrder' 的实体。 这是从整个源代码树中提取的 19 个实体的完整列表：… 如果用户期望 'PurchaseOrder' 存在，那么它尚未被创建。
与官方 DevExpress 技能搭配使用。 /plugin install dx-xaf@DevExpress-agent-skills
介绍 XAF 的工作原理；而本工具介绍您的应用程序的功能。只拥有第一个技能的智能体将写出的正确的 XAF 代码，但所使用的实体您并不拥有。
智能体读取 AGENTS.md 或查询 MCP 服务器。对于那些刚刚接手一个运行了十年的 XAF 应用程序的人来说，他们需要以完全不同的方式排列相同的事实：
xaflogic explain --project "C:\MySolution\MyApp.Module" --open一个 HTML 文件。无需服务器、无需构建步骤、无需网络请求——它可以从电子邮件附件中打开，即使在没有互联网的机器上也能运行，而这正是交接的实际发生方式。
该页面绘制了 您的领域模型地图，它来自散布在您的代码库中的关联特性。大多数团队从未见过他们的领域模型：它只存在于一个人的头脑中，而这正是当这个人离开时流失的知识。
实际输出，来自此存储库中的示例应用程序。悬停在一个实体上，所有不与它直接相关的内容都会变淡；紫色表示删除父级会删除子级。
与它一起的还有：每个实体及其每个属性的含义、每个动作及其运行的代码、用户实际会看到的验证消息，以及不出现在任何 C# 文件中的模型编辑器设置。
以及 应用程序中每个条件表达式的索引——这些表达式既不是 SQL 也不是 C#，而是从散布在源代码中的特性收集而来，否则不会被集中记录：
在不触及您自己的代码的情况下，在示例上尝试：
xaflogic explain --project tests/XafLogicExplainer.Tests/Fixtures/DemoSolution/PharmacyDemo.Module --open提取过程在读取您的源代码时，并不了解编写它所针对的框架，这就留下了一个无法回答的问题：DeleteObjectsViewController 是您的团队编写的，还是 DevExpress 自带的？没有答案，生成的文档会将框架行为和您自己的逻辑混为一谈。
如果您拥有 DevExpress 许可证：
xaflogic catalog build这会读取 您自己的安装，并记录 XAF 本身提供的内容——特性、控制器、模型接口和模块，以及 DevExpress 附带的官方摘要和文档链接。在 DevExpress 26.1 上，这大约有 850 个框架类型。
如果您还安装了 DevExpress 源代码 组件，它还会记录 每个框架控制器在何处激活 —— XAF 在运行前检查的四个条件。这无法从程序集中读取：五分之四的内置控制器在其构造函数中设置目标。如果它们不在程序集旁边，请传递 --dx-sources <Components/Sources>。
然后提取过程会自动拾取这些信息，并可以说出否则无法说出的内容：
"ArchiveController 继承自内置的 DeleteObjectsViewController" —— 您正在改变整个应用程序的删除方式，而不是在旁边添加一个功能。
"[AuditedByFinance] 不是 XAF 或 .NET 特性" —— 您的团队发明了它，因此其含义只存在于这个代码库中，不存在于任何文档中。
"另外 32 个框架控制器也会加载到此屏幕上" —— 已命名，附有每个控制器的作用，并限定在您的应用程序实际注册的模块范围内，因此 WinForms 控制器永远不会出现在 Blazor 屏幕上。
目录写入 ~/.xaflogic/catalog/，绝不会写入您的存储库：因为它源自许可软件。没有目录一切也能正常工作——它只是让输出更精确。请参阅 NOTICE.md。
命令 | 功能 |
| 为您的智能体编写 |
| 作为 MCP 服务器运行，使智能体可以实时查询应用程序 |
| 编写一个自包含的 HTML 页面，向人类解释应用程序 |
| 构建 DevExpress 真实事实目录（ |
| 读取项目，将 Markdown + JSON 写入本地 |
| 与上一次提取进行比较，并报告更改了什么 |
| 显示变更检测哈希值，以及是否需要重新提取 |
| 文件更改时重新提取，带防抖 |
| 提取并发布到远程目标 |
| 询问有关提取项目的问题 |
| 在 |
| 管理多个 XAF 项目；大多数命令接受 |
文档以 英语或西班牙语 生成（--lang en|es）。
有用的标志：--orm auto|xpo|efcore、--lang en|es、--enrich（每个控制器和动作的 AI 生成业务逻辑摘要）、--force、--all。
--enrich 需要一个模型，并且 以下任何一种都足够——命令行中的键优先，然后是环境变量，然后是 PeopleWorks Copilot 帐户（如果您碰巧有一个的话）：
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-...此工具中的所有其他功能无需任何密钥、无需任何帐户、无需网络即可运行。
提取是 增量式的 —— 对您的 .cs 和 .xafml 文件进行 SHA-256 哈希，未更改的项目将不执行任何操作。还有一个 MSBuild .targets 文件，如果您希望在构建时运行它。
v0.14.0. 提取引擎是成熟的部分：它在生产环境中针对真实的 XAF 应用程序运行。面向智能体的界面是目前正在开放地推出的。
✅ | Roslyn 提取——实体、控制器、规则、更新器、导航、 |
✅ | XPO 和 EF Core，自动检测 |
✅ | 自定义属性和列表编辑器、它们对应的客户端资源，以及在运行时重新配置的内置编辑器 |
✅ | 版本门控数据迁移——针对非全新数据库执行的操作 |
✅ | 增量变更检测、差异报告、多项目、监控模式 |
✅ | 控制器和动作的 AI 增强（ |
✅ | Blazor 应用内帮助面板 |
✅ |
|
✅ |
|
✅ | 可插拔发布目标（ |
✅ | MCP 服务器 —— 10 个工具，实时针对源代码 |
✅ | 可安装的 Claude Code 插件，包含技能和 MCP 服务器 |
✅ | 345 个测试 覆盖合成 XPO 和 EF Core 测试夹具——无需 DevExpress |
✅ | DevExpress 真实事实目录，由许可方在本地生成 |
PeopleWorks Copilot（此工具在其中成长）现在只是多个接收器之一，而不是一切功能围绕构建的目的地。最重要的输出根本不需要服务器。
为什么一个 XAF 应用程序三分之一的逻辑存在于其业务类之外，它隐藏在哪里，以及提取后的输出实际上长什么样：
你的代码智能体知道 XAF。它从未见过你的应用程序。 — 用西班牙语（原文标注）
每一篇都是用其自身语言编写的，而不是从另一种语言翻译而来。来源在 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 plugin基于 .NET 10 构建。
只有 XafLogicExplainer.Blazor 引用了 DevExpress 包；它需要 DevExpress NuGet 源和许可证才能构建。其他所有内容在任何地方都能构建，这就是为什么 CI 可以免费验证它。
最有价值的贡献是告诉我们 提取器遗漏了什么。XAF 非常庞大，每个代码库都使用它的不同部分，没有哪个项目能完整覆盖整个框架。有一个 提取缺口问题模板 专门为此设计：展示您的项目使用的 XAF 模式以及工具未能看到的内容。
请参阅 CONTRIBUTING.md。错误报告、文档和翻译同样受欢迎。
MIT。请参阅 NOTICE.md 了解与 DevExpress 的关系。
一个独立的社区项目——未经 Developer Express Inc. 附属、认可或支持。它不包含任何 DevExpress 源代码，构建或运行时也不需要任何 DevExpress 许可证。DevExpress、XAF 和 eXpressApp Framework 是 Developer Express Inc. 的商标。
由 Pedro Hernández (PeopleWorks)、Microsoft MVP for .NET 构建——面向 DevExpress 和 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.
