Limitations and known issues

This appendix lists where AI Power Tools for Sparx EA stops, what it does differently from what you might expect, and what it does with a known defect. Each item states the limit and gives a workaround where one exists. For a symptom you are looking at now, start with Troubleshooting. For a one-page summary, see Limitations at a glance. Terms are defined in Glossary.

Several items describe behavior that comes from Enterprise Architect (EA) itself. AI Power Tools works around those where it can and says so where it cannot. Other items depend on what your surface can do: whether it gives the assistant computer use, local code execution and browser control. Those are grouped under Limitations that depend on your surface's capabilities, and they are limits of a surface, not of AI Power Tools.

Platform and installation

Windows only, with EA on the same machine. The server drives EA through Windows automation, which does not cross machine boundaries. Local MCP servers do not run in cloud sessions of Claude Cowork, so only a local Claude Cowork session reaches EA. See Supported clients and How the server connects to Enterprise Architect.
The server needs EA running, with a project open. The server does not start EA by itself, and the launch_ea operation is not guaranteed safe when EA is already running. With computer use, the assistant can start EA and open the model for you. Without it, you start EA and open the project. Either way, check that EA is not already running first, because a second EA instance against the same model file can corrupt work. See Limitations that depend on your surface's capabilities.
One EA instance per seat. A per-user Sparx license limits concurrency. If several EA windows are open, the server attaches to whichever one Windows returns, which in practice is the first registered. Close extra instances before you start work.
EA 16.1 or later is required. Verification work was done on EA 17.0 and 17.1 builds, and several skills state the build they were checked on. See Requirements.
The skills and the server update separately. The claude.ai marketplace does not sync on its own: you sync novocircle under Manage marketplaces, then quit Claude Desktop completely and reopen it. A new chat then has the new skills, and the Code tab has them after Claude Desktop is reopened. The server updates by installing the new extension file. The ping notice at the start of a session says which of the two is behind. An uploaded plugin file does not update itself. See Claude plugin and Updating and uninstalling.
Organization policy can block third-party marketplaces. Where it does, the skills plugin must reach the machine through your own provisioning or managed settings. See Enterprise fleet deployment.
Skills load twice if an older copy exists. A machine that has the plugin and also holds skills copied there by an older installer shows every skill twice and pays the token cost twice. Installing the plugin through Claude Code's own plugin commands as well as on the claude.ai account loads the skills twice in the Code tab. The server's skills check reports those leftover copies, with migrate-to-plugin.ps1 as the remedy; when the plugin is found installed it reports nothing else. The script also finds copies left by the oldest versions of the installer. See Moving from an older installation.
Claude Code in a terminal cannot use the server. It does not load Claude Desktop extensions. Use the Code tab of the Claude desktop app. See Supported clients.
Upgrading the Desktop extension while Claude Desktop is running can fail with a file-lock error, because the running server holds its program file. Disable the extension or quit Claude Desktop first. See Claude Desktop extension.
A repackaged extension must keep every setting optional or defaulted. Claude Desktop silently drops a server whose manifest has a required setting with no default, in Claude Desktop chat and in Claude Cowork.
The Desktop extension and the VS Code extension deliver the server, not the skills. Claude Desktop chat and Claude Cowork read skills from plugins only, so the skills plugin on your Claude account is needed for the skills, and the plugin brings no server. In VS Code the skills are a plugin you install from VS Code's plugin marketplace, which the extension adds. See Supported clients.
The VS Code extension needs VS Code 1.99 or later, on Windows, and does not update itself. It reports a newer version and never installs it, and it never installs the skills plugin either: you choose Install in VS Code. See VS Code extension.
The server's update check cannot be turned off. The server contacts the public release site when it starts, at most once a day, silently and without telemetry, and no setting disables the check. The VS Code extension also makes its own daily check of an update manifest, which the eaMcp.checkForUpdates setting turns off; that setting does not stop the server's check. The notice it produces gives the upgrade steps for how the server was installed (the Claude Desktop extension, the VS Code extension, or a location it does not recognize), and the ping notice says when the skills are behind. See The AI Power Tools MCP Server for Sparx EA.
Logging and diagnostics settings differ by package. The log level (EA_MCP_LOG_LEVEL) is a setting in the VS Code extension (eaMcp.logLevel) and on the Claude Desktop extension's Configure screen, with the values DEBUG, INFO, WARNING or ERROR and a default of INFO. The Claude Desktop extension has a Log level option on its Configure screen, default INFO. The plugin has no server and no settings. Diagnostics are settings in the VS Code extension (eaMcp.diagnostics and eaMcp.diagnosticsDir) and in the Claude Desktop extension (Enable diagnostic reports, Diagnostic report directory and Slow-call threshold). See Settings and Inside the server.
Code engines run as local Python on the machine where EA runs. The diagram advisor, the composition engine, the census, the inclusion choice, the governance gate, the Parquet and Power BI project generators and the ea-com scripts are not part of the compiled server. They need local code execution and the Python packages listed below, and they do not run without them. The business layer itself is built, checked, replayed and refreshed inside the server. See Limitations that depend on your surface's capabilities and How code engines work.
Some operations need a local file. A local file is a .qea or .qeax file. add_image, which adds pictures to the image library, works only on a local file, and so does loading an icon the model lacks. A server connection (EA connects directly to a shared repository held in a database) and a cloud connection (EA connects to a shared repository through Pro Cloud Server) behave the same for AI Power Tools: EA opens the connection, and the AI Power Tools MCP Server for Sparx EA attaches to EA either way. See Supported repositories.
Read-only mode is decided by operation name, not by effect, and it is set on the extension's Configure screen. The Claude Desktop extension's Configure screen has a Read-only mode option (off by default) that sets EA_MCP_READONLY for the server. The VS Code extension has no setting for it, and whether a system-wide environment variable reaches a server launched some other way depends on the client. Diagram layout operations are refused by name along with the rest, including a collapse dry run. Operations that write files outside the repository, such as exports, are not refused. Treat the setting as a convenience that catches mistakes, not as a security control. See How tools and operations work.

