Archicad-MCP

Overview Schema Source Related Servers Discussions Admin

Find elements by criteria

find_elements

Read-only

Find Archicad elements matching property criteria groups, combining comparisons with AND/OR and restricting element types; returns GUIDs, counts, and coverage.

Instructions

Find elements matching criteria groups. Groups combine with OR; inside a group the comparisons combine with logical_operator 'and' (default) or 'or'. Each group may restrict element types (is / is_not) and lists comparisons of {property, operator, value}; the schema enumerates the element types and the 22 operators, and each field documents its values and units. Call search_definitions to find a property's exact address. An element with no usable value matches no binary operator. Returns GUIDs, counts, how many elements had properties read, and 'coverage' ('whole-plan' with Tapir, 'model-elements-only' without: then 2D elements are invisible and 0 is not proof of absence). Property comparisons read values in the server (no API filters by property); a read spanning more than the element ceiling is refused, so narrow with element_types, story or classification first.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`port`	No
`groups`	Yes
`selection_only`	No

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv0.7.1Oct 1, 2026

changedInput schema / properties / groups / items / properties / element_types / description

Previous value: -"Archicad element type names to restrict this group to. Omit for every type; 'all' says so explicitly."New value: +"Archicad element type names to restrict this group to. Omit for every type; 'all' says so explicitly. 'Unknown' is an element that exists but has no type in either API, such as a native MEP route, segment or node; it is matched over the whole plan, so it is slower."

Addedv0.5.1Sep 3, 2026

TDQS

A4.3/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With readOnlyHint/destructiveHint already covering safety, the description adds substantial non-obvious behavior: property comparisons are evaluated server-side (no API-side property filtering), oversized reads are refused, elements with no usable value match no binary operator, and the returned 'coverage' flag reveals that without Tapir, 2D elements are invisible and a zero count is not proof of absence. These are exactly the traps an agent needs warned about.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

One dense paragraph that is front-loaded with the group/comparison semantics. Every sentence carries operational information, though the single block of prose would be easier to scan if the return-shape and coverage caveats were split out.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, yet the description still adds value by flagging the coverage caveat (2D elements invisible without Tapir) and the read ceiling. The main omission is any explanation of selection_only, which an agent may reasonably expect to control selection state.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Top-level schema description coverage is 0%, and the description explains the nested structure well (groups OR together, comparisons combine via logical_operator, is/is_not type restriction, {property, operator, value}). However it never mentions the top-level 'selection_only' or 'port' parameters, leaving their effect undocumented in both the schema and the description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Find elements matching criteria groups') and immediately defines the criterion structure, so the agent knows this is a property/type-based query rather than a lookup by GUID (get_element_data) or a read of the current selection (get_selection). It also names the companion tool search_definitions for resolving property addresses.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives actionable context: call search_definitions to find a property's exact address, and narrow with element_types, story or classification before a property read or the call is refused for exceeding the element ceiling. It routes to an alternative tool but does not state when to prefer a sibling query tool instead of this one.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.