Spy on remote calls

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

Beyond the annotations, the description discloses real behavioral traits: recording and blocking need hookmetamethod in the executor, the hooks stay installed until the game is left, block drops calls before they reach the server even without recording, and unblock with an empty remotes list releases everything. It does not mention rate limits or what happens if the hook is already installed, and there is a mild tension with destructiveHint=false given that dropping remote calls visibly alters game behavior — though the description flags that risk explicitly rather than contradicting the annotation.

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?

It is front-loaded with the core purpose, then action list, then typical workflow, then the block caveat — a sensible order. The action enumeration partially duplicates the enum and the paragraph runs long, but every sentence (prerequisites, persistence, blocking warning) contributes information an agent needs.

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?

For an 11-parameter, multi-mode tool it covers the prerequisites (connected state, hookmetamethod), session persistence, and the two risky mutating actions, which is the information an agent cannot get from the schema. Return values are not explained, but no output schema exists and the get/since_id pairing is implied well enough through "use the lastId of the previous result."

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%, so every parameter including boundaries, defaults, and the dual start/block meaning of include_own is already documented. The description only lists parameter names per action (only, ignore, max_calls, since_id, contains, remote, limit) without adding format or syntax detail beyond the schema, so the schema carries the semantic load.

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?

The first sentence names the exact resource (RemoteEvent:FireServer / RemoteFunction:InvokeServer calls made by the game's own scripts), what is captured (arguments and calling script), and then enumerates the seven actions including the non-obvious block/unblock pair. This is clearly distinguishable from siblings like execute_lua, get_logs, or inspect_instance, which deal with outgoing code or static inspection rather than intercepted remote traffic.

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?

It gives an explicit operational sequence ("start, make the action happen (ask the user or use gui_interact), then get") and names the sibling gui_interact as the way to trigger activity, plus the alternative of asking the user. It also sets a clear when-not rule for blocking: only when the user asked for it, and tell them which remotes are blocked.

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