Skip to main content
Glama
EL4CTEO

Roblox Studio MCP

by EL4CTEO
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Local

Find instances

find
Read-onlyIdempotent

Searches Roblox Studio's data model by name, class, property, tag, or selector in one request, letting AI agents locate instances without multiple tree scans.

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

TableJSON 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.
detailNoHow 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.standard
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".
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. 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"
+}
  2. First observedv0.1.8

TDQS

A4.8/5.0
Behavior5/5

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

Annotations already declare readOnly/idempotent/non-destructive, yet the description still adds real behavioral insight: tag searches are served from CollectionService's index rather than a tree walk (hence fast on large places), TOO_BROAD is a possible outcome with a documented remedy, and `selector` executes matching in C++ so only survivors return. These are non-obvious performance and error behaviors an agent cannot get from the annotations.

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 capability and an example before any caveats, and the paragraph breaks map cleanly to tags/selector concerns. It is somewhat long for a description, but nearly every sentence carries distinct routing or behavioral content rather than restating the schema.

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 12-parameter, 0-required, no-output-schema tool, the description covers the filter model, tag discovery workflow, subtree narrowing, and the selector escape hatch. Pagination and per-item detail are left to the schema, which documents them fully, so nothing an agent needs to invoke the tool correctly is missing.

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 100%, so the baseline is 3, but the prose meaningfully extends it: it explains the purpose of `op="tags"`, that every supplied filter must match, that `selector` 'combines with the other filters', and that `path` is the remedy for broad results. It stops short of covering paging (`limit`/`cursor`), which only the schema documents.

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 ('Searches the data model by name, class, property value and/or tag') and immediately distinguishes itself from siblings, naming `tree` and claiming to replace separate name/class/property/tag search tools. The concrete example ('anchored BaseParts under Workspace.Map whose name contains door') makes the scope unambiguous.

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 routing advice: 'Prefer it over `tree` whenever you know what you are looking for', 'Narrow with `path` if a search reports TOO_BROAD', and a full paragraph on when to call op="tags" before filtering by tag. It also states when to reach for `selector` (shape-of-tree questions or two-class queries). When-to-use, when-to-narrow, and alternatives are all present.

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