Skip to main content
Glama

Read the property values of R3 components

r3_component_read
Read-onlyIdempotent

Read back what components actually hold — a material's colour and roughness, a mesh's position, which material it uses. r3_project_load gives you the names; this gives you the values behind them.

Pass SEVERAL entityRefs in one call — telling six similarly-named materials apart is the case this exists for, and it is one round trip rather than six. One component: entityRef: "mesh_cube_1" (r3_component_set's name for it) works too.

What comes back is exactly what r3_component_set takes, so read → change → write needs no translation: value components are expanded inline ({"position": {"x": 0, "y": 2, "z": 0}}), references are the target's entityRef as a string (or null when empty), and lists of references are arrays of entityRefs. Use it before any relative change ("20% brighter", "move it up by one"), and after a write to confirm what landed.

Bulk data — mesh vertex arrays and anything else megabyte-sized — is NOT returned. Every property left out is listed with the reason, so an omission is never silent.

Each answer says which entity the component belongs to (entity: {entityRef, id}, or null). An id works in place of an entityRef; an entityRef several components hold (the same name in different entities) is not guessed: it is reported with each holder's id.

An entityRef that does not exist is reported by name and the rest are still read. Value components (a Vector3, a Color) are not read on their own: ask for the component that owns them.

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": {
      "projectId": "<projectId>"
    },
    "name": "r3_component_read"
  }
}

Input Schema

NameRequiredDescriptionDefault
entityRefNoOr one component, e.g. "mesh_cube_1".
projectIdYesThe project the components are in, from r3_project_create or r3_project_load.
entityRefsNoWhich components to read, as reported by r3_project_load: an ARRAY, e.g. ["mesh_cube_1", "material_cube_1"]. Up to 50 per call.

Output Schema

NameRequiredDescriptionDefault
answerYesThis answer in words: what was done, what R3 measured, decided or refused, and what to do next. The same text as the result's text block. Read it: the fields beside it are the data, this is the guidance.
projectIdYes
componentsYes
unreadableYes
projectNameYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changed
    • addedOutput schema / properties / components / items / properties / entity
      Added value: +{
      +  "anyOf": [
      +    {
      +      "additionalProperties": false,
      +      "properties": {
      +        "entityRef": {
      +          "type": [
      +            "string",
      +            "null"
      +          ]
      +        },
      +        "id": {
      +          "type": "string"
      +        }
      +      },
      +      "required": [
      +        "entityRef",
      +        "id"
      +      ],
      +      "type": "object"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ]
      +}
    • changedOutput schema / properties / components / items / required
      Previous value: -[
      -  "entityRef",
      -  "type",
      -  "name",
      -  "id",
      -  "properties",
      -  "omitted"
      -]New value: +[
      +  "entityRef",
      +  "type",
      +  "name",
      +  "id",
      +  "entity",
      +  "properties",
      +  "omitted"
      +]
  2. Changed3 schema fields changed
    • addedInput schema / properties / entityRef
      Added value: +{
      +  "description": "Or one component, e.g. \"mesh_cube_1\".",
      +  "type": "string"
      +}
    • changedInput schema / properties / entityRefs / description
      Previous value: -"Which components to read, as reported by r3_project_load, e.g. [\"mesh_cube_1\", \"material_cube_1\"]. Up to 50 per call."New value: +"Which components to read, as reported by r3_project_load: an ARRAY, e.g. [\"mesh_cube_1\", \"material_cube_1\"]. Up to 50 per call."
    • changedInput schema / required
      Previous value: -[
      -  "projectId",
      -  "entityRefs"
      -]New value: +[
      +  "projectId"
      +]
  3. Changed2 schema fields changed
    • addedOutput schema / properties / answer
      Added value: +{
      +  "description": "This answer in words: what was done, what R3 measured, decided or refused, and what to do next. The same text as the result's text block. Read it: the fields beside it are the data, this is the guidance.",
      +  "type": "string"
      +}
    • changedOutput schema / required
      Previous value: -[
      -  "projectId",
      -  "projectName",
      -  "components",
      -  "unreadable"
      -]New value: +[
      +  "projectId",
      +  "projectName",
      +  "components",
      +  "unreadable",
      +  "answer"
      +]
  4. First observed

TDQS

A4.6/5.0
Behavior4/5

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

The annotations already establish the safety profile (readOnly, idempotent, non-destructive), and the description adds substantial behavior beyond that: omitted bulk vertex data is always reported with a reason, missing entityRefs are reported by name while the rest are still read, and ambiguous refs are never silently guessed. The only gap is that it does not discuss rate limits or the 50-item cap's failure behavior beyond the schema note.

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?

It is front-loaded: the first sentence describes the purpose, and the second names the boundary against r3_project_load. The five paragraphs are dense with useful information, though the return-shape paragraph overlaps with the output schema and could be shorter.

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?

For a read tool with three parameters, full annotation coverage, and an output schema, nothing needed for correct invocation is missing. Edge cases such as missing refs, ambiguous refs, and omitted bulk data are all covered.

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 coverage is 100%, so the baseline is 3. The description goes further by explaining that entityRef and entityRefs are interchangeable for a single component, and that an id from the response can substitute for an entityRef in later calls, which clarifies invocation choices that the schema does not spell out.

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 uses a specific verb and resource: 'Read back what components actually hold — a material's colour and roughness, a mesh's position, which material it uses.' It also contrasts this with sibling tools (r3_project_load gives names, this gives values), so an agent can route between them without opening either schema.

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

Usage Guidelines5/5

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

It states when to use this tool versus alternatives and gives concrete triggers: 'Use it before any relative change' and 'after a write to confirm what landed.' It also names r3_project_load and r3_component_set as the related tools to use at the other steps.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources