filtergc — query the GC heap for functions or tables by structural criteria

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

Annotations already declare read-only/idempotent/non-destructive, but the description adds substantial behavior: every call is pcall-wrapped so a locked object can't abort the query, filtergc is type-guarded and returns {error} where unavailable, output is capped by 'limit', and matches are encoded to compact summaries. This is rich disclosure well beyond the structured hints.

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?

The purpose is front-loaded and well organized, but the description is bloated: it reprints the entire parameter signature that the input schema already defines verbatim, plus phase/cost/idempotency/capability metadata. Several sentences duplicate structured data rather than earning their place.

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?

With no output schema, the description carries the full return-value burden and does so: it documents the {filterType, matchCount, truncated, matches} shape, the per-type match encoding, the limit/truncation behavior, and the {error} path. An agent has everything needed to call and interpret the 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 each option (Name, Hash, Constants, Upvalues, Keys, Values, KeyValuePairs, Metatable, IgnoreExecutor) is already documented. The description groups options by filterType and gives examples, but that largely restates the schema's per-field 'function only'/'table only' annotations, so the baseline 3 applies.

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 (run filtergc) and resource (the live GC heap), and precisely scopes it to finding Lua closures or tables matching a structural fingerprint. It also distinguishes itself from the raw getgc() sweep and from sibling lookup tools, so an agent can identify it without opening the schema.

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?

Gives concrete when-to-use framing ('you describe WHAT you are looking for') and contrasts with a raw getgc() sweep, plus worked examples ('find the closure that owns the string FireServer'). However, it never names the closest siblings (find-functions-by-constant, find-tables-by-key, scan-closures-by-name) to route the agent, so the alternative-selection guidance is implied rather than explicit.

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