Limitations that depend on your surface's capabilities

The server's 149 operations behave the same on every surface. What differs is what else the assistant can do. Four capabilities matter: the MCP server, computer use, local code execution and browser control. A surface that lacks one cannot do the work that depends on it. Surfaces gain capabilities over time, so check Capabilities and surfaces for the current matrix. Each skill's "Capabilities it uses" table says what that skill needs and what happens without it.

Without computer use

The assistant cannot start EA, open a model through its window, or see and dismiss EA's dialogs. EA raises a blocking dialog instead of returning an error, and every later call waits behind it. You take a screenshot of the dialog and paste it into the conversation so the assistant can analyze it, then you dismiss the dialog so processing can continue. You also start EA and open the project yourself.
The assistant cannot look at the real EA window. It can still render a diagram with verify_diagram, which is the server's own render. A check that needs EA's own drawing, toolbox or Quick Linker is yours to do, and the assistant asks what you see.
Tasks that exist only in EA's user interface are handed to you. These include Save Package as MDG Technology, the Manage Technologies dialog, document and report templates, and the procedures ea-help finds in Sparx's user guide. The assistant gives you the steps and asks for the result.
The assistant cannot open or refresh a generated Power BI project. You open it in Power BI Desktop and refresh the data yourself.

Without local code execution

Code engines do not run. That covers the diagram advisor, the composition engine, ea-com scripts, and in the reporting skills the census, the inclusion choice, the governance gate, the Parquet files and the Power BI project. Where a skill allows, the assistant does the computation itself, which costs more tokens and is less consistent. Where a skill has no such fallback, it reports that it cannot run. Each skill's "Capabilities it uses" table says which case applies.
Engines need Python 3 on the machine where EA runs, and some need extra packages. pywin32 is needed only by scripts the AI writes against EA's automation interface (ea-com, and the COM snippets in ea-mdg-deploy), and by no reporting step. pyyaml is needed for the composition engine's notation bindings. pyarrow is needed to write Parquet files and is deliberately not bundled, so install it when you choose that delivery way. CSV is never a substitute. Everything else is Python's standard library.
Server operations are unaffected. All 149 operations run without local code execution. That includes building, checking, replaying and refreshing the business layer from a reporting profile that already exists.
What reporting still needs it for. Without local code execution, the skills cannot compute the census and the inclusion choice, so the inclusion choice that a new reporting profile requires cannot be made, the governance gate cannot run, and no Parquet files or Power BI project can be produced. None of these has a fallback, and the assistant says so.
Model guidance is written for Claude models. A skill whose work is mostly done by code engines depends least on the model, and a skill that relies on AI judgment depends most.

Without browser control

No Prolaborate skill can proceed. They operate Prolaborate's web interface in a signed-in browser. Computer use can see a browser but cannot click in one, so it is not a substitute. Browser control through a built-in browser or Chrome is required, and you must be signed in to Prolaborate yourself. See prol-start-here.
ea-help cannot read Sparx's user guide reliably. The Sparx site challenges plain HTTP clients, so the skill needs a real browser context.

Enterprise Architect behavior

These limits come from EA and its automation interface.

