Skip to main content
Glama

obj_query

Queries schematic or PCB objects and reads their properties, with optional property-value filters and selected fields returned for each matching object.

Instructions

Query schematic OR PCB objects and read their properties.

Iterates objects of the given type, optionally filtering by property values, and returns the requested properties for each matching object.

Args: object_type: Altium object type constant. Schematic: "eNetLabel", "ePort", "ePowerObject", "eSchComponent", "eWire", "eBus", "eBusEntry", "eParameter", "ePin", "eLabel", "eLine", "eRectangle", "eSheetSymbol", "eSheetEntry", "eNoERC", "eJunction" PCB: "eTrackObject", "ePadObject", "eViaObject", "eComponentObject", "eArcObject", "eFillObject", "eTextObject", "eRuleObject", "eDimensionObject", "eConnectionObject" (the ratsnest: one line per unrouted connection, with X1, Y1, X2, Y2, Layer1, Layer2 and Net) properties: Comma-separated property names to return.

    SCHEMATIC objects use the dotted spelling:
    "Text,Location.X,Location.Y" for net labels
    "Designator,Name,ConnectionX,ConnectionY" for pins.
    ConnectionX/ConnectionY are the pin's ELECTRICAL end --
    the point a wire or net label must sit on to attach.
    Location is the BODY-side root and is NOT the connection
    point; deriving the end by hand from Orientation and
    PinLength is a common source of wrong conclusions about
    what is wired.
    "Designator.Text,Comment.Text,LibReference" for components
    A managed (Workspace) component also reads, but does not
    write, "LibIdentifierKind,LibraryIdentifier,DesignItemId,
    VaultGUID,ItemGUID,RevisionGUID,SymbolReference,
    SymbolVaultGUID,SymbolItemGUID,SymbolRevisionGUID". Read
    off a part Altium placed, they are the values the managed
    tools need.

    PCB PRIMITIVES DO NOT. They are a separate, flat set,
    and mixing the two is the single commonest mistake here:
    a caller who used Designator.Text infers a dotted rule,
    writes Net.Name on a track, and gets an error naming the
    right spelling. Net is the one that catches people, and
    it is plain "Net":
    "Net,Layer,Width" for tracks
    "Net,Layer,HoleSize,Size" for vias
    "Designator,Comment,Pattern,Rotation,X,Y" for components
    "Text,Height,StrokeWidth,IsDesignator" for texts
    Full set: ObjectId, X, Y, Layer, Descriptor, Selected,
    Net, X1, Y1, X2, Y2, Width, Radius, StartAngle,
    EndAngle, XCenter, YCenter, HoleSize, Size, TopShape,
    TopXSize, TopYSize, Rotation, Name, Text, Pattern,
    Designator, Comment, SourceDesignator, Kind,
    RemoveDead, RemoveNarrowNecks, RemoveIslandsByArea,
    StandoffHeight, OverallHeight, BodyOpacity3D, InComponent, Component,
    InPolygon, IsKeepout, Locked, Layer1, Layer2,
    IsRedundant, Mode, Height, StrokeWidth, IsDesignator,
    IsComment, UseTTFonts.

    On a text, Height and StrokeWidth are writable in mils
    (Altium's own names, Size and Width, answer the same).
    On a via, Size and HoleSize are writable; a write that
    would leave the hole as large as the pad is refused, so
    give Size first to grow a via and HoleSize first to
    shrink it. Lengths read back in decimal mils.
    On a pad, Name and Designator both read and write its
    designator; an empty one is refused.
    On a 3D body, BodyOpacity3D reads and
    writes 0 (clear) to 1 (solid), not a percentage.
    IsDesignator and IsComment pick out component labels:
    filter "IsDesignator=true" for every designator.

    A board type walks EVERY primitive of that type, a
    footprint's own tracks and a hatched polygon's tracks
    with the routing, on the same copper layers. Filter
    "InComponent=false|InPolygon=false" keeps to free copper;
    Component is the owning footprint's designator.

    An unrecognised PCB property is REFUSED and the reply
    lists the valid ones. It used to come back empty, which
    is indistinguishable from a property that is genuinely
    blank, and that ambiguity has three times been read as
    "the bridge cannot see this data".

    A track on a mechanical layer really does have no net,
    so filter to copper before concluding anything from an
    empty Net: filter="Layer=TopLayer".
scope: Document scope:
    "active_doc", current sheet only (default)
    "project", all SCH sheets in focused project
    "doc:C:\path\to\Sheet.SchDoc", specific sheet by path (no focus change)
    "project:C:\path\to\Project.PrjPcb", specific project by path
    "lib_component:NAME", a named symbol in the active SchLib
    "lib_component:NAME@3", part 3 of a MULTI-PART symbol.
        A SchLib iterator yields one part at a time, so
        without the suffix only part 1 is visible and a pin
        on part 3 reports matched:0. Query each part in
        turn to cover the whole component. The suffix is
        read from the RIGHT, so a LibRef containing '@'
        still works.
        Ask for the `OwnerPartId` property to see which
        part a returned primitive belongs to (0 means
        shared across every part).
filter: Pipe-separated property=value conditions (AND logic), e.g.:
    "Text=VCC", match net labels with Text equal to VCC
    "Designator.Text=R1", match component with designator R1
    "" (empty), match all objects of the type
    On a PCB type a length (X, Y, X1, Y1, X2, Y2, Width, Size,
    HoleSize, ...) matches as a number in mils, to 0.00005
    mil, with '.' or ',' as the decimal point:
    "X2=3172.6356" and "X2=3172,63560" are the same filter.
limit: Maximum number of objects to return (0 = unlimited)

Returns: Dictionary with "objects" array and "count"

Input Schema

NameRequiredDescriptionDefault
limitNo
scopeNoactive_doc
filterNo
propertiesYes
object_typeYes

Output Schema

NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.6.1

TDQS

A4.7/5.0
Behavior5/5

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

With no annotations, the description carries the full behavioral burden and does so richly: it explains return structure, refusal of unrecognized PCB properties, multi-part SchLib visibility, board-type primitive traversal, units in mils, and common false conclusions from empty properties.

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?

The description is long and dense, but the complexity of object types, property naming quirks, and scope behavior justifies most of its length. It is front-loaded and structured with Args sections, though some historical/aside comments could be trimmed.

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

Completeness5/5

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

Given zero annotation coverage, zero schema description coverage, and five parameters for a generic object-query tool, the description is complete enough for correct invocation. It covers parameters, filtering, scope, return shape, and key failure modes.

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

Parameters5/5

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

Schema description coverage is 0%, so the description must document all five parameters, and it does: object_type constants by domain, dotted vs flat property naming, scope values including multi-part syntax, filter grammar and numeric matching, and limit semantics.

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?

The description opens with a specific verb and resource: query schematic or PCB objects and read their properties. It further specifies the iteration/filter/return model, making clear this is a generic read/query tool rather than a write, count, or modification tool.

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?

The description gives substantial context for how to use the tool: scope choices, filter syntax, object-type constants, and pitfalls such as filtering to copper before concluding a net is empty. It does not explicitly name alternatives like pcb_get_components or obj_count and when to prefer them, so it falls short of full when/when-not guidance.

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

Deploy Server

Other Tools