Skip to main content
Glama

Query Faces

query_faces
Read-only

Filters 3D model faces by type, normal direction, radius, or area, returning matching face descriptors for downstream selection or measurement.

Instructions

Filter faces by a structured predicate. Returns matching descriptors.

Predicate fields (all optional, ANDed):

  • kind / type: 'planar' | 'cylindrical' | 'conical' | 'spherical' | 'toroidal' | 'spline'

  • normal_dir: [x, y, z] unit vector for planar faces (with normal_tol)

  • radius_eq: float, matches cylindrical/conical/spherical (with radius_tol)

  • area_min / area_max: bounds in mm^2 Optional ordering:

  • centroid_max / centroid_min: 'x' | 'y' | 'z' (sorts result)

  • order: 'area_desc' | 'area_asc'

Example: {"type": "planar", "normal_dir": [0, 0, 1], "centroid_max": "z"} finds the topmost +Z-facing face.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "handle": "<handle>",
      "predicate": "<predicate>"
    },
    "name": "query_faces"
  }
}

Input Schema

NameRequiredDescriptionDefault
handleYes
predicateYes
workspaceNoRun this call in this named workspace

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv0.5.7
    • addedInput schema / properties / workspace
      Added value: +{
      +  "default": "",
      +  "description": "Run this call in this named workspace",
      +  "title": "Workspace",
      +  "type": "string"
      +}
  2. First observed

TDQS

A3.9/5.0
Behavior4/5

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

The description explains that predicate fields are optional and ANDed, lists supported face kinds, tolerances, area bounds, and ordering options, and provides a concrete example. With readOnlyHint=true and openWorldHint=false already provided in annotations, this adds useful query semantics beyond the safety profile.

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

Conciseness5/5

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

The description is front-loaded, structured as a bulleted field list, and includes a compact example. Every line contributes to understanding how to construct the predicate, with no filler.

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?

For a read-only face-query tool with no output schema, the description explains inputs, predicate AND semantics, supported face types, ordering, and an example. It does not describe the returned descriptor structure, but the core information needed to call it correctly is present.

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

Parameters4/5

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

Schema description coverage is only 33% and predicate is a nested object with additionalProperties=true, so the description carries most of the parameter burden. It thoroughly documents the predicate fields and example; handle itself is not described, but the key nested predicate semantics are well covered.

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

Purpose4/5

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

The description states a specific verb and resource: filter faces by a structured predicate and return matching descriptors. It is clear what the tool does, though it does not explicitly contrast itself with the sibling tool list_faces.

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

Usage Guidelines3/5

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

The description gives an example showing intended use, such as finding the topmost +Z-facing planar face, but it does not explicitly say when to use query_faces instead of list_faces or resolve_face. Usage is implied by the structured-predicate filter rather than stated as a routing rule.

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