nexus_get_collection

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

The description discloses that this uses the v2 GraphQL API and does NOT consume v1 REST rate-limit quota, which is a meaningful behavioral trait beyond the annotations. It also lists the exact return fields (slug, name, summary, description with BBCode, endorsements, downloads, ratings, game, author, tags, category). Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered; the description adds rate-limit and return-format context.

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 concise and front-loaded: the first line states the verb and resource, followed by a short API/rate-limit note and a compact return list. Every sentence earns its place—no filler or repetition of schema details.

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 single-parameter read-only tool with an output schema, the description is largely complete. It covers purpose, endpoint, rate-limit behavior, and return fields. The only minor gap is that it doesn't explicitly mention error cases, but the annotations and output schema carry enough context for a safe and correct call.

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 coverage is 100%, so the schema already documents the slug parameter. The description adds value by specifying the expected format and source of the slug ('Collection slug from nexus_search_collections, e.g. 'collections-skyrimsse-x''). This example clarifies the exact string shape and where to obtain it, going slightly beyond the bare schema.

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 states a specific verb and resource: 'Get full details of a mod collection by slug via v2 GraphQL.' It explicitly distinguishes this from v1 REST by noting there is no v1 collection detail endpoint, and it names the input source (slug from nexus_search_collections). This clearly differentiates it from sibling collection tools like nexus_get_collection_games or nexus_get_collection_revision.

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 explains when to use this tool: to get collection details by slug, and explicitly states that v1 REST has no equivalent endpoint, so this tool is the right choice for collection details. It also references the slug source (nexus_search_collections), giving a clear usage path. No alternatives are named directly, but the v1/v2 distinction and absence of v1 endpoint effectively remove ambiguity.

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