A write EA rejects can be reported as success. EA refuses some writes without raising an error. Only some operations check for the refusal and report it. The operations that create and update packages, elements, attributes and operations, and that move elements, do not. Verify anything that matters by reading it back, by a query, or by rendering the diagram.
A success report does not mean every property landed. When you create or update an item with several properties, compare what was applied with what you sent, and read the list of rejected properties. A property sent with an empty value is skipped without a trace. A tagged value passed as an ordinary property never applies; tagged values have their own operations. See Tagged values.
There is no transaction and no undo. A write takes effect immediately and a delete through automation is permanent. Take a baseline first. See Baselines and ea-change-management.
A call that hangs is usually a dialog inside EA. EA answers SQL it cannot parse, a malformed merge document and some other cases with a dialog that holds the connection until it is dismissed. With computer use, the assistant sees the dialog in EA's window, reads it, uses the message to correct the call, dismisses the dialog and keeps going. Without computer use, you take a screenshot of the dialog and paste it into the conversation so the assistant can analyze it, then you dismiss the dialog so processing can continue. Then the call is retried.
EA is single-threaded. A slow operation blocks everything behind it, and "(Not Responding)" in the title bar normally means EA is working. Wide scans on a repository that other sessions use can time out once and succeed on a second attempt. Scope scans to the smallest package that answers the question.
Changes made around EA are invisible to its open session. A write through a direct query changes the database underneath EA, which can show stale state until it reloads. Reload the diagram, or ask for a refreshed render. Reloading the EA Browser itself is a step in EA's window, which the assistant does with computer use and you do without it. Verifying a diagram always reloads it first.
Identifier schemes differ between operations. Some attribute operations take an attribute's GUID while others take the element id and attribute id. Baseline comparisons use two GUID forms, braced and underscored, that are not interchangeable and fail without an error when mixed.
A few operations do not check some identifiers. For a mistyped attribute GUID, a mistyped operation GUID or a mistyped target package on a move, EA's own internal error reaches you instead of a clear not-found message. A call that supplies neither an id nor a GUID also fails with a plain tool error.
Verify bulk connector edits. Run verify_diagram after bulk connector edits.
Check a count that matters. Treat a count from a single read as a hypothesis and check it with a count query.
A color set through EA's own Default Appearance dialog is invisible to color rules that read per-diagram styles.
EA caches renders. A check that skips the reload can certify a diagram it never saw.
EA draws more than it stores. EA draws a relationship between two elements on the same diagram whether or not a stored link exists. get_diagram reports such a connector with an instance id of 0.
EA can draw an element larger than its stored rectangle. An unbreakable long name makes EA grow the drawn element while the stored geometry keeps the old size. Rules that read stored rectangles cannot see it. The SVG from verify_diagram does.
A color read back is not proof of a color drawn. EA echoes what was written, and some shapes own their fill and ignore a per-diagram fill. Render the diagram and look.
Double-clicking a navigation element may not open its child diagram in some EA builds, even when the audit passes. Test by double-clicking in EA after you build a navigation set. The assistant can do this with computer use. Otherwise you do it. See ea-navigation-diagrams.
EA has been reported to HTML-encode & in a package name on some paths. Read the name back and repair it with update_package.
Technology state has several meanings, and none implies another. A technology can be installed (its file is registered), embedded (stored in the model, at Location: Project or at Location: Model), registered (known to EA's lists) and loaded (live in this EA session). A technology can also be loaded and not enabled: EA reports a technology disabled in Manage Technologies as loaded, and AI Power Tools reads it as registered but not enabled. Whether a technology is loaded applies to the current session only. A true result from an import call is not proof. A delete call reports success while the technology remains until EA restarts. EA's automation interface has no call that lists technologies. See ea_mdg.
An MDG technology id over 12 characters is rejected silently by EA at load time. write_mdg_xml refuses an id over the limit.
Baselines add to the repository file and are not a backup. Each baseline stores a compressed copy of the package subtree inside the same file, so it grows with the file and is lost with it.
create_model has been reported to fail on EA build 1716. Create the model in EA and open it with open_model.

Repository operations

generate_report. It has been reported to produce RTF only, so name the output with an .rtf extension. An empty template name hangs the call. An unknown template name silently falls back to EA's default document, so a success report does not confirm your template ran. Report templates are authored in EA's user interface: the assistant can drive that with computer use, and otherwise you author the template. The RTF embeds each element's created and modified author values verbatim.
XMI is not a backup. export_xmi checks that the file is XMI and that element names appear in it. That proves the file is not empty, not that it is complete. import_xmi ignores its import type, and the option that strips GUIDs must stay on unless you restore into a repository that lacks those GUIDs, because importing with GUIDs preserved into a model that already holds them hangs. A zero-element import is reported as a failure.
apply_baseline is destructive. It restores the package subtree wholesale and discards later work, including other people's. It is not a merge. If the verification comparison itself fails, the response can say the package was restored without the check having run. Run compare_baseline yourself.
create_baseline can return an older baseline's GUID if you reuse a version label. Use a distinct version each time and confirm with list_baselines. A baseline covers a package and its whole subtree.
list_baselines may show an empty date and author in some EA builds. Query the model's baseline records for authoritative metadata. A baseline is deleted with a direct database statement or in EA's user interface. list_baselines takes one package.
compare_baseline is a package-level comparison. Its connector count covers only connectors whose source is inside the scope.
aggregate_portfolio counts only elements that carry the tag. An element of the stereotype with no value for the tag appears in no group.
launch_ea is not guaranteed safe when EA is already running. The server short-circuits only when it already holds a live connection to EA.
The legacy skills installer declines when the plugin supplies the skills. prune_legacy_skills is a dry run unless told to apply. list_available_skills lists the release bundle and needs network access; it does not list what is installed. See Skills (legacy).

Model content operations

Create paths. create_element_in_language rejects tagged values, so set tags afterward. Bulk creates do not report which tags landed, and a stereotype or direction EA refuses in create_connectors_bulk is not reported per item. Verify with get_element_tags and get_connectors_for_element_filtered. A duplicate spec is skipped and does not update the existing element. Run bulk operations one at a time, and create packages and connectors sequentially.
A type warning is advisory and silent for a stereotype the server has no table for.
Moving a package and changing a parameter. A package's parent is changed by copying the package with duplicate_package and deleting the original with delete_package, by a direct query, or in EA's user interface, after a baseline. add_parameter is not an upsert: a repeated name writes nothing. A parameter is changed by recreating the operation.
An element's base type cannot be changed after creation. Recreate the element.
duplicate_package is structurally faithful, not complete. It does not remap classifier references, and it does not copy connector end properties, tagged values on attributes, operations, connectors and packages, or element parentage. Connectors that cross the package boundary keep pointing at the originals. It is slow on large subtrees. After copying a navigation hierarchy, run find_composite_diagram_mismatches on the copy.
find_orphan_elements means "no connectors" and nothing more. It also reports containers, package mirror rows and elements that are only drawn on diagrams. It is a starting list, not a delete list.
traverse_element_subgraph is slow, capped in depth and node count, and can list an edge twice. Treat nodes and edges as sets. Use trace_connectors for large neighborhoods.
set_element_appearance is model-wide. Per-diagram appearance is set_diagram_object_appearance.
get_element_tags with an unknown element id reports an empty list, not a not-found message. Search operations treat % and _ in a name as wildcards, and a limit caps matches in repository order.

Diagrams

layout_diagram arranges but does not align. Its direction setting is recorded but has no effect, because EA's automation ignores it. Valid styles are Orthogonal, Hierarchical, Circular and Sequence, matched exactly. Follow a layout with neaten_diagram_objects.
neaten_diagram_objects will not guess an arrangement, and resize_diagram_objects can leave uneven spacing.
Turning off automatic connectors when placing elements does not fully suppress them. The setting controls what this call stores. EA's own layout pass can write link rows, and the response then carries a warning. Place with no layout to guarantee no stored link. EA still draws the relationship either way. A bare list of ids with no layout leaves every element at the origin.
A stored link is needed to style a connector, not to show it. set_diagram_link fails for a connector EA merely draws. Add it with add_connectors_to_diagram_bulk first.
Custom Style works only on placements EA created itself. Placements added through the API lack the identifier it keys on. Use set_diagram_object_appearance on generated diagrams. See Custom style.
update_diagram with a raw style string replaces the whole style, including display settings, Custom Style blocks and the modeling-language binding. Use the typed operations, which merge.
Display limits. Compartments cannot be removed, only reduced to names. A text alignment request is refused by design. EA's connector vocabulary has no arc, so radial diagrams use straight or Bezier lines.
Custom images. add_image needs a local file (.qea or .qeax), accepts PNG, EMF and WMF only, and refuses files over 1 MiB. On a server connection or a cloud connection, load the artwork through EA's Image Manager and use set_element_image. A success report from set_element_image means the image reference read back after a reload, not that EA drew the picture.
Vendor icon libraries. find_icon and set_element_icon read the libraries EA installs on the local machine, and a machine without them cannot use them. Some glyphs are not in the libraries, and a caption does not always match an icon name. An icon larger than 1 MB, the limit add_image applies, is not read from a library; none that EA ships comes close. Loading an icon the model lacks needs a local file. A verified icon does not mean EA rendered it. In reported runs, captions were not drawn under image elements in the exported PNG. See Vendor icon libraries.
collapse_parallel_connectors is a dry run by default, applies per diagram and is reversible. It refuses when directions disagree, and you place the returned annotation yourself.
export_diagram_to_visio is geometry only. It writes a rectangle per element and straight center-to-center connectors, with no stencils, waypoints, swimlanes or BPMN shapes. A connector hidden in EA is still drawn. Colors, fonts and images are not carried. To redraw a diagram in another tool with each shape tied to its element, read it with get_diagram_manifest (Reading a diagram or a package as a manifest).

Analysis and queries

execute_sql allows writes by default. A write can leave EA's open session stale. Turn writes off per call, or use read-only mode. A column check can reject an invented column before EA is called, and it can be bypassed.
An unreadable query result is an error, not an empty result. A result EA returns that cannot be read, including one over EA's 64 MB limit for query results, fails the call with an error instead of reporting no rows. A blank result still comes back as zero rows, and EA also returns blank for some queries it fails to run, so cross-check an unexpected zero with a count. The row cap shrinks the response, not the work; use the repository dialect's own LIMIT or TOP to make the query cheaper. Avoid selecting every column of tables that hold binary data.
NULL and empty text cannot be told apart in a query result. EA writes both as an empty value. Code that must keep a column non-null has to supply its own value.
SQL uses the open repository's dialect, and the server does not rewrite it. SQLite, Jet and SQL Server differ, and a statement EA cannot parse opens a dialog that hangs the session.
Summary operations count what exists. summarize_tagged_value_usage counts only tagged values that exist, so absence is not proof a tag is unused. summarize_connector_patterns counts only connectors whose two ends exist, and has been reported to fail on older file-based repositories.
Graph operations can return a partial or empty answer that looks valid. trace_connectors collapses edges to one per ordered pair. find_paths returns no paths both for "no route" and for "id not in the model", and a route longer than the depth limit is reported as no route. A truncated result is a prefix. get_traceability_tree needs a real connector-type filter. None of these can prove completeness.
Audit-trail operations are repository-wide and limited in detail. get_updates_in_range and get_user_activity take no package filter, do not cover connectors, attributes or operations, are not paged, attribute a change to the last saver and show raw login names. A modified date shows that an item was written, not that its content differs. Connector history, deletions and field-level changes are not tracked. Use a baseline comparison for those.
Business-view labels exist only where a language defines aliases. Otherwise the label equals the tag name.
The schema catalog reflects one EA schema version. A newer EA build can hold tables the catalog does not list.

Modeling languages (MDG technologies)

Language and technology lists are probes, not inventories. EA has no call that enumerates technologies, so list_available_modeling_languages and list_registered_technologies can miss a technology that is loaded. A technology disabled in Manage Technologies with no project copy looks like one that was never registered. Ask directly with get_mdg_from_runtime, using the id shown in Manage Technologies.
get_embedded_mdgs lists what the model stores, at both Locations (Project and Model), and not what EA uses. A technology loaded from a file on the workstation is not stored in the model and does not appear. An empty answer means the model stores no technology. Whether a stored copy is enabled is answered by get_mdg_from_runtime.
assess_mdg_situation is a hypothesis. It tests stereotype usage against the languages the server classifies as installed or embedded, so a loaded technology classified otherwise can lead to the wrong scenario. It leaves out a technology disabled in Manage Technologies. It cannot see a source profile package. It has been reported to disagree with Manage Technologies. Cross-check, and read its description.
get_mdg_from_runtime requires a technology id, can answer that it cannot determine the state, and has been reported unable to reach a cloud-hosted technology. It reports a technology disabled in Manage Technologies as registered but not enabled, and a technology whose file declares no version as having none.
set_active_mdg records a preference only, for the session, and does not validate the id. To enforce conformance, run ea_validate audit. See ea_mdg.
A successful install_mdg is not proof. Verify with get_mdg_from_runtime and Manage Technologies, and restart EA.
One technology id at two places shadows itself. When a model holds the same id at Location: Project and at Location: Model, EA lists both and answers from the Project copy, so the Model copy has no effect. A technology file on the workstation can shadow an embedded copy too. An install to the model at Location: Model reports installed but shadowed in that case, and replace_project_copy removes the Project copy. If EA leaves it, reopen the project and repeat, or remove it in Manage Technologies. See Modeling languages.
An install of a technology file into the model at Location: Project keeps no toolbox pages. The reply lists what was stored and what was not, and marks the install incomplete. To keep the whole technology, install from an MDG Technology package at Location: Model, or use EA's Import to Model.
write_mdg_xml writes allowed values, not reference data. Enumeration values are written on each tag, and no EA reference data is written, so a technology installed from this output alone can present free-text fields. It writes fixed sizes and colors, and does not check stereotype or metaclass names. Round-trip the file with parse_mdg_xml.
publish_package_as_profile: always supply a version. EA caches the first version it saw for a package and can otherwise emit a stale or empty value. A package that is not a profile package fails with a general failure.
resolve_display_term knows only what the session knows. A technology's aliases resolve after parse_mdg_xml has read its file, and tag aliases are usually not found.
Hand-written MDG files and technologies built from a source model are never reconciled. ea-mdg-author (hand-written XML) and ea-mdg-model-build (built from a source model) diverge permanently, and nothing detects a hand edit to a generated file.
Building a technology from a source model includes a step in EA's user interface, Save Package as MDG Technology, which is not present on every EA build. The assistant performs it with computer use. Without computer use, you do it. Generated files come out unversioned, so stamp the version and put it in the technology's description. The id is truncated to 12 characters, and reference data was absent from every built file examined.
Deployment fails quietly. An id over 12 characters, a toolbox name mismatch and an encoding mismatch all fail without a readable error. Deploying does not migrate existing elements, and an application-level install needs an EA restart. See ea-mdg-deploy.
Writing to EA's image library through automation is not possible. Use add_image on a local file, or EA's Image Manager.
Examples were verified on EA 17.0 build 1704.

Validation

ea_validate has one operation, audit. Authoring a ruleset means writing a file, not calling an operation. See ea_validate.
Stereotype matching is exact. The comparison is a plain string match with no prefix stripping, and for an element that carries more than one stereotype the rule may see only the first. Write the stereotype as EA stores it (WBABusinessApplication, not WBA::WBABusinessApplication). A name one character off selects nothing, and the rule reports no violations.
The response has no count of what was selected, so "nothing violated" and "nothing selected" look the same. Count the candidates yourself.
The ruleset grammar has five condition types, each bound to one selector type, and no conditional. A condition type the engine does not recognize is skipped without an error, so the rule can never fire. A rule about connector end stereotypes applies both lists to every connector it selects.
A package scope applies to element rules only. Connector rules and counts ignore it, and a package id that does not exist scopes to nothing and returns a clean pass.
The audit has no cap or paging on its violations, and a broad rule over a large model issues many queries. Scope the call or run one rule group at a time.
Hosted rulesets must come over HTTPS with no redirects, at most 2 MB, within 15 seconds. The failure detail is deliberately generic. A release-download link that redirects is refused. Use a final raw-content address or a local path.
One conformance ruleset ships: ArchiMate 3.1 (27 rules). Only models built with EA's built-in ArchiMate technology are selected. Specialization and Junction relationships are not covered, and warnings are "should" rules. The cross-layer rules have known false positives, so treat each reported violation as a candidate to review. See ArchiMate 3.1 ruleset.
A ruleset can express less than people expect. There are no conditionals and no cross-element comparison. Do not promise a rule the validator cannot evaluate. A rule that passes on a model that does not use the language proves little, so prove each rule on a known-bad element.
The validator does not strip a technology prefix. Some skill text says it does. The engine compares exact strings.

Skills

Skills trigger from their own descriptions as well as from routing. A skill the ea-start-here routing table does not list still triggers from its description. See ea-start-here.
ea-diagnostic writes a report; it does not send one. The report contains whatever the session contained, including element names, package paths and pasted error text, so review it first. See ea-diagnostic.
ea-help is the slowest and least verifiable approach. It reads Sparx's user guide for the running EA version and drives EA's user interface. It needs network access and a real browser context, because the Sparx site challenges plain HTTP clients, and it needs computer use to act. Without computer use, it gives you the written procedure to follow yourself. A server connection or a cloud connection can have different or missing options.
ea-com bypasses every server protection: the SQL guard, id checks, structured errors, diagnostics and read-only mode. A failed write can look like success, and a malformed SQL statement raises a dialog. Take a baseline first. See ea-com.
Skill text can lag the server. For example, the shared operations list can omit operations, and a few examples may not match the server's behavior. How tools and operations work is the authority for operation names.
ea-modeling. Raw-SQL writes can leave EA stale. Verify every write by reading it back. After creating a connector with only a bare stereotype, read the technology binding back. Westbrook rule ids and demo-state counts in its references are illustrations, not requirements.
ea-navigation-diagrams. A navigation set is a derived artifact and must be regenerated when the hierarchy changes. A person reloads the EA Browser. Its rule thresholds (12 elements, two levels, three parents) are the skill's own choice.
ea-model-hygiene. Orphan detection measures connectors only. Deletes are permanent. A tag few elements fill in, or a connector stereotype in use, is read against your technology's declared set: declared means optional or neglected, undeclared means ad hoc.
ea-change-management. The server cannot enforce the precautions the skill asks for (baseline first, confirm ids). Audit-trail author values are personal identifiers.
ea-diagram-advisor. Only the ArchiMate 3 binding ships a view catalogue, so the advisor has nothing to rank for another notation and falls back to a neutral custom view. Coverage is not fitness, and the ranking cannot see what a diagram is for. See ea-diagram-advisor.
ea-diagram-composition. The engine uses eleven layout grammars: nine are composed by arithmetic, graph diagrams use EA's own layout and are tidied afterward, and EA-semantic diagrams such as sequence and timing cannot be produced by composing coordinates. Some diagram types are deliberately unbound. See Layout grammars.
The diagram linter sees only what it measures. A clean report means no known defect, not that the layout was the right one. Shape-scripted notations draw paths, so label-fit rules stay mostly silent. Crossing counts are approximate. Render and look.
Fill is not always honored, for example for Node and Grouping in the ArchiMate 3 binding. Use Device or SystemSoftware for color-coded technology layers.
Reproducing a diagram from a picture is driven by your prompt, including how the result is compared with the picture.
Vendor-icon diagrams reproduce the asset, not every detail. Stored geometry can differ from drawn geometry by tens of pixels, badges inside containers are not reproduced, and some glyphs are not in the libraries. Judge by a render.
Skill text is not a source of truth for the code. When a skill and an operation disagree about a name or behavior, trust the operation's own response.

Reporting and Power BI

The business layer is the set of tables that the modeling technology defines over EA's own data. It is delivered in one of three ways: as views in the EA database, as a separate reporting database, or as Parquet files. See Reporting business layer, ea-reporting-database and ea-power-bi.

Only views in the EA database are live. They read EA's tables as they stand. A separate reporting database and Parquet files are snapshots of one instant, rebuilt in full on every refresh with no history. Nothing compares two builds.
Your estate decides which delivery ways exist. Views in the EA database need the EA repository to sit in a SQL Server database that you can reach directly with Windows authentication, and the right to create views in it. A local file has no database server, and a database other than SQL Server is not supported for this way. A cloud connection normally gives no direct database access. A separate reporting database needs a SQL Server that you run, or a SQL database in Microsoft Fabric. Parquet files need no database. The last two read EA's tables through EA, so EA must be running with the repository open, and the extraction does not depend on the database engine behind EA. It was measured on SQL Server and on MySQL behind a cloud connection.
SQL Server with Windows authentication, or a SQL database in Microsoft Fabric with Microsoft Entra sign-in. On SQL Server, the account that runs the AI Power Tools MCP Server for Sparx EA connects to the database, and SQL logins are not used. Views in the EA database use only that. A separate reporting database has no up-front rights check, so the account needs enough rights on that database to create it, its schemas, tables and views; owner-level rights are the safe assumption.
The Microsoft Entra sign-in needs a person. A reporting database in Microsoft Fabric is signed in to at Microsoft's sign-in window, once per server process. An unanswered sign-in stops the operation after about ten minutes and writes nothing, so a scheduled refresh into Fabric needs someone at the machine when the server first opens the database. The database is created in the Fabric portal; AI Power Tools cannot create it there. It needs the Microsoft OLE DB Driver for SQL Server.
Use a schema of its own for the views. A build drops every view already in the schema, and removing the layer drops them all. A few schema names are refused, including the one that holds EA's own tables. The build never alters an EA table.
The business layer needs a modeling technology. With none loaded, the AI says so and does not build. The technology and the inclusion choice decide the tables. Nothing is tuned by hand.
A build reports data-quality problems and does not fix them. The one write is a stereotype you choose to apply after the governance gate, behind a baseline. An element with an empty stereotype is in no business table.
Exclusion is by whole package, with no masking. Notes and tagged values in a kept package all reach the output. A kept link into a left-out package keeps an "(excluded)" stand-in at its far end, and left-out content is never written to disk.
Tag values are shown as EA shows them. Of two tags with one name on an element, the first is used. A declared number is accepted in plain form only; anything else is empty in a typed column, and the value check reports it. An empty value is NULL in a number column and empty text in a text column, because EA writes both identically. A comma-joined text tag is one value, and only a declared list-of-references tag becomes one row per reference. A checklist tag stays a column.
A refresh runs in the background. One call starts it and returns a run id; a second call polls it. A scheduled AI agent whose session has the server on the machine where EA runs can start it, poll it and report. EA must be running with the repository open on that machine, and the AI Power Tools MCP Server for Sparx EA must stay up until the run ends, because runs are held in memory. Windows Task Scheduler is not a supported way. A run that fails, or that the reporting preflight stops, leaves the previous data live. For Parquet files, a refresh rewrites the rows and the definition but not the Parquet files or the Power BI project, which wait for the local step.
Only the last build's extract is kept. The kept extract sits beside the profile and each build replaces it. Replay rebuilds a reporting database or the Parquet rows from it with no EA connection and reproduces that build's instant. It is not a refresh, and it does not apply to views in the EA database. The kept extract holds included content, so treat it like the reporting data.
The checks have limits. The alignment check and the value check apply to the two database delivery ways. A check that read no cells fails and never passes. Connectors that use a declared connector stereotype between two element stereotypes the technology does not allow together are reported and stay out of the business tables. A spot check in EA later can differ by a few rows on a shared repository, because other work landed in between: quote the build's as-of time with any snapshot figure.
Power BI storage modes. Views in the EA database support DirectQuery (live) or Import. A separate reporting database and Parquet files support Import only. DirectQuery queries the production database.
A generated .pbip project does not load data on open. Refresh it once in Power BI Desktop; the assistant does this with computer use, and otherwise you do. The Parquet project stores an absolute folder path, so moving the folder or the project means regenerating it.
Refresh in the Power BI service. A published model refreshes with no gateway from a SQL database in Microsoft Fabric. From a SQL Server you run it refreshes through an on-premises data gateway, which was not measured with the generated model. It cannot refresh from local Parquet files. Removing the business layer stops every refresh until the layer is rebuilt.
Every entity table shows one blank member. Power BI shows "(Blank)" in a slicer and one extra row in a table visual. The count measures are right.
The generated files are the source of truth. Edits made to the model inside Power BI are lost when the project is regenerated, while an existing report folder is left untouched, so regenerating neither adds the Overview page to it nor repairs it. Business definitions belong in the descriptions file, which is refused whole when an entry names something the model does not have or is longer than 250 characters. Keep the project folder path short because of Windows' 260-character path limit.
Microsoft 365 Copilot. Measured on one model with Microsoft 365 Copilot Chat only. Answers vary between runs. It finds reports more readily than models. Descriptions reach it when the model is published from Power BI Desktop. The generator's size line warns past 1,000 tables plus columns and chooses nothing.
Stakeholder reporting. Roll-ups never warn that they are partial. An empty roll-up is ambiguous between a wrong stereotype and an untracked tag. Splitting a multi-value tag splits on every comma, so the groups sum to more than the total. resolve_display_term never knows a technology's tag aliases, so for your own technology the labels in the business view and the roll-up are technical names. The figures are a point-in-time read, not a checked one. See ea-stakeholder-reporting.
Import and export. XMI is not a backup, Visio export is geometry only, and report content carries modelers' user names.

Prolaborate

The skills are browser-driven and session-bound. They need no server, but they need browser control and a Prolaborate session you have signed in to. They never enter credentials. The session can end, and the access token expires after 240 seconds unless the application renews it. They depend on Prolaborate's current pages and interface, and were verified against one version (5.6.1.40) as a Super Admin. A Super Admin skips authorization checks, so what a restricted user sees can differ. See prol-start-here.
prol-dashboards cannot arrange tiles. Every dashboard needs manual layout. Lifecycle Road Map and Integration Reports widgets are blocked by prerequisites the skill will not satisfy. Everything was verified against MySQL. A Rich Text security setting is a render-time filter only. Saving a change to a shared dashboard changes what others see immediately.
prol-matrix is read-only. Profiles are authored in EA. There is no paging, and renaming a profile in EA breaks saved links because the name is the identifier.
prol-impact-analysis cannot promise a complete blast radius. Prolaborate has no depth traversal, so a multi-hop result is composed one hop at a time with the AI's own cap, and the total is a floor when the cap was hit. A saved view is a tenant object with no undo.

Things not to assume

A snapshot is not live. A separate reporting database and Parquet files reflect one moment. A refresh rebuilds them, and nothing starts it unless you or a scheduled AI agent do. Replay reproduces a build's instant and is not a refresh.
Power BI is live only over views in the EA database, with DirectQuery. Describe every other model as a snapshot, with its as-of time.
Installed is not embedded, registered or loaded. A technology can be present in any of these states without being live in this EA session. Check with get_mdg_from_runtime and with Manage Technologies.
A success report is not verification. It says the call ran and EA accepted it. It does not say EA applied every property, drew the result or stored it. Verify through a different surface from the one you wrote with. See Where the AI decides and where AI Power Tools decides.
An empty or zero result is not an answer by itself. A wrong id, a wrong direction, a stereotype one character off, an unlisted technology or a failed query can each return nothing. Zero violations is a result only when the selectors matched something.
A truncated traversal is not a complete one.
A recommendation is a hypothesis. assess_mdg_situation, the diagram advisor and the governance gate's suggestions are rule-based. They are repeatable, and they can be wrong.
A baseline is not a backup, and XMI is not a baseline. Both live in or beside the same file, and neither replaces a copy of the model.
Read-only mode is not a security boundary, and a Super Admin Prolaborate session says nothing about what other users see.
Westbrook Bank is an illustration. Its technology, stereotypes and model file are test fixtures of the AI Power Tools team. No step in this reference assumes you have them.
Model recommendations are guidance. The "Recommended models" tables are guidance from a task's characteristics.
A drawn diagram is not the stored diagram. What EA paints (extra relationships, grown elements, its own fill) can differ from what is stored. Judge by a render.