Search for instances in the game

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

Annotations already declare readOnly/idempotent/non-destructive, so safety is covered structurally. The description reinforces with 'Phase: observe', 'idempotency=read-only', and 'Safety: read-only' — redundant rather than additive. 'Produces: bounded-candidates' hints at return shape (tied to the limit param) but lacks rate-limit, pagination, or failure-mode detail beyond a pointer to tool-schema.

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

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

Front-loads purpose well, but the 'Signature/Phase/cost/idempotency/Requires/Produces/Safety/On failure' block is dense metadata that largely restates annotations and schema. Several statements ('read-only' twice, annotations restated) don't earn their place, though the signature is useful.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema, no annotations gap for safety, but the description does not describe return structure beyond 'bounded-candidates', nor does it cover error conditions beyond directing the agent to tool-schema. Selector grammar coverage is good, but the read-only/observation tool is under-specified on result shape and pagination behavior.

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

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

Schema description coverage is 100%, giving a baseline of 3, but the description adds value: it surfaces the full selector grammar (combinators, :not(), :has(), attribute syntax) and the required/optional split via the 'Signature' line, which the schema only partially conveys. It also frames the limit's purpose ('bounded-candidates').

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

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

States a specific verb+resource ('Search Roblox instances') and narrows the query capability (class, name, tag, property, attribute) against a chosen root. It's clear, but it never explicitly distinguishes from sibling finders like find-instances-with-connections or get-instance-tree, leaving the agent to infer routing.

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

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

The description says what kinds of queries it supports ('class, name, tag, property, and attribute queries'), which implies usage, but never states when to prefer this over siblings like get-instance-tree or find-instances-with-connections. No explicit exclusions or alternative routing.

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