Skip to main content
Glama
EL4CTEO

Roblox Studio MCP

by EL4CTEO
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Local

Find instances

find
Read-onlyIdempotent

Search Roblox Studio instances by name, class, property, selector, or CollectionService tag, combining filters to answer layered queries in one call.

Instructions

Searches the data model by name, class, property value and/or tag. Every filter you supply must match, so one call answers questions that would otherwise take several: "anchored BaseParts under Workspace.Map whose name contains door" is a single request.

This replaces separate name / class / property / tag search tools. Prefer it over tree whenever you know what you are looking for.

Tag searches are answered from CollectionService's index rather than by walking the tree, so they stay fast on large places. Narrow with path if a search reports TOO_BROAD.

op="tags" lists which tags the place actually USES, with counts and a few example paths. Call it before filtering by tag on a place you do not know: a tag search that returns nothing looks the same whether you spelled it wrong or nothing carries it, and the tag names are often the clearest description of how a game is organised (Enemy, Checkpoint, Interactable say more than the folder layout does).

selector is the engine's own query language and is the fastest option of all — the matching happens in C++ and only survivors come back. Reach for it when the shape of the tree is part of the question (Model > Part) or when one call should answer two (Part, Model); the filters above still apply on top of it.

Input Schema

NameRequiredDescriptionDefault
opNo'find' searches for instances. 'tags' lists which CollectionService tags exist in the place, with counts — use it when you do not know the tag names yet.find
tagNoCollectionService tag the instance must carry.
pathNoLimit the search to this subtree, e.g. "Workspace.Map". Omit for everything.
limitNoMaximum items to return (1-500).
cursorNoOpaque cursor from a previous call's `nextCursor`. Omit for the first page.
detailNoconcise: compact identity. standard: selected facts. full: all readable properties for inspect; tree/find use the same columns as standard.standard
playerNoclient only: player name; required with multiple players.
targetNoclient: read the actual player's playtest VM. Use the playtest server studioId.studio
handlesNoInclude bounded session handles usable in place of paths. Survive rename/reparent; refuse expired references.
selectorNoEngine query selector, matched inside Studio. Supports a class name ("Part", superclasses included), "#ExactName", "[Anchored=true]", either-or with "Part, Model", direct children with "Model > Part" and descendants with "Model >> Part". No substring names and no < > comparisons — use nameContains and propertyValue for those. Combines with the other filters.
studioIdNoTarget Studio; omit for the active one.
classNameNoClass or superclass, e.g. "BasePart", "Script".
propertiesNoProject just these properties on matching rows, avoiding a second inspect call. Unreadable names are reported.
nameContainsNoSubstring of the instance name, case-insensitive.
propertyNameNoProperty that must exist, e.g. "Anchored". Combine with propertyValue.
propertyValueNoRequired value of `propertyName`, compared as text — "true", "0, 5, 0", "Enum.Material.Neon". Omit to match any instance that has the property.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed3 schema fields changedv0.9.1
    • addedInput schema / properties / handles
      Added value: +{
+  "default": false,
+  "description": "Include bounded session handles usable in place of paths. Survive rename/reparent; refuse expired references.",
+  "type": "boolean"
+}
    • addedInput schema / properties / player
      Added value: +{
+  "description": "client only: player name; required with multiple players.",
+  "type": "string"
+}
    • addedInput schema / properties / target
      Added value: +{
+  "default": "studio",
+  "description": "client: read the actual player's playtest VM. Use the playtest server studioId.",
+  "enum": [
+    "studio",
+    "client"
+  ],
+  "type": "string"
+}
  2. Changed2 schema fields changedv0.8.6
    • changedInput schema / properties / detail / description
      Previous value: -"How much to return per item. 'concise' = name + class only, cheapest, use when scanning or counting. 'standard' = the properties that matter for most edits. 'full' = every readable property, expensive — use only after you have narrowed to a handful of instances."New value: +"concise: compact identity. standard: selected facts. full: all readable properties for inspect; tree/find use the same columns as standard."
    • addedInput schema / properties / properties
      Added value: +{
+  "description": "Project just these properties on matching rows, avoiding a second inspect call. Unreadable names are reported.",
+  "items": {
+    "minLength": 1,
+    "type": "string"
+  },
+  "maxItems": 16,
+  "type": "array"
+}
  3. Changed2 schema fields changedv0.6.5
    • addedInput schema / properties / op
      Added value: +{
+  "default": "find",
+  "description": "'find' searches for instances. 'tags' lists which CollectionService tags exist in the place, with counts — use it when you do not know the tag names yet.",
+  "enum": [
+    "find",
+    "tags"
+  ],
+  "type": "string"
+}
    • addedInput schema / properties / selector
      Added value: +{
+  "description": "Engine query selector, matched inside Studio. Supports a class name (\"Part\", superclasses included), \"#ExactName\", \"[Anchored=true]\", either-or with \"Part, Model\", direct children with \"Model > Part\" and descendants with \"Model >> Part\". No substring names and no < > comparisons — use nameContains and propertyValue for those. Combines with the other filters.",
+  "type": "string"
+}
  4. First observedv0.1.8

TDQS

A4.5/5.0
Behavior4/5

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

Goes well beyond the readOnly/idempotent annotations: it explains that tag searches are served from CollectionService's index rather than tree walks (hence fast on large places), that `selector` matching runs in C++ so only survivors return, that all supplied filters are ANDed, and that a tag search with no results is ambiguous. It does not describe pagination behavior or response shape, but with annotations already covering the safety profile this is rich operational context.

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?

Front-loaded with the core verb+resource and the sibling routing, then organized into tight paragraphs per concern (filters, tags, selector). It is on the longer side for 16 parameters but each paragraph carries distinct guidance; the closing selector paragraph is the most expendable.

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 16-parameter, no-required-argument search tool with no output schema, the description covers the operation modes, filter combination semantics, and the selector escape hatch well. Gaps are minor: return/pagination shape and how `detail`, `handles`, `player`/`target` interact with results are left to the schema.

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 already 100%, so baseline is 3; the description nonetheless adds real meaning — the conjunctive semantics of multiple filters, the TOO_BROAD/`path` interaction, the rationale for `op="tags"`, and when `selector` beats the individual filter params. It does not add much for `limit`/`cursor`/`handles`, keeping it short of a 5.

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 ('Searches the data model by name, class, property value and/or tag') and explicitly names what it supersedes ('This replaces separate name / class / property / tag search tools'). It also differentiates from the sibling 'tree' tool, so an agent can distinguish it without opening any 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?

Explicit when-to-use guidance: 'Prefer it over `tree` whenever you know what you are looking for', plus a dedicated condition for `op="tags"` ('Call it before filtering by tag on a place you do not know') and for `selector` ('Reach for it when the shape of the tree is part of the question'). It also gives a recovery rule ('Narrow with `path` if a search reports TOO_BROAD'), covering alternatives and exclusions.

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