nexus_search_collections

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint: false. The description adds meaningful behavioral detail beyond those: it names the v2 GraphQL backend and explicitly says it does NOT consume the v1 REST rate-limit quota, which informs an agent's cost/rate-limit decisions. It also discloses the returned JSON shape, including totalCount, _returned, and node fields.

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 description is compact and front-loaded: a one-sentence purpose, a brief API context note, and a small Returns block. Every sentence adds distinct information and the return list is formatted readably, with no filler or repetition of schema contents.

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 a six-parameter, zero-required-parameter read-only search, the description combined with the schema and annotations is essentially complete. It explains what is returned, highlights the _returned field for detecting server-side caps, and gives API version/rate-limit context. The only minor gap is no explicit error or empty-result behavior, but that is not critical for this tool.

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%, with each parameter already documented (e.g., term is 'Free-text general search term (matches name/summary/etc). Optional.' and count notes 'Server may silently cap page size; check '_returned''). The main description adds no substantive parameter meaning beyond what the schema provides, so the high-coverage baseline of 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?

The description opens with a specific verb+resource: 'Search Nexus Mods collections (curated mod packs) with free text.' This immediately distinguishes it from sibling search tools like nexus_search_mods, and the parenthetical defines what a collection is. The title 'Search mod collections (v2)' reinforces the scope.

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 gives clear context: it is the correct tool for free-text collection search and is backed by v2 GraphQL, avoiding v1 REST rate-limit quota. It notes that v1 REST has no collections search at all, which helps justify this tool's existence. However, it never names alternative sibling tools or gives explicit when-not-to-use conditions, so it falls short of a 5.

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