Skip to main content
Glama

tag

DestructiveIdempotent

Manage CollectionService labels on one instance: read, add, or remove a label; add/remove are blocked in read-only mode.

Instructions

Read, add or remove CollectionService tags on one instance. get is read-only; add and remove change the instance and are blocked in read-only mode. Tags are how scripts find groups of objects (CollectionService:GetTagged). To list every instance with a tag, use get_tagged.

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": {
      "path": "<path>",
      "action": "<action>"
    },
    "name": "tag"
  }
}

Input Schema

NameRequiredDescriptionDefault
tagNoTag name for add or remove, e.g. "Collectible". Ignored for get.
pathYesInstance whose tags to read or change. Dot path from the DataModel root, e.g. "Workspace.Map.Door" or "StarterGui.HUD.Frame". A leading "game." is optional; a duplicate sibling name takes the suffix Tufan prints, e.g. "Part (2)".
placeNoTarget place (PlaceId or project name). Defaults to the bound/sole connected place.
actionYes"get" lists the instance's tags; "add" and "remove" change one tag and need tag.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed3 schema fields changedv0.1.1
    • changedInput schema / properties / action / description
      Previous value: -"get = list this instance's tags; add/remove need `tag`"New value: +"\"get\" lists the instance's tags; \"add\" and \"remove\" change one tag and need tag."
    • addedInput schema / properties / path / description
      Added value: +"Instance whose tags to read or change. Dot path from the DataModel root, e.g. \"Workspace.Map.Door\" or \"StarterGui.HUD.Frame\". A leading \"game.\" is optional; a duplicate sibling name takes the suffix Tufan prints, e.g. \"Part (2)\"."
    • changedInput schema / properties / tag / description
      Previous value: -"required for add/remove"New value: +"Tag name for add or remove, e.g. \"Collectible\". Ignored for get."
  2. First observedv0.1.0

TDQS

A4.3/5.0
Behavior4/5

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

Annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the safety profile is partly covered. The description adds per-action nuance the annotations cannot express: which of the three actions mutates, and that mutations are refused in read-only mode. It stops short of saying what a removal does to the instance's script-visible behavior or whether a removed tag can be re-added trivially.

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?

Three tight sentences: capability first, per-action behavior second, alternative routing last. Nothing is redundant, though the CollectionService:GetTagged parenthetical is closer to background color than to decision-relevant information.

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?

With no output schema, the description could have said what get returns (a list of tag strings), which is the one thing an agent cannot infer. Otherwise it covers actions, mutation semantics, read-only blocking, and the bulk alternative, which is sufficient for a 4-parameter tool whose annotations already carry the destructive/idempotent flags.

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

Parameters3/5

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

Schema description coverage is 100% and every parameter (path, tag, place, action enum) is already documented in the schema, including the note that tag is ignored for get. The description adds only conceptual framing ('tags are how scripts find groups of objects'), not new per-parameter meaning, so the baseline of 3 applies.

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 set and resource: 'Read, add or remove CollectionService tags on one instance.' The scope ('on one instance') immediately separates it from the bulk sibling get_tagged, so an agent can distinguish the two without inspecting 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 the per-action conditions explicitly ('get is read-only; add and remove change the instance and are blocked in read-only mode') and routes the bulk case elsewhere: 'To list every instance with a tag, use get_tagged.' That is a named alternative with the selecting condition, not an implied one.

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